カスタム・コンポーネント

composite プロパティ

プログラムを使用して複合コンポーネントを扱う場合、複合コンポーネント内の各コンポーネントには、それが属する複合オブジェクトを参照する composite というプロパティがあります。これにより、複合クラスのメソッドを参照する複合コンポーネントのアクションの定義が簡単になります。これは、上記の例にある最初の <button> 要素を見るとわかります。

<button caption="OK"
        onclick="zenThis.composite.okBtn();"/>

この <button> 定義の onclick 属性値では、zenThis.composite を使用して、それが属する複合オブジェクトを表します。この規約を使用すると、<button> から、複合クラス内で定義された okBtn メソッドを呼び出すことができます。

複合コンポーネントとペイン

ペインについて調べ、そのコンテンツがどのように定義されているか確認するには、>Zen の使用法> の “Zen のレイアウト” の章の “ペイン” を参照してください。

<pane> コンポーネントを複合要素に配置すると、このペインのコンテンツをその複合クラス (または、複合クラスのサブクラス) で定義できます。実行時に、複合クラスはまず、指定された名前を持つペインを現在のページで検索し、そこに目的のペインが存在しない場合は複合クラスで検索します。

カスタム・コンポーネント・クラスのパッケージ

すべてのカスタム・コンポーネント・クラスに対して、1 つのクラス・パッケージを使用することをお勧めします。これらの規約が掲げられているのには、次のような理由があります。

• Zen フレームワークでは、カスタム・コンポーネント用の JavaScript および CSS スタイルシートのインクルード・ファイルが自動的に生成されます。これらのファイルは、クラス・パッケージごとに生成されるので、カスタム・コンポーネントを専用のパッケージに収めておけば、その編成がたいへん容易になります。

• Zen ページがカスタム・コンポーネントを参照している場合や、カスタム・コンポーネントが含まれた複合コンポーネントを参照している場合は、コンパイル順序の問題が発生する可能性があります。コンパイル順序の問題を防止するためのいくつかの方法については、後出のセクション “カスタム・コンポーネント・クラスのコンパイル順序” で説明します。1 つの手法は、すべてのカスタム・コンポーネントを 1 つのパッケージに配置して、Zen ページ・クラスが含まれたどのパッケージよりも前に、そのパッケージをビルド・プロシージャによってコンパイルすることです。

Zen ページの XData ブロック内のカスタム・コンポーネントを参照するときは、パッケージ名を使用しないでください。その場合は、次のセクション “カスタム・コンポーネント・クラスの XML ネームスペース” の例で示すように、クラス名のみを使用してください。

カスタム・コンポーネント・クラスの XML ネームスペース

カスタム・コンポーネントには、他のコンポーネントとの名前の競合を防ぐために専用の XML ネームスペースが必要です。このネームスペースは次のように定義して参照します。

• 作成する各カスタム・コンポーネント・クラスで NAMESPACE パラメータを指定します。以下に例を示します。

  • カスタム・コンポーネント・クラス名は次のとおりです。

    myCustom

  • ネームスペースは次のとおりです。

    http://www.mycompany.com/mycomponents

  
  Class MyPackage.myCustom Extends %ZEN.Component.textarea
  {
  
  /// This is the XML namespace for this component.
  Parameter NAMESPACE = "http://www.mycompany.com/mycomponents";
  
  /// This Style block contains component-specific CSS style definitions.
  XData Style
  {
  }
  
  /* Here is the rest of the class... */
  }

  

• カスタム・コンポーネントを参照する各 XData ブロックの先頭で、このネームスペースの接頭辞を定義します。そのうえで、カスタム・コンポーネントを参照する際に、この接頭辞を使用します。以下に例を示します。

  • カスタム・コンポーネント・クラス名は次のとおりです。

    myCustom

  • ネームスペースは次のとおりです。

    http://www.mycompany.com/mycomponents

  • 接頭辞は次のとおりです。

    myco

  XData demoPane [ XMLNamespace = "http://www.intersystems.com/zen" ]
  {
  <pane xmlns="http://www.intersystems.com/zen" 
        xmlns:myco="http://www.mycompany.com/mycomponents" 
        valign="top" >
    <myco:myCustom id="DemoText" name="DemoText" 
                   label="Operator Instructions:" 
                   cols="32" rows="8" 
                   title="Type comments and drag text into the editing area" 
                   hint="Describe how to use the product at this step." 
                   enclosingClass="myValid" />
    <hgroup align="center">
      <button caption="Clear" onclick="zenPage.clearAllValues()" />
      <button caption="Revert" onclick="zenPage.revertToSaved()" />
      <submit caption="Save" />
    </hgroup>
  </pane>
  }

  

1 つの XML ネームスペースを定義してそれをすべてのカスタム・コンポーネント用に使用し、その XML ネームスペースはカスタム・コンポーネント専用にすることをお勧めします。

カスタム・コンポーネント・クラスのコンパイル順序

