ZK 要素

ZK 要素
前のページ	6. ZKユーザーマークアップ言語	次のページ

ZK要素はコンポーネント作成のほかにZUMLページをコントロールします。

`zk` 要素

<zk>...</zk>

特別な要素が他の要素を集めます。本当のコンポーネント(例えば、hbox or div)とは異なり、コンポーネントツリーの一部分ではありません。つまり、コンポーネントではありません。例えば、

<window>
   <zk>
      <textbox/>
      <textbox/>
   </zk>
</window>

は下と同じ働きをします。

<window>
   <textbox/>
   <textbox/>
</window>

では、何のために使うのでしょうか？

一ページ内に多数のルート要素が存在したら

XMLのシンタックス制限により、ドキュメントのルートは一つのみ指定することができます。こうして、多数のルートコンポーネントを持つと、zkをドキュメントルートとして使用しなければならず、ルートコンポーネントをグループ化します。

<?page title="Multiple Root"?>
<zk>
          <window title="First">    
          ...    
          </window>    
          <window title="Second" if="${param.secondRequired}">    
          ...    
          </window>    
</zk>

多種類のコンポーネントの繰り返し処理

コンポーネントのようなzk要素はforEach属性に対応できます。こうして、forEach属性を使って、条件によって違ったタイプのコンポーネントを生成します。以下の例では、mycolsはオブジェクトの集合であって、いくつかのメンバを持っています：isUseText() 、 isUseData() 、 isUseCombo()です。

<window>
          <zk forEach="${mycols}">    
                    <textbox if="${each.useText}"/>        
                    <datebox if="${each.useDate}"/>        
                    <combobox if="${each.useCombo}"/>        
          </zk>    
</window>

Attribute Name	Description
`if`	[Optional][Default: `true`] 処理する条件を定義します。
`unless`	[Optional][Default: `false`] 処理しない条件を定義します。
`forEach`	[Optional][Default: `ignored`] オブジェクトの集合を指定して、ZK要素が集合中のどのオブジェクトに対しても繰り返し処理するようにします。指定されていない、或は、空である場合、属性は無視されます。集合で無いオブジェクトが指定された場合、単要素集合のように、一度だけ処理されます。

Attribute Name

Description

if

[Optional][Default: true]

処理する条件を定義します。

unless

[Optional][Default: false]

処理しない条件を定義します。

forEach

[Optional][Default: ignored]

オブジェクトの集合を指定して、ZK要素が集合中のどのオブジェクトに対しても繰り返し処理するようにします。指定されていない、或は、空である場合、属性は無視されます。集合で無いオブジェクトが指定された場合、単要素集合のように、一度だけ処理されます。

`zscript` 要素

<zscript [language="Java"]> Scripting codes </zscript><zscript src=" uri " [language="Java"]/>

例えば、Javaコードといったスクリプトコードを定義します、そうしてページが処理されるときインタープリットされます。スクリプトコードの言語はデフォルトでJavaです(下を見てください) 。language属性を使用することで異なった言語を選ぶことができます。

zscript要素は上に示したように二つのフォーマットがあります。初めのフォーマットはページ中に直接スクリプトコードを埋め込みます。二つ目のフォーマットはスクリプトコードを含んでいる外部のファイルを参照します。

Attribute Name	Description
`src`	[Optional][Default: `none`] スクリプトコードを含んでいるファイルのURIを指定します。指定されている場合、直接埋め込まれているように、スクリプトコードは読み込まれます。 `src`属性はブラウザとローカル依存URIをサポートしています。つまり、`～`と`*`を異なったコンテクストパス、ブラウザ、ローカル依存情報に割り当てます。より詳しくは国際化の章を参照してくださいメモ：ファイルには直接インタープリットできる選択言語のソースコードが必要です。エンコードはUTF-8でなければなりません。クラスファイルを指定しないように注意しましょう。(Aka.bytecodes)
`language`	[Optional][Default: `Java` or as specified in the `page` directive][Allowed Values: `Java` \| `JavaScript` \| `Ruby` \| `Groovy`] 書かれているスクリプトコードの言語を指定します。
`deferred`	[Optional][Default: `false`] 初めの延期されてない言語の`zscript`コードの処理が必要になるまで、この要素の処理を延期するかどうかをきめられません。以下のHow to Defer the Evalucation セクションを参照してください。
`if`	[Optional][Default: `true`] 処理する条件を定義します。
`unless`	[Optional][Default: `false`] 処理しない条件を定義します。

処理を遅らせる方法

ZKは初めのzscriptコードを処理する前、インタプリタを読み込みます。例えば、以下の例の中で、ユーザーがボタンをクリックするとき、Javaインタプリタは読み込まれます。

<button onClick="alert(&quot;Hi&quot;)"/>

一方で、zscript要素はページを読み込むときに処理される必要があるので、以下のZUMLページを読み込むとき、インタプリタは読み込まれます。

<window>
   <zscript>
   void add() {
   }
   </zscript>
   <button onClick="add()"/>
</window>

インタプリタの読み込みを遅らせる場合は、deferredオプションにtrueを指定します。そうすると、ユーザーがボタンをクリックするまでは、インタプリタは読み込まれません。

<window>
   <zscript deferred="true">
   void add() {
   }
   </zscript>
   <button onClick="add()"/>
</window>

【ヒント】： unlessとsrcと if属性中で指定されたEL表記の処理は遅らせます。

