###########################################
Scribanテンプレートの組み込み機能
###########################################

このトピックでは、Scriban テンプレートの Sitecore 組み込み関数について説明します。

*****************
sc_decorate
*****************

Creative Exchange が必要とするスタイル、グリッドクラス、属性を持つコンポーネントの装飾を返します。

このヘルパー関数は、MVC Razor ビューの @Html.Sxa().Component() ヘルパー関数に相当します。この関数を使用して、Scriban テンプレート内のマークアップを制御することができます。この関数を使えば、Razorビューはほぼ空っぽになります。レンダリングバリアント機能を呼び出して sc_decorate ヘルパー関数を埋め込むことで、ユーザーが選択したスタイルやグリッドクラスをレンダリングパラメータに追加することができます。

パラメーター
==============

+--------+------------+--------------+--------------------------------------------+
| タイプ | オプション | サンプル     | 使用方法                                   |
+--------+------------+--------------+--------------------------------------------+
| string | はい       | `hero promo` | コンポーネントの装飾にクラスを追加します。 |
+--------+------------+--------------+--------------------------------------------+

サンプル
==============

次の例は、Razor ビューを変更してマークアップを提供せず、レンダリングプロセスをバリアントに完全に委譲した場合に、Promo コンポーネントに使用できる Scriban テンプレートを示しています。このマークアップによるテンプレート出力は、デフォルトの Promo バリアントと同じです。例の最初の行では、sc_decorate 関数の使用方法を見ることができます。テンプレート内のタグに他の属性を直接追加することができます。

.. code-block:: 

    <div {{ sc_decorate "promo" }} role="banner">
        <div class="component-content">
            <div class="field-promoicon">
                {{ i_item.PromoIcon }}
            </div>
            <div class="promo-text">
                <div>
                    <div class="field-promotext">
                        {{ i_item.PromoText }}
                    </div>
                </div>
                <div class="field-promolink">
                    {{ i_item.PromoLink }}
                </div>
            </div>
        </div>
    </div>

1行目は、訪問者に対して以下のようにレンダリングされます。

.. code-block:: html

    <div class="component promo col-12" role="banner">

Creative Exchange のクラス編集とスタイルのインポートを有効にします。

.. code-block:: html

    <div class="component promo col-12 add-your-css-classes-here"
    data-pageid="{A25A4448-3319-4A52-93DE-B10A7A158DFD}"
    data-renderingid="{51C13F03-8364-4F61-B860-2EC6CA7439B3}"
    data-uniqueid="{8DED9C5D-5D8D-4C16-93A0-A78928B17656}"
    data-variantid="{D51080C1-C9A8-457A-88B1-EF3CF21DD6FF}"
    data-stylesfield="Styles"
    data-gridfield="GridParameters"
    data-renderingclass="promo"
    role="banner">

***************************************
sc_editframe と sc_enditframe
***************************************

HTML の領域の周りに編集フレームを表示し、その領域内のコンテンツを編集するのに役立つエクスペリエンスボタンのセットを指定することができます。

パラメーター
============

+--------+------------+-------------------+--------------------------------------------------------------------------------------------------------------------------+
| タイプ | オプション | サンプル          | 使用方法                                                                                                                 |
+--------+------------+-------------------+--------------------------------------------------------------------------------------------------------------------------+
| Item   | いいえ     | i_item            | 編集フレームがレンダリングされ、そのフィールドの編集が可能になる項目。                                                   |
+--------+------------+-------------------+--------------------------------------------------------------------------------------------------------------------------+
| string | いいえ     | 'Gallery   Image' | コアデータベース内の/sitecore/content/Applications/WebEdit/Edit   Frame Buttons/パス下のEdit   Frameフォルダ項目の名前。 |
+--------+------------+-------------------+--------------------------------------------------------------------------------------------------------------------------+


sc_endeditframeはパラメータを含まず、ラップされた編集フレームの周辺を閉じるために使用されます。

サンプル
===========

以下の例は、編集フレームを含むデフォルトのギャラリーコンポーネントのレンダリングバリアントを複製しています。デフォルトの設定については、以下を参照してください。/sitecore/system/Settings/Foundation/Experience Accelerator/Rendering Variants/Rendering Variants/Gallery/Default

