ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、こちらまでご連絡ください。

フラグメントツールキットの使用

注

Fragments Toolkit は、Liferay 2024.Q1+/Portal GA112+ 以降では非推奨となります。詳細については、フラグメントツールキットの代替品を参照してください。

フラグメントツールキットは、お気に入りのツールを使用してフラグメントをローカルで作成および管理するのに役立ちます。ここでは、ツールキットを使用して、サンプルのフラグメントを含むフラグメントプロジェクトを生成し、デプロイして、独自のフラグメントセットを追加します。

注

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

ツールキットの設定

ツールキットには次のソフトウェアが必要です。

NPM と Yarn は、ツールキットとそれが依存するモジュールをインストールするために使用するパッケージマネージャーです。

まず、 Node.js LTS経由で NPM と Node.js をインストールします。
サンプルの JavaScript プロジェクトの ZIP ファイルをダウンロードして解凍します。
```
curl https://resources.learn.liferay.com/examples/liferay-x2y6.zip -O
```
```
unzip liferay-x2y6.zip
```
setup_tutorial.sh スクリプトを使用して、フラグメントツールキットとその依存関係を設定します。
```
cd liferay-x2y6
```
```
./setup_tutorial.sh
```
注

setup_tutorial.sh スクリプトは、Yeoman、Yarn、およびツールキットをセットアップするためのコマンドを提供します。スクリプトは、サンプルプロジェクトのZIPファイルで利用できます。

スクリプトによって報告された満たしていない要件をすべて解決し、環境の準備が整ったと報告されるまでスクリプトを再実行してください。

フラグメントプロジェクトを作成する

フラグメントツールキットの yo liferay-fragments コマンドは、フラグメントプロジェクトを生成するためのインターフェイスを起動します。

警告

フラグメントプロジェクトをネストしないでください。新しいフラグメントプロジェクトは、既存のフラグメントプロジェクトとは別の場所に作成してください。

liferay-x2y6 プロジェクトフォルダにいる場合は、それを終了します（例： cd ..）。

フラグメントプロジェクトを生成する方法は次のとおりです。

yo liferay-fragments コマンドを実行して、プロジェクトジェネレータを起動します。
```
yo liferay-fragments
```
プロジェクトに名前を付けます。この例では、Enter をクリックしてデフォルトのプロジェクト名を受け入れます。
```
? Project name (Sample Liferay Fragments)
```

サンプルコンテンツを追加するかどうかを示します。この例では、 Yes と入力します。

? Add sample content? Yes
Creating directory
   force .yo-rc.json
create src/.gitkeep
create .editorconfig
create .gitignore
create liferay-npm-bundler.config.js
create package.json
create README.md
Adding sample content...
Warning: some of these fragments are not compatible all
portal versions, please check the generator documentation before using them:
https://www.npmjs.com/package/generator-liferay-fragments#creating-new-fragments
Running yarn...
Done!
You're ready to create fragments.
create src/sample-collection/collection.json
create src/sample-collection/sample-fragment/index.html
create src/sample-collection/sample-fragment/main.js
create src/sample-collection/sample-fragment/styles.css
create src/sample-collection/sample-fragment/fragment.json
create src/sample-collection/sample-fragment/configuration.json
create src/sample-collection/sample-fragment-with-new-editables/index.html
create src/sample-collection/sample-fragment-with-new-editables/main.js
create src/sample-collection/sample-fragment-with-new-editables/styles.css
create src/sample-collection/sample-fragment-with-new-editables/fragment.json
create src/sample-collection/sample-fragment-with-new-editables/configuration.json
create src/sample-collection/sample-fragment-with-react/index.html
create src/sample-collection/sample-fragment-with-react/main.js
create src/sample-collection/sample-fragment-with-react/styles.css
create src/sample-collection/sample-fragment-with-react/fragment.json
create src/sample-collection/sample-fragment-with-react/configuration.json

これでフラグメントプロジェクトが生成されました。

ジェネレータは、プロジェクト名から派生したフォルダに各プロジェクトを作成します。この例では、プロジェクト名を Sample Liferay Fragments としたので、ジェネレータは sample-liferay-fragmentsというプロジェクトフォルダを作成します。

サンプルのフラグメントセットをインポートする

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

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

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

次に、次の手順に従ってサンプルフラグメントセットを Liferay にインポートします。

