モジュールが出力する変数の表示を加工したい

説明

a-blog cmsでは、各モジュールがそれぞれ出力する変数（情報）の内容を、指定した規則にしたがって加工・編集することができます。

回答

「校正オプション：リファレンス」を参考に、表示する変数の後ろに校正オプションの記述を追加してください。

校正オプションは変数の内容を、最終的に出力する前に指定した内容で変換します。以下に例として一部を示します。

数字のカンマ区切り : [number_format]　数字を千位毎にカンマ区切りにします

改行をHTMLに変換 : [nl2br]　改行コードを <br /> に変換します

一行をリストのHTMLに変換 : [list]　一行ごとに <li> ~ </li> に変換します

テンプレートの基本

a-blog cms で更新ができるページを作るためのHTMLファイルをテンプレートファイルといいます。テンプレートファイルにいろいろなモジュールを貼り付けていくことで、データベースに保存されている情報をHTMLに配置していきます。

a-blog cms のテンプレートファイルは基本的にはHTMLファイルで作られており、PHPのプログラムを直接記述することはありません。データベースに保存されている情報を表示するためのモジュールや、表示/非表示を制御するブロック、外部ファイルを読み込むインクルード、テンプレートのどこに記述しても動作するグローバル変数といった記述を、HTMLファイル内に組み込んで作成することになります。

テンプレート内でエントリーの一覧を表示している例

<!-- BEGIN_MODULE Entry_List -->
<div>
<!--#include file="/admin/module/setting.html"-->
<ul>
	<!-- BEGIN entry:loop -->
	<li><a href="{url}">{title}</a></li>
	<!-- END entry:loop -->
</ul>
</div>
<!-- END_MODULE Entry_List -->

この例では、Entry_Listモジュールを使って、エントリーのタイトルとリンク先を出力しています。
＜!-- BEGIN entry:loop --＞から＜!-- END entry:loop --＞の間を繰り返し表示する事になります。また、モジュールのコメントタグについては実行後には削除され通常のHTMLソース側には表示されません。

また、a-blog cms ではテンプレートファイルはテキストファイルであれば、どのようなファイルでもテンプレートにできます。

Ver.2.5以前ではブロックがモジュール内で一度しか利用できない仕様となっておりましたが、同じモジュール内でもVer.2.5より再利用できるようになりました。

インクルード

テンプレート内に外部ファイルを読み込む

いくつかのテンプレートファイルを作成していると、サイト内の共通部分を再利用できるように管理をしたい場合があります。a-blog cmsでは、テンプレート内に外部ファイルを読み込むインクルード機能があり、任意のファイルをテンプレート内に表示できます。

Ver. 2.8.0 以上

Ver. 2.8.0 から新しい記法でインクルード文がかけるようになりました。以前のインクルードはただファイルを読み込んでくるだけでしたが、新しいインクルード文には、変数を読み込み先テンプレートに渡せる機能が追加されています。

＊ Ver. 2.7以下の記法でも動作しますので、バージョンアップしても大丈夫です。

読み込み元

@include("/path/to/file", {"key": "value", "key2": "value2"})

読み込み先

<p>{{key}}</p>
<p>{{key2}}</p>

変数の渡し方は、@include()の第２引数に、JSON形式で渡します。変数の使い方は、通常の変数と違い２重の中括弧で囲むことで表示できるようになります。

デフォルト値

変数が空だったり引数として渡されなかった場合に、デフォルト値を設定できるようになっています。 |（パイプ）で区切り、default(" ") で定義できます。また、|（パイプ）で区切るものはデフォルト値だけでなく、別変数も記述できます。その場合は、左から見ていき空でない値があったときに、その変数が表示されます。

{{key | key2 | default("デフォルト値")}}

例：Ver. 2.7.x 以下

<!--#include file="/include/sample.html"-->
<!--#include file="http://www.example.com/include/sample.txt"-->

上記の表記については、SSI（サーバーサイドインクルード） と同様の記述になりますが、a-blog cms がSSIを使ってインクルードをしているという事ではありません。Adobe Dreamweaver のデザインビューでインクルード後の画面が表示されるように同じ表記としています。