.. code-block::

    {{-
    if i_item.template_name == "Gallery Image"
        sc_editframe i_item 'Gallery Image' -}}
        <a class="field-image">
        <a title="{{ i_item.ImageTitle.raw }}" href="{{ i_item.Image.media_url }}">
        {{ i_item.Image }}
        </a>
        </a>{{
        sc_endeditframe
    end -}}

    {{-
    if i_item.template_name == "Gallery Video"
        sc_editframe i_item 'Gallery Video'
        if (i_item.VideoID.raw ) == "" &amp;&amp; (i_item.VideoThumbnail.raw) == "" -}}
        <span>[Edit Gallery Video here]</span>{{
        else -}}
        <a title="{{i_item.VideoTitle.raw }}" href="http://www.youtube.com/watch?v={{ i_item.VideoID.raw }}">
        <img src="{{ o_model.thumbnail_url }}" alt="{{ i_item.VideoDescription.raw }}"
                data-title="{{ i_item.VideoTitle.raw }}" data-description="{{ i_item.VideoDescription.raw }}" ></img>
        </a>{{
        end
        sc_endeditframe
    end }}

*******************
sc_placeholder
*******************

動的プレースホルダを、オプションのコンテキストスイッチでレンダリングします。

パラメーター
==============
+--------+------------+----------+-----------------------------------------------------------------------------------------------------------+
| タイプ | オプション | サンプル | 使用方法                                                                                                  |
+--------+------------+----------+-----------------------------------------------------------------------------------------------------------+
| string | いいえ     | 'mykey'  | プレースホルダキー。                                                                                      |
+--------+------------+----------+-----------------------------------------------------------------------------------------------------------+
| Item   | はい       | i_item   | コンテキストを切り替えるオプションのアイテム。                                                            |
|        |            |          +-----------------------------------------------------------------------------------------------------------+
|        |            |          | item を指定すると、プレースホルダ内のコンポーネントは i_item   でレンダリングされたかのように動作します。 |
+--------+------------+----------+-----------------------------------------------------------------------------------------------------------+

サンプル１
================

次の例では、ダイナミック SXA プレースホルダをレンダリングする方法を示します。

.. code-block:

    {{ sc_placeholder "mydynamic"  }}


サンプル2
================

次の例は、SXA プレースホルダをダイナミックにレンダリングし、そのコンテキストを関連する i_product アイテムに切り替える方法を示しています。このプレースホルダ内のコンポーネントは、レンダリングされたページが i_product であるかのように動作します。

.. code-block:

    {{
    i_product = i_page.RelatedProducts.target
    sc_placeholder "relatedproducts" i_product
    }}

*******************
sc_execute
*******************

Scriban テンプレートの下にあるレンダリングバリアントフィールドを実行します。

SXA では、Scriban テンプレートの下にレンダリングバリアントフィールドを追加で埋め込むことができますが、sc_execute で明示的に呼び出さない限りレンダリングされません。

runsc_execute i_item "Item below template" を実行すると、テンプレートエンジンに階層内の Item below template をレンダリングし、sc_execute 関数のある場所に貼り付けるように指示します。

+--------+------------+----------------------+--------------------------------------------------------------+
| タイプ | オプション | サンプル             | 使用方法                                                     |
+--------+------------+----------------------+--------------------------------------------------------------+
| item   | いいえ     | i_item               | レンダリングバリアント要素が実行されるコンテキスト内の項目。 |
+--------+------------+----------------------+--------------------------------------------------------------+
| string | いいえ     | 'Responsive   Image' | レンダリングバリアントフィールドの名前。                     |
+--------+------------+----------------------+--------------------------------------------------------------+

*******************
sc_evaluate
*******************

Scriban テンプレートの下に保存されているレンダリングバリアントルールを評価し、ルールの実行結果に基づいて評価値 (true または false) を返します。

パラメーター
==============

+--------+------------+----------------------+----------------------------------------------------------------------------------------------------------------+
| タイプ | オプション | サンプル             | 使用方法                                                                                                       |
+--------+------------+----------------------+----------------------------------------------------------------------------------------------------------------+
| Item   | いいえ     | i_item               | ルールが評価される項目。                                                                                       |
+--------+------------+----------------------+----------------------------------------------------------------------------------------------------------------+
| string | いいえ     | 'Responsive   Image' | レンダリング処理中に評価されるレンダリングバリアントルール（Scriban テンプレートの下に保存されている）の名前。 |
+--------+------------+----------------------+----------------------------------------------------------------------------------------------------------------+

サンプル
================

