ThingWorx 위젯을 사용자 정의하는 데 사용할 수 있는 함수
이 단원에서는 위젯에 사용할 수 있는 함수를 설명합니다.
Mashup Builder에서의 위젯 수명 주기
Mashup Builder에서 위젯의 수명 주기는 다음과 같습니다. 각 수명 주기 상태에서 Mashup Builder는 위젯에 사용할 수 있는 다음 함수를 호출합니다.
• 검색됨
위젯은 index.html에 로드되고 위젯 도구 모음 또는 팔레트에 추가됩니다.
|
함수
|
설명
|
|---|---|
|
widgetProperties()
|
매쉬업의 모든 위젯에 대한 정보를 가져옵니다. 표시 이름 및 설명과 같은 정보를 읽어들입니다.
|
|
widgetEvents()
|
모든 위젯에 의해 노출되는 이벤트에 대한 정보를 가져옵니다.
|
|
widgetServices()
|
모든 위젯에 의해 노출되는 서비스에 대한 정보를 가져옵니다.
|
• 작성됨
위젯이 매쉬업 패널에 추가됩니다.
|
함수
|
설명
|
|---|---|
|
afterload()
|
객체가 로드되고 파일에서 속성이 복원된 후 객체가 렌더링되기 전에 호출됩니다.
|
• 추가됨
위젯이 작업공간 DOM 요소에 추가됩니다.
|
함수
|
설명
|
|---|---|
|
renderHtml()
|
매쉬업 DOM 요소에 삽입되는 HTML 조각을 가져옵니다.
|
|
afterRender()
|
위젯을 나타내는 HTML 조각이 매쉬업 DOM 요소에 삽입되고, 위젯 콘텐츠를 포함하는 DOM 요소에 사용 가능한 요소 ID가 지정된 후에 호출됩니다. 그러면 DOM 요소를 조작할 준비가 된 것입니다.
|
• 업데이트됨
위젯은 위젯 속성 창에서 크기를 조정하거나 업데이트합니다.
|
함수
|
설명
|
|---|---|
|
beforeSetProperty()
|
위젯 속성이 업데이트되기 전에 호출됩니다.
|
|
afterSetProperty()
|
위젯 속성이 업데이트된 후에 호출됩니다.
|
• 제거됨
매쉬업에서 위젯이 삭제됩니다.
|
함수
|
설명
|
|---|---|
|
beforeDestroy()
|
위젯의 DOM 요소가 제거되고 위젯이 상위 위젯에서 분리되고 할당 취소되기 전에 호출됩니다. 위젯의 수명 주기 동안 얻은 플러그인 및 이벤트 처리기와 같은 리소스를 확보해야 합니다. 지연 로드된 컨테이너에서 위젯 다시 로드를 지원하려면 beforeDesctroy() 함수에 domOnly 인수를 추가한 다음 값이 false인 경우에만 위젯을 폐기해야 합니다. domOnly 인수를 사용하지 않으면 위젯이 올바르게 다시 로드되지 않습니다. 자세한 내용은 매쉬업에서 지연 로드 사용을 참조하십시오.
|
속성 모음
속성 모음은 이름-값 쌍의 집합입니다. 각 쌍은 단순하게 값이 저장되는 곳입니다. ThingWorx에서는 속성 모음을 매쉬업에 대한 구조 지속 메커니즘으로 사용합니다.
위젯에 사용할 수 있는 Mashup Builder API
다음 API는 Mashup Builder 컨텍스트에서 위젯을 통해 액세스할 수 있습니다.
• this.jqElementId - HTML 페이지에서 위젯이 렌더링된 후 객체의 DOM 요소 ID입니다.
• this.jqElement - jQuery 요소입니다.
• this.getProperty(name) - 속성의 이름을 읽어들입니다.
• this.setProperty(name,value) - 위젯에 afterSetProperty()가 정의되어 있는 경우 이 함수를 호출할 때마다 afterSetProperty() 함수가 호출됩니다.
• this.updatedProperties() - 위젯에서 속성이 변경될 때 이 함수를 호출해야 합니다. 함수가 호출되면 Mashup Builder에서 위젯 속성 창을 업데이트합니다.
• this.getInfotableMetadataForProperty(propertyName) - 바인딩된 속성에 대한 인포테이블 메타데이터를 가져옵니다. 속성이 바인딩되지 않은 경우에는 undefined가 반환됩니다.
• this.resetPropertyToDefaultValue(propertyName) - 지정된 속성을 해당 기본값으로 재설정합니다.
• this.removeBindingsFromPropertyAsTarget(propertyName) - 지정된 속성에서 대상 데이터 바인딩을 제거합니다.
• this.removeBindingsFromPropertyAsSource(propertyName) - 지정된 속성에서 소스 데이터 바인딩을 제거합니다.
• this.isPropertyBoundAsTarget(propertyName) - 속성이 대상으로 바인딩되었는지 확인합니다. 함수를 사용하여 속성이 설정되었는지 아니면 바인딩되었는지 확인할 수 있습니다. 예를 들어, 다음 샘플에서는 블로그 위젯의 validate() 함수를 사용하여 속성이 바인딩되었는지 확인하는 방법을 보여줍니다.
this.validate = function () {
var result = [];
var blogNameConfigured = this.getProperty('Blog');
if (blogNameConfigured === '' ||
blogNameConfigured === undefined) {
if (!this.isPropertyBoundAsTarget('Blog')) {
result.push({ severity: 'warning',
message: 'Blog is not bound for {target-id}' });
}
}
return result;
}
var result = [];
var blogNameConfigured = this.getProperty('Blog');
if (blogNameConfigured === '' ||
blogNameConfigured === undefined) {
if (!this.isPropertyBoundAsTarget('Blog')) {
result.push({ severity: 'warning',
message: 'Blog is not bound for {target-id}' });
}
}
return result;
}
• this.isPropertyBoundAsSource(propertyName) - 속성이 소스로 바인딩되었는지 확인합니다. 함수를 사용하여 속성이 대상에 바인딩되었는지 확인할 수 있습니다. 예를 들어, 다음 샘플에서는 확인란 위젯의 validate() 함수를 사용하여 속성이 바인딩되었는지 확인하는 방법을 보여줍니다.
this.validate = function () {
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
Mashup Builder에서 위젯으로의 콜백
위젯의 동작을 수정하기 위해 Mashup Builder에서 위젯의 다음 함수가 호출됩니다.
• widgetProperties() [필수 항목] - 위젯의 속성을 정의하는 JSON 구조를 반환합니다.
필수 속성은 다음과 같습니다.
◦ name - 위젯 도구 모음에 표시되는 위젯의 이름입니다.
선택적 속성은 다음과 같습니다.
|
속성
|
설명
|
|---|---|
|
description
|
도구 설명으로 사용되는 위젯에 대한 설명입니다.
|
|
iconImage
|
위젯 아이콘 또는 이미지의 파일 이름입니다.
|
|
category
|
위젯을 사용할 수 있는 카테고리를 지정하는 문자열의 배열입니다.
예를 들어, 공통, 차트, 데이터, 컨테이너 등이 있습니다. 이를 사용하면 사용자가 위젯을 카테고리 유형별로 필터링할 수 있습니다.
|
|
isResizable
|
위젯의 크기를 조정할 수 있는지 지정합니다.
|
|
defaultBindingTargetProperty
|
데이터 또는 이벤트 바인딩 대상으로 사용해야 하는 속성의 이름입니다.
|
|
borderWidth
|
위젯에 테두리가 있는 경우 이 속성을 테두리 너비로 설정합니다. 이 속성은 개발 및 런타임 중에 픽셀이 완벽한 설계를 보장하는 데 도움이 됩니다.
예를 들어, 런타임 시 크기가 테두리 크기가 1픽셀인 10X10 픽셀이어야 하는 위젯의 경우 디자인 타임 시 위젯의 크기는 디자인 타임에 추가된 1픽셀을 처리하도록 8X8 픽셀이어야 합니다. 그러면 위젯 내부에 테두리가 배치되고 위젯 속성의 너비 및 높이가 정확하게 설정됩니다.
|
|
isContainer
|
위젯 인스턴스가 다른 위젯 인스턴스에 대한 컨테이너가 될 수 있는지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 false입니다.
|
|
customEditor
|
위젯 구성을 설정하고 편집하는 데 사용해야 하는 사용자 정의 편집기 대화 상자의 이름입니다. 위젯 프로젝트에서 이름이 TW.IDE.Dialogs.<name>인 대화 상자를 만듭니다.
|
|
customEditorMenuText
|
위젯의 플라이아웃 메뉴에 나타나는 텍스트입니다. 또한 ThingWorx Composer에서 위젯의 도구 설명으로 표시되는 텍스트이기도 합니다. 예를 들어, 그리드 열 구성입니다.
|
|
allowPositioning
|
위젯을 패널에 배치할 수 있는지 확인합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 true입니다.
|
|
supportsLabel
|
위젯이 레이블 속성을 지원하는지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 false입니다.
true로 설정하면 위젯에서 레이블 속성을 노출합니다. 이 속성은 ThingWorx Composer 및 런타임 시 위젯 옆에 표시되는 텍스트 레이블을 만드는 데 사용됩니다.
|
|
supportsAutoResize
|
위젯이 크기 조정을 자동으로 지원하는지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 false입니다.
true로 설정하면 위젯이 열, 행, 반응형 탭 및 반응형 매쉬업 등의 반응형 컨테이너에 배치될 수 있습니다.
|
|
properties
|
위젯이 매쉬업에 추가될 때 수정할 수 있는 위젯의 속성을 설명하는 위젯에 대한 JSON 객체의 컬렉션입니다. 이러한 속성은 속성 이름으로 사용되는 각 객체의 이름과 함께 Mashup Builder의 속성 창에 표시됩니다. 해당 속성은 속성 값이 설정되는 방법을 제어합니다.
예:
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
각 속성 객체에 대해 지정할 수 있는 속성은 다음과 같습니다.
|
속성
|
설명
|
||||
|---|---|---|---|---|---|
|
description
|
도구 설명에 사용되는 위젯에 대한 설명입니다.
|
||||
|
baseType
|
위젯의 기본 유형입니다. 기본 유형 값이 FIELDNAME이면 위젯 속성 창에 인포테이블에서 사용할 수 있는 필드 목록이 표시됩니다. 필드는 기본 유형 제한에 따라 sourcePropertyName 값에 바인딩됩니다.
다른 특수 기본 유형은 다음과 같습니다.
• STATEDEFINITION - 상태 정의를 선택합니다.
• STYLEDEFINITION - 스타일 정의를 선택합니다.
• RENDERERWITHSTATE - 데이터 렌더러 및 상태 서식 적용을 선택할 수 있는 대화 상자를 표시합니다.
• STATEFORMATTING - 고정 스타일 또는 상태 기반 스타일을 선택할 수 있는 대화 상자를 표시합니다.
• VOCABULARYNAME - 런타임 시 데이터 태그 어휘를 선택합니다.
|
||||
|
mustImplement
|
기본 유형이 THINGNAME이고 mustImplement 속성을 지정하는 경우 Mashup Builder는 대화 상자에서 지정된 EntityType 및 EntityName을 구현하는 팝업만 열리도록 제한합니다. Mashup Builder는 QueryImplementingThings 함수를 호출하여 전달된 값이 EntityType 유형인지 검사하고 EntityName이 구현되었는지 확인합니다.
예:
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
위젯의 기본 유형이 RENDERERWITHFORMAT으로 설정된 경우 이 속성은 구성에 사용되는 인포테이블의 속성을 지정합니다.
|
||||
|
sourcePropertyName
|
위젯의 기본 유형이 FIELDNAME으로 설정된 경우 이 속성은 구성에 사용되는 인포테이블의 속성을 확인합니다.
|
||||
|
baseTypeRestriction
|
이 속성을 지정하는 경우 값을 사용하여 FIELDNAME 드롭다운 목록에서 사용 가능한 필드를 제한합니다.
|
||||
|
tagType
|
기본 유형이 TAGS로 설정된 경우 이 속성은 태그 유형을 지정합니다. 유효한 값은 기본값인 DataTags 또는 ModelTags입니다.
|
||||
|
defaultValue
|
속성의 기본값을 설정하는 데 사용됩니다. 기본값은 undefined입니다.
|
||||
|
isBindingSource
|
속성이 데이터 바인딩 소스인지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 fasle입니다.
|
||||
|
isBindingTarget
|
속성이 데이터 바인딩 대상인지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 fasle입니다.
|
||||
|
isEditable
|
ThingWorx Composer에서 속성을 편집할 수 있는지 지정합니다. 유효한 값은 기본값인 true 및 false입니다.
|
||||
|
isVisible
|
속성 창에 속성이 표시되는지 지정합니다. 유효한 값은 true 및 false입니다. 속성의 기본값은 true입니다.
|
||||
|
isLocalizable
|
속성을 지역화할 수 있는지 지정합니다. 이 속성은 기본 유형이 STRING으로 설정된 경우에 필요합니다. 유효한 값은 true 및 false입니다.
|
||||
|
selectOptions
|
값 또는 표시 텍스트 구조의 배열입니다.
예:
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer에서 속성이 데이터 바인딩 소스인지 확인합니다. 유효한 값은 true 및 false입니다.
속성 값이 true로 설정되었지만 속성이 바인딩되지 않은 경우 ThingWorx Composer에서 매쉬업을 저장하기 위해 완료해야 하는 항목 목록을 생성합니다.
|
||||
|
warnIfNotBoundAsTarget
|
Composer에서 속성이 데이터 바인딩 대상인지 확인합니다. 유효한 값은 true 및 false입니다.
속성 값이 true로 설정되었지만 속성이 바인딩되지 않은 경우 ThingWorx Composer에서 매쉬업을 저장하기 위해 완료해야 하는 항목 목록을 생성합니다.
|
• afterLoad() [선택 항목] - 객체가 로드되고 파일에서 속성이 복원된 후 HTML 페이지에 객체가 렌더링되기 전에 함수가 호출됩니다.
• renderHtml() [필수 항목] - 이 함수는 ThingWorx Composer가 화면에 배치하는 HTML 조각을 반환합니다. 위젯의 콘텐츠 컨테이너(예: div)에는 위젯 콘텐츠 클래스가 지정되어 있어야 합니다. 그러면 컨테이너 요소가 DOM에 추가됩니다. 이러한 컨테이너는 jqElement를 사용하여 액세스할 수 있으며 해당 DOM 요소 ID는 jqElementId에서 사용할 수 있습니다.
• widgetEvents() [선택 항목] - 이벤트의 컬렉션입니다. 각 이벤트에는 다음과 같은 속성이 포함될 수 있습니다.
◦ warnIfNotBound - Composer에서 속성이 바인딩되었는지 확인합니다. 유효한 값은 true 및 false입니다.
속성 값이 true로 설정되었지만 속성이 바인딩되지 않은 경우 ThingWorx Composer에서 매쉬업을 저장하기 위해 완료해야 하는 항목 목록을 생성합니다.
• widgetServices() [선택 항목] - 서비스의 컬렉션입니다. 각 서비스에는 다음과 같은 속성이 포함될 수 있습니다.
◦ warnIfNotBound - Composer에서 속성이 바인딩되었는지 확인합니다. 유효한 값은 true 및 false입니다.
속성 값이 true로 설정되었지만 속성이 바인딩되지 않은 경우 ThingWorx Composer에서 매쉬업을 저장하기 위해 완료해야 하는 항목 목록을 생성합니다.
• afterRender() [선택 항목] - HTML 조각이 DOM에 삽입된 후 함수가 호출됩니다.
• beforeDestroy() [선택 항목] - 위젯의 DOM 요소가 제거되고 위젯이 상위 위젯에서 분리되고 할당 취소되기 전에 함수가 호출됩니다. 위젯의 수명 주기 동안 얻은 플러그인 및 이벤트 처리기와 같은 리소스를 확보해야 합니다.
• beforeSetProperty(name,value) [선택 항목] [Mashup Builder만 해당 - 런타임이 아님] - ThingWorx Composer에서 속성이 업데이트되기 전에 함수가 호출됩니다. 새 속성 값이 커밋되기 전에 해당 값에 대한 유효성 검사를 수행할 수 있습니다. 유효성 검사가 실패하면 사용자에게 잘못된 입력을 알리는 메시지 문자열을 반환할 수 있습니다. 새 속성 값은 커밋되지 않습니다. 유효성 검사 동안 반환된 것이 없으면 값이 유효한 것으로 간주됩니다.
• afterSetProperty(name,value) [선택 항목] [Mashup Builder만 해당 - 런타임이 아님] - ThingWorx Composer에서 속성이 업데이트된 후 함수가 호출됩니다. 값을 true로 지정하면 값이 변경된 후 ThingWorx Composer에서 위젯이 다시 렌더링됩니다.
• afterAddBindingSource(bindingInfo) [선택 항목] - 데이터가 위젯에 바인딩될 때마다 이 함수가 호출됩니다. bindingInfo의 유일한 필드는 속성의 이름이며 바인딩된 targetProperty입니다.
• validate() [선택 항목] - ThingWorx Composer에서 해당 할 일 목록을 새로 고칠 때 함수가 호출됩니다. 호출은 결과 객체의 배열을 반환합니다.
◦ severity - 이는 선택적 속성입니다. 감지된 문제의 심각도입니다.
◦ message - 이는 필수 속성입니다. 메시지 텍스트에는 {target-id}와 같은 사전 정의된 토큰이 하나 이상 포함될 수 있습니다. 이 메시지는 사용자가 메시지를 생성한 특정 위젯을 탐색하고 선택할 수 있는 하이퍼링크로 대체됩니다.
예:
this.validate = function () {
var result = [];
var srcUrl = this.getProperty('SourceURL');
if (srcUrl === '' || srcUrl === undefined) {
result.push({ severity: 'warning',
message: 'SourceURL is not defined for {target-id}'});
}
return result;
}
var result = [];
var srcUrl = this.getProperty('SourceURL');
if (srcUrl === '' || srcUrl === undefined) {
result.push({ severity: 'warning',
message: 'SourceURL is not defined for {target-id}'});
}
return result;
}