プロジェクトのルートフォルダ（例： sample-liferay-fragments）で yarn run import コマンドを呼び出して、フラグメントセットを Liferay インスタンスにインポートします。あるいは、フラグメントセットを手動でインポートすることもできます。
```
cd sample-liferay-fragments
```
```
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 DXP
Building project...
Importing project...
Project imported
   force .yo-rc.json
   force ../../.yo-rc-global.json
Done in 21.43s.

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

注

Liferay DXP 7.1 および 7.2 の場合は、代わりに製品メニューの サイト → サイトビルダー → ページフラグメント に移動して、 フラグメント ページに移動します。

ここまでで、フラグメントセットを正常にデプロイしました。

フラグメントセットのストラクチャー

各フラグメントセットは、次の構造を使用します。

collection.json: フラグメントセットを説明するテキストファイル。
```
{
   "description": "Optional description",
   "name": "Fragment Set Name"
}
```
language.properties (オプション)：フラグメントセットに定義された言語キー。
[fragment-name]/: フラグメントのすべてのファイルを含むフォルダ。
- configuration.json(オプション): フラグメントの構成を定義する JSON ファイル。詳細については、「フラグメントへの構成オプションの追加」を参照してください。
- fragment.json: フラグメントを説明するJSONファイル。詳細については、 fragment.json の変更を参照してください。
resources/ (オプション): フラグメントが必要とする追加の画像またはファイルを含むフォルダ。詳細については、「フラグメントにデフォルトのリソースを含める」を参照してください。

フラグメントツールキットを使用すると、この構造でプロジェクトをすばやく作成できます。

fragment.json の変更

fragment.json には、フラグメントの機能と使いやすさを向上させるために変更できるフラグメント属性が含まれています。

キー	Description
`cssPath`	.css、.scss、または .sass ファイルを指定します。
`configurationPath`	フラグメントの構成ソースを指定します。
`htmlPath`	フラグメントの HTML ソースを指定します。
`jsPath`	フラグメントの JavaScript ソースを指定します。
`name`	フラグメントの名前。
`type`	コンポーネントまたは React フラグメントを指定します。
`icon`	インポートされたフラグメントに粘土アイコンを追加します。使用可能なアイコンについては、 Clay アイコンリストを参照してください。
`sass {loadPaths:[]}}`	外部依存関係を指定します。

{
   "cssPath": "styles.css",
   "configurationPath": "configuration.json",
   "htmlPath": "index.html",
   "jsPath": "main.js",
   "name": "Fragment name",
   "type": "[component|react]",
   "icon": "adjust"

   // This configuration is optional and can be removed
   "sass": {
         "loadPaths": [
            "../../../node_modules"
         ]
   }
}

プロジェクトにフラグメントセットを追加する

add-collection コマンドを使用して、プロジェクトにフラグメントセットを追加します。

プロジェクトのルートフォルダに移動して、次のコマンドを実行します。
```
yarn run add-collection
```

プロンプトが表示されたら、フラグメントセットの名前と説明を入力します。

> yo liferay-fragments:collection
? Collection name (required) My Set
? Collection description (optional) This is my new Fragment Set.
create src/my-set/collection.json

新しいフラグメントセットがプロジェクトのsrcフォルダに正常に作成されたことを確認します。 collection.jsonファイルのみが含まれているはずです。
```
{
   "description": "This is my new Fragment Set.",
   "name": "My Set"
}
```

新規フラグメントを作成する

add-fragment コマンドを使用して、新しいフラグメントをセットに追加します。

プロジェクトのルートフォルダに移動して、次のコマンドを実行します。
```
yarn run add-fragment
```
CLI がプロセスを開始します:
```
> yo liferay-fragments:fragment
```
フラグメントに名前を付けます。
```
? Fragment name (required) My Jumbotron
```
React または別の JavaScript フレームワークを使用するかどうかを選択します。 React には Liferay 7.3 以降が必要です。このチュートリアルでは、React の使用を拒否してください。
```
? Use React (or other JS framework)? No
```
Liferay 7.3 以降の場合は、新しい編集可能な要素の構文を使用します。
```
? Use new data-lfr editable syntax? Yes
```
注

フラグメントで React の使用を受け入れた場合、ツールキットは Liferay 7.3 以降を使用していると想定し、新しい編集可能な要素の構文を構成します。 Liferay の編集可能なデータ構文の詳細については、フラグメント固有のタグを参照してください。
先ほど作成したフラグメントセットを選択します（My Set）。
```
? Choose a collection
   My Set
   Sample Set
   + New Collection
