レイアウト・メソッドの定義

レイアウト・メソッドとレイアウト・グラフの概要

このドキュメントで前述したように、レイアウト・メソッドは、テンプレート・クラス内にある、レイアウト・グラフを返すメソッドです。テンプレート・クラスの onGetContent() メソッドは、同じクラスのレイアウト・メソッドを呼び出します。onGetContent() メソッドは、次の 2 つの引数を任意のレイアウト・メソッドに渡すことができます。

• key は、レイアウト・グラフを取得する際に使用するキーを指定します。

• criteria は、レイアウト・グラフを取得する際に使用するその他の条件です。

形式的には、レイアウト・グラフは以下の要件を満たす JSON または JavaScript オブジェクトです。

• オブジェクトに children プロパティがあること。

• children プロパティがレイアウト・オブジェクトの配列であること。

  各レイアウト・オブジェクトは documentView 内の項目を表します。documentView では通常、リストに表示される順序でこれらの項目を表示します。

• 各レイアウト・オブジェクトに type プロパティがあること。このプロパティは該当のオブジェクトの全体的な外観と動作を指定します。

  このオブジェクトのその他のプロパティを指定して、ページの対応する部分の外観と動作を制御することができます。各オブジェクトには固有のプロパティがあります。詳細は、プラグイン・リファレンス・ドキュメントを参照してください ("Zen Mojo プラグインの使用法" の “プラグイン・ドキュメント” を参照してください)。

  通常は、レイアウト・オブジェクトの値、表示するキャプションやタイトル、およびスタイル情報を決定するプロパティを指定します。

  大半のレイアウト・オブジェクトでは、key という名前のプロパティがある場合は、イベントをサポートしています。また、このプロパティを使用して、メソッド内から該当のオブジェクトを参照します (“レイアウト・オブジェクトとの対話操作” を参照してください)。反対に、不要な場合には、key プロパティは指定しないでください。

• プロパティの値が、有効な JavaScript 式、現在のデータ・オブジェクトへの参照、または (特殊な場合は) レイアウト・オブジェクトによって提供される変数への参照のいずれかであること。

  Zen Mojo には、現在のデータ・オブジェクトやレイアウト・オブジェクトによって提供される変数を参照するための特別な構文が用意されています (次のセクションの “現在のデータ・オブジェクトの参照” を参照してください)。

• レイアウト・グラフで、ZEN マクロ $$$Text() をローカリゼーション用に使用できること。レイアウト・グラフ内でユーザに表示される文字列すべてにこのマクロを使用することをお勧めします。

  ページ・クラスやテンプレート・クラスの両方で DOMAIN パラメータを定義している場合にのみ、この文字列をローカライズできます。ローカリゼーションの詳細は、"Zen アプリケーションの開発" の “Zen のローカライズ” を参照してください。

• レイアウト・グラフに sourceData という名前のプロパティを含めることができること。このプロパティは特別な方法で処理されます。この章で後述する “レイアウト・グラフでの sourceData プロパティの使用” を参照してください。

以下の簡単な例では、静的なレイアウト・グラフが返されます (このグラフは、データ・オブジェクト、変数、または特殊な sourceData オブジェクトを参照しません)。この例では、HTML5 ヘルパー・プラグインで定義されているレイアウト・オブジェクトを使用しています ("Zen Mojo プラグインの使用法" の “HTML5 のヘルパー・プラグイン” を参照してください)。

ClientMethod myGetMainViewLayout(key, criteria) [ Language = javascript ]
{
    var myLayoutGraph = {};
    //The standard technique is to have a switch/case construct that creates 
    //branches based on the key argument;
    //In this case only one key value is possible, so there is no need to branch

    myLayoutGraph = {
        children: [
            { type: '$header', $content: $$$Text('Tutorial 1 - Sample Zen Mojo Page')},
            { type: '$p',      $content: $$$Text('This page displays some simple text.')},
            { type: '$p',      $content: $$$Text('Here is another paragraph.') },
        ]
        

    }
    return myLayoutGraph;
}

