a-blog cmsにhtmx（jsライブラリ）を実装してみました - ブログ

先日a-blog cms + htmxの勉強会で学んだことを忘れない様に、早速チャレンジしてみました。
当サイトで便利に活用できそうな場所ということで、「制作事例」一覧ページを制作事例のタグを使って絞り込みをします。
htmxって何？という方は、先に前回のブログ「a-blog cmsとhtmx（jsライブラリ）は非常に相性が良い」をご覧ください。

2024/6/14追記：a-blog cms ver 3.1.17からhtmxとの親和性がより高くなり「hx-ext="ajax-header"」の表記が不要となりました。
また、htmx利用時のセキュリティも向上しておりますので、詳しくは下記の説明に追記した【a-blog cms ver3.1.17より変更】の箇所をご確認ください。

a-blog cmsへのhtmx実装方法

今回はすでに制作事例のエントリーに付いているタグを利用して、「主要キーワードでの絞り込み」というものを作ることにしました。
ただ、あまり細かなタグを並べても数が多すぎるので、ページ上部は主要なものだけにして、細かいタグは各事例の部分で絞り込める様になっています。

※こちらではhtmxの細かな設定についてというより、htmxをa-blog cmsに実装する方法をご紹介しておりますので、htmx自体について知りたい方は htmx の公式ページをご確認ください。

a-blog cmsの設定確認と用意するもの

config.system.yamlの設定を確認

#a-blog cms ver3.1.6以前の場合
forbid_tpl_url_context: off
html_format_validate: off

こちらの2つの設定が「off」になっていないと、htmxを利用することは出来ませんので、まず最初に確認してください。

【a-blog cms ver3.1.17より変更】
a-blog cms ver3.1.17からa-blog cmsの機能が向上しており、下記の設定で動作可能です。また新たな設定も追加されておりますので、従来よりセキュアな環境でご利用いただけるようになっております。

#a-blog cms ver3.1.7以降の場合
forbid_tpl_url_context: on #on / off どちらでも可
html_format_validate: on #on / off どちらでも可
ajax_security_level: 2 #ajaxリクエストのセキュリティレベルを設定します。（0: チェックなし 1: RefererとHttpヘッダーを確認 2: CSRFトークン確認）

a-blog cms ver3.1.17以降はこちらの2つの設定が「on」「off」のどちらでもhtmxをご利用可能です。
「ajax_security_level」はa-blog cms ver3.1.17より追加された設定です。こちらはお好みで設定してください。

【重要】「ajax_security_level:2」に設定する場合は、htmlの要素に「check-csrf-token」の記述が必要となります。class名などでどこかに追加をしてください。「check-csrf-token」の文字列があるとa-blog cmsがCSRFトークンを発行します。（例：<body class="check-csrf-token">）

jsライブラリとa-blog cms用の記述を設定

次にhtmxのjsライブラリとa-blog cmsに必要な記述を設定します。
記述は<head>内で大丈夫です。htmxのファイルは公式サイトからDLしてください。

・htmx　htmxのオフィシャルサイトはこちら
・htmx ajax header　htmxのオフィシャルサイト「htmx ajax header」についてはこちら（a-blog cms ver3.1.17以降は不要）

<!-- htmx -->
<script src="/js/htmx.min.js"></script>
<script src="/js/ajax-header.js"></script> <!-- a-blog cms ver3.1.17以降の場合は不要 -->

<!-- a-blog cms で htmx を動かすおまじない -->
<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;
    });

    //a-blog cms ver3.1.17より追加
    document.addEventListener("htmx:configRequest", function(event) {
        const csrfToken = document.querySelector('meta[name="csrf-token"]').content;
        event.detail.headers['X-CSRF-Token'] = csrfToken;
    });

    //htmx:afterSwap swap処理後にJSを実行
    addEventListener('htmx:afterSwap', function (event) {
        ACMS.Dispatch(event.target);
    });
</script>

「addEventListener」の「htmx:beforeHistoryUpdate」は、htmxでテンプレートを適用する際に「/tpl/include/htmx/xxxxx.html」の様なパスが付いてしまう場合に、リプレイスして削除処理するためのものです。こちらはファイルの置き場所によってパスを変更します。
「addEventListener」の「htmx:afterSwap」はhtmxのswap後に、a-blog cmsのjsを実行する際に必要な記述の様です。

