microCMS

拡張フィールドを簡単に作れるSDKとテンプレートを公開しました

はじめに


microCMS では拡張フィールド機能を提供しています。
これは microCMS に iframepostMessage でデータを渡すサイトを用意して、そのサイトの URL を microCMS のフィールドに設定することで、任意のデータを microCMS に登録できる機能です。

現時点ではサードパーティのものも含めて、以下のような拡張フィールドが開発 & 公開されています。


このように様々なことが行えます。
JSON にシリアライズ可能なデータであれば、どんなものでも連携可能です。

今まではこれらを実現するために postMessage を用いたプロトコル を把握する必要がありました。
しかし本日公開した microcms-field-extension パッケージ (GitHub) を使うと、プロトコルの詳細を把握せずとも簡単に外部データ連携の仕組みを作ることができます。

この記事では microcms-field-extension の利用方法を紹介します。

環境構築


Next.js の環境構築


ブラウザですぐに開発して Vercel にデプロイできる CodeSandbox を用意しました。

create-next-app で使えるテンプレートも用意されています。

$ npx create-next-app my-app --example https://github.com/microcmsio/microcms-field-extension/tree/main/examples/nextjs
$ cd my-app
$ export NEXT_PUBLIC_MICROCMS_ORIGIN='https://example.microcms.io'
$ yarn dev


React の環境構築


Next.js を使わずに素の React を使うこともできます。
こちらもブラウザですぐに開発して Vercel にデプロイできる CodeSandbox を用意しました。

create-react-app で使えるテンプレートリポジトリも用意されています。

$ npx create-react-app my-app --template microcms-field-extension-app
$ cd my-app
$ export REACT_APP_MICROCMS_ORIGIN='https://example.microcms.io'
$ npm start


create-react-app を使わない場合は以下のコマンドでパッケージをインストールできます。

$ npm i microcms-field-extension-react


フレームワーク無しの環境構築


microcms-field-extension-api パッケージを使うことによって、 Vue.js など React 以外のフレームワークでも簡単にフィールドを拡張できます。
こちらもブラウザですぐに開発して Vercel にデプロイできる CodeSandbox を用意しました。

以下のコマンドでパッケージをインストールできます。
詳しい使用方法は README を参照してください。

$ npm i microcms-field-extension-api


使用方法


Next.js を使う場合でも React を使う場合でもフレームワーク無しでも基本的な使い方は同じです。
最初に SetupOption を指定して、データを更新する際に Message を指定するだけです。

SetupOption は以下のようなオブジェクトです。

{
  /**
   * この iframe はこのオリジンからのみメッセージを受け取ります。
   * "*" を指定すると全てのオリジンからメッセージを受け取ることができますが、意図しないオリジンからメッセージが注入されるリスクがあるため "*" の指定は推奨しません。
   * 必須。
   */
  origin: "https://example.microcms.io",

  /**
   * microCMS 上で表示される iframe フィールドの高さ。数値 or 文字列。
   * オプショナル。
   */
  height: 200,

  /**
   * microCMS 上で表示される iframe フィールドの幅。数値 or 文字列。
   * オプショナル。
   */
  width: "100%",

  /**
   * iframe フィールドに保存済みの初期値を取得した際のコールバック。
   * オプショナル。
   */
  onDefaultData: (message) => console.log(message),

  /**
   * set の呼び出しが成功した際のコールバック。
   * オプショナル。
   */
  onPostSuccess: (message) => console.log(message),

  /**
   * set の呼び出しが失敗した際のコールバック
   * オプショナル。
   */
  onPostError: (message) => console.log(message),
}


Message は以下のようなオブジェクトです。

{
  id: "item_123456",

  /**
   * 管理画面で表示されるテキスト。
   * オプショナル。
   */
  title: "foo",

  /**
   * 管理画面で表示されるテキスト。
   * オプショナル。
   */
  description: "foo\nbar\n",

  /**
   * 管理画面で表示される画像のURL。
   * オプショナル。
   */
  imageUrl: "http://placehold.jp/150x150.png",

  /**
   * 管理画面で表示される更新日時。
   * オプショナル。
   */
  updatedAt: "2022-04-26T00:27:13.176Z",

  /**
   * JSON にシリアライズ可能な任意のオブジェクト。
   * この値がコンテンツ API で返されます。
   * 必須。
   */
  message: {},
}


React (Next.js) を使う場合は以下のようなコードが動作します。

import { useFieldExtension } from "microcms-field-extension-react";
import { ChangeEvent } from "react";

// CHANGEME
const origin =
  process.env.REACT_APP_MICROCMS_ORIGIN || "https://example.microcms.io";

export default function App() {
  const { data, sendMessage } = useFieldExtension("#00ff00", { origin });

  const onChangeColor = (e: ChangeEvent<HTMLInputElement>) => {
    sendMessage({ id: "color", data: e.target.value });
  };

  return (
    <input type="color" value={String(color)} onChange={onChangeColor} />
  );
}


ここで color の型は any です。プロダクションでは例えば zod などでバリデーションをすることが望ましいです。

また、 useFieldExtension の第2引数には width, height, onPostSuccess, onPostError などのフィールドを指定することができます。
アプリケーションの要件に応じて拡張フィールドの高さを変えたり、 データをセットした後のコールバックで通信の成否をトーストでユーザに伝える仕組みを追加するとより親切です。

その他の仕様例を examples ディレクトリから探すこともできます。

おわりに


拡張フィールド機能はとてもパワフルで遊びがいのある仕組みですが、今までは敷居が高い仕組みでもありました。
今後は新たな連携を作るのがより簡単になり、 様々な連携が公開され、 microCMS はよりパワフルなプラットフォームになると思います。
ぜひこの SDK を使って素敵な連携を開発してみてもらえると嬉しいです。

まずは、無料で試してみましょう。

APIベースの日本製ヘッドレスCMS「microCMS」を使えば、 ものの数分でAPIの作成ができます。

microCMSを無料で始める

microCMSについてお問い合わせ

初期費用無料・14日間の無料トライアル付き。ご不明な点はお気軽にお問い合わせください。

お問い合わせ

microCMS公式アカウント

microCMSは各公式アカウントで最新情報をお届けしています。
フォローよろしくお願いします。

  • twitter
  • facebook
  • github

ABOUT ME

λ沢
microCMS のバックエンド担当。Go, TypeScript, AWS が得意です。好きな AWS サービスは CloudWatch Logs です。