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 エレメントが除去される前に呼び出され、ウィジェットがその親ウィジェットから切り離されて割当解除されます。ウィジェットの有効期間内に取得したプラグインやイベントハンドラなどのリソースを解放する必要があります。
|
プロパティバッグ
プロパティバッグは名前と値のペアのセットです。各ペアは単純な値ストアです。ThingWorx ではプロパティバッグがマッシュアップの構造永続化メカニズムとして使用されます。
ウィジェットに使用可能な Mashup Builder API
ウィジェットは Mashup Builder のコンテキストで以下の API にアクセスできます。
• 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
|
ウィジェットに境界がある場合、このプロパティによって境界の幅を設定します。このプロパティにより、開発中およびランタイムでピクセルパーフェクトの設計が可能になります。
たとえば、ランタイムでのサイズが 10X10 ピクセルで境界サイズが 1 ピクセルのウィジェットがあるとします。デザインタイムでは、デザインタイムで追加される 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 属性を指定した場合、指定した EntityType および EntityName を実装するポップアップだけがダイアログボックスで開きます。Mashup Builder は関数 QueryImplementingThings を呼び出して、渡された値が EntityType タイプであるかどうかを検証し、EntityName が実装されているかどうかをチェックします。
次に例を示します。
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
ウィジェットのベースタイプが RENDERERWITHFORMAT として設定されている場合、この属性はコンフィギュレーションにインフォテーブルのどのプロパティを使用するかを指定します。
|
||||
|
sourcePropertyName
|
ウィジェットのベースタイプが FIELDNAME として設定されている場合、この属性はコンフィギュレーションにインフォテーブルのどのプロパティが使用されているかをチェックします。
|
||||
|
baseTypeRestriction
|
この属性が指定されている場合、この値を使用して、フィールド名ドロップダウンリストで使用可能なフィールドが制限されます。
|
||||
|
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
|
このプロパティがデータバインドのターゲットであるかどうかがチェックされます。有効な値は true および false です。
この属性値が true に設定されているにもかかわらず、プロパティがバインドされていない場合、ThingWorx Composer はアイテムのリストを生成します。マッシュアップを保存するには、このリストに入力する必要があります。
|
• afterLoad() [オプション] - この関数は、オブジェクトがロードされてプロパティがファイルから復元された後、オブジェクトが HTML ページにレンダーされる前に呼び出されます。
• renderHtml() [必須] - この関数は ThingWorx Composer の画面上に配置されている HTML フラグメントを返します。ウィジェットのコンテンツコンテナ (div など) 内でウィジェットコンテンツクラスが指定されている必要があります。この後、コンテナエレメントが DOM に追加されます。コンテナには jqElement を使用してアクセスでき、その DOM エレメント ID は jqElementId 内にあります。
• widgetEvents() [オプション] - イベントのコレクション。各イベントは以下のプロパティを持つことができます。
◦ warnIfNotBound - このプロパティがバインドされているかどうかがチェックされます。有効な値は true および false です。
この属性値が true に設定されているにもかかわらず、プロパティがバインドされていない場合、ThingWorx Composer はアイテムのリストを生成します。マッシュアップを保存するには、このリストに入力する必要があります。
• widgetServices() [オプション] - サービスのコレクション。各サービスは以下のプロパティを持つことができます。
◦ warnIfNotBound - このプロパティがバインドされているかどうかがチェックされます。有効な値は 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 の To Do リストが再表示された場合に呼び出されます。この呼び出しは結果オブジェクトの配列を返します。
◦ severity - これはオプションのプロパティです。検出された問題の重大度。
◦ message - これは必須のプロパティです。メッセージテキストには、{target-id} などの、1 つ以上の定義済みトークンを含めることができます。メッセージはハイパーリンクに置き換えられ、これを使用してユーザーはメッセージを生成した特定のウィジェットをナビゲートおよび選択できます。
次に例を示します。
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;
}