コンテンツへスキップ

はじめに

このガイドでは、Blockstudioをセットアップし、最初のカスタムブロックを作成します。

インストール

シェル
composer require blockstudio/blockstudio

Blockstudioはcomposer/installers経由でプラグインとしてインストールするか、テーマ内に直接バンドルできます。すべてのインストール方法については、Composerのドキュメントをご覧ください。

Composerでインストールした場合、更新はComposer経由で行われます。組み込みのGitHubアップデーターは自動的に無効になります。

手動インストール

最新リリースをGitHubからダウンロード

zipをWordPressプラグインディレクトリにアップロードし、プラグインを有効化します。手動インストールの場合、組み込みのGitHubアップデーターにより、WordPressダッシュボードで自動更新通知を受け取れます。

どちらのインストール方法でも、Markdown、YAML、アップデーターの各ライブラリとその依存関係は、非公開のコピーとして同梱されます。他のプラグインやテーマが提供するバージョンを使用したり、置き換えたりすることはありません。アプリケーションでこれらのライブラリを直接使用する場合は、独自の Composer 依存関係をインストールしてください。Blockstudio に同梱されているコピーは内部用であり、公開される PHP API ではありません。

認証済みの更新確認

手動インストールでは、デフォルトで GitHub を匿名で確認します。1つの送信元 IP を複数のサイトで共有すると、GitHub の匿名 API 利用枠を使い切り、更新確認時に HTTP 403 応答を受け取ることがあります。7.7.4 では、wp-config.php の GitHub パーソナルアクセストークンを、WordPress の読み込み前に設定します:

PHP
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');

このトークンには、公開リポジトリ情報へのアクセス権限だけが必要です。書き込み権限は付与しないでください。サーバー側の設定に保管し、バージョン管理、blockstudio.json、ブロック属性、フロントエンドコードには含めないでください。アップデーターは、認証済みの確認とリリースのダウンロードのため、同梱された GitHub クライアントにトークンを渡します。無関係なリポジトリやその他のダウンロードホストへのリクエストには、トークンは送信されません。

環境変数で管理するシークレットには、MU プラグインからトークンを設定または上書きできます:

PHP
<?php
add_filter('blockstudio/updater/token', function ($token) {
  return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});

このフィルターは、テーマの読み込み前に Blockstudio がアップデーターを初期化するときに実行されます。functions.php ではなく、MU プラグインに登録してください。空文字列を返すと、定数が定義されていても認証が無効になります。値が空、または文字列以外の場合、確認は匿名で行われます。トークンは任意です。設定しなくても、既存の更新動作は変わりません。Composer のインストールでは、引き続き更新に Composer を使用し、このアップデーターは初期化されません。

最初のブロックを作成する

1. ブロックディレクトリを作成する

テーマ内に新しいディレクトリを作成します:

コード
my-theme/
  blockstudio/
    my-first-block/
      block.json
      index.php

2. ブロックスキーマを定義する

ブロック設定を記述したblock.jsonを作成します:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/my-first-block",
  "title": "My First Block",
  "category": "common",
  "icon": "star-filled",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Hello World"
      },
      {
        "id": "content",
        "type": "textarea",
        "label": "Content"
      }
    ]
  }
}

3. テンプレートを作成する

レンダリング用のindex.phpを作成します:

PHP
<div class="my-first-block">
  <h2><?php echo $a['heading']; ?></h2>
  <p><?php echo $a['content']; ?></p>
</div>

Twigテンプレートを使う

BlockstudioはTwigテンプレートを標準でサポートしています。代わりにindex.twigを使用してください:

Twig
<div class="my-first-block">
  <h2>{{ a.heading }}</h2>
  <p>{{ a.content }}</p>
</div>

スタイルを追加する

同じフォルダーにstyle.cssファイルを作成します:

CSS
.my-first-block {
  padding: 2rem;
  background: #f5f5f5;
}

ブロックの使用時にBlockstudioがこのスタイルシートを自動的に読み込みます。

翻訳

Blockstudioのエディターコントロールと管理画面の概要では、WordPressを通じてblockstudioテキストドメインのJavaScript翻訳を読み込みます。一致する言語パックをインストールするか、翻訳ツールを使ってwp-content/languages/plugins/にスクリプト翻訳JSONファイルを生成してください。利用可能な翻訳がない文字列は英語のまま表示されます。これはBlockstudio独自のインターフェースを翻訳するもので、ブロックで定義するコンテンツやフィールドラベルは対象外です。

次のステップ

これでブロックをWordPressエディターで使えるようになりました。ドキュメントを引き続き確認して、次の内容を学びましょう:

ブロックライブラリを構築する

1つのブロックから完全なライブラリへ。デザイントークン、セクションパターン、リピーター、画像、ページ構成について説明します。