2018.12.11

【Craft 3 サイト構築の基本】「ニュース」セクションの作成（エントリデータのインポート編）

これは Craft CMS Advent Calendar 2018 11日目の記事です。
連載「サンプル制作で覚える Craft 3 サイト構築の基本」として「ニュース」セクションに関する設定ができましたので、エントリデータをインポートしてみます。

ここでは、次の作業を行います。

プラグインのインストール
JSON データの準備
プラグインの設定
インポートの実行
「リンク」入力タイプのインポート

プラグインのインストール

Craft 3 でエントリデータをインポートするには、プラグインを追加する必要があります。

グローバルナビゲーションから プラグインストア に移動後、キーワード feedme でヒットする Feed Me プラグインをクリックします。カテゴリーやユーザー、アセットなどもインポート対象にしたい場合は、有償版の Feed Me Pro を利用することになります。

プラグインの説明などが記載されたモーダルウィンドウが開きますので、右上にある インストール ボタンをクリックします。

プロジェクトルートの composer.json にプラグインが追記され、内部的に composer update が実行されます。

終了するとプラグインのウェルカムページへ遷移し、グローバルナビゲーションに Feed Me が追加されています。

なお、ここではエントリデータをインポートで必要な基本操作の解説となりますので、より詳しい仕様やカスタマイズ方法についてはプラグインの公式リファレンスを参照してください。

Feed Me - Installation & Setup | Verbb：
https://verbb.io/craft-plugins/feed-me/docs/get-started/installation-setup

JSON データの準備

インポートにあたり、データソースとなる JSON ファイルを用意します。
なお、Feed Me プラグイン自体は CSV や XML もサポートしていますので、気になる方はそちらも試してみてください。

素材データ

公式デモサイトの「ニュース」セクションに含まれるエントリデータの JSON をリポジトリに用意してあります。
「素材データ専用リポジトリ vol-6 ブランチの web/import ディレクトリ」をローカル環境の web 直下に配置してください。

その後、下記 URL のようにローカル環境のホスト名を利用してブラウザからアクセスし、内容を表示できることを確認します。

https://craft3.dev/import/entry/news_default.json
https://craft3.dev/import/entry/news_link.json

Feed Me プラグインのデータソースには URL を指定するため、あらかじめ用意しておく必要があります。

データ構造

エントリごとのデータ構造を見てみましょう。それぞれのエントリは items キーの配列にオブジェクトとしてセットされています。

{
  "items": [
    {
      "title": "タイトル",
      "slug": "entry-slug",
      "postDate": "2018-12-11 00:00:00",
      "featuredEntry": 0,
      "featuredImage": "augmented-reality.jpg",
      "shortDescription": "概要文",
      "heading": "大見出し",
      "subheading": "小見出し",
      "Matrix": {
        "articleBody": [
          {
            "newSection_sectionHeading": "セクション見出し"
          },
          {
            "heading_heading": "見出し"
          },
          {
            "text_text": "テキスト",
            "text_positoin": "center"
          },
          {
            "pullQuote_pullQuote": "リード文",
            "pullQuote_positoin": "left"
          },
          {
            "image_image": "awesome-cities.jpg",
            "image_caption": "キャプション",
            "image_positoin": "right"
          },
          {
            "gallery_images": [
              "bike.jpg",
              "glasses.jpg",
              "skateboard.jpg"
            ]
          },
          {
            "quote_quote": "引用",
            "quote_attribution": "帰属",
            "quote_positoin": "center"
          }
        ]
      }
    }
  ]
}

title（タイトル）、slug（スラグ）、 postDate（投稿日）などの基本データに加え、featuredEntry（固定表示フラグ）といった必要なフィールドを定義します。

ポイントになる項目は、次の通りです。

キー	概要
featuredEntry	`LightSwitch` フィールドのため、`0` または `1`
featuredImage など	画像を1つだけ選択可能な `アセット` フィールドのため、ファイル名を `文字列` として記述
shortDescription など	`Redactor` フィールドは HTML が保存されるため、`JSON エンコードした文字列` を記述
Matrix	行列フィールドに関するデータ
Matrix / articleBody	`記事本文` フィールドに関するデータ
Matrix / articleBody / gallery_images	画像を3つまで選択可能な `アセット` フィールドのため、`配列` にファイル名を列挙

