テンプレート・ディレクティブの使用

3.11 テンプレート・ディレクティブの使用

テンプレート・ディレクティブを使用して、置換文字列をサポートする属性の処理方法を制御します。

テンプレート・ディレクティブについて
テンプレート・ディレクティブについて学習します。
if条件ディレクティブ
アイテムまたは列に値があるかどうかに基づいてテキストを条件付きで表示するには、ifディレクティブを使用します。
case条件ディレクティブ
アイテムまたは列の値に基づいてテキストを表示するには、caseディレクティブを使用します。
loopディレクティブ
複数値(文字区切り)のアイテムまたは列値でアイテムごとにテキストを1回ずつ繰り返すには、loopディレクティブを使用します。
ディレクティブの使用および適用
withディレクティブを使用して、applyディレクティブで指定されたテンプレート・コンポーネントのプレースホルダに値を割り当てます。
テンプレート・ディレクティブの組込み置換
テンプレート・ディレクティブで使用可能な組込み置換文字列について学習します。

3.11.1 テンプレート・ディレクティブについて

テンプレート・ディレクティブについて学習します。

テンプレート・ディレクティブは、テンプレート・コンポーネント・プラグイン、電子メール・テンプレート内の特定の属性、およびカード、対話グリッド、クラシック・レポート、アプリケーション検索および対話モード・レポート・リージョンでのみサポートされます。ディレクティブはネストできます。つまり、任意のテンプレート・テキストに別のディレクティブを含めることができます。これらのディレクティブは、クライアント側またはサーバー側の置換の一部として処理されます。

属性がテンプレート・ディレクティブをサポートするかどうかを判別するために、ページ・デザイナのヘルプに「クライアント側テンプレート・ディレクティブのサポート」または「サーバー側テンプレート・ディレクティブのサポート」というテキストが表示されます。ディレクティブ構文の詳細は、Oracle APEX JavaScript APIリファレンスのapex.util.applyTemplateを参照してください。

ノート:

このトピックの構文の説明テキストは、角カッコの使用によって記述され、省略可能です。大カッコは実際には入力しません。大文字のテキストは、説明で説明されている内容を表します。

親トピック: テンプレート・ディレクティブの使用

3.11.2 if条件ディレクティブ

アイテムまたは列に値があるかどうかに基づいてテキストを条件付きで表示するには、ifディレクティブを使用します。

構文

{if [!][?|=]NAME/}
TRUE_TEMPLATE_TEXT
{elseif [!][?|=]NAME2/}
ELSE_TRUE_TEMPLATE_TEXT
{else/}
FALSE_TEMPLATE_TEXT
{endif/}

内容は次のとおりです。

NAMEはアイテム、列名またはテンプレート・コンポーネント属性です。
値がtrueの場合、次のテキストが出力されます。
空の文字列であるか、F、Nまたは0である場合、値はfalseです。
falseでない値はすべてtrueです。
NAMEの前に感嘆符(!)が続いている場合、ロジックは否定され、値がfalseの場合は次のテンプレート・テキストが処理されます。
先頭と末尾のスペースを切り捨てた後に空の文字列である場合、値はfalseになります。