【a-blog cms ver3.1.17より変更】
「htmx ajax header」の読み込みは不要となりました。また、「htmx:configRequest」はver3.1.17で新たに追加された機能です。a-blog cms ver3.1.17以上で利用する場合に必要な記述になります。

これで準備はOKです。あとはテンプレートに記述するだけ。今回のケースでは下記テンプレートを用意しました。

htmx用のテンプレートを用意します

a-blog cmsテンプレートのインクルードの記述

a-blog cmsのテンプレートは1度の処理で動きますが、htmxでは複数箇所動かす場合があるため「multi_swap」の値で制御しているそうです。@includeでその為の値を渡してテンプレートを読み込んでいます。

@include("/include/htmx/work_htmx.html",{"multi_swap": "off"})

<a>がリクエスト側の記述／ <div id="work_htmxfield">がレスポンス側の記述

<a>をクリックしたら#work_htmxfield（親のwrapper）を「/include/htmx/work_htmx.html」で置き換えています。（自分自身を置き換え）
こちらのサンプルでは絞り込みは「Web制作」だけになっています。
先ほどの「multi_swap」は<title>のところを制御しています。（値がoffではない時のみ表示）

【a-blog cms 3.1.17より変更】
下記ソースにも追記しましたが、a-blog cms ver3.1.17以降は「hx-ext="ajax-header"」の記述は不要となりました。
a-blog cms ver3.1.17以降でご利用の場合は「hx-ext="ajax-header"」の記述を削除してください。

<div id="work_htmxfield">
  <!-- htmx で絞り込み  -->
  <!-- 注：a-blog cms ver3.1.17以降は hx-ext="ajax-header"の記述は不要です  -->
  <a href="/service/creative_work/tag/Web制作/" hx-get="/service/creative_work/tag/Web制作/tpl/include/htmx/work_htmx.html" hx-trigger="click" hx-target="#work_htmxfield" hx-swap="innerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/tag/Web制作/">【Web制作】</a>

  <!-- ここに Entry_Summary などのモジュールで置き換えたい事例リストを掲載 -->
</div>

<!-- 選択したタグを含めた結果で <title> を置き換え -->
<!-- BEGIN_IF [{{multi_swap}}/neq/off] -->
  <!-- BEGIN_MODULE Ogp --><title>{title}</title><!-- END_MODULE Ogp -->
<!-- END_IF -->

一応簡単に説明すると、ポイントとしては下記の様な感じです。
・href：本来遷移するURL
・hx-trigger：発火条件／clickは要素をクリック
・hx-target：置き換え対象／#work_htmxfield
・hx-swap：置き換え方法／innerHTMLは指定要素の中身を置き換えます。
・hx-get：a-blog cmsのURLコンテキストが通るhtmxテンプレートも含めたパス
・hx-push-url：ブラザウのURL欄に表示したいパス

「hx-get」はa-blog cmsのURLコンテキストが通る「/tpl/」も含めたhtmxテンプレートへのパスになる為、冒頭でご紹介したjsで「/tpl」以降のパスを削除して表示しています。（検索botなどから無駄なURLへのクロール・キャッシュを防ぐ目的があるそうです）

また、Entry_SummaryなどのモジュールID（今回でいうところの制作事例の一覧）は、tagで絞り込める様にモジュールを設定しておく必要があります。<title>部分は、絞り込んだ状態のタイトル情報で上書きしています。こちらはhtmxの機能で、<title>タグの書き換えができます。

少しお断りを入れると、今回実装した実際のコードは「hx-」を「data-hx-」にしています。こちらはhtmlのバリデーターの問題を避けるためで、海外の情報を参考にしました。公式ではございませんのでこちらでは「data-」は省いております。

ページャーの設定

エントリー数が多くなると、一覧表示時に一度に表示することが困難になってきますので、ページャーにも対応してみました。
PCとスマホとの両立を考えると、「続きを見る」としてその場でロードし追加表示する実装も良いと思いますが、再度アクセスした際に初期状態に戻ってしまうことを考えると、今回はページャーを実装しページを分けてヒストリーバックが機能する様にしてみました。

【a-blog cms 3.1.17より変更】
下記ソースにも追記しましたが、a-blog cms ver3.1.17以降は「hx-ext="ajax-header"」の記述は不要となりました。
a-blog cms ver3.1.17以降でご利用の場合は「hx-ext="ajax-header"」の記述を削除してください。

