솔루션 개발을 위한 모범 사례 > ThingWorx 솔루션에 대한 사용자 경험 설계 > ThingWorx 솔루션의 위젯 > 사용자 정의된 ThingWorx 위젯 만들기 > ThingWorx 위젯을 사용자 정의하는 데 사용할 수 있는 런타임 함수
ThingWorx 위젯을 사용자 정의하는 데 사용할 수 있는 런타임 함수
이 단원에서는 런타임 시 위젯에 사용할 수 있는 함수를 설명합니다.
런타임 시 위젯 수명 주기
• 위젯을 처음 만들 때 런타임은 runtimeProperties() 함수를 호출하여 선언된 모든 속성을 가져옵니다.
자세한 내용은 런타임에서 위젯으로의 콜백 단원을 참조하십시오.
• 매쉬업 정의에 저장된 속성 값은 함수를 호출하지 않고 객체에 로드됩니다.
• 위젯이 로드된 후 화면에 렌더링되기 전에 런타임은 renderHtml() 함수를 호출합니다. 이 함수에서 객체에 대한 HTML을 반환합니다. 런타임은 함수에 의해 반환된 HTML을 DOM의 적절한 위치에서 렌더링합니다.
• DOM에 HTML이 추가된 후 afterRender() 함수가 호출됩니다. 필요한 경우 jQuery 바인딩을 수행할 수 있습니다. 이 시점에서 실제 DOM 요소를 참조할 수 있습니다. 예를 들어, 다음 코드를 사용하여 DOM 요소를 참조합니다.
// note that this is a jQuery object
var widgetElement = this.domElement;
* 
런타임은 DOM 요소의 ID를 변경합니다. 항상 jQuery 객체 this.domElementId를 사용하여 DOM 요소의 ID를 가져오는 것이 좋습니다.
• 바인딩할 수 있는 이벤트를 정의한 경우 다음 예와 같이 이벤트를 트리거할 수 있습니다.
var widgetElement = this.domElement;
// change ‘Clicked’ to be your event name
// you defined in your runtimeProperties
widgetElement.triggerHandler('Clicked');
• 데이터 대상으로 바인딩된 속성이 있는 경우 updateProperty() 함수가 호출됩니다. 변경된 속성이 DOM에 영향을 주는 경우 DOM을 직접 업데이트해야 합니다. 데이터가 바인딩되면 대부분의 경우 DOM이 변경됩니다.
• 데이터 소스로 정의된 속성이 있고 이러한 속성이 바인딩된 경우 getProperty_{propertyName}() 함수를 호출할 수 있습니다. 이 함수를 정의하지 않으면 런타임은 속성 모음에서 값을 가져옵니다.
위젯에 사용할 수 있는 런타임 API
다음 API는 런타임 컨텍스트에서 위젯을 통해 액세스할 수 있습니다.
• this.jqElementId - HTML 페이지에서 위젯을 렌더링한 후 객체의 DOM 요소 ID입니다.
• this.jqElement - jQuery 요소입니다.
• this.getProperty(name) - 속성의 이름을 가져옵니다.
• this.setProperty(name,value) - 속성의 이름과 값을 설정합니다.
• this.updateSelection(propertyName,selectedRowIndices) - 위젯이 선택한 행의 속성을 변경할 때 이 함수를 호출합니다. 이러한 행에는 데이터가 바인딩되어 있습니다. 예를 들어, 콜백에서 onSelectStateChanged()와 같은 이벤트를 정의하고 API this.updateSelection(propertyName,selectedRowIndices)을 호출하면 선택한 행에 종속된 모든 위젯이 업데이트됩니다.
런타임에서 위젯으로의 콜백
위젯에 대한 다음 함수는 런타임에 의해 호출됩니다.
• runtimeProperties() [선택 항목] - 위젯의 속성을 정의하는 JSON 구조를 반환합니다.
선택적 속성은 다음과 같습니다.
속성
설명
isContainer
위젯 인스턴스가 다른 위젯 인스턴스에 대한 컨테이너가 될 수 있는지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 fasle입니다.
needsDataLoadingAndError
유효한 값은 true 및 false입니다. 속성의 기본값은 fasle입니다. 받은 데이터가 없을 때 위젯에서 표준 25%의 불투명도를 표시하려면 속성을 true로 설정합니다. 데이터를 읽어들이는 동안 오류가 발생하면 위젯이 빨간색으로 바뀝니다.
borderWidth
위젯에 테두리가 있는 경우 이 속성을 테두리 너비로 설정합니다. 이 속성은 개발 및 런타임 중에 픽셀이 완벽한 설계를 보장하는 데 도움이 됩니다.
supportsAutoResize
위젯이 크기 조정을 자동으로 지원하는지 지정합니다. 유효한 값은 true 및 false입니다.
propertyAttributes
지역화할 수 있는 STRING 속성이 있으면 이 속성에 나열합니다.
예를 들어, TooltipLabel1을 지역화할 수 있는 경우 다음과 같습니다.
this.runtimeProperties = function () {
return {
'needsDataLoadingAndError': true,
'propertyAttributes': {
'TooltipLabel1': {'isLocalizable': true} }
}
};
• renderHtml() [필수 항목] - 이 함수는 런타임이 화면에 배치하는 HTML 조각을 반환합니다. 예를 들어, 위젯의 콘텐츠 컨테이너 div에는 위젯 콘텐츠 클래스가 지정되어 있어야 합니다. 클래스가 지정된 후 컨테이너 요소가 DOM에 추가됩니다. 컨테이너는 jqElement를 사용하여 액세스할 수 있으며 해당 DOM 요소 ID는 jqElementId에서 사용할 수 있습니다.
• afterRender() [선택 항목] - 위젯 HTML 조각이 DOM에 삽입된 후 이 함수가 호출됩니다. this.domElementId를 사용하여 DOM 요소 ID를 가져옵니다. this.jqElement 요소를 사용하여 jQuery DOM 요소를 가져옵니다.
• beforeDestroy() [옵션 항목이지만 매우 권장] - 위젯을 화면에서 제거할 때 이 함수를 호출합니다. 이 함수를 사용하여 다음을 수행할 수 있습니다.
◦ 바인딩의 바인딩 해제
◦ .data()를 사용하여 데이터 집합 지우기
◦ 타사 라이브러리 또는 플러그인을 제거하고 해당 소멸자를 호출합니다.
◦ 모든 변수를 null로 설정하여 할당했거나 클로저에서 보유 중인 모든 메모리를 확보합니다.
◦ 위젯 내에서 DOM 요소를 제거할 필요는 없습니다. 이러한 요소는 런타임에 의해 제거됩니다.
◦ 함수에 DOMOnly 인수를 추가하여 DOM만 제거합니다.
* 
위젯에 지연 로드를 사용하려면 DOMOnly 인수를 함수에 추가합니다.
• resize(width,height) [선택 항목 - supportsAutoResize: true를 선언하는 경우에만 유용] - 위젯의 크기를 조정할 때 이 함수가 호출됩니다.
일부 위젯에서는 이를 처리할 필요가 없습니다. 예를 들어, 위젯의 요소와 CSS 자동 배율의 경우입니다.
그러나 대부분의 위젯에서는 위젯 크기가 변경될 때 처리해야 합니다.
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) - 선택한 행이 지정된 속성으로 해당 행에 바인딩된 데이터 소스에 의해 수정될 때 이 함수가 호출됩니다. selectedRows는 실제 데이터의 배열이고 selectedRowIndices는 선택한 행의 색인 배열입니다.
* 
목록 또는 그리드 위젯을 바인딩하지 않고 전체 selectedRows 이벤트 기능을 가져오려는 경우 이 기능을 정의해야 합니다.
• serviceInvoked(serviceName) - 사용자가 정의한 서비스가 트리거될 때 함수가 호출됩니다.
• updateProperty(updatePropertyInfo) - updatePropertyInfo는 다음과 같은 JSON 구조가 있는 객체입니다.
{
DataShape: metadata for the rows returned
ActualDataRows: actual Data Rows
SourceProperty: SourceProperty
TargetProperty: TargetProperty
RawSinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
SinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
converted to the defined baseType of the
target property [not implemented yet],
SelectedRowIndices: an array of selected row indices
IsBoundToSelectedRows: a Boolean letting you know if this
is bound to SelectedRows
}
각 데이터 바인딩의 경우 소스 데이터가 변경될 때마다 위젯의 updateProperty()가 호출됩니다. updatePropertyInfo.TargetProperty를 확인하여 위젯에서 업데이트해야 할 측면을 확인해야 합니다.
위젯의 다음 예를 참조하십시오.
this.updateProperty = function (updatePropertyInfo) {
// get the img inside our widget in the DOM
var widgetElement = this.jqElement.find('img');
// if we're bound to a field in selected rows
// and there are no selected rows, we'd overwrite the
// default value if we didn't check here
if (updatePropertyInfo.RawSinglePropertyValue !==
undefined) {
// see which TargetProperty is updated
if (updatePropertyInfo.TargetProperty === 'sourceurl') {
// SourceUrl updated - update the <img src=
this.setProperty('sourceurl',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("src",
updatePropertyInfo.SinglePropertyValue);
} else if (updatePropertyInfo.TargetProperty ===
'alternatetext') {

// AlternateText updated - update the <img alt=
this.setProperty('alternatetext',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("alt",
updatePropertyInfo.SinglePropertyValue);
}
}
};
위젯 객체에서 속성의 로컬 복사본을 설정합니다. 이렇게 하면 런타임 시스템이 속성 모음에서 속성을 가져올 수 있습니다.
또는 사용자 정의 getProperty_{propertyName} 메소드를 제공하고 값을 다른 방식으로 저장할 수 있습니다.
• getProperty_{propertyName}() - 런타임에 속성 값이 필요하면 위젯이 해당 속성의 값으로 재정의하고 가져오는 함수를 구현하는지 확인합니다. 이는 런타임이 위젯의 데이터를 가져와 서비스 호출을 위한 매개 변수를 채울 때 사용됩니다.
도움이 되셨나요?