hx-post の利用

a-blog cms を長く利用されている方であれば、POST リクエストで部分的に HTML を取得・表示する post include 機能を使った経験があるかもしれません。hx-post は、この post include の発想を引き継ぎつつ、より汎用的で拡張性の高い 上位互換 と考えて差し支えありません。

post include が POST メソッド限定だったのに対し、htmx の hx-post では hx-get をはじめとする他のメソッドとも共通の書き方で扱えるため、これまで実現できなかった部分更新のパターンや UI を、同じシンプルな記述で実装できるようになりました。

基本構文

<form action="" method="post"
      hx-post=""
      hx-target="#search-result"
      hx-swap="outerHTML">
  <input type="hidden" name="tpl" value="/include/entry/search-result.html">
  <input type="text" name="keyword" placeholder="キーワード">
  <button type="submit" name="ACMS_POST_2GET_Ajax">検索</button>
</form>

<div id="search-result">
  <!-- 送信結果がここに表示される -->
</div>

この例では、もともと a-blog cms で動作している検索機能に htmx を組み合わせ、ページ遷移なしで検索結果を表示します。

変更点は次のとおりです。

1. hx-post / hx-target / hx-swap を付与
   hx-post="" で現在のページに POST 送信し、返ってきた HTML を #search-result の要素ごと（outerHTML）置き換えます。

2. name="tpl" の hidden フィールドを追加
   取得した HTML を描画するテンプレート（例：/include/entry/search-result.html）を指定します。

3. 送信ボタンの name を変更
   通常の検索フォームでは name="ACMS_POST_2GET" となっていますが、これを name="ACMS_POST_2GET_Ajax" に変更します。これにより、指定したテンプレートを使った部分的な HTML を返すモードになります。

この方法を使えば、既存の検索フォームを大きく書き換えることなく、スムーズな Ajax 型の検索に置き換えられます。

hx-push-url と ACMS_POST_2GET_Ajax の拡張設定

hx-post で hx-push-url="true" を指定すると、フォーム送信後の履歴には hx-post に指定した URL がそのまま記録されます。そのため、例えば次のような URL になることがあります。

https://example.com/keyword/検索文字列/tpl/include/entry/search-result.html

この URL をブラウザで直接リロードすると、tpl パラメータ以降を解釈できず、404 Not Found となってしまいます。この状態では、履歴やブックマークからの再アクセスが正常に動作しないため、hx-push-url のメリットが活かせません。

この問題を解消するために、a-blog cms では ACMS_POST_2GET_Ajax に URL を組み立て直す機能が追加されました。この機能を有効にすると、履歴には tpl 以降を除いた URL が保存され、リロードやブックマーク時にも正しくページが表示されるようになります。

利用方法

<div data-acms-hx-push-url="true">
  <!-- 検索結果の内容 -->
</div>

この属性を持つ要素がテンプレート内に含まれている場合、ACMS_POST_2GET_Ajax が履歴用の URL を組み立て直し、tpl 以降を除外して履歴に反映します。

最終的に履歴へ保存される URL

data-acms-hx-push-url="true" を返却テンプレートに指定し、hx-post で hx-push-url="true" を用いた場合、履歴には tpl 以降を除いた 正規化された URL が保存されます。

https://example.com/keyword/検索文字列/

この形であれば、リロードやブックマーク、共有時にも期待通りのページが表示されます。

hx-post 実装例

siteテーマ「事例紹介」検索機能

https://utsuwa3m.ablogcms.org/works/htmx.html#works-search

通常のグローバルナビゲーションからアクセスするページでは、htmx を利用しない通常の検索機能として実装されていますが、htmx.html に実装サンプルが用意されています。

詳しくは hx-swap-oob 実装例 をご覧ください。