このメソッドは、(このメソッド内で myLayoutGraph と呼ばれる) オブジェクトを返します。このオブジェクトには、children という名前のプロパティがあります。children プロパティは、3 つのオブジェクトを含む配列です。1 つ目のオブジェクトのタイプは $header で、2 つ目と 3 つ目のオブジェクトのタイプは $p です。$$$Text() マクロを使用していることに注意してください。

現在のデータ・オブジェクトの参照

レイアウト・グラフでは、データ・オブジェクトのプロパティを参照できます (また、通常は参照しています)。データ・オブジェクトのプロパティの値 (propertyname) を参照するには、'=[propertyname]' を使用します。

プロパティのプロパティを参照するには、ドット構文を使用できます。例：'=[propertyname.subprop1]'

同様に、プロパティが配列である場合は、角括弧と配列の項目番号を使用できます。例：'=[arrayprop[3]]' または '=[arrayprop[3].subprop]'

レイアウト・グラフ内で、Zen Mojo が '=[propertyname]' 形式の値を持つレイアウト・オブジェクト・プロパティを見つけた場合は、現在のデータ・オブジェクトで指定されたプロパティ (propertyname) も探し出そうとします。このプロパティが見つかった場合は、Zen Mojo はその値をレイアウト・グラフの対応する部分に挿入します。このプロパティが見つからなかった場合は、代わりに null 値を使用します。Zen Mojo からエラーがスローされることはありません。

指定された documentView のデータ・オブジェクトに以下のプロパティがあるとします。

• name (文字列)

• dob (文字列)

• homeaddress (プロパティ street、city、および postalcode を持つオブジェクト)

• favoritecolors (文字列の配列)

以下のサンプル・レイアウト・メソッドでは、このオブジェクトのデータを表示します。この例では、HTML5 ヘルパー・プラグインのレイアウト・オブジェクトも使用しています ("Zen Mojo プラグインの使用法" の “HTML5 のヘルパー・プラグイン” を参照してください)。

ClientMethod myGetMainViewLayout(key, criteria) [ Language = javascript ]
{
    var myLayoutGraph = {};
    myLayoutGraph = {
        children: [
            { type: '$header', $content: $$$Text('Data Object Demo Template')},
            { type: '$p', title:'Name', $content:'=[name]' },
            { type: '$p', title:'Birth Date', $content:'=[dob]' },
            { type: '$p', title:'Home City', $content:'=[homeaddress.city]' },
            { type: '$p', title:'First Favorite Color', $content:'=[favoritecolors[1]]' },
            { type: '$p', title:'Number of Favorite Colors', $content:'=[favoritecolors.length]' },
        ]
    }
    return myLayoutGraph;
}

レイアウト・グラフでのテンプレート・メソッドの呼び出し

構文を使用して、レイアウト・オブジェクト内のメソッドを呼び出すことができます。

myLayoutProperty: '=[$method.methodname]'

ここで、methodname はテンプレート・クラスに定義されているコールバック・メソッドに渡される文字列です。コールバックが呼び出されると、methodname に定義されている操作が実行され、適切な値が返されます。

以下の一般的な手順で、コールバックを実装します。

• コールバック属性 onresolvemethod を指定する

  ページ・クラスで、onresolvemethod 属性を pageContents XData ブロックの documentView 要素に追加します。以下に例を示します。

    onresolvemethod="return zenPage.getTemplate().resolve(context,which);"
  

  

  ここで、resolve() は (テンプレート・クラスに実装されている) コールバック・メソッドであり、basePage メソッド getTemplate() は現在のテンプレートへの参照を返します(documentView コールバックの一般情報は、“コールバックとイベント・ハンドラの概要” を参照してください)。

