タグ検索:htmx

先に前回のブログ「a-blog cmsにhtmx(jsライブラリ)を実装してみました【ver3.1.17対応版】」の続きになりますが、絞り込み中のタグをより分かりやすくするために、選択中のボタンに変化を加える処理を考えてみました。

自分でjsを作れば色々対応は出来ますが、a-blog cmsにはシステムに用意された「組み込みJS」という機能があります。こちらの機能はWebサイトを制作する上でよく使う機能があらかじめ用意されており、目的に合うものがあれば便利に使う事ができます。

a-blog cms Developers 組み込みJS

今回はそんな「組み込みJS」の中から、現在位置の状態を取得可能な「linkMatchLocation」を使ってみることにしました。

linkMatchLocationとは

表示中のページのURLとclassを付与した<a>の「href」を比較して、条件が合う場合に指定した別のclassを<a>に付与する事が出来る機能です。下記はテンプレートの記述例とその実行後の状態になります。条件に合うとclassに「指定した値(今回はstay)」が付与されます。

a-blog cms Developers 現在位置を装飾する

<!-- 例:ブラウザのアドレスが「https://www.ideasource.jp/blog/」の場合で付与するclassが「stay」の場合 -->
<!-- テンプレートの記述 -->
<a href="https://www.ideasource.jp/blog/" class="js-link_match_location">ブログ</a>

<!-- 実行後 -->
<a href="https://www.ideasource.jp/blog/" class="js-link_match_location stay">ブログ</a>

linkMatchLocationの種類

「linkMatchLocation」には複数種類があります。
値を含んでいる場合、完全一致する場合、ブログ、カテゴリー、エントリーが含まれている場合など、判定したい用途に合わせて設定します。



linkMatchLocationMark 現在表示しているページのURLが、アンカーリンクのリンク先URL中に含まれている場合に指定したclassを付与します
linkMatchLocationFullMark 現在表示しているページのURLと、アンカーリンクのリンク先URLが完全一致した場合にclassを付与します
linkMatchLocationBlogMark 現在表示しているブログのURLが、アンカーリンクのリンク先URL中に含まれている場合にclassを付与します
linkMatchLocationCategoryMark 現在表示しているカテゴリーのURLが、アンカーリンクのリンク先URL中に含まれている場合にclassを付与します
linkMatchLocationEntryMark 現在表示しているエントリーのURLが、アンカーリンクのリンク先URL中に含まれている場合にclassを付与します

今回は「linkMatchLocationMark(.js-link_match_location)」を利用して実装


linkMatchLocationでタグの絞り込みをわかりやすく実装

「主要なキーワード(tag)」で絞り込んだ際に、ボタンの<a>にclassで「stay」を付与し、cssで色を変えています。
「linkMatchLocationMark」はURLを含む値で判定できますので、ページャーなどで次ページに移った際にも判定出来ますので、ボタンの「stay」の状態が切れることはありません。htmxでURLを変更した際にも「linkMatchLocation」は問題なく動作しますので、htmxのSPA的な動きと組み合わせると色々なところで応用が効きそうです。

・実装したページはこちら(弊社の制作事例ページ

最後に

今回はa-blog cmsの「組み込みJS」とhtmxを使い、簡単に現在位置の反映ができました。この様にa-blog cmsはhtmxとの連携にも強く、a-blog cmsに元々備わっている「組み込みJS」を使った場合にも、効率的に動作させる事が出来ます。a-blog cms ver3.1.17でhtmxの利用が従来より簡単になり、セキュリティ面も強化されましたので、さらに安心して利用する事が出来る様になりました。htmxはUXの改善にも使いやすいので非常に嬉しいです。

ということで、今回はa-blog cmsとhtmxで「組み込みJS」を使ってみました。
またa-blog cmsとhtmxにつきましては、随時レポートしていこうと思います。

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


先日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 https://htmx.org/
・htmx ajax header https://htmx.org/extensions/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;
    });

    addEventListener('htmx:afterSwap', function (event) {
        ACMS.Dispatch(event.target);
    });

    //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;
    });
