見出し生成機能を ブログコンテンツ や マニュアル系コンテンツ などで使用したいと多くの方のご要望もあり、目次を生成する組み込みJSが a-blog cms Ver. 2.10 で搭載されました。このハンズオンではこの組み込みJSを使って、目次ユニットを作ってみましょう。

ここでは、beginner2019テーマの初期インストール状態を例に解説していきます。環境が異なる場合はご自身の環境に合わせて読み替えてください。

完成イメージ

組み込みJS の仕様確認

ブログコンテンツ や マニュアル系コンテンツ などで便利な見出し一覧を出力するための組み込みJS。

特徴

以下のような特徴があります。

• 文章のアウトラインを ul/ol でマークアップしたものを出力
• アウトラインアルゴリズムは、HTML5（Living Standard）の仕様に従っている
• HTML全体ではなく、部分的にアウトライン化可能
• アンカーリンクを自動生成

組み込み方法

<div class="target-list"></div>

<div class="js-outline" data-target=".target-list">
<!-- コンテンツ内容 -->
</div>

コンテンツ内容を js-outline クラスを振った要素で囲み、data-target で出力先を指定します。

オプション

オプションは data属性で指定します。または、ACMS.Config.documentOutlinerConfigの値を変更することで調整可能です。 data属性はコンテンツを囲う、"js-outline"クラスがあるdivで指定します。

例

<div class="entry-body acms-entry js-outline"
     data-target=".js-outline-yield"
     data-link="true"
     data-listType="ol"
     data-listClassName="outline-list"
     data-itemClassName="outline-item"
     data-linkClassName="scrollTo"
     data-anchorName="heading-$1"
     data-levelLimit="1"
     data-exceptClass="js-except">
<!-- コンテンツ -->
</div>

カスタムユニットの作成

目次を出力するカスタムユニットを作っていきます。

編集側の設定（ボタンの追加）

まずは、カスタムユニットを追加するボタンを作成します。

管理ページ > コンフィグ > 編集設定 の 「ユニット追加ボタン」で以下の項目を追加します。

• モード: 拡張（custom_outline）
• ラベル: 目次

ユニット追加ボタンの追加

次にユニット設定で、先ほど追加したボタンの振る舞いを設定します。

管理ページ > コンフィグ > ユニット設定 に移動し、目次ユニットに「目次」を追加します。

ユニット設定

ユニット編集側のカスタマイズ

これで、目次ユニットの追加ができるようになりましたが、このままだとユニットを追加しても、空のユニットが表示されるだけなので、わかりずらいです。編集時のユニットの設定をしましょう。

「themes/beginner2019/admin/entry/unit/extend.html」で拡張ユニットの編集画面時のテンプレートをカスタマイズできます。

<!-- BEGIN custom_outline -->
<p>ここに目次（アウトライン）が表示されます</p>
<!-- END custom_outline -->

編集側のテンプレートは、この程度で問題ないかと思います。

テンプレートを書かないと、空でわかりにくい

編集時のテンプレートを書いた場合

ユニット表示側のカスタマイズ

拡張ユニット（目次）が追加できるようになったので、肝心の 組み込みJS を使った、表示側を実装していきましょう。

テンプレート

表示側のテンプレートは、「themes/beginner2019/include/unit/extend.html」になります。ここに以下のようなコードを記述します。

<!-- BEGIN unit#custom_outline -->
<nav class="outline">
  <h2 class="outline-title js-except">目次</h2>
  <div class="js-outline-yield outline-list-wrap"></div>
</nav>
<!-- END unit#custom_outline -->

ポイントは２つあります。

ポイント１ このユニットが、目次表示されるところなので、あとで設定する組み込みJSからターゲット指定できるように クラス js-outline-yield をつけておく。

ポイント２ 目次自体の見出しは、目次リストに出したくないので見出しに js-except クラスを振っておく。

これで、カスタムユニットの設定は完了です。

組み込みJSの実装

最後に、目次が先ほど追加したカスタムユニットに表示されるように組み込みJSを実装していきます。

最初の例でいうと、

<div class="js-outline" data-target=".target-list">
<!-- コンテンツ内容 -->
</div>

の部分になります。目次化したい箇所をただ囲んであげればいいです。

beginner2019の場合は、以下のテンプレートがエントリ詳細のテンプレートになります。

• themes/beginner2019/include/entry/body.html: 36行目付近

<div class="acms-entry entry-column js-outline" data-target=".js-outline-yield">
    <div class="acms-grid">
    ...
    </div>
