アプリケーション開発の最良事例 > ThingWorx アプリケーションのユーザーエクスペリエンスの設計 > ThingWorx アプリケーション内のウィジェット > カスタマイズされた ThingWorx ウィジェットの作成 > ThingWorx ウィジェットのカスタマイズに使用可能なランタイム関数
ThingWorx ウィジェットのカスタマイズに使用可能なランタイム関数
このセクションでは、ランタイムでウィジェットに使用可能な関数について説明します。
ランタイムでのウィジェットのライフサイクル
• ウィジェットが最初に作成されると、ランタイムは関数 runtimeProperties() を呼び出すことで、宣言されているすべてのプロパティを取得します。
詳細については、 ランタイムからウィジェットへのコールバックのセクションを参照してください。
• 関数を呼び出すことなく、マッシュアップ定義に保存されているプロパティの値がオブジェクト内にロードされます。
• ウィジェットがロードされた後、画面上にレンダーされる前に、ランタイムは関数 renderHtml() を呼び出します。この関数で、オブジェクトの HTML を返します。ランタイムはこの関数によって DOM 内の適切な場所に返された HTML をレンダーします。
• HTML が DOM に追加された後、関数 afterRender() が呼び出されます。必要に応じて、jQuery バインドを実行できます。この時点で、実際の DOM エレメントを参照できます。たとえば、以下のコードを使用して DOM エレメントを参照します。
// note that this is a jQuery object
var widgetElement = this.domElement;
* 
ランタイムは DOM エレメントの ID を変更します。DOM エレメントの ID を取得するには、jQuery オブジェクト this.domElementId を必ず使用することをお勧めします。
• バインド可能なイベントを定義している場合、以下の例に示すように、イベントをトリガーできます。
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 に挿入された後で呼び出されます。DOM エレメント ID を取得するには this.domElementId を使用します。jQuery DOM エレメントを取得するには this.jqElement エレメントを使用します。
• beforeDestroy() [オプション、強く推奨] - この関数は、ウィジェットが画面から除去されるときに呼び出されます。この関数では、以下の処理を行えます。
◦ バインドを解除する
◦ .data() を使用してすべてのデータセットをクリアする
◦ サードパーティのライブラリまたはプラグインをすべて破棄したり、そのデストラクタを呼び出したりする。
◦ すべての変数を null に設定することで、割り当てたメモリやクロージャ内に格納されているメモリをすべて解放する
◦ ウィジェット内の DOM エレメントを破棄する必要はなく、これらはランタイムによって破棄されます
• 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}() - ランタイムがプロパティの値を必要とする場合、そのプロパティの値をオーバーライドして取得する関数がウィジェットが実装されているかどうかをチェックします。これは、ランタイムがウィジェットからデータを取得してサービス呼び出しのパラメータを設定する場合に使用されます。