フラグメントへの構成オプションの追加

対応可能：Liferay DXP 7.2 SP1以降

構成可能なオプションを使用して、フラグメントを柔軟にすることができるので、似たようなフラグメントを多数管理する必要はありません。たとえば、スタイルAの見出しを持つ1つのフラグメントとスタイルBの見出しを持つ別のフラグメントを作成する代わりに、スタイルAとBのオプションを持つ見出しに対し構成可能なスタイルを持つフラグメントを1つ作成できます。ここでは、フラグメントに構成オプションを追加する方法を学びます。

構成可能なフラグメントのデプロイ
構成の検討
設定の変更
変更のプロパゲートとテスト
関連情報

note

Liferay DXP 7.4以降の場合、フラグメントコレクションはLiferay UIではフラグメントセットと呼ばれます。

構成可能なフラグメントのデプロイ

新しいLiferay インスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120。

http://localhost:8080でLiferayへのサインインします。メールアドレス test@liferay.com とパスワード test を使用してください。プロンプトが表示されたら、パスワードを learn に変更します。

次に、以下の手順でサンプルをデプロイし、Fragmentの設定オプションがどのように機能するかを確認する：

example Fragment Set をダウンロードして解凍する：

curl https://resources.learn.liferay.com/dxp/latest/en/site-building/developer-guide/developing-page-fragments/liferay-c7f8.zip -O

unzip liferay-c7f8.zip

フラグメントツールキットを設定します。
```
cd liferay-c7f8
```
```
./setup_tutorial.sh
```

フラグメントツールキットを使用して、フラグメントコレクションをDockerコンテナにインポートします。あるいは、手動でフラグメントをインポートすることもできます。

yarn run import

> yo liferay-fragments:import

? Liferay host & port http://localhost:8080
? Username test@liferay.com
? Password [hidden]
Checking connection...
Connection successful

? Company ID liferay.com
? Group ID Liferay
Building project...
Importing project...
✔ Fragment C7F8 Card imported
Project imported

フラグメントセットが利用可能であることを確認します。 サイトメニュー() を開き、［デザイン］ → ［フラグメント］に移動します。セットがリストに表示されます。

note

Liferay DXP 7.1および7.2では、代わりにプロダクトメニューのサイト → サイトビルダー → ページフラグメントに移動して、フラグメントページを表示します。
コンテントページに移動し、編集アイコン（）をクリックして編集を開始します。
フラグメントとウィジェットパネルの C7F8セット 見出しを展開し、 C7F8カード フラグメントをページにドラッグします。
ページで C7F8カード を選択して、フラグメント設定メニューを開きます。［一般］タブで、コンポーネントのテキストスタイルを「暗い」または「明るい」に設定します。

構成可能なフラグメントを正常にインポートして設定しました。

構成の検討

フラグメントの構成オプションは、Liferayに内蔵されているフラグメントエディタやテキストファイルで編集することができます。

フラグメントエディタの使用： UIで、フラグメントエディタを使用してフラグメントを編集し、［設定］タブをクリックします。フラグメントの設定がエディタに表示されます。

フラグメント設定ファイルの編集： フラグメントファイルがない場合は、フラグメントのアクションメニューを開き、［エクスポート］をクリックしてフラグメントからエクスポートします。フラグメントのfragment.jsonファイルのconfigurationPathフィールド（オプション）は、.json構成ファイルを指定します。構成ファイルがない場合は、構成ファイルを作成し、configurationPathフィールドを構成ファイル名に設定します。

サンプルのfragment.jsonファイルを開き、フラグメントの構成ファイルを決定します。

{
    "configurationPath": "index.json",
    "cssPath": "index.css",
    "htmlPath": "index.html",
    "jsPath": "index.js",
    "name": "C7F8 Card",
    "type": "component"
}

"configurationPath": "index.json"プロパティは、このフラグメントの構成ファイルがindex.jsonであることを示しています。

構成ファイルを開きます。

{
    "fieldSets": [
        {
            "fields": [
                {
                    "dataType": "string",
                    "defaultValue": "dark",
                    "label": "Text Style",
                    "name": "c7f8TextStyle",
                    "type": "select",
                    "typeOptions": {
                        "validValues": [
                            {
                                "value": "dark"
                            },
                            {
                                "value": "light"
                            }
                        ]
                    }
                }
            ],
            "label": "C7F8"
        }
    ]
}