【ヒント】：インタプリタが読み込まれるまでに、コンポーネントがページからはずれたらzscriptコードは無視されます。例えば、前の例でウィンドウがページに属していないと判断された場合、延期されたzscriptはインタープリットされません。

異なったスクリプト言語を選択する方法

一つのページで複数のスクリプト言語を使うことができます。

<button onClick="javascript:do_something_in_js()"/>
<zscript language="groovy">
do_something_in_Groovy();
</zscript>

スクリプト言語が指定されていない場合、Javaが想定されます。デフォルトのスクリプト言語を変更したい場合、page属性を以下のように使用します。

<?page zscript-language="Groovy"?>

<zscript>
def name = "Hello World!";
</zscript>

他のスクリプト言語を使用

ZKはJava, JavaScript,Ruby,Groovyをサポートしていますが、簡単に拡張することができます:

org.zkoss.zk.script は org.zkoss.zk.scriping.Interpreterインターフェースを実装するクラスを供給します。ネーム空間を操作する場合、直接実装する代わりに、org.zkoss.zk.scripting.util.GenericInterpreterクラスから得ることができます。また、インタプリタがBSF(Bean Scipring Framwork)をサポートしている場合、org.zkoss.scripting.bsh.BSFInterpreterクラスから得ることができます。
WEB-INF/zk.xml又はzk/config.xml中でスクリプト言語を宣言します。

<zscript-config>
   <zscript-language>
      <language-name>SuperJava</language-name><!-- case insensitive --!>
      <interpreter-class>my.MySuperJavaInterpreter</interpreter-class>
   </zscript-language>
</zscript-config>

WEB-INF/zk.xmlについての詳細は開発用リファレンスを参照ください。また、zk/config.xmlについてはComponent Development Guideを参照してください。

`attribute` 要素

要素を閉じるために使われるXML属性を定義します。要素の中身は属性の値です。name属性は属性名を指定します。属性の値が複雑、又は属性に条件が付いている場合に使うと便利です。

Attribute Name	Description
`name`	[Required] 属性名を指定します。
`trim`	[Optional][Default: `false`] 値の前後にあるホワイトスペースを省略するかを指定します。
`if`	[Optional][Default: `none`] 処理する条件を指定します。
`unless`	[Optional][Default: `none`] 処理しない条件を指定します。

`variables` 要素

変数のセットを定義します。variables要素が親ページと親コンポーネントを持っていて、ページレベルで宣言されている場合、variables要素は親コンポーネントを持っていれば、 Component のsetVariableメソッドと同じ働きをします。

以下に書かれているように、variablesはプログラムなしで変数を指定するのに便利です。

<window>
   <variables rich="simple" simple="intuitive"/>
</window>

上記は下記と同じ働きをします。

<window>
   <zscript>
      self.setVariable("rich", "simple", false);
      self.setVariable("simple", "intuitive", false);
   </zscript>
</window>

もちろん、値にEL表記を指定することができます。

<window>
   <window id="w" title="Test">
      <variables title="${w.title}"/>
      1: ${title}
   </window>
   2: ${title}
</window>

コンポーネントのsetVariableのように、以下のように現IDスペースにローカル変数を宣言するかどうか決めることができます。指定されていない場合、local=”false”が想定されます。

<variables simple="rich" local="true"/>

`null` 値

以下の例ではvarは空の文字列です。

<variables var=""/>

nullを変数に指定するのに、以下のステートメントを使用します。

<variables var="${null}"/>

`custom-attributes` 要素

カスタム属性のセットを定義します。custom属性は特定の領域と関係するオブジェクトです。使用できる領域はコンポーネント、スペース、ページ、デスクトップ、セッション、アプリケーションです。

以下に示したように、custom-attributesはプログラムなしでcustom属性を指定するのに便利です。

<window>
   <custom-attributes main.rich="simple" very-simple="intuitive"/>
</window>

上記は以下と同じ働きをします。

<window>
   <zscript>
      self.setAttribute("main.rich", "simple");
      self.setAttribute("very-simple", "intuitive");
   </zscript>
</window>

さらに、custom属性を割り当てる領域を指定します。

<window id="main" title="Welcome">
   <custom-attributes scope="desktop" shared="${main.title}"/>
</window>

上記は下記と同様の働きをします。

<window id="main">
   <zscript>
      desktop.setAttribute("shared", main.title);
   </zscript>
</window>

ここで注意してほしいのは、EL表記はコンポーネントが作成されているときに処理されます。例えば、以下の例で${componentScope.simple}がnullと処理されます。どうしてでしょうか？それは<label value="${componentScope.simple}"/>のショートカットです。つまり、ELが処理されるとき、コンポーネントselfはウィンドウというより、ラベルです。

<window>
   <custom-attributes simple="intuitive"/>
   ${componentScope.simple}
</window>

上記は下記と同様の働きをします。

<window>
   <custom-attributes simple="intuitive"/>
   <label value="${componentScope.simple}"/><!-- self is label not window -->
</window>

【ヒント】： attributeとcustom-attributesを混同しないよう注意してください。その二つに関係ありません。Attribute要素は閉じるためのXML属性を定義する一つの方法です。一方、custom-attributes要素はcustom属性を特定の領域に割り当てます。

Attribute Name	Description
`scope`	[Optional][Default: `com` `ponent`] カスタム属性を関連付ける領域を指定する。
`if`	[Optional][Default: `none`] 処理する条件を定義します。
`unless`	[Optional][Default: `none`] 処理しない条件を定義します。

Attribute Name

Description

scope

[Optional][Default: com ponent]

カスタム属性を関連付ける領域を指定する。