• コールバック・メソッドをテンプレート・クラスに追加する

  コールバック・メソッドには、methodname(context,which) 形式のシグニチャが必要です。このメソッドが呼び出されると、以下の引数を受け取ります。

  • context — コールバックを呼び出したレイアウト・オブジェクトのプロパティを含むオブジェクト。

  • which — '=[$method.methodname]' 式の methodname 文字列。

  コールバック・メソッドでは、通常、適切なアクションを決定するために、which の値に基づいて switch を実装します。

• レイアウト・グラフでコールバックを呼び出す

  以下の $p レイアウト・オブジェクトは、値をプロパティ myValue に割り当て、プロパティ $content を定義するためのコールバックを呼び出します。

  { type: '$p', myValue: '345' , $content: '=[$method.readValue]'}
  

  

  この例では、コールバック引数 which は文字列 'readValue' であり、引数 context は (プロパティ myValue を含む) 元のレイアウト・オブジェクトに解決される変数 $instance をとります。

以下の例では、簡単な onresolvemethod コールバックとその使用方法について説明します。

例：簡単な値とループを持つ resolve() コールバックの使用

この例では、resolve() という名前のコールバック・メソッドを実装します。onresolvemethod 属性は以下のように定義されます。

  onresolvemethod="return zenPage.getTemplate().resolve(context,which);"

resolve() メソッドはテンプレート・クラスに実装されます。

  ClientMethod resolve(context, which) [ Language = javascript ] {
    switch (which) {
      case 'readValue': return 'myValue = \"' + context.$instance.myValue + '\"';
      case 'readLoop': return 'myLoop('+context.$loopNumber+') = \"' + context.$loopValue + '\"';
    }
  }

resolve() メソッドは以下の 2 つの異なるタイプの context オブジェクトを処理します。

• 'readValue' では、簡単なレイアウト・オブジェクトによって呼び出されること、また、context が、元のレイアウト・オブジェクトに解決される変数 $instance をとることを想定しています。

• 'readLoop' は、呼び出しオブジェクトが $loop であることを想定しています。コールバックが呼び出されるたびに、特別なループ変数の現在値を使用して、ループの現在の繰り返しが処理されます。

  • $loopValue は外側のループのデータ・バインディングに解決され、繰り返しごとにデータへの直接アクセスを可能にします。

  • $loopNumber は 1 を基準とするループの繰り返しカウントです。

  詳細および例は、"Zen Mojo プラグインの使用法" の “$loop レイアウト・オブジェクト” を参照してください。

以下のテンプレート・メソッドには、両方のコールバック・オプションを使用するレイアウト・グラフが含まれています。これは、次の 2 つの主要なレイアウト・オブジェクトで構成されます。$p は ('=[$method.readValue]' を使用して) コールバックを 1 回呼び出します。$loop は ('=[$method.readLoop]' を使用して) コールバックを繰り返し呼び出します。

  ClientMethod myMainLayout(key, criteria) [ Language = javascript ] {
    var myLayoutGraph = {};
    myLayoutGraph = { children: [
      { type: '$p', myValue: 'a single value' , $content: '=[$method.readValue]'},
      { type: '$loop', value:['nergles','frabsters'], 
        children: [ { type: '$div', $content: '=[$method.readLoop]'} ]
      }
    ]}
    return myLayoutGraph;
  }

レイアウト・オブジェクトは以下のようにレンダリングされます。

• $p オブジェクトは '=[$method.readValue]' を呼び出します。これは、レイアウト・オブジェクト・プロパティ myValue の値を含む文字列を (context.$instance.myValue を通じて) 返します。

• $loop オブジェクトは 2 つの値の配列を定義し、それぞれについて '=[$method.readLoop]' を 1 回呼び出します。繰り返しごとに、(context.$loopNumber に含まれる) 現在のループ・カウントを含む文字列値と、(context.$loopValue に含まれる) value 配列の現在の項目が返されます。

myLayoutGraph がレンダリングされると、以下のテキストが表示されます。

    myValue = "a single value"

    myLoop(1) = "nergles"
    myLoop(2) = "frabsters"

レイアウト・グラフでのスタイル属性の指定

