Developer

クリッカブル日本地図 — 開発者向け情報

フック・ショートコード・カスタム投稿タイプなど、本プラグインを拡張・連携するための技術情報です。

本ページの内容は v2.0.0 時点のものです。v2.0.0 では、無料版(WordPress.org 配布の Japan Clickable Map)とデータを共有するため、識別子の接頭辞を jcm_ から plg_jcm_ へ全面変更しました。ショートコード名・ブロック名・REST 名前空間・post type・post meta・オプションがすべて変わっており、後方互換のエイリアスはありません。CSS クラス(jcm-*)は変更していないため、既存のカスタム CSS はそのまま使えます。

ショートコード / ブロック

  • [plg_jcm_map id="マップID" level="…" class="…"] — マップを描画。id は必須(都道府県マップ・市町村マップの投稿 ID。post type はサーバー側で自動判定)。
  • level(任意)— このショートコードに限り精度レベルを上書き。都道府県マップ: low / low-smooth / mid / high、市町村マップ: low / mid / high(low-smooth は都道府県マップのみ)。投稿側の設定より優先され、許可外の値は無視されます。
  • class(任意)— ルート要素に追加するカスタム CSS クラス(sanitize_html_class() を通ります)。
  • ブロック名 plg-jcm/map(「クリッカブル地図」)。属性 id(integer, 初期値 0)。動的ブロックで、レンダリングはショートコードと同じ処理に委譲されます(level / class はブロックでは指定できません)。

カスタム投稿タイプ

post_type用途
plg_jcm_map都道府県マップ
plg_jcm_muni_map市町村マップ

いずれも public => false で、フロントの単独ページは持ちません(ショートコード/ブロック経由でのみ表示)。設定は post meta に配列で保存されます。

メタキー内容
_plg_jcm_config都道府県マップの設定一式(モード・配色・リンク・表示オプション・凡例エリア・ピン等)
_plg_jcm_muni_config市町村マップの設定一式(選択コード・エリア・上書き・ピン等)

設定配列のうち、v2.0.0 で追加されたキーは次のとおりです(フックで加工する場合の参考に)。

キー対象内容
show_legend両マップ凡例を出すか(bool・既定 false)
legend_other_label都道府県どのエリアにも属さない行のラベル(空なら「その他」)
groups都道府県凡例エリアの定義配列(key / name / color / link)。定義順が凡例の並び順
group_assign都道府県都道府県コード(2桁) => エリアの key の対応
pins両マップピンの配列(x / y / label / link)。座標はベース viewBox(0〜800 / 0〜913)の user 座標で、保存時に clamp されます

プラグイン全体の設定はオプションに保存されます。プリセット色は plg_jcm_color_presets(hex カラーの配列・最大 24 件)、ピン画像は plg_jcm_pin_image_id(添付ファイル ID。0 なら同梱の assets/img/pin-default.svg)、アンインストール時の削除フラグは plg_jcm_uninstall_remove_all_data です。

REST API

エンドポイントメソッド / 権限内容
/wp-json/plg-jcm/v1/mapsGET / edit_posts公開済みマップの一覧を [{ id, title, kind }] で返す(ブロックエディタの選択 UI 用。kind は prefecture | municipality)

フロントエンドの出力

  • 地図は インライン SVG として出力されます(画像ファイルへの参照なし)。選択範囲・除外設定に応じて viewBox を再計算します。
  • ルート要素には jcm-map(市町村マップはさらに jcm-muni-map)クラスが付与され、ショートコードの class 属性で任意のクラスを追加できます。CSS の上書きはこのクラスを起点にしてください。
  • リンク設定のある領域のみ <a> でラップされます。リンクなしの領域はクリック不可(カーソル変化なし)。
  • 凡例は SVG の外側に <ul class="jcm-legend">(各行は jcm-legend__swatch / jcm-legend__label)として出力されます。SVG 本体だけが wp_kses を通り、凡例はエスケープ済みの HTML として連結されます。
  • ピンは SVG 内の <g class="jcm-pins"> に、<image class="jcm-pin"> + ラベルの <text> として描画されます。リンクありのピンは <a class="jcm-pin-link"> で包まれ、常に target="_blank" / rel="noopener noreferrer" が付きます(県・市区町村の領域リンクは外部 URL のときのみ別タブ)。ピンの大きさは最終 viewBox の短辺に比例し、座標点は画像の下端中央です。block-region レベルではピンは描画されません。
  • CSS(jcm-base.css)はマップを描画したページでのみ読み込まれます。ポップアップを使うマップでは jcm-popover.css / jcm-popover.js が追加で読み込まれます(vanilla JS・jQuery 非依存)。
  • ポップアップのデータは <script type="application/json" class="jcm-popover-data"> としてマップ直後に埋め込まれ、フロント JS が DOM を生成します。ESC・外側クリックで閉じ、タッチ端末ではクリックトリガー・狭幅画面ではボトムシート表示に切り替わります。