Zen ページが複合コンポーネントまたはカスタム・コンポーネントを参照している場合は、コンパイル順序の問題が発生する可能性があります。コンパイル順序の問題の症状は、コードをリコンパイルするだけで修正できるコンパイル時エラー・メッセージが表示されることです。このような場合は、エラー・メッセージを防止してアプリケーションを正しくコンパイルするには、ビルド・プロシージャは、次のようにまず最下位レベルのクラスをコンパイルして、上に向かって順番にクラスをコンパイルする必要があります。

1. カスタム・コンポーネント。これらは、コンパイル順序における最下位レベルのクラスであるため、最初にコンパイルします。

2. 複合コンポーネント。これらは、カスタム・コンポーネントを参照している可能性があるため、すべてのカスタム・コンポーネントの後にコンパイルします。

3. ページ。これらは、複合コンポーネントやカスタム・コンポーネントを参照している可能性があるため、これらのコンポーネントを先にコンパイルしてから、最後にページをコンパイルします。

次のようないくつかの方法で、Zen アプリケーションでのコンパイル順序の問題を防止できます。

• すべてのクラスが同じパッケージ内に存続できるようにする一方で、下位レベルのクラスを参照する必要のある上位レベルのクラスで DependsOn キーワードを指定します。これは、クラス数が少なく、他のクラスへの参照があまり階層化されていない場合には、ごく簡単に実行できます。下位レベルのクラスを参照する各上位レベル・クラスの定義の先頭に、DependsOn 文を記述するだけです。DependsOn の値には、参照先の下位レベル・クラスのパッケージとクラスの名前を指定する必要があります。次に例を示します。

  
  Class MyPackage.MyZenPage Extends %ZEN.Component.page 
                            [ DependsOn = MyPackage.myCustom ]
  {
  /* Here is the rest of the class... */
  }

  

• 大規模なアプリケーションの場合は、すべてのカスタム・コンポーネント・クラスを 1 つのパッケージに配置し、すべての複合コンポーネントを 2 つ目のパッケージに配置して、すべての Zen ページ・クラスを 3 つ目のパッケージに配置することをお勧めします。ビルド・プロシージャでは、各パッケージを個別にコンパイルするために別々のコマンドを呼び出して、これら 3 つのパッケージを最下位レベルから最上位レベルに向かって適切な順序でコンパイルする必要があります。

• すべてのクラスを別々のコンパイル・グループに割り当てる場合は、大規模なアプリケーションでこれらのクラスを同じパッケージ内に保持できるようにすることも可能です。このためには、次のように下位レベル・クラスに System キーワードを追加して、これらのクラスを複数のコンパイル・グループに分類します。

  1. カスタム・コンポーネント・クラスを [System=3] に設定して、これらが最初にコンパイルされるようにします。

  2. 複合コンポーネントを [System=4] に設定して、これらがその次にコンパイルされるようにします。

  3. 残りのアプリケーション・クラスについては、System のキーワードや値を指定せずに、これらが最後にコンパイルされるようにします。

  System キーワードは、スタジオで設定できます。このプロパティの値を 3 か 4 に設定すると、希望の結果が得られます。既定値の 0 を使用すると、クラスに System 値を設定しない場合と同じ結果になります。

  Caution:

  System キーワードの値を 1 や 2 に設定しないことを強くお勧めします。5 以上の値はサポートされていないため、スタジオ・インスペクタではこれらの値を選択できません。

Zen コンポーネント・ウィザード

新しい Zen コンポーネント・クラスを作成するには、スタジオの新規 Zen コンポーネント・ウィザードを使用します。このウィザードを起動するには、スタジオの [ファイル]→[新規作成] コマンドを選択し、[Zen] タブをクリックし、[新規 Zen コンポーネント] アイコンをクリックします。

コンポーネントのベース・クラス

コンポーネントを新規作成するときは、そのベース・クラスを選択する必要があります。選択肢は 5 つあります。以下の図とテーブルは、その選択肢の概要を示しています。

コンポーネントのクラス・パラメータ

カスタム・コンポーネントに選択したベース・クラスに応じて、さまざまなクラス・パラメータを使用できます。各コンポーネントのベース・クラスによって、そのコンポーネントのクラス・パラメータが、コンポーネントの種類で最も役に立つ値に設定されます。必要に応じて、これらの値を再設定できます。次のテーブルは、重要と考えられるクラス・パラメータを示しています。

これ以外のクラス・パラメータは、使用しているベース・クラスのクラス・リファレンス・ドキュメントで調べることができます。その手順は次のとおりです。InterSystems のオンライン・ドキュメントを開きます。 ドキュメントのホーム・ページの上部にあるメニュー・バーで [クラスリファレンス] を選択します。%SYS ネームスペースおよび %ZEN.Component または %ZEN.SVGComponent のいずれかのパッケージを選択します。クラス名をクリックします。

XData SVGStyle

Style は、Zen SVG コンポーネントには適用されません。Zen SVG コンポーネントでは、XData SVGStyle を使用します。

カスタム Zen SVG コンポーネント・クラスのスタイルを定義するには、XData SVGStyle ブロックを指定し、<style type="text/css"> タグと、終了タグの </style> との間に CSS 文を追加します。以下はその例です。