```
注

fragment.json は、フラグメントの CSS、HTML、および JavaScript へのパスを定義します。これらのファイル名のいずれかを変更する場合は、 fragment.json内のパスを更新してください。

フラグメントの index.html は次のとおりです。

<div class="my-jumbotron">
    <h1 data-lfr-editable-id="title" data-lfr-editable-type="text">
        My Jumbotron
    </h1>
</div>

フラグメント HTML は、data-lfr の新しい編集可能な構文を使用します。

フラグメントを編集する

フラグメントの任意の部分を変更します。

HTML (index.html)
CSS (styles.css)
JavaScript (main.js)
フラグメント属性 (fragment.json)
構成オプション (configuration.json)。

たとえば、上記の HTML を基にして、 Clayの Bootstrapベースのコンポーネントを使用して、次の index.htmlに示すように、注目を集める見出しと説明を含むフラグメントを作成できます。

<div class="component-my-jumbotron">
    <div class="jumbotron">
        <h1
            class="display-4"
            data-lfr-editable-id="01-title"
            data-lfr-editable-type="rich-text"
        >
            Editable Jumbotron Headline
        </h1>

        <p
            class="lead"
            data-lfr-editable-id="02-lead"
            data-lfr-editable-type="rich-text"
        >
            Edit this text to call extra attention to featured content or information.
        </p>

        <hr />

        <p
            data-lfr-editable-id="03-text"
            data-lfr-editable-type="rich-text"
        >
            Edit this text to provide more information.
        </p>

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

注

Liferay 7.2以前を使用している場合は、 data-lfr-editable-[id|type] 属性を削除し、フラグメント固有のタグで説明されているように、コンテンツ要素を lfr-editable 要素で囲みます。

最初の div 要素の class="component-my-jumbotron" 属性は、ページ上のこのフラグメントを一意に識別しようとします。

ヒント

フラグメントの HTML ファイルでは、メインのラッパー要素 (上記の例では <div> ) を使用してフラグメントを一意に識別し、ページ上の他のコンポーネントと競合しないようにします。

次に、 <div class="jumbotron"/> 要素がコンテンツをラップし、 Bootstrapのジャンボトロンコンポーネントを適用します。このコンポーネントは、コンテンツを際立たせます。コンテンツ要素は次のとおりです。

<h1 class="display-4" ...>編集可能なジャンボトロン ... フラグメントの見出しを作成します。 Bootstrapの display-4 サイズスタイルを使用します。 data-lfr-editable- 属性により、見出しテキストが編集可能になります。 data-lfr-editable-id="03-text" 属性は要素を識別し、 data-lfr-editable-type="rich-text" 属性はコンテンツタイプを宣言します。
<p class="lead" ...>このテキストを編集... Clay の リード スタイルコンポーネントによって区別されるリード本文テキストです。 data-lfr-editable- 属性は、段落を編集可能にします。
<hr/> と次の <p ... 要素はそれぞれ水平線と別の編集可能な段落を生成します。
<クラス ="ボタン btn-primary btn-lg" ... 変更可能なリンクを指定します。 btn-primary クラスはそれをメインボタンとしてスタイル設定し、btn-lg はそれを拡大します。 href="#" 属性は、リンクがクリックされたときにユーザーをページの先頭に移動します。 data-lfr-editable-type="link" 属性により、リンクは編集可能になります。

フラグメントにリソースを含めることもできます。詳細については、「フラグメントにデフォルトのリソースを含める」を参照してください。

注

フラグメントと構成オブジェクトは JavaScript の引数として渡され、それぞれ fragmentElement および configuration パラメーターとして使用できます。

新しいフラグメントをインポートする

元のサンプルフラグメントと同じように、新しいフラグメントをインポートできます。

import コマンドを実行し、資格情報を提供します。
```
yarn run import
```
フラグメントセットが利用可能であることを確認します。 サイトメニュー () を開き、 デザイン → フラグメントに移動します。セットがリストに表示されます。

セットが利用可能です。

ここまでで、これで、フラグメントツールキットを使用してフラグメントを作成および管理する方法がわかりました。ツールキットコマンドの詳細については、フラグメントツールキットコマンドリファレンスを参照してください。

フラグメントツールキットの代替品

Fragments Toolkit は、Liferay 2024.Q1+/Portal GA112+ 以降では非推奨となります。

フラグメントの開発には、いくつかの代替手段を使用できます。

エクスポート/インポート: フラグメントをエクスポート/インポートする必要がある場合は、フラグメントアプリのエクスポート/インポートフラグメントオプションを使用して、フラグメントを .zip 形式でエクスポート/インポートできます。
基本的なカスタム要素を作成する: React コンポーネントを開発および管理する必要がある場合は、カスタム要素クライアント拡張を作成できます。この方法では、React コンポーネントをウィジェットに変換し、ページで使用できるようになります。

利用可能: Liferay DXP 2023.Q4+/Portal GA102+ Reactフラグメントを作成する: 静的JSインポートを使用して、フラグメント内のReactコンポーネントをインスタンス化します。以下のサンプルコードとそのコメントを参照してください。

静的 JS インポートを使用してフラグメント内の React コンポーネントをインスタンス化します。

// Import statements. Clay Components, React, and ReactDOM are already included in Liferay's importMap.
import React, { useState } from "react";
import ReactDOM from "react-dom";

// my-collection/my-fragment/Counter.jsx
// A simple Counter component to increase or decrease a given variable (count).
function Counter() {
const [count, setCount] = useState(0);
const increase = () => setCount((previousCount) => previousCount + 1);
const decrease = () => setCount((previousCount) => previousCount - 1);

// Rendering an output element that displays the current count, along with two buttons for increasing/decreasing the count.
return React.createElement(
   React.Fragment,
   null,
   React.createElement("output", null, count),
   React.createElement("button", { onClick: increase, type: "button" }, "+"),
   React.createElement("button", { onClick: decrease, type: "button" }, "-")
);
}

// my-collection/my-fragment/index.jsx
// Another functional React component. It renders an instance of the Counter component.
function MyFragment(props) {
console.log("MyFragment props", props);
return React.createElement(Counter, null);
}

// Cleanup process: Unmounts any existing React component associated with the specified DOM element (fragmentElement) before rendering a new component.
ReactDOM.unmountComponentAtNode(fragmentElement);
// Renders an instance of MyFragment with a configuration prop into the specified DOM element (fragmentElement) using ReactDOM.render.
ReactDOM.render(
React.createElement(MyFragment, { configuration }),
fragmentElement
);
// Cleanup process: Listens for the beforeNavigate event using Liferay.once and, when triggered, unmounts the React component associated with fragmentElement to clean up before navigating to another page.
// Liferay.once(event, callback); function is used to add an event listener that is executed only once when the specified event occurs.
Liferay.once("beforeNavigate", () =>
ReactDOM.unmountComponentAtNode(fragmentElement)
);

注

Liferay の importMapに含まれていない React コンポーネントをインポートする場合は、 importMap ClientExtensionを作成して追加できます。

ページの編集中に、ユーザーがフラグメントを操作したときに、フラグメントが複数回レンダリングされることがあります (フラグメント構成の変更時など)。 React コンポーネントが確実に再マウントされるようにするには、最初のクリーンアッププロセスにレイアウトモードをチェックする条件を追加します。以下のサンプルコードを参照してください。

// my-collection/my-fragment/index.jsx
// Checking the layout mode
if (props.layoutMode === 'edit') {
   React.DOM.unmountComponentAtNode(fragmentElement);
}

ReactDOM.render(...)

バンドラーを使用してフラグメントを構築します: JSX または複数のファイルを使用する場合は、インポートする前にファイルをバンドルする必要があります。

バンドラーのデフォルトの動作 (例: esbuild、 webpack、 vite-plugin-externals) は、すべてのコンテンツ (React、ReactDOM、およびすべての依存関係を含む) を 1 つの JS ファイルにマージすることであることに注意してください。したがって、インポートは importMapsに依存するため、最終バンドルに含めないライブラリを選択するメソッドを使用する必要があります。
可能な場合は CSS を使用する: SASS のみの機能が必要な場合を除き、SASS の代わりに標準 CSS を使用することを検討してください。

CSS でネストが利用できるようになりました。