</div>

先ほど、カスタムユニットのテンプレートで指定した、.js-outline-yield を data-target に指定して、 js-outline クラスを振って完成です。

完成例

以上で完成になります。オプションも色々あるので、実際に設定してみて試してくみてください。今回は、エントリーのユニットで、目次を好きな位置に入れれるようにしましたが、組み込みJSなので、静的なHTMLなど他の場所でも利用できます。

コンテンツに合わせてぜひ活用してみてください。

チャレンジ

余力のある方は、以下のようなスタイルをCSSで実装してみましょう。ポイントは、リスト番号に親の番号も入っている点です。

ヒントは、「counter」「counter-increment」「counter-reset」です。

リストのスタイル例

a-blog cmsでは、httpとhttpsのリンクを自動で書き換える機能が標準で実装されています。（v1.4.0より） この機能は、相対パスでリンクしているナビゲーションのリンク先を、通常のhttpのページでは設定しているリンクのみhttpsとし、お問い合わせフォーム等のhttpsで運用したいページでは、設定していないリンク先を任意にhttpsではなくhttpとすることができます。

Ver. 2.8 で ctx（外部コンテキスト）が実装されてから、URLにない情報を動的に引っ張ってこれるになったため、ポストインクルードの利用頻度は下がったと思います。ただ現状でもポストインクルードにしかできない事もあります。このハンズオンでは、そんなポストインクルード機能の一例をご紹介します。

ここでは、beginner2019テーマの初期インストール状態を例に解説していきます。環境が異なる場合はご自身の環境に合わせて読み替えてください。

ポストインクルードの基本

まず、初めて触る方もいると思うので、ポストインクルード機能のおさらいをします。

どんな機能？

ポストインクルード（post include）機能は、フォームでpost（送信）した結果を、ページのリロードなしで表示する機能です。つまりページリロードなしに、他ページの情報を引っ張ってくることができます。技術的にはJavaScriptのAjaxを使用しています。

使い方

使い方は簡単で、検索したい情報の書かれた「POST_2GETモジュール」フォームを用意し、クラスに js-post_include をつけるだけです。あとは、検索ボタンを押した時に、フォームの情報の内容をひっぱてきて、 target で指定した要素に、コンテンツをページリロードなしで表示します。（targetを省略した場合は、form自体が置きかわります）

<form action="" method="post" class="js-post_include acms-form" target="#target">
  <input type="text" name="keyword" value="カスタムフィールド " size="15" />
  <input type="hidden" name="tpl" value="include/searchResultSample.html" />
  <input type="submit" name="ACMS_POST_2GET" class="acms-btn" value="検索" />
</form>

<div id="target"></div>

ポイントは、フォームで tplコンテキスト を指定している点です。これがなくてもポストインクルードは動作しますが、テンプレートを指定していないので、ページ全部を持ってきてしまいますので、テンプレートを指定する場合が多いと思います。

下にデモを用意したので、検索ボタンを押してみてください。

ポストインクルードの実装ポイント

これで、基本の使い方はわかりましたが、もう少しポストインクルードの実装方法をみていきます。

コンテンツの情報は、input要素だけでなく action でも指定可能

基本的には、ACMS_POST_2GETモジュールは、input要素でコンテンツの情報を指定しますが、 actionでもURLコンテキストを指定可能です。例えば以下のようにキーワードをactionに指定する事も可能です。

<form action="?keyword=カスタムフィールド" method="post" class="js-post_include acms-form" target="#target">
  <input type="hidden" name="tpl" value="include/searchResultSample.html" />
  <input type="submit" name="ACMS_POST_2GET" class="acms-btn" value="検索" />
</form>

<div id="target"></div>

すぐさま実行

さきほどまでは、自分でボタンを押すまで、コンテンツをひっぱてこないようになっていましたが、ページ表示時に自動で持ってきたい場合もあると思います。その時は、フォームにつけるクラス名を「js-post_include-ready」に変更します。これで自動できにひっぱってくることができるようになります。

その他のオプション

そのほかにもオプションはありますが、ここでは割愛します。詳しくは、ドキュメント をご覧ください。

次のエントリーをひっぱってくる

ポストインクルードの基本が抑えられたので、本題の次のエントリーを引っ張ってくる実装をしていきましょう。

概要

エントリー詳細ページで、次の記事へのリンクをつけることは、よくあると思います。ただ詳細ページを表示する Entry_Bodyモジュール の変数表をみると、urlとエントリータイトルしか出力ができません。デザインによっては、画像を表示したり、カスタムフィールド の情報を出力したい場合があると思います。これをポストインクルードを使って実装していきましょう。