XData SVGStyle
{
<style type="text/css">
.customSVGComponent {
  fill: url(#myGrad);
  stroke: black;
  stroke-width: 2px;
}
</style>
}

XData SVGDef

前述の例の XData SVGStyle は、SAMPLES ネームスペースのクラス ZENTest.customSVGComponentOpens in a new tab に基づいています。これは、色の myGrad を customSVGComponent シェイプの塗りつぶし色として参照します。

myGrad は同じクラスの、XData SVGDef という別のブロックで定義します。このブロックは、myGrad を青から赤へ変化する階調として定義しています。

XData SVGDef
{
<defs>
<linearGradient id="myGrad" x1="0%" y1="0%" x2="0%" y2="100%">
<stop offset="0%" style="stop-color:darkblue" />
<stop offset="30%" style="stop-color:#FF00FF" />
<stop offset="70%" style="stop-color:#FF00FF" />
<stop offset="100%" style="stop-color:darkred" />
</linearGradient>
</defs>
}

Zen のカラー定義

組み込みクラス %ZEN.SVGComponent.svgPageOpens in a new tab は、便利なカラー定義をいくつか XData SVGDef ブロックに提供します。

• グローシルバー色は、<speedometer> メータなどの計測アイテムにメタリックな外観を与えます。

• 信号機などのメータでは、インジケータ・ランプにグローレッド、グローイエロー、グローグリーンを使用します。

• ランプ色のグローブルー、グローパープル、グローオレンジ、グローティールも使用できます。

<svgFrame> は、svgPage 属性により、このクラスまたはこのクラスのサブクラスを必ず参照するので、これらのカラーはすべての SVG コンポーネントでいつでも使用できます。

名前付け規約

Zen のクラスのプロパティには、大文字と小文字を区別する名前付け規約があります。詳細は、"Zen の使用法" の “Zen チュートリアル” の章にある “Zen の名前付け規約” を参照してください。これらの規約の概要をまとめると以下のようになります。

• クライアントのみのプロパティ ： myProperty

• サーバのみのプロパティ (% が必須) ： %MyProperty

• Javascript でイベント・ハンドラを呼び出すプロパティ ： onmousedown

• サーバ側コールバック・メソッドを特定するプロパティ ： OnCreateDataSet

• その他のプロパティ ： myProperty

XML プロジェクション

すべての Zen コンポーネントは %XML.AdaptorOpens in a new tab クラスから派生し、XML の動作の定義にこのクラスのメカニズムを使用します。この詳細は "オブジェクトの XML への投影" を参照してください。特に、このトピックで説明した XMLPROJECTION パラメータについては、“単純なプロパティのプロジェクションが持つ形式の制御” を参照してください。ここには、XMLPROJECTION の各値 ("attribute"、"element"、"wrapped"、"none" など) の影響を説明しているテーブルがあります。

Zen コンポーネントの単純なプロパティにはすべて、XMLPROJECTION 値 "attribute" が設定されています。プロパティを XML で表示しない場合は、以下の例のように、その XMLPROJECTION パラメータを "none" に設定します。

Property beeswax As %ZEN.Datatype.string(XMLPROJECTION="none");

%ZEN.Datatype パッケージのデータ型は、XMLPROJECTION の既定値 "attribute" を使用して、XML 属性として投影されるようにしています。Zen データ型を使用すると、カスタム・コンポーネント・クラスでプロパティを定義する際に便利な点が多数あります。詳細は、“データ型クラス” を参照してください。

setProperty メソッド

カスタム・コンポーネント・クラスにプロパティを追加する場合は、サブクラスの setProperty メソッドをオーバーライドして、カスタム・コンポーネント・クラスに追加した各プロパティのケース処理を実装する必要があります。スーパークラスのプロパティには、スーパークラス・メソッドを既定にすることができます。この章には、この操作の実際例があります。“%DrawHTML のヘルパー・メソッド” にあるコンポーネント・クラスのサンプルを参照してください。

データ型のパラメータ

すべての Zen クラスは、%ZEN.componentParametersOpens in a new tab から以下のプロパティ・パラメータのセットを継承します。このプロパティ・パラメータは、Zen クラスに追加するすべてのプロパティに適用できます。プロパティで以下のパラメータを使用するために、プロパティを Zen データ型とする必要はありません。

• ZENCLIENTONLY

• ZENENCRYPT

• ZENEXPRESSION

• ZENLOCALIZE

• ZENSETTING

データ型クラス

Zen には、Zen クラスでプロパティを定義するときに使用可能なデータ型クラスのセットが用意されています。このデータ型クラスは %ZEN.Datatype パッケージにあります。以下のテーブルはその一覧です。

新しい Zen クラスを定義するときには、どのデータ型クラスでも自由に使用できます。%ZEN.Datatype クラスを使用すると、Web アプリケーションのコンテキストで、そのプロパティをどのような目的で使用しているかがわかりやすくなります。また、多くの場合、データ型クラスを使用することにより、従来はユーザ側でのエンコード処理が必要だった機能が自動的に使用できるようになります。これにより、容易なローカライズ、イベント・ハンドラの規約、言語に依存しないブーリアン値とリスト配列などが実現します。

基本的に、すべての Zen データ型クラスは文字列です。以下のテーブルに挙げられているデータ型はすべて、同じベース・クラス %ZEN.Datatype.datatypeOpens in a new tab を共有しています。このベース・クラスの値は、%Library.StringOpens in a new tab 型として定義されています。テーブルのエントリからわかるように、これらの文字列はそれぞれ、有効な独自の方法でサブクラスにより解釈されます。

%DrawHTML のヘルパー・メソッド

Zen フレームワークでは、カスタム・コンポーネントの %DrawHTML メソッドで使用する 3 つのサーバ側ヘルパー・メソッド、%MakeId、%Attr、および %GetEventHandlers を定義しています。<button> のクラス・コードは、これらのメソッドを %DrawHTML で効果的に使用する 1 つの方法を次のように示しています。

Class %ZEN.Component.button Extends control
{

Parameter DEFAULTCONTROLCLASS = "button";

/// Caption displayed for this button.<br>
/// This is a localized value.
Property caption As %ZEN.Datatype.caption;

/// defines style sheet used by this component
XData Style
{
<style type="text/css">
/* @doc="Style for button (input)." */
.button {
}
</style>
}

Method %DrawHTML()
{
  Set disabled = $S(..disabled:"disabled",1:"")
  Set tIgnore("onchange") = ""
  &html<
  <input type="button" class="#(..controlClass)#"
  id="#(..%MakeId("control"))#" #(..%Attr("title",..title))#
  #(..%Attr("name",..name))# #(..%Attr("value",..caption))# #(disabled)#
  #(..%Attr("style",..controlStyle))# #(..%GetEventHandlers(.tIgnore))#>
  >
}

/// This method fills in reasonable default values for
/// this control. Used by tools (such as Control Tester) to
/// dynamically create controls.
Method %SetDefaultValues()
{
  Set ..caption = "Button"
}

/// Set the value of a named property.
ClientMethod setProperty(property, value, value2) [ Language = javascript ]
{
  switch(property) {
  case 'caption':
    this.caption = value;
    var el = this.findElement('control');
    if (el) {
      el.value = this.caption;
    }
    break;
  case 'value':
    // do not set control value; just internal value
    this.value = value;
    break;
  default:
    // dispatch
    return this.invokeSuper('setProperty',arguments);
  }
  return true;
}
}

以下のトピックでは、各 %DrawHTML ヘルパー・メソッドの使用方法について説明します。

• %MakeId — ページにコンポーネントを表示する HTML 要素の ID 値を生成します。クライアント側メソッド findElement でページの HTML 要素を検出できるように、一貫した名前付け方式を使用します。

• %Attr — ページにコンポーネントを表示する HTML 要素の属性に値を割り当てます。このメソッドは、コンポーネントの表示に必要なすべての HTML 属性に値を割り当てるために、繰り返し呼び出すことができます。

• %GetEventHandlers — コンポーネント定義からイベント処理情報をすべて取得します。これにより、そのコンポーネントの HTML 表現で、各ユーザ・イベントと実行するコードが正しく一致するようにします。

HTML 要素の識別

%MakeId サーバ側メソッドを使用すると、出力ページの各 HTML 要素の ID が確実に一意になります。“%DrawHTML のヘルパー・メソッド” にある例では、次のように埋め込み HTML から %MakeId を呼び出し、HTML の <input> 要素の ID を設定します。

id="#(..%MakeId("control"))#"

%MakeId は、呼び出し元が指定する文字列を、アンダースコア文字 “_” を使用して、ページに配置される各コンポーネントに割り当てられた一意の連続番号と連結します。次に、この識別子を Zen に渡して、要素を囲む <div> の ID 属性の値として使用します。さらに、コンポーネントが繰り返しグループの一部である場合、Zen ではさらにアンダースコア文字 “_” の後にタプル番号を追加します。

このように、生成された Zen ページのソースを表示すると、spacer_23 のように生成された ID 値が <div> 要素に囲まれていることがわかります。以下にその例を示します。

<div class="spacer" id="spacer_23" style="width:20px;"/>

以下のより複雑な抜粋では、ラジオ・ボタンの繰り返しグループの各要素に対して、一意の HTML ID 値を Zen で指定する方法を示しています。この抜粋は、SAMPLES ネームスペースのクラス ZENDemo.FormDemoOpens in a new tab を Zen で表示する際の結果となるページの一部です。

<tr valign="top">
<td style="padding: 4px; padding-left: 5px; padding-right: 5px;" >
<span id="zenlbl_26" class="zenLabel"  >Marital Status:</span>
<div class="zendiv" id="MaritalStatus" >
<input type="hidden" id="hidden_26" name="$V_MaritalStatus" value="">
<span class="radioSetSpan"><input type="radio" id="textRadio_1_26"
      name="r26" value="S" onclick="zenPage.getComponent(26).clickItem(1);">
   <a class="radioSetCaption" id="caption_1_26" href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(1);return false;">
      Single</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_2_26"
      name="r26" value="M" onclick="zenPage.getComponent(26).clickItem(2);">
   <a class="radioSetCaption" id="caption_2_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(2);return false;">
      Married</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_3_26"
      name="r26" value="D" onclick="zenPage.getComponent(26).clickItem(3);">
   <a class="radioSetCaption" id="caption_3_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(3);return false;">
      Divorced</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_4_26"
      name="r26" value="W" onclick="zenPage.getComponent(26).clickItem(4);">
   <a class="radioSetCaption" id="caption_4_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(4);return false;">
      Widowed</a>&nbsp;</span>
<span class="radioSetSpan"><input type="radio" id="textRadio_5_26"
      name="r26" value="O" onclick="zenPage.getComponent(26).clickItem(5);">
   <a class="radioSetCaption" id="caption_5_26"  href=""
      onclick="javascript:zenPage.getComponent(26).clickItem(5);return false;">
      Other</a>&nbsp;</span>
</div>
</td>
</tr>

クライアント側で %MakeId と同等なものは、makeId という JavaScript メソッドです。カスタム・メータ・コンポーネントの例で、makeId を使用しています。

HTML 要素の検索

クライアント側コードを記述していて、ページ上の特定の HTML 要素にアクセスする必要がある場合は、findElement メソッドを使用します。このメソッドの引数は、ページにコンポーネントを配置する際に id 属性に割り当てた値です。findElement は、この文字列と、出力ページの要素の連続番号の識別子を組み合わせて、出力ページの要素に対して適切な HTML ID を生成します。この情報を使用して、表示するページのページ・オブジェクト・モデルにあるコンポーネント・オブジェクトへのポインタを取得し、そのポインタを返して、コンポーネント・オブジェクトのプロパティとメソッドを使用できるようにします。

通常の Zen コンポーネントは、%ZEN.Component.objectOpens in a new tab から findElement を継承します。SVG コンポーネントでは、%ZEN.SVGComponent.svgComponentOpens in a new tab の findSVGElement を使用する必要があります。カスタム・メータ・コンポーネントの例で、findSVGElement を使用しています。

findElement と findSVGElement は、%MakeId (サーバ) または makeId (クライアント) を使用して HTML ID 値を割り当てた場合にのみ、正常に動作します。

HTML 属性値の設定

%Attr サーバ側メソッドは、ページにコンポーネントを表示する HTML 要素の属性に値を割り当てます。このメソッドは、コンポーネントの表示に必要なすべての HTML 属性に値を割り当てるために、繰り返し呼び出すことができます。以下の %DrawHTML メソッドのサンプルでは、%Attr を <button> コンポーネントの表示に使用しています。

Method %DrawHTML()
{
  Set disabled = $S(..disabled:"disabled",1:"")
  Set tIgnore("onchange") = ""
  &html<<input type="button" class="#(..controlClass)#"
               id="#(..%MakeId("control"))#" #(..%Attr("title",..title))#
                   #(..%Attr("name",..name))# #(..%Attr("value",..caption))#
                   #(disabled)# #(..%Attr("style",..controlStyle))#
                   #(..%GetEventHandlers(.tIgnore))#>>
}

<button> の controlStyle 属性の値が、現在は myActionStyle であるとします。%DrawHTML メソッドは HTML を出力するので、式は以下の形式になります。

#(..%Attr("style",..controlStyle))#

以下の出力を生成します。

style="myActionStyle"

HTML 要素へのイベント・ハンドラのアタッチ

%GetEventHandlers サーバ側メソッドは、指定されたコンポーネントのイベント・ハンドラ属性をすべて取得し、それを使用して、出力ページにそのコンポーネントを表示する HTML にイベント・ハンドラ属性をすべて書き出します。

Zen フォームのコントロール・コンポーネントに指定できるイベント・ハンドラ属性のリストは、"Zen コンポーネントの使用法" の “Zen コントロール” の章の “コントロールの属性” を参照してください。このリストに挙げられているイベントのタイプには、マウス移動、マウス・クリック、キー・クリックなどがあります。その他のタイプの Zen コンポーネントにはイベント・ハンドラがありますが、Zen コントロールでは、比較用に大規模なプールを 1 つ用意しています。

前述の章では、組み込み Zen コンポーネントのイベント・ハンドラを設定するために、対応するイベント・ハンドラ属性の値として JavaScript 式を指定する必要があることを説明しました。一般的に、この JavaScript 式は、このイベントの “ハンドラ” の役割をするクライアント側メソッドを呼び出します。もちろん、この方法でコンポーネントを設定する場合は、呼び出されるクライアント側メソッドも記述する必要があります。

カスタム・コンポーネントでは、各ユーザ・イベントと適切なハンドラを組み合わせる手順を追加する必要があります。この組み合わせは、カスタム・コンポーネントの %DrawHTML メソッドで行います。<image> コンポーネントの %DrawHTML メソッドを考えてみます。

Method %DrawHTML()
{
  #; handle onclick directly
  Set tIgnore("onclick")=""
  Set tIgnore("onchange")=""

  #; select image to display
  Set tSrc = ..src
  If (..streamId '= "") {
    Set tSrc = ##class(%CSP.Page).Link(
    "%25CSP.StreamServer.cls?STREAMOID="_$ZCVT(..streamId,"O","URL"))
  }

  #; disabled logic
  Set tSrc = $Case(..disabled,0:tSrc,:$S(..srcDisabled="":tSrc,1:..srcDisabled))

  &html<<img id="#(..%MakeId("control"))#"
             #($S(..onclick="":"",1:"class=""imageLink"""))#
             #(..%Attr("src",tSrc))#
             #(..%Attr("title",..title))#
             #(..%Attr("width",..width))#
             #(..%Attr("height",..height))#
             #(..%GetEventHandlers(.tIgnore))#
             onclick="zenPage.getComponent(#(..index)#).imageClick();"/>>
}