また、インクルードの記述をする際には、相対パスで記述する事も可能ですが、絶対パスで設定する事をおすすめします。絶対パスのルートについてはテーマのディレクトリがルートディレクトリとなり、SSIとは違う解釈となります。

setTemplate setRenderedを使いこなそう

setTemplate及びsetRenderedは Ver. 2.6.0 より追加されたテンプレートエンジンです。setTemplate, setRenderedを使うとテンプレートの変数化ができ、何度も同じテンプレートを使い回したり、複雑なレイアウトのページでも作りやすくなります。

作業場所

作業テーマ： simple2016
作業テンプレート：/themes/simple2016/realestate/index.html
作業URL： http://ドメイン/

ハンズオン内容

  • setTemplateを理解する
  • setRenderedを理解する
  • 変数表(VarsTable)を利用する

SetTemplateを理解する

setTemplateはテンプレートが解決される前のテンプレートを変数化します。 また、setTemplateで囲まれたテンプレートは非表示になります。
例えば、インクルード用のファイルを用意して、そこによく使うようなテンプレートを <!-- BEGIN_SetTemplate id="" --><!-- END_SetTemplate --> で囲います。これで、そのインクルードファイルを一つインクルードするだけで、複数のテンプレートセットを使えるようになります。インクルード数が減り、テンプレートの管理がしやすくなります。

下のソースコードはsetTemplateでテンプレートを定義し、そしてgetTemplateでそれを実際に呼び出すサンプルとなります。

（例） /themes/simple2016/include/set_template.html に記述

<!-- インクルードファイル -->
<!-- BEGIN_SetTemplate id="summary_a" -->
<p>Aが呼ばれました。</p>
<!-- END_SetTemplate -->

<!-- BEGIN_SetTemplate id="summary_b" -->
<p>Bが呼ばれました。</p>
<!-- END_SetTemplate -->

（例）/themes/simple2016/entry.html に記述

<!-- 上のインクルードファイルをインクルード 。この時点では何も表示されません。-->
<!--#include file="/include/set_template.html" -->

<!-- 以下の一行のコードを呼び出すと、Aが呼ばれました。と表示されます。-->
<!-- GETは一度だけではなく何度でも呼び出せます。 -->
<!-- GET_Template id="summary_a" -->

またsetTemplate内で使える変数があります。この変数は呼び出し元（getTemplate）から値を代入できます。例えばページに応じて別のモジュールIDを使いたいときなどに便利です。この際の変数は{{}}（二重カッコ）で括ります。
以下の例では、defaultというモジュールIDでエントリーサマリーを呼び出しています。

<!-- GET_Template id="summary_a" module_id="default" -->

<!-- BEGIN_SetTemplate id="summary_a" -->
<!-- BEGIN_MODULE Entry_Summary id="{{module_id}}" -->
<!-- エントリーサマリーのソースが入ります -->
<!-- END_MODULE Entry_Summary -->
<!-- END_SetTemplate -->

またsetTemplateには変数の初期値を設定する機能があり、何も変数が代入されていない場合の値を以下のように決めておくことができます。

<!-- BEGIN_SetTemplate id="summary_a" module_id="default" -->
<!-- BEGIN_MODULE Entry_Summary id="{{module_id}}" -->
<!-- エントリーサマリーのソースが入ります -->
<!-- END_MODULE Entry_Summary -->
<!-- END_SetTemplate -->

<!-- GET_Template id="summary_a" -->
<!-- モジュールIDがdefaultとして実行される -->

<!-- GET_Template id="summary_a" module_id="news_summary" -->
<!-- モジュールIDが"news_summary"として実行される -->

ハンズオン課題1：デフォルトで「a-blog cmsが呼ばれました。」と表示し、「a-blog cms」の部分を変更可能なテンプレートを作成してみましょう。

simple2016テーマに/include/vars/all.htmlというファイルを作成し、それを/realestate/index.htmlでincludeします。 下記のようにgetTemplateすると下の図のような実行結果が得られるように/include/vars/all.html内でsetTemplateを定義しましょう。 nameに値が入っていればその値が出力結果に反映され、入っていなければデフォルトでa-blog cmsが表示されるようにしてください。 また、実行結果は ドメイン名/realestate/ で確認できるようにしてください。

