a-blog cmsにhtmx（jsライブラリ）を実装してみました
記事を書いた人：Webデザイナー 新謙二
先日a-blog cms + htmxの勉強会で学んだことを忘れない様に、早速チャレンジしてみました。
当サイトで便利に活用できそうな場所ということで、「制作事例」一覧ページを制作事例のタグを使って絞り込みをします。
htmxって何？という方は、先に前回のブログ「a-blog cmsとhtmx（jsライブラリ）は非常に相性が良い」をご覧ください。
a-blog cmsへのhtmx実装方法
今回はすでに制作事例のエントリーに付いているタグを利用して、「主要キーワードでの絞り込み」というものを作ることにしました。
ただ、あまり細かなタグを並べても数が多すぎるので、ページ上部は主要なものだけにして、細かいタグは各事例の部分で絞り込める様になっています。
※こちらではhtmxの細かな設定についてというより、htmxをa-blog cmsに実装する方法をご紹介しておりますので、htmx自体について知りたい方は htmx の公式ページをご確認ください。
a-blog cms の設定確認と用意するもの
config.system.yaml の設定を確認
forbid_tpl_url_context: off html_format_validate: off
こちらの2つの設定が「off」になっていないと、htmxを利用することは出来ませんので、まず最初に確認してください。
js ライブラリと a-blog cms 用の記述を設定
次にhtmxのjsライブラリとa-blog cmsに必要な記述を設定します。
記述は<head>内で大丈夫です。htmxのファイルは公式サイトからDLしてください。
・htmx https://htmx.org/
・htmx ajax header https://htmx.org/extensions/ajax-header/
<!-- htmx -->
<script src="/js/htmx.min.js"></script>
<script src="/js/ajax-header.js"></script>
<!-- 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;
});
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を実行する際に必要な記述の様です。
これで準備は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を「/include/htmx/work_htmx.html」で置き換えています。（自分自身を置き換え）
こちらのサンプルでは絞り込みは「Web制作」だけになっています。
先ほどの「multi_swap」は<title>のところを制御しています。（値がoffではない時のみ表示）
<div id="work_htmxfield">
<!-- htmx で絞り込み -->
<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="outerHTML" hx-ext="ajax-header" hx-push-url="/service/creative_work/tag/Web制作/">【Web制作】</a>
<!-- ここに Entry_Summary などのモジュールで置き換えたい事例リストを掲載 -->
<!-- 選択したタグを含めた結果で <title> を置き換え -->
<!-- BEGIN_IF [{{multi_swap}}/neq/off] -->
<!-- BEGIN_MODULE Ogp --><title>{title}</title><!-- END_MODULE Ogp -->
<!-- END_IF -->
</div>一応簡単に説明すると、ポイントとしては下記の様な感じです。
・href：本来遷移するURL
・hx-trigger：発火条件／clickは要素をクリック
・hx-target：置き換え対象／#work_htmxfield
・hx-swap：置き換え方法／outerHTMLは指定要素ごと置き換えます。
・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とスマホとの両立を考えると、「続きを見る」としてその場でロードし追加表示する実装も良いと思いますが、再度アクセスした際に初期状態に戻ってしまうことを考えると、今回はページャーを実装しページを分けてヒストリーバックが機能する様にしてみました。
<!-- BEGIN pager:veil -->
<!-- ページ送り 開始▼▼ -->
<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="outerHTML" 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">«</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="outerHTML" 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="outerHTML" 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="outerHTML" 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="outerHTML" 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">»</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をお勧めする理由