上記の例では、イベント・ハンドラに関していくつか興味深いことが発生しています。以下の行では、onchange イベント・ハンドラに指定された値を検出しても、それらをすべて無視することを %GetEventHandlers に指示しています。

Set tIgnore("onchange") = ""

上記の例の onclick と onchange で示したように、%DrawHTML で直接処理するイベント・ハンドラのそれぞれに対して、このような行を 1 行指定する必要があります。そのうえで、例に示すように、%DrawHTML の最後で、参照によって変数 tIgnore を %GetEventHandlers に渡します。

#(..%GetEventHandlers(.tIgnore))#

上記の %DrawHTML の例では、onclick と onchange を無視するように %GetEventHandlers に要求していますが、その理由はそれぞれのケースで異なります。<image> は、ユーザ入力を受け付けないため、onchange を無視します。<image> は、すべての onclick イベントを同じ方法で処理するように設計されていて、Zen のプログラマはページ・クラスで異なる動作を指定できないため、onclick を無視します。したがって、%DrawHTML のコードでこのイベントを直接処理します。このように %DrawHTML で明白に無視されないイベント・ハンドラはすべて、Zen のプログラマが定義したとおり正確に、ページに書き出されます。

上記の例にある以下の式について考えてみます。

#($S(..onclick="":"",1:"class=""imageLink"""))#