レンダリングバリアントに Scriban タイプのレンダリングバリアントフィールドを追加することで、Scriban テンプレートでパーソナライズルールをレンダリングすることができます。たとえば、Promo コンポーネントのバリアントを作成し、Personalized Promo と名付けます。Scriban タイプのレンダリングバリアントフィールドを追加し、テンプレートという名前にします。次に Rule 型のレンダリング バリアント フィールドを追加した場合、次のコードを Template レンダリング バリアント フィールドに貼り付けると、パーソナライズ ルールがレンダリングされます。

.. code-block::

    <div class="promo-text">{{
    if sc_evaluate i_datasource "Personalization" -}}
        <div>
        This will be shown when the personalization rule will evaluate to TRUE
        </div>{{
    else -}}
        <div>
        This will be shown when the personalization rule will evaluate to FALSE
        </div>{{
    end -}}
    </div>

*******************
sc_raw
*******************

アイテムからフィールドの生の値を取得します。

パラメーター
==============

+--------+------------+-------------+--------------------------------+
| タイプ | オプション | サンプル    | 使用方法                       |
+--------+------------+-------------+--------------------------------+
| Item   | いいえ     | i_item      | フィールドの値を取得する項目。 |
+--------+------------+-------------+--------------------------------+
| string | いいえ     | 'FieldName' | 取得したいフィールドの名前。   |
+--------+------------+-------------+--------------------------------+

サンプル１
================

.. code-block::

    <h1>{{ sc_raw i_page "Title" }}</h1>

*******************
sc_field
*******************

フィールドが空の場合にフォールバックが可能なSitecoreフィールドをレンダリングし、画像やリンクなどのタグにパラメータを追加することができます。

パラメーター
==============

+--------------------+------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| タイプ             | オプション | サンプル                                             | 使用方法                                                                                                                                                   |
+--------------------+------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Item               | no         | i_item                                               | フィールドの値を取得する項目です。                                                                                                                         |
+--------------------+------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| string or string[] | no         | 'FieldName'                                          | レンダリングされるフィールドの名前です。                                                                                                                   |
|                    |            |                                                      +------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                    |            |                                                      | あるいは、フィールド名の配列を指定することもできます。この場合、この関数は左から右へとリストをチェックし、空ではない最初のフィールドをレンダリングします。 |
|                    |            |                                                      +------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                    |            |                                                      | エクスペリエンスエディタでは、編集モードでは、空であっても常に最初のフィールドが使用されます。                                                             |
+--------------------+------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| string[][]         | no         | [['attribute1','value1'],   ['attribute2','value2']] | リンクやイメージなどのフィールド上のフィールドレンダラに追加のパラメータを指定できるようにする、名前/値の文字列の配列。                                    |
+--------------------+------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+

サンプル
================

例えば、以下のサンプルコードを使用して、sc_field関数を呼び出してアイテムのフィールドをレンダリングします。

.. code-block:: 

    {{ sc_field i_page 'Title' }}

フィールドフォールバックの例
================================

著者が値を入力するためのフィールドを提供し、著者が値を入力しなかった場合でもフィールドが空にならないようにしたい場合は、sc_field関数で提供されているフィールドフォールバック機能を使用することができます。

.. code-block::

    {{ sc_field i_page ['NavigationTitle', 'Title', '__Display Name'] }}

テンポラリエンジンは 'NavigationTitle' をレンダリングしようとし、その中に値が見つからない場合、'Title' フィールドに移動して試みを返し、失敗した場合は最終的に '__Display Name' にフォールバックします。


リンクと画像フィールドの書式設定とデータ属性
=================================================

リンクやイメージレンダリングフィールドのデフォルトのレンダリング動作を拡張したい場合は、以下の例のように、3番目のパラメータとしてSitecoreフィールドレンダラーに渡される追加の名前/値コレクションを指定することができます。

画像レンダラーの例
========================

以下の例では、高さと幅が 50 に設定され、追加のデータ属性 data-purpose が設定された画像をレンダリングしています。

.. code-block:: 

    {{ sc_field i_item 'PromoIcon' [['h', '50'], ['w', '50'], ['data-purpose', 'Promo Icon']] }}

上記のコードの結果、あなたのページには以下のようなHTMLが表示されます。

.. code-block:: html

    <img src="/-/media/MyImage.jpg?h=50&amp;amp;iar=0&amp;amp;w=50" alt="" width="50" height="50" data-purpose="Promo Icon">

レンダリングされるフィールドでは、以下のパラメータが使用されます。追加のパラメータはデータ属性として使用されます。