URLとタイトルしか出せない

ポストインクルードを仕込む

まず次のエントリー、前のエントリーのリンク部分をカスタマイズしましょう。beginner2019テーマだと、 themes/beginner2019/include/parts/pager.html になります。

<!-- BEGIN serialNavi:veil -->
<nav aria-label="ページ送り">
	<ul class="serial-nav clearfix">
		<li class="serial-nav-item serial-nav-item-prev"><!-- BEGIN prevLink -->
			<form action="{url}" method="post" class="js-post_include-ready">
				<input type="hidden" name="tpl" value="include/parts/serial-navi.html">
				<input type="hidden" name="ACMS_POST_2GET">
			</form>

			<!-- END prevLink -->
		</li>
		<li class="serial-nav-item serial-nav-item-next"><!-- BEGIN nextLink -->
			<form action="{url}" method="post" class="js-post_include-ready">
				<input type="hidden" name="tpl" value="include/parts/serial-navi.html">
				<input type="hidden" name="ACMS_POST_2GET">
			</form>
			<!-- END nextLink -->
		</li>
	</ul>
</nav>
<!-- END serialNavi:veil -->

ポイントは、次（前）のエントリーの情報が、URLとタイトルしかないので、フォームの action に、URLを入れて、次（前）のエントリー情報を渡しているところになります。 またクラスに、 js-post_include-ready を指定して、自動的に読み込まれるようにしています。

リンクのテンプレートを作る

ポストインクルードの仕込みができたので、表示するテンプレートを用意しましょう。 今回は、 themes/beginner2019/include/parts/serial-navi.html に新しいHTMLを作成します。モジュールは色々な情報を出力できる、 Entry_Summary を使いましょう。

<!-- BEGIN_MODULE Entry_Summary ctx="/bid/%{BID}/eid/%{EID}" -->
<!-- BEGIN unit:loop -->
<!-- BEGIN entry:loop -->
<a href="{url}"><!-- BEGIN image:veil -->
	<img src="%{ROOT_DIR}{path}" alt="{alt}" class="acms-img-responsive" width="100"><!-- END image:veil -->
	<!-- BEGIN noimage --><img src="/images/default/noimage.gif" alt="" class="acms-img-responsive" width="100"><!-- END noimage -->
	<p>{title}</p>
</a>
<!-- END entry:loop -->
<!-- END unit:loop -->
<!-- END_MODULE Entry_Summary -->

ポイントは、ctx（外部コンテキスト）で情報を絞っているところです。bidとeidをURLの情報で絞り込むようにしています。ctxの記述がないと、単なるエントリーのリストが表示されてしまいます。（ctxではなくモジュールID化しても大丈夫です）

次（前）の画像をひっぱってこれた

以上で完了です。Entry_Summaryで表示できるものなら、なんでも引っ張ってくることができるようになりますので、ぜひお試しください。

英語版パッケージの紹介。

a-blog cmsの英語版が欲しいという要望にお応えするために作成しました。
英語版パッケージは上の図のように管理画面で使えます。

ツールチップも英語化されています。

ツールチップも英語化されていますので、英語圏の方でも安心して作業が出来ます。

導入方法

下記のファイルを解凍して、systemというフォルダを取り出してください。

system.zip

a-blog cmsの以下のフォルダを解凍したフォルダで置き換えて下さい。

• themes/system

この際に日本語の管理画面を残したい場合は、元のsystemフォルダを別の名前に書き換えて、解凍したフォルダを配置しましょう。
これで管理画面の英語化は完了です。

制作・リニューアル時の確認に便利な機能

すでに公開されているサイトの表示を変更するとき、公開前に実際のページにテンプレートを適用して表示を確認したい場合があります。この場合は、URLコンテキストを利用することで任意のテンプレートを使ってページを表示するように指定できます。

利用方法

本来のページの末尾に"/tpl/使用したいテンプレート"という記述を加えることで、任意のテンプレートを指定できます。以下に例を示します。

http://example.com/ccd/ecd.html を
"使用中のテーマ/modified.html"で表示したい場合

http://example.com/ を
"使用中のテーマ/renewal/newTop.html"で表示したい場合

注意点

/tpl/以下で指定するテンプレートhtmlファイルは、公開サイトで使用しているテーマディレクトリに格納されている必要があります。別テーマディレクトリ内のテンプレートhtmlファイルは摘要できませんのでご注意ください。