この式では、ObjectScript の $SELECT 関数を使用して、リストにある式の中で True を返す最初の式を返します。提示された式を見てみます。<image> コンポーネントの onclick 属性値が空白の文字列の場合、この文は空白の文字列を記述します。それ以外の場合、この文は、以下の文字列を書き出すことで、出力ページの HTML 要素をフォーマットします。

class="imageLink"

以下の式では、クライアント側 HTML ページを送信して、対応する HTML 要素の上をユーザがマウスでクリックすると、それに反応してコンポーネントの imageClick メソッドを呼び出します。

onclick="zenPage.getComponent(#(..index)#).imageClick();"

imageClick メソッドは、<image> コンポーネント・クラスのクライアント側 JavaScript メソッドです。このメソッドは、JavaScript ヘルパー・メソッド zenInvokeCallbackMethod を使用して、この <image> コンポーネントの onclick コールバック・メソッドを呼び出します。imageClick メソッドは以下のようになります。

ClientMethod imageClick() [ Language = javascript ]
{
  if (!this.disabled) {
    // invoke callback, if present
    zenInvokeCallbackMethod(this.onclick,this,'onclick');
  }
}

ここで、zenInvokeCallbackMethod 引数は以下のとおりです。

• this.onclick — コンポーネントの onclick 属性値 (クライアント側 JavaScript メソッドを呼び出す JavaScript 式)。