+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| タイプ | オプション                                                                     | サンプル                               | 使用方法                                                                                                                                        |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| as     | true                                                                           | false                                  | 画像を元のサイズを超えて引き伸ばすことを許可する？                                                                                              |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| bc     | Color   names (such as black or red) and HTML hex color codes (such as CE55E2) | black                                  | 画像が元のサイズを超えて引き伸ばされたときに追加されるボーダーの背景色（および   allowStretch=false）。                                         |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| db     | Any   Sitecore database defined on the site.                                   | content   database of the current site | 画像をプルする Sitecore の名前。                                                                                                                |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| dmc    | true                                                                           | false                                  | このリクエストのためにメディアキャッシュを無効にするか？true にすると、画像は常にデータベースから取得され、メディアキャッシュをバイパスします。 |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| h      | Any positive integer                                                                                                    | 画像の高さ。高さを元のサイズよりも大きくしたい場合は as=true を含めなければなりません。                                                         |
+--------+-------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| la     | Any valid language name                                                                                                 | アイテムの特定の言語バージョンから画像を取得します。                                                                                            |
+--------+-------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| mh     | Any positive integer                                                                                                    | 表示する画像の最大高さ。  必要に応じて、画像をこのサイズまで縮小します。                                                                        |
+--------+-------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| mw     | Any positive integer                                                                                                    | 表示する画像の最大幅。  必要に応じて画像をこのサイズに縮小します。                                                                              |
+--------+-------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| sc     | Any positive floating point number using a dot as a   decimal point (such as 1.5, which corresponds to 150%)            | 表示される画像の拡大縮小率。  画像を元のサイズよりも大きくする場合は、as=true を含める必要があります。                                          |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| thn    | true                                                                           | false                                  | 要求されたファイルのサムネイルを表示します。画像だけでな く 、 PDF やフ ラ ッ シ ュ な ど の他の メ デ ィ ア タ イ プに も有用です。            |
+--------+--------------------------------------------------------------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| vs     | Any positive integer                                                                                                    | アイテムの特定のバージョンの画像を取得します。                                                                                                  |
+--------+-------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| w      | Any positive integer                                                                                                    | 画像の幅。幅が元のサイズよりも大きくなる場合は as=true を含める必要があります。                                                                 |
+--------+-------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+

リンク レンダラーの例
=====================

リンク フィールド レンダラーと同様に、リンク レンダラーでは、ニーズに応じて属性を追加することができます。次の例では、PromoLinkターゲットアイテムのタイトルを使用して、リンクにARIAアクセシビリティラベルを追加しています。

.. code-block::

    {{ sc_field i_item 'PromoLink' [['aria-label', (i_item.PromoLink.Title.raw)]] }}

上記の例では、以下のようなHTMLを生成できます。

.. code-block::

    <a href="/Page" aria-label="Page Title">Page</a>

*******************
sc_follow
*******************

フィールドから選択された項目を返し、項目へのリンクを格納します。フィールドに複数の項目へのリンクを格納できる場合は、リストの最初の項目が返されます。フィールドが空の場合、この関数はヌル値を返します。

パラメーター
==============

+--------------------+------------+-------------+----------------------------------------+
| タイプ             | オプション | サンプル    | 使用方法                               |
+--------------------+------------+-------------+----------------------------------------+
| Item               | いいえ     | i_item      | フィールドの値が取得される項目。       |
+--------------------+------------+-------------+----------------------------------------+
| string or string[] | いいえ     | 'FieldName' | アイテムにリンクするフィールドの名前。 |
+--------------------+------------+-------------+----------------------------------------+

.. note:: より短い i_item.target 記法を使用することもできます。その場合、i_item.targetでは、'.'、','、ホワイトスペースなどの特殊文字を含むフィールドへのリンクを許可していないことに注意してください。

サンプル
================

Promo コンポーネントからリンクされた商品の詳細情報をレンダリングします。

.. code-block::

    <h2>{{ sc_follow i_item "Promo Link" | sc_field "Title" }}</h2>

*******************
sc_followmany
*******************

アイテムへのリンクを格納できるフィールドで選択されたアイテムの配列を返します。フィールドが空の場合、この関数は空のリストを返します。

パラメーター
==============

+--------------------+------------+-------------+----------------------------------------+
| タイプ             | オプション | サンプル    | 使用方法                               |
+--------------------+------------+-------------+----------------------------------------+
| Item               | いいえ     | i_item      | フィールドの値が取得される項目。       |
+--------------------+------------+-------------+----------------------------------------+
| string or string[] | いいえ     | 'FieldName' | アイテムにリンクするフィールドの名前。 |
+--------------------+------------+-------------+----------------------------------------+