レイアウト・グラフには、スタイル全体を制御する属性が含まれています。レイアウト・グラフ内で、外観を制御するレイアウト・オブジェクトの属性も指定することができます。

以下に例を示します。

        content = {
            documentStyle:'background:white;min-height:100%;',
            children:[
                {type:'$para',
                    style:'line-height:150%;',
                    blockStyle:'padding-left:20px;padding-bottom:20px;',
                    title:'inbox',
                    titleStyle:'font-size:36px;color:#606060;',
                    text:'Messages and answers you have received',
                },
      ...

外観を制御するほとんどの属性は次の 2 つのカテゴリに分類されます。

• 生成された HTML の対応する部分の style 属性を制御するもの。このような属性には、通常、style、blockStyle などの名前が付いています。

  これらについて、CSS スタイル指示を指定します。

• 生成された HTML の対応する部分の class 属性を制御するもの。これらの属性には、通常、paraClass、tableClass などの名前が付いています。

  利用可能な CSS スタイル・シートのいずれかで指定されているように、これらについて CSS クラスの名前を指定します (詳細は、“スタイル・シートの組み込み” の章を参照してください)。

レイアウト・グラフでの sourceData プロパティの使用

レイアウト・メソッド内で、データ・オブジェクトをバイパスし、代わりに特殊な sourceData オブジェクトを使用することができます。

特に、レイアウト・グラフには、sourceData という名前のオブジェクト値プロパティを含めることができます。このプロパティは特別な方法で処理されます。この場合、Zen Mojo では sourceData オブジェクトを、一般的なデータ・オブジェクトではなく、現在のデータ・オブジェクトとして使用します。

レイアウト・グラフに sourceData プロパティが含まれている場合は、構文 '=[propertyname]' が sourceData オブジェクトを参照します。

以下に例を示します。

ClientMethod myGetMainViewLayout(key, criteria) [ Language = javascript ]
{

    var myLayoutGraph = {};
    myLayoutGraph = {
        sourceData: {
            name : 'Higgins,Bert',
            dob: '15-July-1973',
            homeaddress: {
                street: '4595 Center Street',
                city: 'Hopkinton',
                postalcode: '89304'
                },
            favoritecolors : ['blue']
            },
        children: [
            { type: '$header', $content: $$$Text('sourceData Demo')},
            { type: '$p', title:'Name', $content:'=[name]' },
            { type: '$p', title:'Birth Date', $content:'=[dob]' },
            { type: '$p', title:'Home City', $content:'=[homeaddress.city]' },
            { type: '$p', title:'First Favorite Color', $content:'=[favoritecolors[1]]' },
            { type: '$p', title:'Number of Favorite Colors', $content:'=[favoritecolors.length]' },
        ]
    }
    return myLayoutGraph;
}

この例では、sourceData オブジェクトはインラインで定義されています (つまり、レイアウト・グラフ内で定義されています)。代わりに、以前に定義したオブジェクトへの参照を使用できます。

        sourceData: myObject

sourceDataでの stash ファイルに保存した値の使用

sourceData オブジェクトには、サーバを不必要に呼び出すことができないようにするために、以前にクライアント上のstash ファイルに保存した値を使用する便利な方法が用意されています。特に、以下の操作を実行できます。

1. クライアント・メソッドの適切な場所で、値をページ・インスタンスやテンプレート・インスタンスのプロパティに保存することにより、stash ファイルに保存します。以下に例を示します。

   zenPage._MyNewValues={name:mainView.getControlValue('enterName'),
                         city:mainView.getControlValue('enterCity')};
   

   

   詳細は、“背景情報とタスク” の “stash ファイルへの値の保存” を参照してください。

2. sourceData オブジェクトを作成する場合は、stash ファイルに保存した値への参照を含めます。

3. レイアウト・グラフ内で、(以前に “レイアウト・グラフでの sourceData プロパティの使用” で説明したように) sourceData オブジェクトを参照します。つまり、構文 '=[propertyname]' を使用して sourceData オブジェクトのプロパティを参照します。