• this — コンポーネント・オブジェクトへのポインタ。

• 'onclick' — イベントの HTML 名 (引用符が必要)。

これで、HTML 要素、イベント、およびそのハンドラ間の接続が完了します。カスタム・コンポーネントでサポートしようとするすべてのイベントに対して、同様の規約を指定する必要があります。

動的なコンポーネントの HTML

%DrawHTML は、実行時情報に応じて変化したり、SVG を使用して生成されたりするコンポーネントでは動作が異なります。

<calendar> は、静的な HTML を記述しないコンポーネントの例です。%DrawHTML メソッドは、ページでカレンダーの再描画が必要となるたびに呼び出される複雑な JavaScript メソッド renderContents に備えて、現在選択されている月や日などのプロパティ値の設定のみを実行します。renderContents とそのヘルパー・メソッドは、ユーザがカレンダーで現在選択している月と日に基づいて、動的な HTML 文の配列を生成します。詳細は、%ZEN.Component.calendarOpens in a new tab のクラス・コードについて調べてください。

%OnDrawEnclosingDiv

コンポーネントのサブクラスで定義されている場合、このコールバック・メソッドは、サブクラスが実行時にコンポーネントのエンクロージング <div> 要素に追加の HTML 属性を挿入できるようにします。%OnDrawEnclosingDiv は、入力引数は受け取りません。実装すると、メソッドが %StringOpens in a new tab 値を返します。既に <div> 要素を変更している可能性がある他の属性との競合を防ぐために、文字列の先頭にスペースを付ける必要があります。