</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="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とスマホとの両立を考えると、「続きを見る」としてその場でロードし追加表示する実装も良いと思いますが、再度アクセスした際に初期状態に戻ってしまうことを考えると、今回はページャーを実装しページを分けてヒストリーバックが機能する様にしてみました。

【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="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">&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="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">&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をお勧めする理由


a-blog cmsとhtmxが非常に相性が良いということで、ベースキャンプ名古屋で開催された「htmx」の勉強会に行ってきました。

htmxは初めて学んだのですが、htmlに記述するだけで複雑なjsを書かなくても、簡単に非同期で要素の置き換えなどができる、多くの機能を備えた js ライブラリの様です。a-blog cms に慣れたユーザーでしたら、「ポストインクルード」の代わりになるものと説明すると分かりやすいかもしれません。

・htmx
https://htmx.org/

・a-blog cms ポストインクルード
https://developer.a-blogcms.jp/document/postinclude/

htmxの話は今回初めて聞いたため、まだ使っておらず機能的なことも詳しくないのですが、すでに海外では非常に人気のあるライブラリの様です。ただ日本ではあまり活用されておらず話題も少ないとのことでした。

htmxの使い方

このhtmxはhtmlに少し専用の記述を追加するだけで簡単に実装ができます。機能を発火させるトリガーの種類や、置き換え対象要素の指定方法なども複数設定がある様なので、その中で仕様に合うものがあれば、低コストで機能性を高めたサイトを作れる可能性があります。ぜひ詳細はhtmxのページを見てください。

<!-- 例:キーアップの500ミリ秒後に #search-results を所得した結果で置き換え -->
<input type="text" name="q"
    hx-get="/trigger_delay"
    hx-trigger="keyup changed delay:500ms"
    hx-target="#search-results"
    placeholder="検索"
>
<div id="search-results"></div>

強力なa-blog cmsのテンプレート(html)の活かし方が広がる

a-blog cmsのテンプレートエンジンは非常に強力で、a-blog cmsの大きな魅力のひとつだと思います。
PHPなどのプログラムが書けなくても、htmlに専用の記述を書くだけで、DBから欲しい情報を簡単に取得し加工出来る優れた機能を持っています。(もちろんPHPが出来るともっと色々なことができます)

今回の勉強会で話を聞いていて、この優れたテンプレート機能にhtmxがもつUXを改善できる手軽さが加わることで、今まで以上にa-blog cmsの幅を広げるのではないかと思いました。今までもポストインクルードという似た機能はありましたが、個人的には少し取り扱いが難しいと感じていたところもあり、どうしても必要な時にしか使ってこなかった印象があります。ただこのhtmxの場合、最初にセットアップさえしてしまえば、あとは手軽に実装できますので、非常に痒いところに手が届くものになる可能性がありそうです。

また、a-blog cmsには強力なテンプレートのキャッシュ機能がありますので、テンプレートをキャッシュさせてhtmxで非同期に取り扱うことで、従来より高速に動くというお話もありました。このあたりは非常に興味のある話題で、実際にどれほど差があるのかとても興味が湧きました。

SEOの流れにも繋がるところがある

前回のブログ(SEOの話題)で「SEOとは「UX を高めていく事」という時代になったのだと思う」という話を書きましたが、このhtmxはまさにその流れに乗ったものかもしれません。

正直jsをごりごりと書いているプログラマーの方は、htmxだと物足りないと思うかもしれませんが、htmxでUXを改善する手間が減れば、より多くのサイトで機能性を高めるきっかけになると思います。もしかすると日本であまり流行っていないのは、このあたりの認識が海外より重要視されていないのかもしれません。

以上、勉強会の感想でしたが、このブログを書いている段階では、まだ一度も実装したことがありません。
ただ、今回お話を聞いて「これは良さそう」と感じましたのでhtmxのことは今後も少し勉強していこうと思います。

最後に

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