<!-- GET_Template id="summary_a" -->
<!-- GET_Template id="summary_a" name="hands-on" -->

実行結果

ハンズオン課題2：/realestate/のページにてエントリーサマリーを以下の仕様を満たすテンプレートに作り変えましょう

  • 変数でモジュールIDを設定可能、デフォルトでsummary_indexを表示する
  • 変数で日付のあり、なしを設定可能（デフォルトでは日付なし）
  • 変数でページャーのあり、なしを設定可能（デフォルトではページャーなし）

/realestate/index.htmlを編集して、

<!-- #include file="/include/entry/summaryCustom.html" -->

と書いてある部分をgetTemplateで呼び出せるようにしてください。その際、setTemplateが定義されたファイルは下記のように別途読み込んでください。 /include/entry/summaryCustom.html に書いてある内容を /include/vars/all.html にコピーして作業を開始すると便利です。 なお、物件情報にはエントリーがデフォルトで3件しか登録されていませんので、エントリー数を増やすか、モジュールの設定でエントリーの表示件数を減らすかしてページャーが表示されるようにしてください。

...
<body>
<!-- #include file="/include/vars/all.html" -->
...

実装のヒント：ページャーの有無、日付の有無にはそれぞれ以下のソースコードをご利用ください。

<!-- BEGIN_IF [{{date}}/eq/true] -->
<time>{date#Y}/{date#m}/{date#d}</time>
<!-- END_IF -->

<!-- BEGIN_IF [{{pager}}/eq/true] -->
<!-- #include file="/include/parts/pager.html" -->
<!-- END_IF -->

GET_Templateの例

<!-- GET_Template id="summary" date="true" pager="true" module_id="property_entry_summary" -->

完成系のイメージ

setRenderedを理解する

setRenderedはsetTemplateとは違い、テンプレートが解決された後に変数化します。IFブロックよりも後で実行されるということになります。

以下のソースコードはEntry_Summaryのページャーにあたる部分を変数化して、それを全く別の場所に表示している例になります。

<div class="acms-container">
<div class="acms-grid-r">
  <div class="acms-col-md-9">
    <!-- BEGIN_MODULE Entry_Summary id="summary" -->
      ...
      <!-- BEGIN_SetRendered id="pager" -->
      <!-- #include file="/include/parts/pager.html" -->
      <!-- END_SetRendered -->
    <!-- END_MODULE Entry_Summary -->
  </div>
  <div class="acms-col-md-3">
    <!-- GET_Rendered id="pager" -->
  </div>
</div>

ハンズオン課題3：先ほど作成したテンプレートを編集し下の図のように上下にページャーがつくようにしてみましょう。

完成系のイメージ

※パディングなどの見た目の調整はお好みに合わせて各自でスタイルを調整してください。

変数表を使用する

Ver.2.6.1よりsetTemplateを定義したファイル群をTemplate_VarsTableモジュールで囲うことで、変数表を生成できるようになりました。以下がそのサンプルのソースになります。

<!-- BEGIN_MODULE Template_VarsTable -->

<!-- すべてのパーツの読み込み -->
<!--#include file="/include/vars/base.html" -->

<!--#include file="/admin/template/vars-table.html"-->

<!-- END_MODULE Template_VarsTable -->

また、以下のようなコメント文をsetTemplate前に記述することでVarsTableに表示する内容を調整できます。

<!--@doc
-->
  • id:テンプレートのID名
  • param:テンプレートに代入できる変数名（複数指定可）
  • author:テンプレートの作成者名
  • create:作成日

この変数表はblog2016, site2016, bootstrap2016テーマにおいて /varstable.htmlにアクセスすることで閲覧することが可能になっています。参考にしてください。

ハンズオン課題4：課題2で作成したテンプレートを表示する変数表を作成してみましょう。

site2016テーマよりvarstable.html複製し、同じファイル名でsimple2016テーマに設置してみましょう。

完成系のイメージ