%OnDrawTitleOptions

.expando クラスは、サーバ側コールバック・メソッド %OnDrawTitleOptions を提供します。これは .expando のサブクラスで定義されると、<expando> の framed 属性が True に設定されている場合、タイトル・バーの右側にコンテンツを追加する方法を提供します。%OnDrawTitleOptions で記述された HTMLは、<expando> が表示されるときにそのタイトル・バーに挿入されます。詳細は、"Zen コンポーネントの使用法" の “ナビゲーション・コンポーネント” の章にある “<expando>” を参照してください。

データのドラッグ・アンド・ドロップ・メソッド

"Zen の使用法" の “Zen コンポーネントの概念” の章にある “ドラッグ・アンド・ドロップ” の説明に従って、ページにコンポーネントを配置するたびに、コンポーネント属性 onafterdrag、onbeforedrag、ondrag、および ondrop の値を指定できます。ただし、Zen アプリケーションの開発者がコンポーネントごとにデータのドラッグ・アンド・ドロップ属性を設定する必要はなく、ユーザがカスタム・コントロール・コンポーネントに必要な動作を組み込むことができます。この方法によって、ページにコンポーネントを配置する際に、開発者は必要な動作が組み込まれたカスタム・コントロールを選択できます。

カスタム・コントロール・クラスのデータのドラッグ・アンド・ドロップをカスタマイズする場合は、オーバーライド可能なベース・クラス %ZEN.Component.componentOpens in a new tab および %ZEN.Component.controlOpens in a new tab に一連のメソッドがあります。これらのメソッドはそれぞれ 1 つのパラメータ dragData を受け取ります。これは、メソッドとプロパティが Zen クライアント側のライブラリで定義されている JavaScript オブジェクトへのポインタです。また、これらのメソッドは、ZLM.setDragAvatar などのライブラリ内で定義されている関数も呼び出します。これらの項目の詳細は、このドキュメントの “クライアント側ライブラリ” の章を参照してください。

以下のテーブルは、ソースの Zen コンポーネントとターゲットの Zen コンポーネント間でドラッグ・アンド・ドロップが行われた際の内部イベントのシーケンスをトレースします。これらのイベントの間、ソース・コンポーネント・クラスとターゲット・コンポーネント・クラス内の特定の JavaScript メソッド は、Zen クライアント側ライブラリ内の特定の JavaScript 関数を呼び出します。コンポーネント・メソッドは、Zen フレームワークによって自動的にトリガされます。カスタム・コントロール・クラスのデータのドラッグ・アンド・ドロップをカスタマイズするときに、これらのメソッドが自動的に呼び出された際のメソッド内での動作の詳細を変更できます。

オーバーライドするために設計されているベース・クラス %ZEN.Component.componentOpens in a new tab および %ZEN.Component.controlOpens in a new tab には、いくつかメソッドがあります。以下の数セクションで、これらのメソッドを示します。前のテーブルの他のメソッドは Zen フレームワークの一部であるため、これらはカスタマイズしないことをお勧めします。オーバーライドするために設計されたメソッドは、以下のとおりです。

• getDragData

• dragStartHandler

• dragFinishHandler

• dropStartHandler

getDragData

getDragData は、ユーザが任意のコントロールまたは <image> コンポーネントでドラッグ操作を開始するたびに自動的に呼び出される JavaScript メソッドです。他のコンポーネントは getDragData メソッドをサポートしていません。コントロール・コンポーネントのベース・クラス %ZEN.Component.controlOpens in a new tab は、以下の例のような getDragData ベース・バージョンを実装しています。その目的は、dataDrag オブジェクトの text フィールドおよび value フィールドを設定するためです。

ClientMethod getDragData(dragData) [ Language = javascript ]
{
  dragData.value = this.getValue();
  if (null != this.text) {
    // if there is a text property, use it as the text value
    dragData.text = this.text;
  }
  else {
    dragData.text = dragData.value;
  }
  return true;
}

%ZEN.Component.controlOpens in a new tab のサブクラスは、getDragData をオーバライドしてカスタマイズされた動作を提供できます。メソッドが True を返す前に dataDrag.text および dataDrag.value の値が設定されていれば、メソッド内の動作は何でもかまいません。以下の例は、%ZEN.Component.imageOpens in a new tab が getDragData をオーバーライドする方法を示しています。このメソッドによって、ドラッグ可能な論理値と表示値の両方として <image> text 属性の文字列値が割り当てられます。

ClientMethod getDragData(dragData) [ Language = javascript ]
{
  dragData.value = this.text;
  dragData.text = this.text;
  return true;
}

dragStartHandler

dragStartHandler は、コンポーネント内でドラッグ操作が開始されるたびに自動的に呼び出される JavaScript メソッドです。コントロール・コンポーネントのベース・クラス %ZEN.Component.controlOpens in a new tab は、以下の例のような dragStartHandler メソッドのベース・バージョンを実装しています。dragStartHandler メソッドは、以下を実行します。

