/
Macros - NXML

Macros - NXML

Owned by Xiaoyan Kong (Unlicensed)
Last updated: Dec 05, 2012Version comment
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は、このマクロを識別する固有の名前を指定します。
マクロを定義する場合には、次のことに留意してください。
  • マクロの名前は固有でなければなりません。新しいマクロを既存のマクロと同じ名前で作成すると、新しく作成されたマクロは古いマクロを上書きします。
  • 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' )" />

マクロでのパラメータの指定


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'')

マクロまたはイベントハンドラの呼び出しで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’)"