WordPressのブロックエディアでオリジナルブロックを制作する方法をまとめです。
ブロックエディタはReactで制作されています。オリジナルブロックの制作にはReactの扱いに多少慣れが無いと難しいですので、Reactを触った事が無い場合はまずはReactのチュートリアルをやってみる事をおすすめします。
他にも開発環境やnode.jsなどの知識も必用となってきますが、この記事ではReactや開発環境、nodeについてなどの解説は省き、ブロックの作り方についてフォーカスして記載します。
制作方法の概要
制作方法
ブロックエディタの制作方法は以下の2つがあります。
- プラグインとして制作する
- テーマの一部として制作する
2つの制作方法がありますが、一般的な方法はプラグインとして制作する方法のようです。
公式チュートリアルでもプラグインとして制作する方法が紹介されているので、こちらの記事でもプラグインとして制作する方法を紹介します。
WordPressの開発環境
ブロックエディタはWordPressの中で動きますのでWordPressの開発環境が必要です。
ローカルでWordPressを動かす場合はPHP,SQL,Apache,データベースを動かす事ができる環境を用意しなければいけません。
今回はMAMPを使用して進める事を前提とします。
他の実行環境を使用しても作り方は同じですので問題ありません。
ブロックエディタの開発環境
Reactをコンパイルするための開発環境が必要になってきますが、開発環境は自作する方法と@wordpress/create-blockを使って作る方法があります。
開発環境を自作すると時間が掛かってしまうので@wordpress/create-blockを使用して制作するのがおすすめです。
そもそもReactで開発をしないという選択肢
この記事ではReactを使用しての開発ですが、そもそもコーディングをするのではなく、GUIベースでオリジナルブロックを制作する事も可能です。
ですが、できる事が制限される事と、編集画面での見た目が直観的ではないです。
時間とクオリティを相談し、Genesis Custom Blocksにするという選択肢も持っておきましょう。
開発環境とひな形の制作
@wordpress/create-blockを使用してブロック開発環境とオリジナルのブロックのひな形を制作します。
@wordpress/create-blockを実行するとプラグインとして環境が制作されます。
WordPressはプラグインをwp-conent/plugins/の中に格納しますのでwp-conent/plugins/の中で以下のコマンドを使用して@wordpress/create-blockをインストールします。
npx @wordpress/create-block [slug]
slug
出力先のディレクトリとプラグイン名を設定します。
今回はプラグイン名をblock-tutにします。
名前を好きに決めて良いですが名前のルールとして一般的に全て小文字で単語の区切りはハイフンでつないで制作する事が多いです。
ですので今回は以下のような形でコマンドを入力します。
npx @wordpress/create-block block-tut
ひな形のディレクトリ
インストールが完了すると以下のような形のデータがwp-conent/plugins/内に制作されたと思います。
wp-content └── plugins └── block-tut // 制作したプラグイン ├── build // コンパイル後、実際に使用するコードが入る ├── node_modules // パッケージ ├── src // 開発用のコードが入る ├── .editorconfig ├── .gitignore ├── block-tut.php // プラグインのエントリーポイント ├── package-lock.json ├── package.json └── readme.txt
開発で主に使用するのはblock-tut.phpとsrcです。
block-tut.phpはプラグインのエントリーポイントとなり、こちらに記載したものがプラグインに設定に反映されます。
srcディレクトリ内でブロックを制作し、コンパイルするとbuildないへ出力されます。
実際にWordPressがブロックを反映するために見るコードはbuildのコードですので、本番反映時はbuildとblock-tut.phpの2つをデプロイします。
srcディレクトリ
@wordpress/create-blockをインストールした時点でsrcディレクトリの中にサンプルとなるブロックが1つ入り、同時にコンパイルされたものがbuildの中にも入っています。
このサンプルを改造しブロックを作っていく流れになりますが、一旦この状態でも問題なくプラグインが動作するか確認してみましょう。
プラグインを有効にする
MAMPなどでローカル環境を起動させ、WordPressの管理画面を開きます。
メニューのプラグインからプラグイン一覧を開くと今回制作したプラグインである「block-tut」が表示されていますので「有効化」ボタンをクリックしてプラグインを有効化しましょう。
新しく記事を制作し、ブロック一覧を見るとBlock Tutというサンプルブロックがあるはずです。
ブロックを選択し表示されると「Block Tut – hello from the editor!」が表示されるだけですが、ブロックを新たに追加する事ができました。
サンプルブロックを改造して作り方の概要を知る
このサンプルブロックを改造し、どこを触ればどうなるのか、ブロック制作の概要を掴みましょう。
まず、src内を見ると以下のファイルが表示されます。
- block.json
- edit.js
- editor.scss
- index.js
- save.js
- style.scss
このファイルのそれぞれの役割を理解しましょう。
block.json
ブロックの設定を記載するファイルです。
実際にblock.jsを開くと以下のようなコードが記載されています。
{ "$schema": "https://schemas.wp.org/trunk/block.json", "apiVersion": 2, "name": "create-block/block-tut", "version": "0.1.0", "title": "Block Tut", "category": "widgets", "icon": "smiley", "description": "Example static block scaffolded with Create Block tool.", "supports": { "html": false }, "textdomain": "block-tut", "editorScript": "file:./index.js", "editorStyle": "file:./index.css", "style": "file:./style-index.css" }
これがブロックの設定です。
基本的にどのブロックにも共通して設定しなければいけないフォーマット部分がほとんどですが、ブロック制作するにあたって以下の項目を理解しておけばよいでしょう。
name
ブロックを識別するための名前を決めます。
現在は1つのブロックしか制作していないませんが後に複数のブロックを制作する際に被ってはいけません。
値を見ると/(スラッシュ)で区切られていますが、この形式を使う事が一般的です。
スラッシュの初めがnamespaceとなります。
今回は@wordpress/create-blockを使用しているのでcreate-blockというnamespaceが付いています。
今後ブロックを複数増やす場合も「create-block/好きな名前」という形にするとよいでしょう。
title
ブロックエディタで一覧などに表示されるブロックの名前(タイトル)を入力します。日本語でも問題ありません。
category
ブロックが一覧のどのカテゴリに属するのかを設定します。
デフォルトで存在するカテゴリは以下になります。
- text
- media
- design
- widgets
- theme
- embed
他にもオリジナルのカテゴリを追加する事も可能です。
くわしくは公式のblock.json のメタデータページに記載されています。
icon
ブロックを選択した時や、一覧でタイトルと一緒に表示されるiconを設定する事が可能です。
使用出来るiconは公式のDashiconsページに記載されています。
description
一覧にブロックが表示される際にブロックの簡単な説明文が表示されますが、その説明文を入力します。
日本語の使用可能です。
textdomain
ブロック名を記載します。
namespaceは必要ありません。
index.js
こちらのファイルがブロックを制作する際のエントリーポイントとなるファイルです。
実際にindex.jsファイルを見るとコメントなどいろいろ記載されていますが、重要な箇所をピックアップして解説します。
// ブロックをあたらしく制作すうための関数を読み込み import { registerBlockType } from '@wordpress/blocks'; // フロント側で使用するスタイルを読み込み import './style.scss'; // 編集ページに関する処理を記載しているjsファイル import Edit from './edit'; // 保存ボタンを押した時の処理を記載いているjsファイル import save from './save'; // 設定ファイルを読み込み import metadata from './block.json'; registerBlockType( metadata.name, { edit: Edit, save, } );
index.jsのページは全く難しい事はありません。
やっていることはファイルを読み込んで新しいブロックを追加する処理を記載しているだけです。
新しいブロックを追加するにはregisterBlockType関数に2つの引数を渡します。
第一引数はブロックの名前です。
これはblock.jsonに記載したnameの部分をセットします。
第二引数にブロックの設定を記載します。
ブロックは2つの処理が必要です。
- edit:編集ページ(ブロックエディタ)で使用する処理です。
- save:保存ボタンを押した時の処理。どのようなhtml構造で保存するかを決める処理です。
他にstyle.scssを読み込んでいますが、これはフロント側で適応させたいcssを記載します。scssの文法で記載する事が可能で、自動的にcssにコンパイルしてくれます。
style.scssの他にもeditor.scssがありますが、これは編集ページで当てるcssを記載するscssファイルです。
もし、cssファイルをまとめる場合はこの読み込みは記載しなくても問題ありません。
edit.js
index.jsの説明で記載したように、編集ページで使用する処理を記載します。
例えば編集ページでの見た目はこうしたいのでhtml構造をこう記載する。
サイドバーで数値を入力させてカスタマイズできるように…と様々な設定をする事が可能となります。
コードはReactベースです。
editor.scss
編集ページに反映させたいcssを記載します。
save.js
index.jsの説明で記載したように、保存ボタンを押したときの処理です。
保存ボタンを押した時点で取得できるのはデータのみです。
それをどのようなhtml形式で保存するかはこのsava.jsで記載したコードで決めます。
こちらもReactベースで制作します。
style.scss
フロント側に反映させたいcssを記載します。
実際に改造してみる
@wordpress/create-blockで制作したサンプルブロックは文字が表示されるだけで、編集などはできません。
これをテキストを編集し、保存ができるようにしてみましょう。
edit.jsとsave.jsを触りますので編集と保存ができれば一通り概要がつかめるはずです。
値の編集・保存ができるようにするためには以下の3つのファイルを変更する必要があります。
- block.json
- edit.js
- save.js
block.json
値を保存するためには保存する場所が必要です。
ですがそもそもブロックエディタでは入力した値をどのように保存しているのかというと2つの方法があります。
1つは、htmlの値として保存する方法です。
例えば以下のようなhtmlがあり、リンク先の値やリンクのテキストを変更したいとします。その場合、再修正する場合に、既存の値を参照する必要がありますが、その値はhtmlのhrefやコンテンツ部分から参照します。
htmlに記載されているもの自身がメモリのような役割をしているわけです。
<a href="https://sample.com">リンク</a>
上の話は想像がつきやすいかと思いますが、この方法はブロックエディタでは一般的ではりません。理由は保存出来る値の自由度が制限されるからです。
2つ目の方法。これが一般的な値の保持の仕方です。
2つ目はhtmlのコメントに残す方法です。
<!-- wp:image {"id":1525,"sizeSlug":"medium","linkDestination":"none"} --> <figure class="wp-block-image size-medium">略...</figure> <!-- /wp:image -->
ビジュアルエディタからコードエディタへ変換するとこのような形でコメントとセットになったhtmlコードで記事が構築されている事がわかります。
このコメント部分がメモリの役割を残し、keyとvalueからなるobject形式のコメントで値を保存しています。
値を参照する必要があればこのコメント部分を解析して取得するというわけです。
ここからが本題ですが、block.jsonでは値の保存方法の選択と、どのような値を保存するのかという事を設定します。
今回はコメント形式で保存したいのでまずはblock.jsonを以下のように修正しましょう。
{ "$schema": "https://schemas.wp.org/trunk/block.json", "apiVersion": 2, "name": "create-block/block-tut", "version": "0.1.0", "title": "Block Tut", "category": "widgets", "icon": "smiley", "description": "Example static block scaffolded with Create Block tool.", "supports": { "html": false }, "attributes": { "textContent": { "type": "string", "default": "" } }, "textdomain": "block-tut", "editorScript": "file:./index.js", "editorStyle": "file:./index.css", "style": "file:./style-index.css" }
追加したのは13行目のattributesプロパティです。
attributesにセットしたデータ構造がコメントのobejct構造になり、この中に値を保存す事が可能となります。
今回はテキストを編集・保存がしたいので、保存する値を1つしか設定していません。
attributes内のtextContentプロパティです。このtextContent名前は任意に決める事ができ、これ1つ1つが変数のようなものです。まず、変数名をきめ、変数にはtypeを持たせる必要があります。
今回はテキストを入れるのでstringとします。
typeはstringのほかにも以下が存在ます。
- null
- boolean
- object
- array
- number
- string
- integer
type以外にも初期値を設定できるdefaultがあったりといくつかオプションとして設定する事が可能です。
block.jsonのattributes設定について詳しくは公式ドキュメントを参照ください。
もし保存したい値の種類が複数ある場合はattributesの中にカンマ区切りでいくつでも追加する事が可能です。
これで保存先(変数)の設定は完了です。
edit.js
値を保存する変数の設定が完了したので次は編集ページに表示する内容をedit.jsから設定していきます。
edit.jsの中身を見るとコメントがいろいろ記載されていますが、重要な部分をピックアップし、解説します。
// 国際化対応 import { __ } from '@wordpress/i18n'; // エディタを動かすために必要なもの import { useBlockProps } from '@wordpress/block-editor'; // 編集ページで当てたいcss import './editor.scss'; export default function Edit() { return ( <p { ...useBlockProps() }> { __( 'Block Tut – hello from the editor!', 'block-tut' ) } </p> ); }
i18nをインポートしていますが、これは国際化対応です。
WordPressは世界で使用される事を想定しております。
その場合、言語の違いが出てきますが、i18nを使用する事で国際的な翻訳のフォーマットに沿った形でコードを書く事ができます。
今回は日本語でのみ使うという想定でこちらは消しておきましょう。
Edit関数のpタグ内で__()という形で使用されていますが、こちらも消して問題ありません。
次にuseBlockPropsですが、こちらはエディタを動かすために最低限必要なものです。必ずコンテンツのrootに{ …useBlockProps() }という形でつけます。
最後にeditor.scssですが、こちらは編集ページでのみ適応したいcssの読み込みです。
別でcssをまとめている場合など、cssが必要ない場合は消しても問題ありません。
現在はテキストが表示されているだけですが、これを編集可能にします。
では、edit.jsの中を以下のように修正しましょう。
import { useBlockProps,RichText } from '@wordpress/block-editor'; export default function Edit({ attributes, setAttributes }) { const { textContent } = attributes; const onTextChanged = ( text ) => { setAttributes({ textContent: text }); }; return ( <p { ...useBlockProps() }> <RichText tagName="p" value={textContent} onChange={onTextChanged} placeholder={ 'テキストを入力してください...' } className={ 'p-text-area u-font -size_s' } /> </p> ); }
テキストを編集するには@wordpress/block-editorに格納されているRichTextコンポーネントを使用する事で可能です。
RichTextにはpropsとして以下を設定します。
tagName | htmlタグ名をセットします。 |
value | 表示するtextをセットします。 |
onChange | 値に変更があった時の処理をセットします。 |
placeholder | 入力が何もなかった時に表示するplaceholderの値をセットします。 |
className | class名をセットします。 |
valueにはtextContentという変数をセットしています。
textContentはblock.jsonでセットした変数です。
Edit関数の引数からattributesとsetAttributesを取得していますが、attributesからblock.jsonでセットした値を取得する事ができます。
setAttributesは変更があった際にattributesに値を入れなおすための関数です。
テキストの値に変更があった場合はonTextChanged関数を通して値をattributesに保存します。
値の保存はsetAttributes関数を使用します。
これで値の編集が可能となり、変更した値をattributesに保存する事ができました。
WordPressの編集画面でこのブロックを使用し、記事を公開もしくは保存・更新すると値が保存され、ページをリロードしても保存した値が保たれているはずです。
ですが、これだけでは値を変数(コメントとして)に保存する事ができただけで、ユーザーが見る画面にどのようにその値を表示するのかは設定していません。
なので次のsava.jsでユーザー側へ表示するhtmlを組んでいきます。
save.js
sava.jsではユーザーが見る画面にどのような形でhtmlを出力するのかの設定をしていきます。
表示するためには先ほどattributesに保存した値を取得する必要があるわけですが、Edit関数と同じように引数からattributesとして取得する事が可能です。
save.jsを以下のように修正しましょう。
export default function save({ attributes }) { const { textContent } = attributes; return ( <p { ...useBlockProps.save() }> { textContent } </p> ); }
これで完成です。
実際に編集ページを開き、ブロックを使用して値の編集保存をし、フロント側で見てみてください。
次のステップ
- 複数のブロックを開発できる環境の制作
- 画像を表示する
- 入れ子構造(子供の制御/繰り返し/親の値を取得/子供の値を取得)
- サイドバーをカスタマイズする(inputから値をセットして反映まで)
- ラジオボタン
- チェックボックス
- 範囲選択(レンジ)
- カテゴリ一覧を取得する
- ダイナミックブロックの作り方
- 他の記事を表示する