• getDragData を呼び出して、dragData.text および dragData.value を設定します。

• ページでドラッグされる際にフィールドを表すために、アバター (icon) を作成します。

• "クライアント側ライブラリ" 関数 (ZLM.setDragAvatar) を呼び出して、このアイコンを使用します。

ClientMethod dragStartHandler(dragData) [ Language = javascript ]
{
  // get drag data
  if (!this.getDragData(dragData)) {
    return false;
  }

  // avatar
  var icon = this.getEnclosingDiv().cloneNode(true);
  icon.style.position="absolute";
  icon.style.border ="1px solid darkgray";
  icon.style.background ="#D0D0F0";
  ZLM.setDragAvatar(icon);

  return true;
}

%ZEN.Component.controlOpens in a new tab のサブクラスは、dragStartHandler をオーバライドしてカスタマイズされた動作を提供できます。例えば、クラス %ZEN.Component.abstractListBoxOpens in a new tab は、次の例に示すように、dragStartHandler をオーバーライドします。この例は、以下を実行します。

• getDragData の呼び出しはいずれも省略します。

• ドラッグを開始する特定のリスト項目へのポインタ (dragItem) を取得します。

• リスト・コントロール内のこのアイテムへの正確なポインタ (anchor) を検索します。

• dragData オブジェクトの sourceItem、value、および text の各フィールドを設定します。

• ページでドラッグされる際にフィールドを表すために、アバター (icon) を作成します。

• "クライアント側ライブラリ" 関数 (ZLM.setDragAvatar) を呼び出して、このアイコンを使用します。

ClientMethod dragStartHandler(dragData) [ Language = javascript ]
{
  var ok = false;
  var dragItem = this._dragSource;
  if (null != dragItem) {
    delete this._dragSource;
    var anchor = this.findElement('item_' + dragItem);
    if (anchor) {
      dragData.sourceItem = dragItem;
      ok = true;
      dragData.value = this.getOptionValue(dragItem);
      dragData.text = this.getOptionText(dragItem);

      // avatar
      var icon = anchor.cloneNode(true);
      icon.style.position ="absolute";
      icon.style.width = this.getEnclosingDiv().offsetWidth + 'px';
      icon.style.border = "1px solid darkgray";
      ZLM.setDragAvatar(icon);
    }
  }
  return ok;
}

dropStartHandler

dropStartHandler は、コンポーネント内でドロップ操作が開始されるたびに自動的に呼び出される JavaScript メソッドです。コントロール・コンポーネントのベース・クラス %ZEN.Component.controlOpens in a new tab は、以下の例のような dropStartHandler ベース・バージョンを実装しています。ターゲット・コントロールの値に dragData.toString() が設定されます。この値は、クラス内の別のドラッグ・アンド・ドロップ・メソッドの操作によって以前に設定されたものです。通常、この値はソース・コントロールから取得されます。

ClientMethod dropStartHandler(dragData) [ Language = javascript ]
{
  this.setValue(dragData.toString());
  return true;
}

%ZEN.Component.controlOpens in a new tab のサブクラスは、カスタマイズされた動作を提供するために dropStartHandler をオーバライドできます。例えば、クラス %ZEN.Component.listBoxOpens in a new tab は、次の例に示すように、ベース・コントロール dropStartHandler をオーバーライドします。この例は、以下を実行します。

• dragData オブジェクトから value フィールドおよび text フィールドを取得します。

• この <listBox> が他のコンポーネントからドロップを受け取っている場合は、以下のようになります。

  以下のことを実行するために、appendOption を呼び出します。

  • 論理値と表示値として value および text の各フィールドを持つ新しいリスト・オプションを作成する

  • この新しいオプションを <listBox> に追加する

  • <listBox> を再表示する

• この <listBox> がそれ自体からドロップを受け取っている場合は、以下のようになります。

  • クライアント側ライブラリ関数の ZLM.getDragInnerDestination を呼び出して、ドラッグ操作が終了した最も内側のエンクロージング <div> の識別子を取得します。

  • これを使用して、適切な dragData.targetItem 識別子を算出します。

  • 以下のことを実行するために、moveOption を呼び出します。

    • 位置 dragData.sourceItem にあるリスト・オプションを識別された位置 dragData.targetItem に移動する

    • 領域を確保するために、その他のリスト・オプションを配置する

    • <listBox> を再表示する

ClientMethod dropStartHandler(dragData) [ Language = javascript ]
{
  var value = dragData.value;
  var text = dragData.text;

  if (this != dragData.sourceComponent) {
    // drag from another component: append
    this.appendOption(value,text);
  }
  else {
    // move item within this list
    var tgtId = ZLM.getDragInnerDestination().id;
    var tgtIndex = -1;
    if (tgtId && tgtId.indexOf('item')!=-1) {
      tgtIndex = tgtId.split('_')[1];
    }
    dragData.targetItem = tgtIndex;
    var srcIndex = dragData.sourceItem;
    this.moveOption(srcIndex,tgtIndex);
  }
  return true;
}