「newSection_sectionHeading は articleBody 行列フィールドの newSection ブロックの sectionHeading フィールドを指す」というように、キーを 対応するフィールドのハンドル に揃えておくとあとから判別しやすくオススメです。

また、articleBody に含まれるブロックごとのデータは、上から順にインポートされます。そのため、実際のエントリの内容に合わせてブロックが重複・増減したり、並び順が変わります。

プラグインの設定

グローバルナビゲーションから FeedMe に移動後、画面右上にある New feed ボタンをクリックします。

新しいフィードの作成

次の内容を入力してから Save & Continue ボタンをクリックします。

ラベル	値
Name	「ニュース」エントリ（入力タイプ：デフォルト）
Feed URL	https://craft3.dev/import/entry/news_default.json
Feed Type	JSON
Element Type	Entry
Section	ニュース
Entry Type	デフォルト
Import strategy	`Create new elements` のみ ON
Passkey	デフォルトのまま
Backup	ON

Feed URL のホスト名は、実際のローカル環境にあわせてください。このとき、以前の記事「ローカル環境を Docker で構築してみた」を参考に用意されたローカル環境だと、https でエラーになるかもしれません。その際は http で指定してください。

今回は新しいエントリとして追加する目的のため Import strategy で Create new elements のみ ON としていますが、その他のチェックボックスを利用して既存エントリを更新・削除することもできます。

なお、Backup についてはお好みで切り替えてください。個人的には SQL クライアントやコマンドラインからバックアップを別途取得した方が早いため、都度 OFF にしています。

フィードのオプション設定

次の内容を入力してから Save & Continue ボタンをクリックします。

ラベル	値
Primary Element	/items (x6 elements)
Pagination URL	No Pagination URL

各エントリのデータは items キーに配列でセットしてあるため、Primary Element と紐づけています。

フィールドマッピングの設定

次に、JSON に存在する項目とエントリのフィールドを紐付けます。

Entry Fields

Craft 3 のエントリが持つ、共通フィールドの設定です。Feild と Feed Element を次の内容と同じになるよう調整します。

Feild	Feed Element
Title	`<title>`
Slug	`<slug>`
Post Date	`<postDate>`

上記以外のフィールドはインポート対象ではないため、デフォルトのままとします。

コンテンツ Fields

エントリ編集画面の コンテンツ タブに含まれるフィールドの設定です。Feild と Feed Element を次の内容と同じになるよう調整します。

行列フィールドのマッピングが少し面倒に感じるかもしれませんが articleBody[newSection][sectionHeading] と <Matrix/articleBody/newSection_sectionHeading> のようにハンドル名で判別しやすくしたつもりです。なお、Feed Element に表示されるサンプルデータは JSON の最初のデータとなるため、サンプルデータの1件目にすべてのブロックを意図的に定義してあります。

Feild	Feed Element
固定表示フラグ	`<featuredEntry>`
メイン画像	`<featuredImage>`
概要文	`<shortDescription>`
大見出し	`<heading>`
小見出し	`<subheading>`
新しいセクション: セクション見出し	`<Matrix/articleBody/newSection_sectionHeading>`
見出し: 見出し	`<Matrix/articleBody/heading_heading>`
テキスト: テキスト	`<Matrix/articleBody/text_text>`
テキスト: 位置	`<Matrix/articleBody/text_position>`
リード文: リード文	`<Matrix/articleBody/pullQuote_pullQuote>`
リード文: 位置	`<Matrix/articleBody/pullQuote_position>`
画像: 画像	`<Matrix/articleBody/image_image>`
画像: キャプション	`<Matrix/articleBody/image_caption>`
画像: 位置	`<Matrix/articleBody/image_position>`
ギャラリー: 画像	`<Matrix/articleBody/gallery_images>`
引用: 引用	`<Matrix/articleBody/quote_quote>`
引用: 帰属	`<Matrix/articleBody/quote_attribution>`
引用: 位置	`<Matrix/articleBody/quote_position>`

画像に関するフィールドのマッピングのオプションで「Create asset from URL」を ON にすると、指定された URL から画像を取得することもできます。今回のように画像に関する JSON データに augmented-reality.jpg のようなファイル名をセットしている場合は、フィールドに対応するボリュームのアセットとして画像があらかじめ登録されている必要があります。

また、行列フィールドの 位置 に関する JSON データには left のようなプルダウンの値がセットされているため、マッピング時に「Data provided for this field is: Value」として値で比較するようにしています。