WordPress プラグイン ユーザーガイド
このガイドは 4 つのセクションで構成されています。§1 クイックスタート ではスクリーンショットと共に最初のショートコードを公開するまでのすべての手順をたどれます。§2〜§4 はもっと深く作り込んだり、問題を解決したりするときに参照する詳細リファレンスです。
1. クイックスタート
WordPress の管理画面で 3Min API → + New メニューを開くと、ショートコードビルダーが表示されます。上から順に 4 ステップをたどれば、ショートコードがひとつ完成します。
はじめての方は、3Min API を見てまわる でエンドポイントと API キーの発行方法を先に確認するか、ChatGPT Apps で「3Min API」を検索して会話から始めることもできます。
1.1 エンドポイント入力 + テスト
- エンドポイント ID と API key を貼り付け、HTTP メソッド(Get Record / Get List / POST)を選びます。
- Test endpoint ボタンを押すと実際のリクエストが送信され、レスポンスがその場にインラインで表示されます。
- レスポンスが正常であれば、次のカード(変数、テンプレート)が自動で埋まります。
POST エンドポイントはビルダー内で事前にテストできません。ショートコードを保存してページに貼り付けてから、フォームを送信して確認してください。
1.2 変数の確認
テストレスポンスを解析して、利用できるテンプレート変数 がチップ形式で表示されます。代表的な変数:
{{response}}— レスポンス全体{{response.payload}}— ユーザーレコードの本体{{response.payload.title}}、{{response.id}}のような「ドット記法」で深い階層にアクセス
これらの変数を次のステップの HTML/CSS にそのまま挿入すれば、安全に処理されます。
1.3 テンプレート選択 + AI でデザイン
- メソッド別のテンプレートを選ぶと、HTML/CSS·JavaScript パネルが自動で埋まります。
- 上部の Copy AI prompt ボタンを押すと、選んだテンプレートのコード + プラグインの作成ルール + 自動検出された変数がシステムプロンプトにまとめられ、クリップボードへコピーされます。
- ChatGPT / Claude / Gemini のような LLM にそのまま貼り付け、「もう少しミニマルに」「ダークモードをデフォルトに」「星評価も見せて」のような自然な言葉でデザインを整えていきましょう。
- 結果を HTML/CSS パネル(必要なら JavaScript パネルにも)に戻して、右側のライブプレビューで確認します。
JavaScript パネルはオプションです。JavaScript はサイト管理者のみ保存できます。
1.4 保存 + ページに公開
- ショートコード名 を入力します(初回保存後は変更できません)。
- Save を押すと、次の形式のショートコードが生成されます:
[3minapi name="your-snippet-name"] - この 1 行を記事・固定ページ・ウィジェット・ブロックのどこにでも貼り付ければ、その場所に作成した UI がレンダリングされます。
同じショートコードを複数のページで再利用でき、1 ページに別々のショートコードを複数置くこともできます — それぞれ独立してレンダリングされます。
2. HTML/CSS ガイド
HTML/CSS は保存時にセキュリティ上の理由で一部のコードが自動的に取り除かれます。安全に使用できるタグ・属性・CSS を以下で確認してください。
2.1 レンダリングの仕組み
- Get Record: ページが開いたときにサーバーで API を呼び出し、レスポンスを含む HTML/CSS が描画された後で JavaScript コードが実行されます。
- Get List: Get Record と同じ流れです。ただし、最初のページだけサーバーでレンダリングされ、次のページからは JavaScript の
threeminApi.fetch()で取得します(「Load more」ボタンなど)。 - POST: フォームの HTML/CSS が先にレンダリングされ、ユーザーがフォームを送信したときに API 呼び出しと JavaScript ハンドラーが動作します。(JavaScript コード自体はレンダリング直後に登録され、送信時点で動くように準備されます。)
- すべてのショートコードはレンダリング時に自動で
<div class="threemin-api-rendered" data-3minapi-preset="<snippet>">…</div>で包まれます。JavaScript で root を探すときはこの属性を使ってください — 自分の HTML にdata-3minapi-presetを 追加してはいけません。
2.2 許可されるタグ・CSS
| カテゴリ | 許可 |
|---|---|
| テキストタグ | h1–h6、p、div、span、blockquote、ul / ol / li、テーブル系、a、img、figure、figcaption |
| フォームタグ | form、input、button、textarea、select、option、fieldset、legend、label |
| スタイリング | <style> ブロック |
| CSS | 色 / タイポグラフィ、ボックスモデル、レイアウト(Flexbox + Grid)、モーション(transform、transition、animation、filter)、インタラクション(pointer-events、cursor、user-select) |
| 表示切替 | hidden 属性、<style> 内の display:none クラス、インライン style="display:none" |
| 保存時に削除 | <script> タグ、PHP タグ(<?php、<?=)、インラインイベントハンドラー(onclick、onerror、…)、javascript: URL |
一部のインライン style プロパティは保存時に削除されます — CSS ルールは <style> ブロックの中に書いてください。
2.3 推奨パターン
- セマンティック HTML5 — 見出し、リスト、表は表系のタグで、画像 + キャプションは
figure+figcaptionを組み合わせます。 - ショートコード名を接頭辞に持つ BEM クラス —
.product-card、.product-card__titleのような形。同じショートコードが 1 ページに複数あっても衝突しません。 - ショートコードごとに
<style>ブロックを 1 つ。 - モダンなレイアウト — Flex / Grid /
gapすべて許可。 - レスポンシブな単位 —
rem、%、vw、vh。 - 画像の遅延読み込み —
<img loading="lazy">。 - アクセシビリティ —
aria-label、aria-hidden、role="..."はすべて保存後もそのまま動作します。 - HTML5 フォームバリデーション —
required、min、max、pattern、type=email/number/date/…がそのまま適用されます。
2.4 避けるべきパターン
- ⚠️ フォーム系タグへの独自
data-3minapi-*(最もよくある無反応の原因 — エラーすら出ません)。<button>/<input>/<textarea>/<form>/<select>/<fieldset>にホワイトリスト外のdata-*属性を付けると、保存時にひそかに削除され、その後の JS のquerySelector('[data-...]')はnullを返しますが、コンソールにエラーも出ません。ボタンや入力のようなインタラクション要素は BEM クラスで指定してください。<div>/<span>/<li>のような一般タグはどんなdata-*も通過します。 - セレクターは HTML と完全に一致しなければなりません — 1 文字のタイプミスでもエラーなく無反応になります。
<div role="button">ではなく<button>を使ってください。- レイアウトをインライン
style="..."で組まないでください —<style>ブロックの中に書きます。 idでスタイリングしないでください — 同じショートコードが 1 ページに 2 回入ると id が衝突します。クラスを使ってください。- トップレベルのコンテナに固定
px幅は禁止 — レスポンシブが壊れます。
2.5 メソッド別の作成のコツ
2.5.1 Get Record — API フィールドを HTML に差し込む
- Test endpoint 実行後、Variables カードに 2 つのチップが表示されます:
{{response}}(レスポンス全体)、{{response.payload}}(ユーザーレコード)。 - ドット記法で下位にアクセス:
{{response.payload.title}}、{{response.id}}、{{response.payload.author.name}}。 - 変数の値は自動的に安全に処理されます。
- 表示/編集の切替属性(フォーム系タグ用のホワイトリスト):
data-3minapi-view-mode、data-3minapi-edit-mode、data-3minapi-edit-toggle、data-3minapi-save、data-3minapi-cancel、data-3minapi-delete。編集フォーム内の input は普通のname="..."を使います。
2.5.2 Get List — 動的なアイテムのレンダリング
- HTML には空のコンテナだけを置き、JavaScript がランタイムで各行を追加します。ハードコードした行は公開ページで重複してしまいます。
- DOM フックのホワイトリスト:
<ul data-3minapi-feed-list>(アイテムコンテナ)、<button data-3minapi-feed-more>(Load more)、[data-3minapi-feed-empty](空状態)。 - 変数チップ:
{{response.data}}(配列 — テンプレート内では空に置換、参考表示のみ)、{{response.pagination.next_cursor}}、{{response.data.0.payload.x}}(インデックスで単一レコードにアクセス、静的に表示される領域用)。 - 複数行のレンダリングとページネーションは JS パネルで処理します。
2.5.3 POST — フォームをエンドポイントに接続
- エンドポイントの body フィールド定義を 3Min API ダッシュボードで確認してください。
- 各 input の
name属性を body フィールド名と完全に一致させてください。 - 自動送信バインディング:
[data-3minapi-preset]の内側に<form data-3minapi-form>を置くと、ランタイムが submit イベントをインターセプトします。組み込みの POST テンプレートにはすでに含まれています。 - 自動ステータスフィードバック: フォームの中に
<div data-3minapi-status></div>を置いてください。ランタイムがtextContentを書き込み、is-success/is-errorクラスを切り替えます。 - HTML5 バリデーション属性(
required、min、max、pattern、type=email/number/date/…)はそのまま適用されます — JS なしで軽量なバリデーションが可能です。 - カスタムバリデーション、条件付き送信、ライフサイクルフックが必要な場合は JavaScript パネルを使ってください。
3. JavaScript ガイド
JavaScript パネルはオプションで、サイト管理者のみ保存できます。ここに貼り付けたコードはショートコードの HTML/CSS がレンダリングされた直後に自動で実行されます。
3.1 実行方式
- ランタイムで
(function(scope){ /* your code */ })('<snippet>')の形に自動で包まれます。<script>タグ、import、IIFE ラッパーはどれも必要ありません。 scope変数は自動で注入されるので、そのまま使ってください。ショートコード名を 文字列リテラルとしてコードに直接書かないでください。- 同じショートコードが 1 ページに複数現れる場合、各インスタンスは自分の scope で独立して実行されます。
- すべてのヘルパーは
window.threeminApi.*から使えます。レスポンスフィールドの正確なパスとサンプルコードは Copy AI prompt の結果にある[Sample —]ブロックにすべて入っています。
3.2 実行環境
- 普通のブラウザ JavaScript(ES2017+) —
async/await、fetch、Promise、アロー関数、分割代入すべて動作します。 - DOM API を直接使用 —
document.querySelector、addEventListener、createElementなど。 - ショートコード内では
importは使えません。外部ライブラリはテーマ/プラグインのwp_enqueue_scriptで読み込み、グローバル(window.X)としてアクセスしてください。 - JavaScript の保存はサイト管理者のみ可能です。HTML/CSS など他のフィールドは管理者以外のユーザーでも保存できます。
3.3 ヘルパー一覧
| ヘルパー | モード | 動作 |
|---|---|---|
data(scope) |
All | インラインされたレスポンスをパース(ネットワーク呼び出しなし)。なければ null。 |
fetch(scope, q) |
Get List | サーバープロキシ経由で次のページを取得。{ cursor: <next_cursor> }。 |
fetchById(scope, id) |
Get List | id で単一レコードを GET。 |
submit(scope, body) |
POST | <form data-3minapi-form> があれば自動バインドされます — 直接呼ぶケースはまれです。 |
update(scope, body) |
Get Record | ショートコードが指すレコードを PUT。 |
updateById(scope, id, body) |
Get List | id で単一レコードを PUT。 |
delete(scope) |
Get Record | ショートコードが指すレコードを DELETE。 |
deleteById(scope, id) |
Get List | id で単一レコードを DELETE。 |
on(scope, event, cb) |
POST | 'before-submit' / 'success' / 'error' フックを登録。 |
mutation はキュー確認レスポンスのみ返します。更新後のレコードは返しません。
update/delete/updateById/deleteByIdのレスポンスはsuccess、message、id(キュータスク id でレコード id では ありません)、queued_atを含む確認レスポンスです。送信した body で DOM を直接更新してください(楽観的 UI)。実際のレコード書き込みは後続の GET より ~3 秒程度遅れる可能性があります。
3.4 推奨 / 避けるべきパターン
推奨
- root は一度だけ探す —
var root = document.querySelector('[data-3minapi-preset="' + scope + '"]');として、その後すべてのセレクターをroot.querySelector(...)で範囲を限定。同じショートコードが複数レンダリングされても安全です。 - イベント委譲 — 動的に追加される行には、コンテナに 1 つだけリスナーを掛けて
e.target.closest('.…')で識別します。 - dataset で行の識別 —
li.dataset.recordId = item.idで 1 度刻んでおき、クリックハンドラーでe.target.closest('li').dataset.recordIdを読みます。 - 読み込みはキャッシュを利用 —
threeminApi.data(scope)はインラインの JSON をパースするだけなので、繰り返し呼んでも負担はありません。 - mutation のレスポンスは確認レスポンス —
update/deleteのレスポンスはキュー確認レスポンスだけなので、送信した body で DOM を更新(楽観的 UI)してください。
避ける
- ⚠️
scope+record_idの文字列連結で element id を作る — ショートコード名とアップストリームのレコード id はまったく異なる文字列です。 - ⚠️ mutation レスポンスの wrap 深度の誤認 — success は
res.json.data.data.successにあります。res.json.data.success(.dataが 1 つ足りない)を読むと常に falsy になり、HTTP 200 がエラー処理経路に流れる最もよくある落とし穴になります。 - mutation のレスポンスから更新後のレコードを読もうとする — キュー確認レスポンスにはレコードの中身はありません。
- mutation 直後にすぐ再取得する — 非同期処理で ~3 秒遅れる可能性があります。
setTimeout(..., 3000)と "Saving…" インジケーターを使ってください。 - mutation の body を
{ payload: { ... } }で包む — body は 1 段のオブジェクト{ field: value }の形です。ネストされたオブジェクトは URL エンコードの過程でエラーなく消えてしまいます。 record_idを合成する —[A-Za-z0-9_-]に一致し、≤256 文字である必要があります。違反するとサーバーが 422 エラーを返します。前のレスポンスで API が返した id をそのまま再利用してください。- ショートコード名をコードに直接書く — 自動注入された
scope変数を使ってください。
3.5 レスポンスの wrap 深度 — よくある落とし穴
WordPress の wp_send_json_success が 1 度、プラグインの admin-ajax ハンドラーが 1 度ラップします。結果:
- ページ内の単一 GET 読み込み(
data(scope)) —data(scope).data.payload.X。 fetch()の次のページ — レスポンス全体はres.json.data.data(.data2 つ)。fetchById()単一レコード — レコードはres.json.data.data.data(.data3 つ)。- mutation キュー確認レスポンス —
res.json.data.data.{success, message, id, queued_at}(.data2 つ)。 - POST
'success'フックのイベント —e.response.data.data.{success, …}(.data2 つ)。
シグネチャ全体と検証済みのサンプルコードは Copy AI prompt の結果にある [Sample —] ブロックを参照してください。
4. よくある質問
4.1 「ボタンをクリックしても反応がなく、コンソールにエラーも出ません」
フォーム系タグ(<button>、<input>、<form>、<select>、<fieldset>)に data-* 属性を付けましたね。WordPress のセキュリティフィルター(wp_kses)が保存時に削除したため、querySelector('[data-...]') が null を返し、リスナーが登録されず、ログも何も出ません。
解決 — その要素を BEM クラス(<button class="my-card__back">)に切り替え、root.querySelector('.my-card__back') で探してください。
4.2 「カードが空、もしくはフィールドが undefined として表示されます」
レスポンスから読み込んでいるパスが間違っています。ヘルパーごとの正確なパスは AI prompt の [Sample —] ブロックにすべて記載があります。よくある正解:
data(scope).data.payload.X— 単一 GET。res.json.data.data.data.payload.X—fetchById(三重ラップ)。
4.3 「Update が HTTP 200 を受け取ったのに画面が変わりません」
res.json.data.success を確認していますね。このパスは .data が 1 つ足りないため、mutation では常に undefined になります。mutation の success フラグは res.json.data.data.success にあります(WP が 1 度、プラグインが 1 度包みます)。delete / updateById / deleteById も同じです。POST 'success' フックの対応パスは e.response.data.data.success です。
4.4 「リストが空に見えますが API は 200 を返しています」
DOM フックのセレクターが HTML と完全に一致していません。HTML を再度見て、data-3minapi-feed-list(またはカスタムフック)がそのまま書かれているか確認してください。
4.5 「保存後に CSS ルールが効きません」
そのルールがインラインで安全フィルターに削除されたか、安全 CSS リストにないプロパティです。<style> ブロックの中に移してください。
4.6 「POST はちゃんと送信されたのにフィードバックが見えません」
フォームの中に <div data-3minapi-status></div> がありません。ランタイムはこの要素にしか textContent を書き込まず、is-success / is-error を切り替えません。
4.7 「Update は成功したのに UI に古い値が残っています」
mutation のレスポンスから更新後のレコードを読もうとしましたね。mutation はキュー確認レスポンスのみを返します — レコードの中身はありません。送信したばかりの body で DOM を直接更新してください。
4.8 「mutation 直後にページを再読み込みしても古いデータが見えます」
mutation は非同期で処理されるため、再取得が ~3 秒まで遅れる可能性があります。楽観的 UI を使ってください。再取得がどうしても必要であれば、"Saving…" インジケーターと一緒に setTimeout(..., 3000) で行います。
4.9 「JS パネルが無効化されており案内が出ます」
そのアカウントには JavaScript を保存する権限がありません(マルチサイトや制限ロールでよくあります)。JavaScript なしで保存するか、サイト管理者に JavaScript 部分の保存を依頼してください。
4.10 「Test endpoint がネットワークエラーを返します」
3Min API ダッシュボードでエンドポイント ID と API キーを確認してください。
ヘルプを得る
- 3Min API を見てまわる — 3minapi.com/tour
- 直接お問い合わせ — contact@3minapi.com
- WordPress.org サポートフォーラム — プラグインの正式公開後、ディレクトリページの Support タブで利用できます。