可用於自訂 ThingWorx 小器具的函數
本部份將介紹可用於小器具的函數。
小器具在 Mashup Builder 中的生命週期
小器具在 Mashup Builder 中有下列生命週期。在每個生命週期狀態下，Mashup Builder 呼叫適用於小器具的下列函數：
• 已發現
小器具在 index.html 中載入並新增至小器具工具列或調色盤。
|
函數
|
描述
|
|---|---|
|
widgetProperties()
|
取得有關混搭中每個小器具的資訊。擷取例如顯示名稱與描述等資訊。
|
|
widgetEvents()
|
取得有關每個小器具均顯示的事件的資訊。
|
|
widgetServices()
|
取得有關每個小器具均顯示的服務的資訊。
|
• 已建立
小器具已新增至混搭面板。
|
函數
|
描述
|
|---|---|
|
afterload()
|
將在物件已載入且內容已從檔案還原之後，但物件轉譯之前呼叫。
|
• 已附加
小器具會附加至工作區 DOM 元素。
|
函數
|
描述
|
|---|---|
|
renderHtml()
|
取得插入混搭 DOM 元素中的 HTML 片段。
|
|
afterRender()
|
將在表示小器具的 HTML 片段插入混搭 DOM 元素且可用元素 ID 已指派給儲存小器具內容的 DOM 元素之後呼叫。然後，即可對 DOM 元素進行操作。
|
• 已更新
小器具會在小器具內容視窗中重定大小或更新。
|
函數
|
描述
|
|---|---|
|
beforeSetProperty()
|
在小器具內容更新之前呼叫。
|
|
afterSetProperty()
|
在小器具內容更新之後呼叫。
|
• 已銷毀
小器具從混搭中刪除。
|
函數
|
描述
|
|---|---|
|
beforeDestroy()
|
在移除小器具的 DOM 元素之前，小器具從其父項小器具分離小器額取消分配時呼叫。您應釋放小器具生命週期內取得的資源，例如外掛程式和事件處理常式。
|
內容包
內容包是一組的名稱值對。每一對是一個簡單的值儲存區。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) - 取得所繫結的內容之 InfoTable 中繼資料。若未繫結內容，會傳回 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
|
如果小器具有邊界，則將此內容設定為邊界的寬度。此內容可協助您確保在開發期間以及執行時間像素能夠完美設計。
例如，假設小器具在執行時間的大小應該是 10X10 像素，其邊界大小為 1 像素。則在設計階段中，小器具大小應該是 8X8 像素，以便處理在設計時間新增的 1 像素。這會使得邊界放置在小器具內，並且使小器具內容中的寬度和高度精確。
|
|
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，則小器具內容視窗會顯示 InfoTable 中可用欄位的清單。欄位會根據基礎類型限制繫結至 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，則屬性會指定將 InfoTable 的哪些內容用於組態。
|
||||
|
sourcePropertyName
|
如果小器具的基礎類型設定為 FIELDNAME，則屬性會檢查 InfoTable 的哪些內容用於組態。
|
||||
|
baseTypeRestriction
|
如果指定了此屬性，則值用來限制 FIELDNAME 下拉式清單中的可用欄位。
|
||||
|
tagType
|
如果基礎類型設定為 TAGS，則屬性可指定標籤類型。有效值為 DataTags (預設值) 或 ModelTags。
|
||||
|
defaultValue
|
用來設定內容的預設值。預設值未定義。
|
||||
|
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() [選用] - 會在 DOM 中插入 HTML 片段之後呼叫此函數。
• 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;
}