if条件ディレクティブは、空の(または空ではない)テストとブールtrue/falseテストの両方を(Y'/'N'などの文字true/false値の規則を使用して)同時に処理します。これにより、空でないかどうかをテストする意図があるが実際の値がNであるまれなケースに混乱が生じ、空ではないが偽であるとみなされます。オプションの'?'接頭辞演算子を使用すると、値が空であるかどうかを明示的にテストできます。オプションの'='接頭辞演算子を使用すると、値がtrueまたはfalseであるかどうかを明示的にテストできます。

次の表に、使用可能な条件ディレクティブの概要を示します。

条件ディレクティブ	説明	PL/SQL式
`{if MYITEM/}`	`MYITEM`には値を含める必要があり、値は`‘F'`、`‘N'`または`‘0'`にできません。	`:MYITEM is not null and upper( :MYITEM ) not in ( 'F', 'N', '0' )`
`{if ?MYITEM/}`	`MYITEM`には値を含める必要があります。	`:MYITEM is not null`
`{if !MYITEM/}`	`MYITEM`は空にすることも、`‘F'`、`‘N'`または`‘0'`を含めることもできます。	`:MYITEM is null or upper( :MYITEM ) in ( 'F', 'N', '0' )`
`{if !?MYITEM/}`	`MYITEM`が空です。	`:MYITEM is null`
`{if =MYITEM/}`	`MYITEM`が空であるか、`‘F'`、`‘N'`または`‘0'`が含まれていません。	`:MYITEM is null or upper( :MYITEM ) not in ( 'F', 'N', '0' )`
`{if !=MYITEM/}`	`MYITEM`には、`‘F'`、`‘N'`または`‘0'`と等しい値が含まれます。	`upper( :MYITEM ) in ( 'F', 'N', '0' )`
`{if MYITEM%assigned/}`	複数のデータ行に一貫した出力が必要な場合に役立ちます。 `&COLUMN_NAME.`のような値が`MYITEM`に割り当てられていると、置換の適用後に一部の行が空になる場合があります。この場合は、すべての行について`%assigned`条件がtrueと評価されます。	なし

ゼロ個以上のelseifディレクティブを指定できます。elseifおよびelseディレクティブはオプションです。ディレクティブは、表示されている順序で実行する必要があります。

Example

カード・レポートに、DESCRIPTIONという名前の列が含まれています。次の「HTML式」属性は、null (空の文字列)でない場合は説明を表示し、それ以外の場合は「No description」を表示します。

{if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/}

親トピック: テンプレート・ディレクティブの使用

3.11.3 case条件ディレクティブ

アイテムまたは列の値に基づいてテキストを表示するには、caseディレクティブを使用します。

構文

{case NAME/}
{when STRING1/}
TEMPLATE_TEXT1
{when STRING2/}
TEMPLATE_TEXT2
{otherwise/}
TEMPLATE_TEXT
{endcase/}

NAMEはアイテム、列名またはテンプレート・コンポーネント属性です。値がそれぞれのwhenディレクティブの後の文字列と比較され、それらが等しい場合、次のテキストが出力されます。一致するwhenディレクティブがない場合は、otherwiseディレクティブの後のテキスト(存在する場合)が出力されます。比較の前に、値とそれぞれの文字列から先頭と末尾の空白が切り捨てられます。この比較では、大文字と小文字が区別されます。

Example

サンプルのEMP表を使用する次の例では、JOBに応じて報酬が異なる方法で表示されます。営業担当については、給与と歩合の両方が表示されます。社長については、給与のかわりに「--」が表示され、他のすべてのジョブについては、給与のみが表示されます。


{case JOB/}
{when SALESMAN/}
&SAL. (&COMM.)
{when PRESIDENT/}
--
{otherwise/}
&SAL.
{endcase/}

親トピック: テンプレート・ディレクティブの使用

3.11.4 loopディレクティブ

複数値(文字区切り)のアイテムまたは列値でアイテムごとにテキストを1回ずつ繰り返すには、loopディレクティブを使用します。

構文

{loop ["SEP"] NAME/}
TEMPLATE_TEXT
{endloop/}

NAMEは、SEPで指定された文字で区切られた複数の値を持つアイテムまたは列の名前です。デフォルトのセパレータは「:」です。SEPが複数の文字である場合は、正規表現として扱われます。

ループ内のテンプレート・テキストでは、次の置換を使用できます:

APEX$ITEM - これは、リスト内の現在のアイテムの値です。
APEX$I - これは、リスト内の現在のアイテムの1ベースの索引です。

Example

次の例は、apples,cherries,pearsのようなタグのカンマ(,)区切りリストを含むTAGSという列を取り、それを、CSSを使用して適切にスタイル設定できるHTMLリストに変換します。

<ul class="tags">{loop "," TAGS/}
  <li class="tag-item">&APEX$ITEM.</li>
{endloop/}</ul>

親トピック: テンプレート・ディレクティブの使用

3.11.5 ディレクティブの使用および適用

withディレクティブを使用して、applyディレクティブで指定されたテンプレート・コンポーネントのプレースホルダに値を割り当てます。

構文

{with/}
PLACEHOLDER1:=EXPRESSION1
PLACEHOLDER2:=EXPRESSION2
{apply TEMPLATE_INTERNAL_NAME/}

このディレクティブを使用する際の要件は次のとおりです。

withディレクティブを使用して、applyディレクティブで指定されたテンプレート・コンポーネント・プラグインのプレースホルダに値を割り当てます。
テンプレート・コンポーネント・プラグインはサーバー側のレンダリングを使用します。
値式内でのテンプレート・ディレクティブの使用がサポートされています。

Example

{with/}
TYPE:=IMAGE
IMAGE:=&IMAGE_URL.
ALT:={if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/}
{apply THEME$AVATAR/}

この例では、THEME$AVATARは、アプリケーションにインストールされているテンプレート・コンポーネント・プラグインの内部名です。このテンプレートには、3つのプレースホルダTYPE、IMAGEおよびALTがあり、それらに値が割り当てられます。

親トピック: テンプレート・ディレクティブの使用

3.11.6 テンプレート・ディレクティブの組込み置換

テンプレート・ディレクティブで使用可能な組込み置換文字列について学習します。

ノート:

テンプレート・コンポーネント・プラグインのテンプレート・ディレクティブでは、多くの追加の組込み置換もサポートされています。さらに学習するには、アイテム・ヘルプを参照してください。

置換文字列説明

置換文字列	説明
`APEX$ITEM`	ループ・ディレクティブ内で使用できます。リスト内の現在のアイテムの値を指定します。
`APEX$I`	ループ・ディレクティブ内で使用できます。リスト内の現在のアイテムの1ベースの索引を指定します。
`APEX$DOM_ID`	テンプレート・ディレクティブ・スニペットの現在の実行について一意のランダムな`DOM ID`を生成します。使用例: `<h1 id="#APEX$DOM_ID#_heading">#HEADING#</h1><someelement aria-labelledby="#APEX$DOM_ID#_heading">`

APEX$ITEM

ループ・ディレクティブ内で使用できます。リスト内の現在のアイテムの値を指定します。

APEX$I

ループ・ディレクティブ内で使用できます。リスト内の現在のアイテムの1ベースの索引を指定します。

APEX$DOM_ID

テンプレート・ディレクティブ・スニペットの現在の実行について一意のランダムなDOM IDを生成します。使用例:

<h1 id="#APEX$DOM_ID#_heading">#HEADING#</h1><someelement aria-labelledby="#APEX$DOM_ID#_heading">

親トピック: テンプレート・ディレクティブの使用