<!-- BEGIN pager:veil -->
<!-- ページ送り　開始▼▼ -->
<!-- 注：a-blog cms ver3.1.17以降は hx-ext="ajax-headerの記述は不要です"  -->
<nav id="work_tagsearch_htmx_pager">
	<ul class="pagination">
		<!-- BEGIN backLink --><li class="serial-nav-item serial-nav-item-prev"><!-- BEGIN prevPage --><a href="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{backPage}/#work_tagsearch_htmx" hx-get="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{backPage}/tpl/include/htmx/work_htmx.html" hx-trigger="click" hx-target="#work_htmxfield" hx-swap="innerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{backPage}/" aria-label="前へ" class="scrollTo"><span aria-hidden="true">&laquo;</span></a></li><!-- END backLink -->

		<!-- BEGIN firstPage:veil --><li {pageCurAttr}[raw]><span><a href="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->#work_tagsearch_htmx" hx-get="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->tpl/include/htmx/work_htmx.html" hx-trigger="click" hx-target="#work_htmxfield" hx-swap="innerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->" class="scrollTo">{firstPage}</a></span></li><li class="peger_pipe"></li><!-- END firstPage:veil -->

		<!-- BEGIN page:loop --><li {pageCurAttr}[raw]><span><!-- BEGIN link#front --><!-- END link#front --><a href="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{page}/#work_tagsearch_htmx" hx-get="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{page}/tpl/include/htmx/work_htmx.html" hx-trigger="click" hx-target="#work_htmxfield" hx-swap="innerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{page}/" class="scrollTo">{page}</a><!-- BEGIN link#rear --><!-- END link#rear --><!-- BEGIN glue --><!-- END glue --></span></li><!-- END page:loop -->

		<!-- BEGIN lastPage:veil --><li class="peger_pipe"></li><li {pageCurAttr}[raw]><span><a href="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{lastPage}/#work_tagsearch_htmx" hx-get="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{lastPage}/tpl/include/htmx/work_htmx.html" hx-trigger="click" hx-target="#work_htmxfield" hx-swap="innerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{lastPage}/" class="scrollTo">{lastPage}</a></span></li><!-- END lastPage:veil -->

		<!-- BEGIN forwardLink --><li><a href="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{forwardPage}/#work_tagsearch_htmx" hx-get="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{forwardPage}/tpl/include/htmx/work_htmx.html" hx-trigger="click" hx-target="#work_htmxfield" hx-swap="innerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/<!-- BEGIN_IF [%{TAG}/nem] -->tag/%{TAG}/<!-- END_IF -->page/{forwardPage}/" aria-label="次へ" class="scrollTo"><span aria-hidden="true">&raquo;</span></a></li><!-- END forwardLink -->
	</ul>
</nav>
<!-- ページ送り　終了▲▲ -->
<!-- END pager:veil -->

上記のポイントとしては、Entry_Summaryの通常のページャーを使っています。
簡易ページャーでは前後のURLの変数が、ページ番号を含めひとまとめになっていることで、htmxの記述を適用することが難しかったため、表示ページのページ番号だけで取得可能なページャーがおすすめです。もし簡易ページャーで実装する場合は、何かしら現在ページの/page/の値を取得する方法を考えなくてはいけないと思います。

また、上記のページャー自体の機能で/page/の値の有無は判断できますが、/tag/の有無は判定できないため、グローバル変数%{TAG}で表示ページのタグの有無を調べ、タグがある場合だけIFブロックで「href」「hx-get」「hx-push-url」にタグに関連する内容を出力しています。

注意ポイント

「hx-push-url」でアドレスを変更したので、その変更したアドレスでダイレクトにアクセスされた際にも、同様のページが表示できるかは確認をしてください。今回はタグ・ページャーともに絡んだ実装になるため気を使いましたが、別タブでリンクを開く人も多いので重要だと思います。逆に「hx-push-url」を使わない実装の場合は、アクセスしたページのみで機能するので手軽に対応できると思います。

実際に実装してみて

正直「こんなに簡単にできるとは！！！」という感じです。
すごく手軽に実装できるので、積極的に取り入れても良いのではないでしょうか。
UXの向上はSEOにも効果があるということですしね。とても良いものを教えていただきました。

最後に

弊社がなぜa-blog cmsを愛用しているのか、a-blog cmsの特徴やメリットとは。
a-blog cmsをお勧めする理由につきましてはこちらのページをご覧ください。
a-blog cmsをお勧めする理由