Macros - NXML
Platform 4.2 以上が必要
マクロでのパラメータの使用
マクロを使用すると、Nexaweb Platform がメモリにロードして随時実行する、有効な Nexaweb ページの命令 (XUpdate、MCO、データなど) のグループに名前を関連付けることができます。
Nexaweb 4.2.x では、java.text.MessageFormat シンタックスを使用して、ロジックを実行するマクロにパラメータを指定できます。これにより、マクロで引数が使用できるようになります。 MessageFormat シンタックスでは、引数が使用される場所とこのような引数のフォーマット (コンマ区切りやドル記号などを含む数値フォーマットなど) を指定できます。マクロでパラメータを使用すると、各マクロを再利用してさまざまなコンポーネントで動作させることができるので、各マクロの柔軟性が向上 します。たとえば、2 つの異なるウィンドウを閉じる動作を記述するのに、パラメータを使用しない場合は 2 つの異なるマクロを記述する必要がありますが、パラメータを使用する場合は 1 つのマクロを記述するだけで済みます。
クライアントサイドのロジックの開発でマクロを使用すると、次のようなメリットがあります。
- クライアント UI の開発に使用される XML ベースのツールが使用できる
- サーバーへの往復が不要になる
- 将来の Nexaweb クライアント環境への移植性がある
次の例では、パラメータを使用しないマクロの使用方法を示します。
マクロ:
<modifications document="nxml"> <remove select="id(‘‘MyWindow’’)"> </modifications> このマクロを呼び出す場合: onCommand=”macro://mymacro.execute()"
次の例では、パラメータを使用するマクロの使用方法を示します。
マクロ:
<modifications document=”nxml”>
<remove select="id(''{0}'')">
</modifications>
このマクロを呼び出す場合:
onCommand=”macro://mymacro.execute (‘Window1’)
マクロの定義の概要
次に、マクロの定義に使用される基本フォーマットを示します。
<macro xmlns:macro="http://nexaweb.com/macro">
name = name-attribute-type
(パラメータの代わりに使用される場合に Nexaweb ページ要素となる、有効な Nexaweb 要素または文字列)
</macro>
name-attribute-typeは、このマクロを識別する固有の名前を指定します。
name = name-attribute-type
(パラメータの代わりに使用される場合に Nexaweb ページ要素となる、有効な Nexaweb 要素または文字列)
</macro>
name-attribute-typeは、このマクロを識別する固有の名前を指定します。
マクロを定義する場合には、次のことに留意してください。
- マクロの名前は固有でなければなりません。新しいマクロを既存のマクロと同じ名前で作成すると、新しく作成されたマクロは古いマクロを上書きします。
- Nexaweb は、マクロにインクルードする Nexaweb ページの命令をすべて文字列に変換し、java.text.message フォーマットを使用してフォーマット処理を行います。したがって、マクロ内の Nexaweb ページの命令は java.text.message フォーマットのシンタックスに準拠している必要があります。たとえば、java.text.message フォーマットのシンタックスに準拠するには、Nexaweb ページの命令に一重引用符と中かっこを使用してエスケープする必要があります。
パラメータを使用しないマクロでのXUpdate コマンドの定義
次に、XUpdate コマンドを使用したマクロを含むページの例を示します。ここではパラメータが使用されていません。
この例では、 mymacro というマクロがページに含まれています。このマクロの本文には、ラベル ("mylabel") のテキストを変更する XUpdate コマンド (set-attribute) が1 つだけ含まれています。ユーザーがボタン "Execute Macro" を押すと、このマクロが実行されて、ラベルの名前がOld Text からNew Text に変更されます。
<nxml>
<macro:macro name="mymacro" xmlns:macro="http://nexaweb.com/macro">
<xu:modifications xmlns:xu="http://nexaweb.com/xupdate">
<xu:set-attribute select="id(''mylabel'')">
<xu:attribute name="text" value="New Text" />
</xu:set-attribute>
</xu:modifications>
</macro:macro>
<panel>
<flowLayout align="center"/>
<label text="Old Text" id="mylabel" bgcolor="green"/>
<button text="Execute Macro" onCommand="macro://mymacro.execute()"/>
</panel>
</nxml>
パラメータを使用したマクロでの XUpdate コマンドの定義
次に、パラメータを使用した同じマクロの例を示します。
<macro:macro name="mydialog" xmlns:macro="http://nexaweb.com/macro">
<xu:modifications document="nxml" xmlns:xu="http://nexaweb.com/xupdate">
<xu:append select="/nxml/rootPane">
<dialog title="My Dialog" closeable="false" focused="true" centered="true">
<label text="My dialog is your dialog, from California, to the New York islands"/>
</dialog>
</xu:append>
</xu:modifications>
</macro:macro>
<macro:macro name="generic-dialog" xmlns:macro="http://nexaweb.com/macro">
<xu:modifications document="nxml" xmlns:xu="http://nexaweb.com/xupdate">
<xu:append select="/nxml/rootPane">
<dialog title="{0}" closeable="{1}" focused="{2}" centered="{3}">
<label text="{4}"/>
</dialog>
</xu:append>
</xu:modifications>
</macro:macro>
次の例では、パラメータを使用したマクロへの呼び出しを示します。
<macro:macroCall name="generic-dialog" xmlns:macro="http://nexaweb.com/macro" > <macro:parameter>ThisIt</macro:parameter> <macro:parameter>true</macro:parameter> <macro:parameter>true</macro:parameter> <macro:parameter>false</macro:parameter> <macro:parameter>Answer</macro:parameter> </macro:macroCall>
次の例では、パラメータを使用したマクロへのイベントハンドラの呼び出しを示します。
<button onCommand="macro://generic-dialog.execute( 'ThisIt', 'true', 'true', 'false', 'Answer' )" />
<button onCommand="macro://generic-dialog.execute( 'ThisIt', 'true', 'true', 'false', 'Answer' )" />
マクロでのパラメータの指定
java.text.MessageFormat を使用して、Nexaweb の命令で属性値に使用するマクロのパラメータを指定します (Java MessageFormat シンタックスの詳細については、http://java.sun.com/j2se/1.4.2/docs/api/を参照してください)。
注: JVM (Java Virtual Machine) 1.4 以前のバージョンでは、1 つのマクロで使用可能なプレースホルダの数に制限があります。バージョン 1.4 以降の JVM では、プレースホルダを無制限に指定できます。この制限の詳細については、java.sun.com を参照してください。
MessageFormat シンタックスでは、一重引用符 (') は特殊文字で、MessageFormat で無視されるリテラル文字列を指定する場合に使用されます。したがって、このフォーマットで一重引用符を使用する場合は、一重引用符を 2 つ('') 使用する必要があります。
注: この場合、一重引用符(') を 2 つ重ねて使用する必要があります。代わりに二重引用符(") を使用することはできません。
このように指定すると、マクロで使用されない Nexaweb の命令は、次に示す例の最初の文字列のように表示されます。これに対し、マクロで使用される Nexaweb の同じ命令は、この例の 2 番目の文字列のように表示されます。
id('mywindow')
id(''mywindow'')
id(''mywindow'')
マクロまたはイベントハンドラの呼び出しでNexaweb の命令が実行されるときに、これらのパラメータに代わって使用される実際の値を指定します。
マクロでは 2 種類のパラメータを指定できます。
- リテラルとして指定される静的な値
- ドキュメントに対して XPath 文として指定される動的な値
イベントハンドラでのパラメータの指定
<button onCommand="macro://generic-dialog( {id('myDialogTitleField')/@text}, 'true', 'true', 'false', {MyDataDocument:id('myTextField')/@text} )" />
プログラムを使用したマクロの定義と呼び出し
次に、プログラムを使用してマクロを定義する例を示します。
MacroContainer macroContainer = ClientSession.getMacroContainer();
Macro macro = macroContainer.createMacro
("<xu:modifications xmlns:xu=\"http://nexaweb.com/xupdate\" document=\"nxml\">" +
" <xu:append select=\"/nxml/rootPane[1]\">" +
" <dialog>" +
" <label text=\"Call me Ishmael.Some years ago- never mind how long precisely...\" />" +
" </dialog>" +
" </xu:append>" +
"</xu:modifications>" );
macroContainer.putMacro("nexaweb-examples-herman-melville-dialog", macro);
次に、プログラムを使用してマクロを呼び出す例を示します。
MacroContainer macroContainer = clientSession.getMacroContainer();
Macro melvilleMacro = macroContainer.getMacro( "nexaweb-examples-herman-melville-dialog" );
melvilleMacro.execute();
Macro genericXUpdateMacro = macroContainer.getMacro( "nexaweb-examples-generic-xupdate" );
genericXUpdateMacro.execute( new Object [] { "remove-element", "id('anElementId')", "" } );
genericXUpdateMacro.execute( new Object [] { "append", "/nxml/rootPane[1]", "<dialog><label text=\"Mylabel\"/></dialog>" } );
マクロのデバッグとトラブルシューティング
マクロをデバッグするには、アプリケーションのクライアントコンフィギュレーションファイル、nexaweb-client.xmlで、次のようにマクロのデバッグロギングを有効にします。
<log-configuration> <log name="Macro" log-level="debug"/> </log-configuration>
次はマクロログからのアウトプットサンプルになります。(全てのクライアント側のロギングはブラウザのjava コンソールに行きます) :
注 : 次のサンプルアウトプットは特定の引数、マクロ、POST フォーマットを示しています。
[Debug - 10:42:22 (Macro): Enabled debug logging.]
[Debug - 10:42:35 (Macro): Formatting macro with 0 args: []]
[Debug - 10:42:35 (Macro): Macro pre-formatting:
<nxml><xu:modifications xmlns:xu="http://nexaweb.com/xupdate" document="nxml">
<xu:append select="/nxml/rootPane[1]">
<dialog>
<label text="Call me Ishmael. Some years ago- never mind how long precisely..."/>
</dialog>
</xu:append>
</xu:modifications></nxml>]
[Debug - 10:42:35 (Macro): Macro post-formatting:
<nxml>
<xu:modifications xmlns:xu="http://nexaweb.com/xupdate" document="nxml">
<xu:append select="/nxml/rootPane[1]">
<dialog>
<label text="Call me Ishmael. Some years ago- never mind how long precisely..."/>
</dialog>
</xu:append>
</xu:modifications>
</nxml>]
[Debug - 10:42:46 (Macro): Formatting macro with 3 args: ["append", "/nxml/rootPane[1]", "<dialog><label text="Mylabel" /></dialog>"]]
[Debug - 10:42:46 (Macro): Macro pre-formatting:
<nxml>
<xu:modifications document="nxml" xmlns:xu="http://nexaweb.com/xupdate" >
<xu:{0} select="{1}" >
{2}
</xu:{0}>
</xu:modifications>
</nxml>]
[Debug - 10:42:46 (Macro): Macro post-formatting:
<nxml>
<xu:modifications document="nxml" xmlns:xu="http://nexaweb.com/xupdate" >
<xu:append select="/nxml/rootPane[1]" >
<dialog><label text="Mylabel" /></dialog>
</xu:append>
</xu:modifications>
</nxml>]
後方互換性
Nexaweb 4.2リリース以前のマクロを使用し、それらのマクロがMessageFormat 特定文字を含んでいる場合、以前のようにマクロが機能し続ける様、MessageFormat 機能を無効するのがよいでしょう。これは nexaweb-client.xml ファイルで次の値を true に変更することにより可能です :
<!-- This parameter is supplied so that the macro code can know NOT --> <!-- to use MessageFormat for the macro strings. in 4.2 we added parameters --> <!-- which use MessageFormat, thus single tick escaping is required in 4.2 --> <!-- plus. We want existing macros to work if the customer so desires. --> <ensure-pre-4-dot-2-macro-compatibility>false</ensure-pre-4-dot-2-macro-compatibility> onCommand=”macro://mymacro.execute (‘Window2’)"