上記の構成ファイルでは、 dark または light テキストスタイルをフラグメントに適用するためのセレクタを指定しています。この構成には、c7f8TextStyleという名前のフィールドがあります。フィールドのtypeはselectであり、セレクタコンポーネントになります。詳細は、Fragment Configuration Typesを参照してください。セレクタの有効な値は、darkまたはlightです。 "dataType": "string"プロパティは、セレクタが文字列データで動作することを意味します。

このセレクタは、 C7F8 というラベルの付いたフィールドセットの一部です (ラベルはオプションです)。 UIでは、このセレクタは、フラグメントの C7F8 というラベルが付いた構成セクションにあります。セレクタは、フィールドのlabelプロパティごとに、Text Styleとラベル付けされています。次の図にセレクタを示します。

これが C7F8 カードフラグメントのセレクタです。

warning

フラグメントエディタは、有効になるまで構成を保存しません。プレビューする前に、JSON構成が有効であることを確認してください。

ユーザーが選択した構成値は、FreeMarkerコンテキストを介してHTMLで使用できるようになります。これらは、HTMLの中で ${configuration.fieldName}という表記で参照されます。このサンプル（${configuration.textAppliedStyle}）は、ユーザーが選択した構成値に応じて dark または light を返し、CSS クラスを text-light または text-darkに設定します。

<div class="component-c7f8-card">
    <div class="card">
        <img
            class="card-img-top"
            data-lfr-editable-id="01-image"
            data-lfr-editable-type="image"
            src="https://clayui.com/images/home/lexicon_symbol.svg"
        />

        <div class="card-body">
            <h5
                class="card-title text-${configuration.c7f8TextStyle}"
                data-lfr-editable-id="02-title"
                data-lfr-editable-type="rich-text"
            >
                Editable Card Title
            </h5>

            <p
                class="card-text text-${configuration.c7f8TextStyle}"
                data-lfr-editable-id="03-text"
                data-lfr-editable-type="rich-text"
            >
                Here is some editable text.
            </p>

            <a
                class="btn btn-primary"
                data-lfr-editable-id="04-label"
                data-lfr-editable-type="link"
                href="#"
            >
                Editable Link
            </a>
        </div>
    </div>
</div>

この例は、選択の構成を示しています。使用可能なフラグメント構成タイプの完全なリストは、Configuration Types Referenceを参照してください。

設定の変更

構成がどのように機能するかを理解したので、構成を変更できます。

サイトメニュー（）を開き、［デザイン］ → ［フラグメント］に移動します。

note

Liferay DXP 7.1および7.2では、代わりにプロダクトメニューのサイト → サイトビルダー → ページフラグメントに移動して、フラグメントページを表示します。
［C7F8セット］を選択し、C7F8 カードの アクション(）ボタンをクリックして、［編集］を選択します。フラグメントエディタが開きます。
［設定］タブをクリックし、カードの説明を非表示／表示するチェックボックスフィールドで構成を更新します。 c7f8TextStyleフィールドの閉じ括弧とカンマ（},) の後の新しい行に次のコードを挿入します。
```
{
    "name": "showDescription",
    "label": "Show Description",
    "description": "show-description",
    "type": "checkbox",
    "defaultValue": true
}
```
tip

フィールドセットに configurationRole 値を追加して（JSONの fields オブジェクトと一緒に）、関連するフィールドがどのタブに表示されるかを指定することができます。値を styles に設定すると［スタイル］タブにフィールドが表示され、advanced に設定すると［詳細設定］タブに表示されます（Liferay DXP バージョン U23+ または GA23+ でのみ使用可能）。 configurationRoleが設定されていない場合、デフォルトで［一般］タブに表示されます。
［コード］タブの［HTML］ペインに戻り、チェックボックスの値をチェックするための条件付きステートメントで段落要素をラップします。［Publish］をクリックして変更を適用します。
```
[#if configuration.showDescription]
  <p data-lfr-editable-id="03-card-text" data-lfr-editable-type="rich-text"
  class="card-text text-${configuration.textAppliedStyle}">
    Here is some editable text.
  </p>
[/#if]
```