.. note:: より短い i_item.targets 記法を使用することができます。その場合、'.'、','、','、空白などの特殊文字を含むフィールドへのリンクは許可されないことに注意してください。

サンプル１
================

現在の製品に関連する製品をレンダリングする。

.. code-block::

    {{ for i_product in (sc_followmany i_page "Related Products") }}
    <h2>{{ sc_field i_product "Title" }}</h2>
    <b>Content</b>:{{ sc_field i_product "Content" }}
    {{ end }}

*******************
sc_link
*******************

パラメータとして指定した項目のURL文字列を返します。項目が null の場合は # を返します。

パラメーター
==============

+--------+------------+----------+--------------------------+
| タイプ | オプション | サンプル | 使用方法                 |
+--------+------------+----------+--------------------------+
| Item   | いいえ     | i_item   | リンクが生成された項目。 |
+--------+------------+----------+--------------------------+

.. note:: より短い i_item.url 記法を使用することもできます。もし使用する場合は、'.'、','、ホワイトスペースなどの特殊文字を含むフィールドへのリンクを許可していないことに注意してください。

サンプル
================

データソース項目の表示名をリンクのテキストとして使用して、コンポーネントのデータソースへのリンクをレンダリングします。

.. code-block::

    <a href="{{ sc_link i_datasource }}">{{ i_datasource.display_name }}</a>

*******************
sc_medialink
*******************

パラメータとして指定された項目のメディアURL文字列を返します。アイテムがNULLの場合、この関数は#を返します。

ファンクション パラメーター
===========================

+--------+------------+----------+----------------------------------+
| タイプ | オプション | サンプル | 使用方法                         |
+--------+------------+----------+----------------------------------+
| Item   | いいえ     | i_item   | リンクが生成されるメディア項目。 |
+--------+------------+----------+----------------------------------+

.. note:: より短い i_item.media_url 記法を使用することもできます。その場合、'.'、','、ホワイトスペースなどの特殊文字を含むフィールドへのリンクは許可されないことに注意してください。

.. code-block:: 

    <a download href="{{ sc_follow i_datasource 'PromoIcon' | sc_medialink }}">{{ i_datasource.PromoIcon.name }}</a>

*******************
sc_query
*******************

Sitecore クエリを実行し、結果の項目を配列として返します。

パラメーター
==============

+--------+------------+-------------+------------------------------------------+
| タイプ | オプション | サンプル    | 使用方法                                 |
+--------+------------+-------------+------------------------------------------+
| Item   | いいえ     | i_item      | クエリが実行されるコンテキスト内の項目。 |
+--------+------------+-------------+------------------------------------------+
| string | いいえ     | 'query:./*' | 実行するクエリ。                         |
+--------+------------+-------------+------------------------------------------+


サンプル
================

.. code-block::

    {{ for i_child in (sc_query i_page 'query:./*') }}
    <h1>{{ i_child.Title }}</h1>
    {{end}}


*******************
sc_parameter
*******************

レンダリングパラメータの値を取得します。

パラメーター
==============

+--------+------------+----------+--------------------------------+
| タイプ | オプション | サンプル | 使用方法                       |
+--------+------------+----------+--------------------------------+
| string | いいえ     | ID       | 値を取得するパラメータの名前。 |
+--------+------------+----------+--------------------------------+

.. code-block::

    <div>This rendering is in the '{{ sc_parameter 'Placeholder' }}' placeholder.<div>

*******************
sc_translate
*******************

入力された文字列とページがレンダリングされる現在の言語に応じたテキストを返します。翻訳は、サイトアイテムのルートにある辞書に保存されます。

パラメーター
==============

+--------+------------+----------+------------------------------------------------------------------------------------------------------------------------+
| タイプ | オプション | サンプル | 使用方法                                                                                                               |
+--------+------------+----------+------------------------------------------------------------------------------------------------------------------------+
| string | いいえ     | key      | サイト辞書からのキーです。                                                                                             |
+--------+------------+----------+------------------------------------------------------------------------------------------------------------------------+
| string | はい       | language | リクエストコンテキストから言語を取得する代わりに、テキストを特定の言語に強制的に翻訳するための言語コードを提供します。 |
+--------+------------+----------+------------------------------------------------------------------------------------------------------------------------+

サンプル
================

.. code-block::

    <button class="button cancel">{{ sc_parameter 'Cancel' }}</button>


.. tip:: 英語版 https://doc.sitecore.com/developers/sxa/93/sitecore-experience-accelerator/en/the-embedded-functions-for-the-scriban-template.html