a-blog cms と htmx で作る SPA(Single Page Application) なブログテーマの実装方法
今回、この a-blog cms で作られているブログを htmx を利用して SPA(Single Page Application) にする実験をしてみましたので、その点について紹介をしてみます。
Single Page Application（SPA）とは
ウェブ開発の世界では、Single Page Application（SPA）がますます人気になっています。SPA は、従来の複数ページからなるウェブサイトと異なり、単一の HTML ページで動作し、ユーザーの操作に応じて部分的に、必要なデータだけをサーバーから取得するためデータの授受が最小限になり、ページの表示速度向上が向上します。
一般的には、React や Vue.js などのフレームワークを利用して構築することが多く、エンジニアのコストが増えることもあります。
htmx をフロントエンドに、
バックエンドには a-blog cms を採用すると
a-blog cms では、PHP のコードを書くことなく、テンプレートには HTML のみを記述し、管理画面で表示件数やソート順、表示する情報の条件を設定する必要がなく、バックエンドのコードは記述する事がありません。また、そのテンプレートの HTML に属性を追加するだけで、htmx が動作し、手軽に SPA を実現することが可能です。
最初のアクセスは a-blog cms が担当
トップページはもちろんですが、Google検索や SNS のリンクなどで途中のページにアクセスがあった際にも、最初のアクセスは a-blog cms がページ全体の HTML を生成します。
分かりやすくするために、サブカラムの一番上に a-blog cms のロゴを表示するようにしています。
2ページ目以降は htmx が担当し Ajax で更新しています
1ページ目を表示し、どこかのリンクをクリックすると Ajax で部分的にページを更新するような実装になっています。この時には a-blog cms のロゴだったところが、htmx に変わっている事で確認できます。
History API の活用（ hx-push-url ）
一般的には htmx の属性で hx-push-url="true" と追加することで、htmx でページを書き換えた際にブラウザの URL も変更されます。また、URL 以外にタイトルタグの更新も簡単にできるため、ページ全体をリロードしない部分的な更新であっても、ブラウザの履歴にはクリックするたびにタイトルと URL が記録されます。そのため、ブラウザの戻るボタンで前のページに戻ることが可能になります。
今回の実装では、この書き換えられた URL でブラウザのリロードをした場合に a-blog cms が同様のページを生成できるように、hx-push-url="{url}" のように URL を指定し History API に書き込む情報を調整しています。
htmx 化する際の実装方法
リンクの修正
通常 <a herf="{url}"> と書かれているようなリンクを以下のように修正します。
<a href="{url}"
hx-get="{url}/tpl/include/htmx/entry-body.html"
hx-push-url="{url}"
hx-swap="innerHTML"
hx-target="#main-contents"
class="scrollTo">今回は、ほとんどのリンクが entry-body.html のテンプレートを利用して部分的にページを更新する事になりました。内容としては、以下のようになります。
- 元のリンク先
- a-blog cms をバックエンドに利用する際には必要な記述
- htmx でアクセスする URL を指定
- History API に記録したい URL を設定
- 置き換えたい場所の <div id="main-contents"> <div>を残す設定
- 置き換えたい場所を指定
- ページの上部にスクロールする a-blog cms 側の設定
「htmx でアクセスする URL を指定」で、例えば https://kazumich.com/htmx-spa-blog202405.html/tpl/include/htmx/entry-body.html と指定しているとすると https://kazumich.com/htmx-spa-blog202405.html で表示される内容を、/tpl/include/htmx/entry-body.html のテンプレートに切り替えて表示させるという指示になります。
次に、そのテンプレートについて解説します。
呼び出されるテンプレート entry-body.html
呼び出されるテンプレートについては、もともと Entry_Body のモジュールだけ書かれているテンプレートファイルですが、ここに Topicpath モジュールと、タイトルタグを生成するための Ogp モジュールを追記して1つのファイルにまとめています。
<!-- BEGIN_MODULE Entry_Body -->
（略）
<!-- END_MODULE Entry_Body -->
<!-- BEGIN_IF [{{multi_swap}}/neq/off] -->
<!-- BEGIN_MODULE Topicpath -->
<div id="topicpath" hx-swap-oob="true">
（略）
</div>
<!-- END_MODULE Topicpath -->
<!-- BEGIN_MODULE Ogp -->
<title>htmx:{title}</title>
<!-- END_MODULE Ogp -->
<!-- END_IF -->entry-body.html のテンプレートファイルの中で hx-swap-oob="true" が付いている <div id="topicpath"> 〜 </div> は、id="topicpath" の部分が置き換わります。hx-swap-oob="true" については複数のエリアを一緒に更新ができる便利な属性になります。また、<title>〜</title> については htmx の属性をつける事なくタイトルタグを置き換えることができます。
残った HTML が、<div id="main-contents"> 〜 </div> に置き換えられる事になり、複数のエリアの置き換えが完了する事になります。
このように a-blog cms を利用するとバックエンドの処理を PHP で書くことなく、htmx を呼び出すついでに、呼び出される HTML ファイルを書き、呼び出される側の HTML にも hx-swap-oob="true" などの属性を付加するなどして相互に関連するテンプレートを HTML だけで書いていくことが可能なのです。
検索機能の実装
これまでは <a hx-get="{url}" ... > タグでリンクを作成し、htmx を動かしコンテンツを呼び出すことについて説明を書いてきましたが、次は記事の検索機能を hx-post を利用して作っていくことを解説していきます。
標準的な検索フォーム
<form action="" class="search-form" method="post" role="search" aria-label="検索フォーム">
<input type="hidden" name="query" value="keyword">
<input type="hidden" name="bid" value="%{BID}">
<input type="text" name="keyword" class="search-form-text" value="%{KEYWORD}" size="15" placeholder="検索キーワード">
<span class="search-form-btn-wrap">
<button type="submit" name="ACMS_POST_2GET" class="search-form-btn">
<span class="acms-icon-search"></span>
</button>
</span>
</form>htmx 化するには
hx-get で方法が身についていれば、hx-post でも同様に書くことができます。今回のフォームでの htmx を動作させる場合のトリガーには hx-trigger="submit" を利用します。
<form action="" class="search-form" method="post" role="search" aria-label="検索フォーム" hx-post="" hx-trigger="submit" hx-swap="innerHTML" hx-target="#main-contents">
加えて name="tpl" を hidden で追加します。
<input type="hidden" name="tpl" value="/include/htmx/entry-body.html">
これで hx-post の設定は完了です。
オマケ： input 要素に hx-trigger="keyup" で htmx を動かす
キーワード検索の <input> を以下のように修正します。
<input type="text" name="keyword" class="search-form-text"
value="%{KEYWORD}" placeholder="検索キーワード"
hx-get="/include/htmx/entry-summary.html"
hx-trigger="keyup delay:1s"
hx-target="#entry_summary"
hx-push-url="true" >
<form> 自体を POST する必要があると最初は考えましたが、この <input> タグ単体でサーバーに情報を送ることができたらと考え hx-get で呼び出したい URL を指定し、hx-trigger="keyup" で GET リクエストを送ってみたところ思った動きになりました。その後、delay:1s を追加し、1秒後に動作するようにしています。
あと、hx-push-url="true" とする事で URL も
https://kazumich.com/?keyword=htmx
のようになります。ここでは entry-summary.html を指定しており、サブカラムの最新記事を更新しています。
hx-post で hx-push-url="true" をする際のオマジナイ
History API を利用して URL を書き換える際に、hx-get であれば URL を hx-push-url="{url}" のように、この URL にしたいと事前に設定ができますが、hx-post の場合には POST 後に URL が確定し、書き換えられた URL となってしまいます。 この URL から include/htmx/＊＊.html を削除する JavaScript になります。
<script>
addEventListener('htmx:beforeHistoryUpdate', function (event) {
const proposedUrl = event.detail.history.path;
const customUrl = proposedUrl.replace(/\/tpl\/include\/htmx\/.*\.html/, '');
event.detail.history.path = customUrl;
});
</script>htmx 動作後に a-blog cms の acms.js を再度起動する
a-blog cms が標準提供している JavaScript で acms.js というものがあります。ページを読み込んだ後で、この acms.js が動かないと困るようなこともありますので、HTML の読み込み後に再起動します。
<script>
addEventListener('htmx:afterSwap', function (event) {
ACMS.Dispatch(event.target);
});
</script>※ 現在、シンタックスハイライトが上記の JavaScript を書いても動作していない問題を抱えています。その点は改善された際にアップデートします。
a-blog cms で作られたブログを SPA にする
ヘッドレスCMS を活用して JSON を相手に、SPA ブログを作ろうと思うと少しづつ SPA 化していくというよりは、最初からそのように実装していく事になります。その点、今回の私のブログを SPA 化する際には、部分的にこの部分を htmx を動くようにしよう！ を繰り返し、最終的には全てのページの遷移を htmx で動くように進めていきました。
ビルド環境も必要ないですし、htmx の利点である JavaScript を書かない = 難しいプログラミングをしない の延長で、バックエンド側である PHP も書かず、htmx属性を追加するついでに、呼び出す HTMLテンプレートを書き、またその中に htmx属性も含める。これで a-blog cms の実装ができる人であれば誰でも簡単に SPA 化していくことが可能になるのではないでしょうか。
もちろん、a-blog cms の学習コストが高いという方もいるかと思いますが、よかったら htmx@blogテーマがどんな実装になっているのか ablogcms.io の環境で試してみてください。
ablogcms.io は30日無料お試し環境で、30日後に有料になったりするものではありません