管理側 AJAX アクション

いずれも nonce 検証つきの管理画面用エンドポイントです(フロントからの利用は想定していません)。

action権限用途
plg_jcm_previewedit_post都道府県マップ編集画面のライブプレビュー(入力値から SVG を生成して返す)
plg_jcm_muni_previewedit_post市町村マップ編集画面のライブプレビュー
plg_jcm_search_objectsedit_postsポップアップのリンク項目用に投稿・タームをインクリメンタル検索(最大 20 件)

このほか、AJAX ではない管理アクションとして、マップ複製(admin_action_plg_jcm_duplicate、権限 edit_post・投稿ごとの nonce。設定 post meta を引き継いだ下書きを作成)、プリセット色の保存(admin_init 上の POST 処理、権限 manage_options・nonce plg_jcm_save_presets)、ライセンスの有効化/無効化(admin_post_plg_jcm_activate_license / admin_post_plg_jcm_deactivate_license)があります。

フック

v2.0.0 で、テーマや拡張プラグインから出力に介入するための公開フックを 10 本 追加しました(すべて接頭辞 plg_jcm_)。

フック種別タイミング / 用途ライブプレビュー
plg_jcm_loadedaction本体の配線完了時(Plugin インスタンスを受け取る)。本体は plugins_loaded より前に初期化されるため、拡張側の add_filter はこのフックに載せるのが確実です。—
plg_jcm_config / plg_jcm_muni_configfilter保存済み設定の読み込み後($config, $post_id)。動的な色・リンクをマージする用途。効きません
plg_jcm_allowed_levelsfilter都道府県マップの精細度レベル許可リスト。block-region(地方ブロック塗り)を受け付けさせることもできます(編集画面のラジオボタンは別途自前 UI が必要)。効きます
plg_jcm_svg_filefilterSVG ファイルのパス解決($path, $level, $pref_code)。ベースマップの差し替えに。効きます
plg_jcm_pref_path_attrs / plg_jcm_muni_path_attrsfilterpath 1 個分の fill / aria_label / link($code, $context)。データ連動の塗り分け(コロプレス)やリンクの動的生成に。効きます
plg_jcm_svg_domactionシリアライズ直前の DOMDocument($config, $level, $kind)。独自マーカー・パターン塗りなどを DOM 段階で注入できます。効きます
plg_jcm_allowed_htmlfilterwp_kses の許可リスト。plg_jcm_svg_dom で要素を足したときは必ずこちらにも追加してください(許可されていないタグ・属性は出力時に除去されます)。効きます
plg_jcm_map_htmlfilterショートコード/ブロックの最終 HTML($post_id, $config, $level, $kind)。wp_kses 通過後のため、追加したマークアップのエスケープは呼び出し側の責任です。効きません

ピン機能そのものが plg_jcm_svg_dom + plg_jcm_allowed_html の実装例になっています。フックの引数の詳細はプラグイン同梱の docs/hooks.md をご覧ください。

無料版との関係

  • WordPress.org 配布の無料版と、post type・post meta・オプション・ショートコード・ブロック名・REST 名前空間が完全に一致します。無料版で作成したデータは変換なしで本製品から扱えます。
  • プラグイン名・名前空間・クラス名も同一のため、両方を同時に有効化することはできません。片方が読み込み済みの場合、後から読み込まれた側が何も宣言せずに停止し、管理画面に案内を表示します(fatal error は発生しません)。
  • 市区町村マップ・都道府県マップの凡例・ピン・上記のフック・ライセンス認証による自動アップデート・バグ報告ウィジェットは本製品のみの機能です。

地図データ

  • 地図データ(SVG)はプラグインに同梱されており、外部 API・地図サービスへのリクエストは発生しません。
  • 市区町村は JIS X 0402(5 桁コード)基準の約 1,900 単位。政令指定都市は区単位(例: 14101 横浜市鶴見区)。
  • 精度レベルごとに別ファイルを持ち、選択されたレベルのデータのみ読み込まれます。
  • 国土交通省「国土数値情報(行政区域データ)」を加工して作成しています。地図を表示するページには出典の明記が必要です。

アンインストール時の挙動

プラグインをアンインストール(削除)しても、既定ではデータは削除されません。「クリッカブル地図 > 設定」でデータ削除(オプション plg_jcm_uninstall_remove_all_data)を有効にしたうえでアンインストールした場合のみ、次のデータが削除されます。停止(無効化)では削除されません。

  • 本プラグインが使用するオプション(plg_jcm_installed_version / plg_jcm_color_presets / plg_jcm_pin_image_id / ライセンス関連など、既知のキーを列挙して削除。同じ接頭辞を使う他プラグインを巻き込まないため、前方一致では削除しません)
  • 更新チェックのキャッシュ(plg_jcm_update_data_*)
  • post meta _plg_jcm_config / _plg_jcm_muni_config
  • plg_jcm_map / plg_jcm_muni_map の全投稿とその meta