ドキュメントdocument

テンプレート

テンプレートの基本

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の管理ページから設定するテンプレートファイルはトップページ・一覧ページ・詳細ページ・エラーページ・管理ページ・エントリー編集ページ・ユニット追加ページ・ログインページの8種類になります。

テンプレートファイルは、管理画面 > コンフィグ > テーマ設定の順に移動し、テンプレートファイルの項目で設定できます。


一般的な設定方法


テンプレートの種類

トップページ

そのサイト(ブログ)のトップページにアクセスした際に適用されるテンプレートファイルです。一覧ページや詳細ページとは違い、URLコンテキストによる影響を受けることが少ないテンプレートです。

一覧ページ

カテゴリーのトップページで複数のエントリーを一覧表示する際に適用されるテンプレートファイルです。そのほかにも、カスタムフィールド・タグ・キーワードの検索結果と現在いるページを指定したときに使用されます。

ブログテーマのように、エントリー本文のモジュールを一覧ページに使用している場合、エントリー編集画面で設定できる『以下のユニットが一覧表示時に「続きを読む」になります』ブロックよりも上部のユニットまでが表示され、以下のユニットは詳細ページのみ表示されます。

詳細ページ

個別のエントリーや固定ページを表示する際に適用されるテンプレートファイルです。詳細ページ・エントリー編集ページ・ユニット追加ページのテンプレートは同じにしておくと、エントリーを書く際に詳細ページと同じ見た目でコンテンツを編集することができます。

エラーページ(404 Not Found)

存在しないURLにアクセスした際に適用されるテンプレートファイルです。カスタマイズ次第で、エントリーが存在しない場合に、検索やオススメのエントリーを表示することもできます。

管理ページ

管理ページを表示する際に適用されるテンプレートファイルです。管理ページ共通のテンプレートファイルになり、/themes/system/admin/ 以下のディレクトリおよびファイルがURLのパスに従って表示されています。

<section id="main" role="main">
    <!--#include file="/admin/%{ADMIN_PATH}.html"-->
</section><!-- /#main -->

エントリー編集ページ

エントリーを投稿・編集する際に適用されるテンプレートファイルです。詳細ページと同じテンプレートにしておくのが一般的です。

ユニット追加ページ

エントリーにユニットを追加する際に適用されるテンプレートファイルです。詳細ページと同じテンプレートにしておくのが一般的です。

ログインページ

ログインページに適用されるテンプレートファイルです。管理者、投稿者・編集者・読者がログインするだけではなく、会員機能サイトをつくる際には、新規読者登録をする画面として使用されます。カスタマイズ次第で、新規読者登録の際の項目を増やすことができます。


インクルード

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

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

例:インクルード機能を使ったファイル読み込みの記述

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

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

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


グローバル変数

テンプレートファイルのどこでも使える変数

通常、{title} のように記述される変数はモジュールの中に記述されている必要がありますが、グローバル変数はテンプレートのどこに記述しても編集されます。

グローバル変数の一例

%{BLOG_NAME}表示ページが属するブログの名前
%{CATEGORY_NAME}表示ページが属するカテゴリーの名前
%{KEYWORD}URLコンテキスト上で、指定されたキーワード
%{CID}カテゴリーID
%{EID}エントリーID

他の機能との組み合わせ

グローバル変数とインクルード機能を組み合わせて使うと、表示ページのカテゴリー毎に違うテンプレートファイルを読み込むという使い方もできます。

<!--#include file='/admin/entry/category%{CID}.html'-->

このような組み合わせでテンプレートのカスタマイズをする事は多くあります。特定のカテゴリーの時だけ利用したいカスタムフィールドを書いたテンプレートファイルを読み込む際に大事なテクニックの1つになります。

各種グローバル変数についてはリファレンス内のグローバル変数のページをご覧ください。


実行順序

テンプレートファイル上での実行順序

テンプレートエンジンの実行順序は以下のようになります。

  1. グローバル変数を解決
  2. インクルード処理を解決
  3. setTemplateを処理(テンプレートの変数化)
  4. getTemplateを解決(変数の挿入)
  5. タッチモジュールを解決(デフォルトON)
  6. モジュール類を内側から解決(同じ階層の場合は下から)
  7. IFブロックを解決
  8. setRenderedを処理(解決済テンプレートを変数化)
  9. getRenderedを解決(変数の挿入)

テンプレートの実行順序を頭に入れておく事はテンプレートを作成していく上で非常に重要になってきます。
例えば、インクルード文を書くときに、グローバル変数を使ったパスで指定するテクニックがあります。

<!--#include file='/admin/entry/category%{CID}.html'-->

上のコードは、正常に動きますが、これはグロバール変数が解決された後にインクルードが動くためです。
下のコードをご覧ください。

<!-- BEGIN_MODULE Blog_ChildList -->
<ul><!-- BEGIN blog:loop -->
	<li><a href="{url}">{name}</a></li>
        <!--#include file='/admin/entry/categoryblog_{bid}.html'--><!-- END blog:loop -->
</ul><!-- END_MODULE Blog_ChildList -->

ここでは、ブログリストでブログ毎にインクルードをしてこようとしていますが、{bid} はモジュールの変数なのでインクルード文より後で解決されます。
つまり、インクルード文が実行される段階では"blog_{bid}"というファイルを探しにいってしまい、うまく動作しません。


パスの書き換え

a-blog cms のパス書き換え

a-blog cmsでは /themes/テーマ/ が ドキュメントルート的な扱いになります。 しかし、このままではパスがおかしくなるので、パスの書き換えを行っています。 a-blog cmsでは、この機能により静的なサイトをそのまま themes に入れても動くようになっております。

書き換えるもの

パスの書き換えには2種類あります。 ファイル指定するものと、アンカー類です。

ファイル指定するもの

  • <!-- include file="" -->
  • src属性をもつHTML要素 ( img|input|script|frame|iframe )
  • link要素
  • object, applet要素
  • background属性

パス書き換え仕様(ファイル指定)

  • 何らかのスキーマ(http://等)から始まっているものは書き換えない
  • "/"のみの場合は書き換えない
  • "/"から始まるパスはドキュメントルートから探索しみつかった場合は書き換えない
  • "/"から始まるパスでa-blog cms設置ディレクトリから探索しみつかった場合は書き換え
  • "/”から始まらない場合はそのテンプレートからの相対パスで検索しみつかった場合は書き換え
  • 上記のどれにも当てはまらない場合は継承テーマから探索しみつかった場合は書き換え

上から優先度が高くなります

アンカー類

  • a要素のhref属性
  • form要素のaction属性

パス書き換え仕様(アンカー類)

  • 空の場合は書き換えない
  • 何らかのスキーマ(http://等)から始まっているものは書き換えない
  • "#"から始まるパスは書き換えない
  • "/"から始まらないパスは書き換えない
  • ディレクトリをほってa-blog cmsが設置してある場合、そのディレクトリのパスから始まっている場合は書き換えない
  • 上記のどれにも当てはまらない場合は、ブログコードからのパスに書き換える

上から優先度が高くなります

書き換えをしたくない場合

このパスの書き換えは便利な機能なのですが、時に書き換えを行ってほしくない場合があります。 例えば、すべてのブログで共通するグローバルナビゲーションなどです。

<a href="/">HOME</a>

上の例ではトップページへのリンクのつもりで書いてますが、子ブログにこのコードがあると、 http://ドメイン/子ブログのコード/ のように、そのブログのトップページへのリンクに書き変わってしまいます。

書き換えを行わないようにするには

パスを書き換えたくない場合は、その要素に"acms_no_rewrite"という属性を追加すると書き換えを行わなくなります。

<a href="/" class="acms_no_rewrite">HOME</a>

上の例では classの値で設定をしておりますが、他の指定方法でも動作します。(独自データ属性など) また、"acms_no_rewrite"の識別子を変更したい場合は、config.system.yaml

acms_no_rewrite : 変更後識別子

として頂ければ変更できるようになっています。


校正オプション

変数のデータを校正・整形するオプション

{data} のような変数に {data}[option] のようにカッコ表記を加えることでデータをプログラムで処理できる機能を校正オプションと呼びます。いろいろな校正オプションがありますが、いくつかの例を紹介します。

文字数を指定した数以下を省略表示(半角の幅は1、全角の幅は2となります。)
{text}[trim(13, '...')]
数字を千位毎にカンマ区切りで表示
{number}[number_format]
日付から和暦の年を算出して表示(1985/08/26[wareki] -> 昭和60年)
{date}[wareki]
日付を誕生日としての現在の年齢を表示(2014年1月31日現在の場合 1984/01/23[age] -> 30)
{date}[age]
| を利用し [ ] 内に複数のオプションを記述する例
[escape|nl2br]

校正オプションを何か一つ設定すると escapeが自動で指定されません。 エスケープが必要な場合は 必ずescapeをパイプで繋げて下さい。 校正オプションが何も指定されない場合には、デフォルトでescapeが指定されます。 例) {var}[escape|nl2br]

お問い合わせフォーム等、不特定のユーザーが入力した内容を表示する箇所では必ずエスケープする校正オプションの併用をするようにして下さい。

独自の校正オプションを作成する

/php/ACMS/User/Corrector.php を編集することでオリジナルの校正オプションを作成できます。Corrector.php 内に記述例がありますので参考にしてください。

各種校正オプションについてはリファレンス内の校正オプションのページをご覧ください。


veilブロック

非表示部分の制御 :veil ブロック

条件による表示/非表示の制御について、モジュール単位では「タッチモジュール」がありますが、ここでは :veil ブロックによるモジュール内での部分的な表示の制御について解説します。

カスタムフィールド画像を表示する場合

例えば、カスタムフィールド画像を表示させる際には、以下のような記述となります。

<img src="{photo1@path}" width="{photo1@x}" height="{photo1@y}">

しかし、この記述では画像が無い場合には、

<img src="" width="" height="">

のようなタグがそのまま表示されてしまう事になります。これを表示しないために、:veil という機能が用意されています。

<!-- BEGIN photo:veil -->
<img src="{photo1@path}" width="{photo1@x}" height="{photo1@y}">
<!-- END photo:veil -->

上記の記述は、カスタムフィールド画像の出力部分を <!-- BEGIN photo:veil --> から <!-- END photo:veil -->で囲むことで、その間にある変数 {photo1@path}, {photo1@x}, {photo1@y} のいずれも編集されなかった時に囲まれていた部分全体を非表示にする、という意味を持っています。

このように :veil を使うことで、変数の有無による表示/非表示の制御ができます。
変数の有無を超えた条件による表示の制御にはIFブロックを使います。


touchブロック

表示制御 :touchブロック

veilブロックの逆の機能としてtouchブロックがあります。これはveilと違って値が等しい時に表示をするブロックになります。

例えば、変数の値が英語で入っていた場合に、日本語に変更したり、文字ではなく専用のアイコンで表示するなど、変数を違う見せ方で見せる場合に有効です。

<!-- BEGIN color:touch#red -->赤色<!-- END color:touch#red -->
<!-- BEGIN color:touch#blue -->青色<!-- END color:touch#blue -->
<!-- BEGIN color:touch#yellow -->黄色<!-- END color:touch#yellow -->

上の例では {color} という変数に "red", "blue", "yellow" が入ってくるとします。 {color} が "red" だった場合には赤色と表示し、blue, yellowも日本語として表示してます。

ただし以下のコードは動きません。

<!-- BEGIN color:touch#red -->赤色({color})<!-- END color:touch#red -->
<!-- BEGIN color:touch#blue -->青色({color})<!-- END color:touch#blue -->
<!-- BEGIN color:touch#yellow -->黄色({color})<!-- END color:touch#yellow -->

touchブロックの中に変数{color}があるので、veilブロックとして動いてしまいます。 {color}に何が来ても、「赤色、青色、黄色」全てが表示されてしまいます。

touchブロックはveilと逆でブロックの中には変数を使わないようにしましょう。

veil, touchブロックで制御できない場合は、IFブロックをお使いください。パフォーマンス的にも問題ありません。


IFブロック

詳細な条件による表示/非表示の制御 IFブロック

条件による表示/非表示の制御については、:veil ブロックによるモジュール内での部分的な表示の制御について解説しましたが、ここでは、より詳細な条件による制御を行う IFブロックについて解説します。

IFブロックの記述例

<!-- BEGIN_IF [%{PAGE}/gte/5] -->
5ページ以上です
<!-- ELSE_IF [%{PAGE}/eq/4] -->
4ページです
<!-- ELSE -->
3ページ以下です
<!-- END_IF -->

上記の記述は、グローバル変数%{PAGE} が5以上の場合は「5ページ以上です」を表示、4の場合は「4ページです」、それら以外の場合は「3ページ以下です」を表示するという意味を持っています。

BEGIN_IF部分には、条件式の指定として[]の中にa-blog cmsのURLコンテキストのように 値/オプション/値 と指定します。またネスト(入れ子)にすることもできます。

<!-- BEGIN_IF [a-blogcms/lk/cms] -->
cms
<!-- ELSE -->
not cms
<!-- END_IF -->

基準となる値を左側に、対象を右側にしてください。例えば上記の「含まれる」では、「a-blogcms」の中に「cms」があるかを判断しています。「cms」の中に「a-blogcms」があるか、ではない点に注意してください。書く順番が重要になります。

オプション

演算子条件意味
eq=等しい
neq!=等しくない
gt>より大きい
gte>=以上
lt<より小さい
lte<=以下
lkLIKE含まれる
nlkNOT LIKE含まれない
reREGEXP指定した正規表現に合致する
nreNOT REGEXP指定した正規表現に合致しない
emEMPTY値が空(何も入っていない)
nemNOT EMPTY値が空(何も入っていない)ではない

テンプレート内での実行順序

テンプレートエンジンの実行順序は以下のようになります。

  • インクルードを解決
  • インクルード処理と同時にグローバル変数を解決
  • タッチモジュールを解決(デフォルトON)
  • モジュール類を内側から解決(同じ階層の場合は下から)
  • IFブロックを解決

IFブロックの解決は一番最後に解決される為、条件式でグローバル変数やモジュールの変数も使用できます。 またモジュールのループ内でも動作します。

AND演算子とOR演算子

IFブロックではバージョン2.1.1からANDとOR演算子が使えるようになりました。AND演算子を使えば、両方の条件を満たした際、満たさなかった際の処理が出来ます。OR演算子を使えば、どちらか一方の条件を満たした際、満たさなかった際について処理できます。

AND演算子の記述例
<!-- BEGIN_IF [3/gt/2/_and_/2/lt/4] -->
	<p>条件を満たします</p>
<!-- ELSE -->
	<p>条件を満たしません</p>
<!-- END_IF -->

このソースのように判定したい条件同士を、_and_でつないであげることによって判定を行うことができます。上のソースの場合、3 > 22 < 4は両者とも条件を満たしますので、条件を満たしますが出力されます。

OR演算子の記述例
<!-- BEGIN_IF [4/lt/2/_or_/2/eq/2] -->
	<p>条件を満たします</p>
<!-- ELSE -->
	<p>条件を満たしません</p>
<!-- END_IF -->

このソースのように判定したい条件同士を、_or_でつないであげることによって判定を行うことが出来ます。上のソースの場合、4 < 2は条件を満たしませんが、2 = 2は条件を満たしますので、条件を満たしますが出力されます。


エスケープ

エスケープとは?

変数やブロックはエスケープする事ができます。 a-blog cms での エスケープとは、変数やブロックを一時的に動かないようにして、処理を遅らせる動きをします。ここでいう処理を遅らせる単位とはモジュール一回分になります。

これによりカスタムフィールドを動的に生成できたり柔軟なテンプレートを作成する事ができるようになります。 ここでは、最初に変数・ブロックのエスケープの仕方を確認して、最後に利用方法を例をだして解説します。

変数のエスケープ

以下のようにすると変数のエスケープができます。

\{hoge\} <!-- エスケープ 1回 -->
\\{hoge\\} <!-- エスケープ 2回 -->

中かっこの前にバックスラッシュを挿入する事により、エスケープができます。またバックスラッシュの数により、エスケープできる数が指定できます。

ブロックのエスケープ

<!-- BEGIN\ hoge --> ... <!-- END\ hoge --> <!-- エスケープ 1回 -->
<!-- BEGIN\\hoge --> ... <!-- END\\ hoge --> <!-- エスケープ 2回 -->

ブロックのエスケープは変数のエスケープと挿入位置が違いますのでご注意ください。 BEGIN, ENDの後ろに挿入します。こちらも変数同様、エスケープ回数をバックスラッシュの数で制御できます。

エスケープを使ったテクニック

エスケープを使ったテクニックをご紹介します。ここでは、ブログのカスタムフィールドグループを使って、エントリーのセレクトの選択肢を動的に出力しています。

<td><!-- BEGIN_MODULE Blog_Field -->
  <select name="label">
    <option value="">ラベルを選択</option><!-- BEGIN item_label:loop -->
    <option value="{item_label}"\{label:selected#{item_label}\}>{item_label}</option><!-- END item_label:loop -->
  </select>
  <input type="hidden" name="field[]" value="label" />
  <!-- END_MODULE Blog_Field -->
</td>

コードを見ていきましょう。モジュールは内側から実行されるので、まずBlog_Fieldが動きます。 そこで、{item_label}が解決されてラベルが設定されていきます。では{label:selecte#...}はどうでしょうか?

この変数はエスケープされているので、Blog_Fieldでは解決されません。バックスラッシュは1個なので、Blog_Fieldが動いた後に 普通の変数になります。

Blog_Fieldが動いた後のテンプレートが以下になります。

<select name="label">
  <option value="">ラベルを選択</option>
  <option value="新製品"{label:selected#新製品}>新製品</option>
  <option vlaue="完売"{label:selected#完売}>完売</option>
  <option value="在庫限り"{label:selected#在庫限り}>在庫限り</option>
  <option value="取寄品"{label:selected#取寄品}>取寄品</option>
  <option value="限定品"{label:selected#限定品}>限定品</option>
  <option value="季節商品"{label:selected#季節商品}>季節商品</option>
</select>

いつも書くセレクトのカスタムフィールドのテンプレートになりました。このようにエスケープをうまく使う事により、カスタムフィールドを動的にしたりできるようになります。


テンプレートの変数化

テンプレートを変数化する :setTemplate :setRendered

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

setTemplate

setTemplateはテンプレートが解決される前のテンプレートを変数化します。 また、setTemplateで囲まれたテンプレートは非表示になります。

例えば、インクルード用のファイルを用意して、そこによく使うようなテンプレートを setTemplate で囲います。これで、そのインクルードファイルを一つインクルードするだけで、複数のテンプレートセットを使えるようになります。インクルード数が減り、テンプレートの管理がしやすくなります。

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

<!-- BEGIN_SetTemplate id="tplB" -->
<p>Bが呼ばれました。</p>
<!-- END_SetTemplate -->
<!-- 上のインクルードファイルをインクルード 。この時点では何も表示されません。-->
<!--#include file="/include/template.html" -->

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

このように、テンプレートをセットにして扱え、好きな時に好きなだけテンプレートを呼べるようになります。 また、テンプレートが動く前を変数化するので、GET_Templateで呼び出されるまでは実行されないので、setTemplateがたくさんあっても重くなりません。

setRendered

setRenderedはsetTemplateとは違い、テンプレートが解決された後に変数化します。なので、先ほどのような使い方をすると、GETで呼び出していないテンプレートも実行されてしまいますので、このような使い方は好ましくありません。ではどのような時に利用するのでしょうか?

以下のコードをみてください。

<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/module/entry/pager.html" -->
      <!-- END_SetRendered -->
    <!-- END_MODULE Entry_Summary -->
  </div>
  <div class="acms-col-md-3">
    <!-- GET_Rendered id="pager" -->
  </div>
</div>

あまり、こうゆうレイアウトはないかもしれませんが、Entry_Summaryのページャーがサイドに呼び出されています。呼び出しているところは、Entry_Summaryの外です。

一見動かないように見えますが、setRenderedなら動きます。(setTemplateは動きません。) なぜならページャーが解決された状態が変数になっているので、どこで呼び出しても正常に動くからです。

このように、setRenderedを使うと、モジュールの囲みから解放されて複雑なレイアウトでもテンプレートを作りやすくなりました。よく使う要素は、テンプレートの先頭のほうで変数化してしまい、後は必要なところで好きに呼び出せます。

テンプレートの呼び出しオプション

setTemplate, setRendered共に、GET_Template, GET_Rendered に テンプレートのIDを指定して表示しましたが、オプションがあるのでここで紹介します。

トリム

以下のように指定すると呼ばれたテンプレートの改行がなくなります。

<!-- GET_Rendered id="tpl" trim="1" -->

専用変数

以下のようにキーと値を設定すると、変数化したテンプレートで、その値を利用できます。 このキーと値のペアは、何個でも指定できます。

ここでは、キーに 「mid, title」 値に 「newsSummary, ニュース」 を設定しています。

<!-- BEGIN_SetTemplate id="summaryTpl" -->
  <h3>{{title}}</h3>
  <!-- BEGIN_MODULE Entry_Summary id="{{mid}}" -->
    ...
  <!-- END_MODULE Entry_Summary -->
<!-- END_SetTemplate -->

<!-- 呼び出し -->
<!-- GET_Template id="summaryTpl" mid="newsSummary" title="ニュース" -->

上のコードのように、キーと値はGETする時に好きな値を何個でも設定できます。 その値を呼び出す時は、{{hoge}} というように 2重の中かっこで表示させる事ができます。

このようにテンプレートを変数化して、呼び出す時にその挙動を決定できるように出来ますので、テンプレートの再利用がしやすくなります。

ポストインクルードを使ってテンプレートファイルを表示するときの注意点

ポストインクルードはhttpリクエストを使ってテンプレートを表示するため、ポストインクルードを記述している元のファイルに変数化(SetTemplateまたはSetRendered)の記述があっても、GET_TemplateまたはGET_Renderedを使用したとき、何も表示されません。表示するには、ポストインクルード先のファイル内にも再度、変数化(SetTemplateまたはSetRendered)の記述が必要になります。

例)ポストインクルードを記述している元のファイル:

<!--#include file="/include/template.html" --><!-- 変数(SetTemplate、SteRendered)が記述されているファイル -->

<!-- ポストインクルードで、include/main/entryList.html を呼び出し -->
<!-- BEGIN_MODULE Entry_Field id="fied_eid" -->
  <form action="" method="post" class="js-post_include-ready">
    <input type="hidden" value="{vars}" name="vars">
    <input type="hidden" value="vars" name="field[]">
    <input type="hidden" name="tpl" value="include/main/entryList.html">
    <input type="submit" name="ACMS_POST_2GET" style="display:none;">
   </form>
<!-- END_MODULE Entry_Field -->

例)ポストインクルード先のファイル(include/main/entryList.html):

<!--#include file="/include/template.html" --><!-- ← 再度記述する必要がある -->

<!-- GET_Template id="entryList" -->

読み込みが必要なCSSファイル

a-blog cmsでは、各種モジュールを組み合わせることで更新できるページのテンプレートファイルを作成しますが、このテンプレートファイルの作成時に読み込みが必要なCSSファイル「normalize.css」「acms-admin.css(Ver.2.5以前ではacms.css)」があります。

表示用テンプレートファイルに読み込みが必要なCSSファイル


a-blog cmsのテンプレートは、制作者が自由に作成できますが、エントリーの登録をはじめとした基本機能の表示について記述しているCSSファイルは読み込みが必要となります。
テンプレートファイルには、各種要素の表示を再定義した「normalize.css」と、グリッドレイアウトやボタン、フォームなどの装飾を記述した「acms-admin.css」の2ファイルを読み込むようにしてください。
これらのファイルを読み込まない場合には、編集画面やレイアウト機能のデフォルトのテンプレートで正しい表示ができなくなるため、必ず読み込むように記述してください。


例:テーマ「site2015」での読み込みの記述( /themes/site2015/include/head/link.html )

<link href="/css/normalize.css" rel="stylesheet">
<link href="/css/acms-admin.min.css" rel="stylesheet">

例としているsite2015においても自作のテーマでも同様ですが、使用しているテーマファイル内に読み込み対象のファイルが無い場合には /themes/system/ 内のファイルが使用されるため、上記の記述があれば使用テーマ内にファイルを置く必要はありません。

内容の上書きをする場合

normalize.css および acms.css は /themes/system/css/ に格納されています。これらのファイルを直接変更してしまうと、a-blog cmsのアップデート時にも変更が必要になってしまいます。内容の変更をする場合には、ファイルの上書きではなく、別途使用するテーマフォルダ内に上書き用のCSSファイルを作成して、normalize.cssおよびacms-admin.cssの後に読み込むようにしてください。

Webサイト表示側のテンプレートにも使う場合(acms.css)※Ver.2.5以降

Ver.2.5以降では、acms.css を、管理画面のスタイルを使用できるCSSフレームワークとして配布しています。Webサイト表示側のテンプレートで使いたい場合にご利用ください。acms.cssではacms-admin.cssとは違い、管理画面で使用されている特殊なスタイルが省いていたり、表示側テンプレートでよく使用するスタイルを用意しています。

acms-admin.css同様、/themes/system/css/ に格納されているため、CMSのアップデートとともにバージョンアップしてしまう可能性があります。ご利用になるときはご利用中のテーマの中にコピーして使用してください。

最小限の装飾を行う場合(acms-lite.css)

基本的には前述のとおり、a-blog cms独自の表示のために normalize.css と acms.css を読み込む必要がありますが、中でも最小限の装飾(ユニット、グリッド、ボタン、フォーム、 ラベル、トピックパス、ページャー、ツールチップ、Webフォント)のみを記述したものとして acms-lite.css というファイルを /themes/system/css/ に格納しています。acms.css の代わりに読み込むことで、a-blog cmsの機能に影響しない最小限の装飾ができます。

Ver.2.5より、機能増加により編集画面で使うスタイルが増えたため、acms-lite.cssは廃止しました。

圧縮済みのファイル

/themes/system/css/ に格納しているacms-admin.css、acms.css、acms-lite.css(Ver.2.5より廃止になりました)は、それぞれ圧縮済みのファイルを同じ場所に格納しています。運用方法に合わせてご利用ください。

acms.css での装飾内容


管理ページ>コンフィグ

管理ページ>コンフィグ

acms.css での装飾内容は、スタイルガイドとして確認できます。
スタイルガイドはa-blog cms リファレンスページ内のスタイルガイドか、a-blog cms 管理ページ内のコンフィグからご確認ください。


読み込みが必要なJavascriptファイル

スニペット

通常以下の2行のコードを読み込む事により、a-blog cmsでJavaScriptが動作するようになります。

<script src="%{JS_LIB_JQUERY_DIR}jquery-2.1.1min.js" charset="UTF-8"></script><!-- BEGIN_MODULE Js -->
<script src="/acms.js{arguments}" charset="UTF-8" id="acms-js"></script><!-- END_MODULE Js -->

a-blog cms の表示、動作に関するファイル「acms.js」

a-blog cmsでは、ページの表示に関する様々な機能を記述したJavascriptファイル「acms.js」があります。a-blog cms のテンプレートファイルでは、このacms.js を読みこむ必要があります。

※Ver.2.5以降から「index.js」→「acms.js」にファイル名が変更になりました

acms.js 読み込みの記述

<!-- BEGIN_MODULE Js --><script src="/acms.js{arguments}" charset="UTF-8" id="acms-js"></script><!-- END_MODULE Js -->

index.js 読み込みの記述 ※Ver.2.5以前の記述です

<!-- BEGIN_MODULE Js --><script  src="/index.js{arguments}" charset="UTF-8" id="acms-js"></script><!-- END_MODULE Js -->

jQuery の読み込みについて

jQuery はa-blog cms に標準で組み込まれています。前述のacms.js (Ver.2.5以前ではindex.js)内で必要に応じて読み込みます。a-blog cmsが標準で使用しているバージョンが書いてあるのは、config.system.default.yamlです。

jquery_version: 1.11.1 # (2.1.1|2.0.3|1.11.1|1.10.1|1.9.1|1.8.3|1.7.2|1.6.4) 2.xはIE9〜

ただし、外部のjQueryのプラグインを使用する場合や、独自のJavaScriptファイルを読み込む場合は、以下のようにacms.jsの前にjQuery本体を読み込む必要があります。acms.jsの後でjQueryを読み込むと、jQueryがバッティングし正常に動作しないことがありますのでご注意ください。

<script src="%{JS_LIB_JQUERY_DIR}jquery-1.11.1.min.js" charset="UTF-8"></script>
<!-- BEGIN_MODULE Js --><script src="/acms.js{arguments}" charset="UTF-8" id="acms-js"></script><!-- END_MODULE Js -->

<script src="/js/site.js" charset="UTF-8"></script>
<script src="/js/main.js" charset="UTF-8"></script>

(非推奨) 以前のJavaScriptファイルの読み込みについて

Ver. 2.5.0 で javascriptの読み込みが非同期になったことにより、以下のようなJavaScriptファイルの読み込み方法がありました。しかし現状では、上記にあるように acms.jsの前にjQueryを読み込む方法を推奨しています。

<!-- BEGIN_MODULE Js --><script src="/acms.js{arguments}" charset="UTF-8" id="acms-js"></script><!-- END_MODULE Js -->
<script>
ACMS.Ready(function() {
  new ACMS.SyncLoader()
    .next('%{HTTP_THEMES_DIR}site2015/js/site.js')
    .next('%{HTTP_THEMES_DIR}site2015/js/main.js')
    .load();
});
</script>

組み込みJSについて

a-blog cmsには、標準でJavaScriptが組み込まれています(組み込みJSと呼んでいます) 組み込みJSでは自分でJavaScriptを書かなくてもいいようにすでに様々な便利な機能が用意されています。 ここでは、その組み込みJSの設定変更の方法について紹介します。各機能の詳細については下記のリファレンスを参照してください。
http://developer.a-blogcms.jp/reference/latest/builtinjs/index.html

各種ライブラリの使用と設定について

各種機能には、ライブラリを使用しているものが多数あります。基本的な設定は/js/config.js に記載しています。 CKEditorなどライブラリによっては、それぞれのconfigファイルがあるものもあります。 設定を変更する場合は、config.jsの内容を変更する必要がありますが、直接/js/config.jsファイルを変更するのではなく、/themes/お使いのテーマ/js/xxxx.js を作成し、必要な値を上書きするようにします。 直接config.jsを変更しないのは、CMSのバージョンアップ時に誤ってconfig.jsを上書きするリスクを回避するためです。

テンプレートごとに組み込みJSの設定を変更する

またconfig.jsで値を上書きしなくても、別のscriptファイルやHTMLファイルで設定を変更することができます。 Ver. 2.5.0以上のバージョンを使用されている方はacms.jsが非同期的にJavaScriptを読み込み実行しますのでconfig.jsが読み込まれたことを保証するACMS.Ready(function(){});の中に設定項目を記述するようにしてください。

ACMS.Ready(function() {
    //例)検索キーワードのハイライトを適用するセレクタ要素を追加する場合
    ACMS.Config.searchKeywordHighlightMark  = '.entryTitle, .search .summary, .selectKeyword';
    //例)絵文字の設定を配列で複数設定する場合
    ACMS.Config.emoArray    = [
    {
        'mark'      : 'textarea.js-emoditorEmoji',
        'toolbar'   : [['Emoji']],
        'config'    : {
            enterMode       : 1,
            language        : 'ja'
        }
    },
    {
        'mark'      : 'textarea.js-emoditorColor',
        'toolbar'   : [['TextColor','BGColor']],
        'config'    : {
             enterMode       : 1,
             language        : 'ja'
        }
    }
    ];
});

テンプレートの探し方

テーマをカスタマイズしているとテンプレートファイルはどうしても多くなってきます。そんな大量のテンプレートの中から、目的のテンプレートを探すのは時間がかかります。また自分以外が作ったテーマを触る場合もテンプレートを探すのに一苦労します。

そこで、ここでは目的のテンプレートを早く見つける方法を紹介していきます。

下準備

管理ページ > コンフィグ > 出力設定の HTMLコメントの削除 のチェックがついていたら外します。


出力設定管理画面

出力設定管理画面


config.server.phpDEBUG_MODE を "1" に設定。

サイトが公開中の場合は、DEBUG_MODEをOFFにする事はオススメできないので、以下のように特定IPアドレスからのアクセスのみDEBUG_MODEをOFFにする事もできます。

if ( $_SERVER['REMOTE_ADDR'] === 'xxx.xxx.xxx.xxx' ) {
  define('DEBUG_MODE', 1);
} else {
  define('DEBUG_MODE', 0);
}

テンプレート確認

ログインをして、テンプレートを確認したいページに移動します。ログインをしている状態だと以下のように、現在表示中のテンプレートと表示され、どのテンプレートが使用されているかわかります。


管理ボックス

管理ボックス


ただし、このテンプレートに目的の修正箇所があればいいのですが、インクルードされたテンプレートがほとんどだと思います。そこで次は修正箇所周辺のソースを確認します。確認すると以下のようにインクルードされている箇所がHTMLコメントで表示されるようになります。


インクルードファイルのソース周辺

インクルードファイルのソース周辺


インクルードファイルのパスがHTMLコメントでわかるようになりました。これで目的のテンプレートをすぐに探すことが出来るようになりました。


同一テンプレートでのコンテンツの出し分け方法

トップページと一覧や詳細ページとで表示する内容を変えたい場合、テンプレートの設定で指定するテンプレートファイルを個別に設定する方法が一般的ですが、ちょっとした表示の違いで個別にテンプレートを用意するのは、テンプレートの修正が発生した際にメンテナンス性が下がります。そこでタッチモジュールやIFブロック、インクルードを使うことで同一のテンプレート内に表示の出し分けを行うことができます。

タッチモジュールの場合

<!-- BEGIN_MODULE Touch_Top -->トップページに表示<!-- END_MODULE Touch_Top -->
<!-- BEGIN_MODULE Touch_Index -->一覧ページに表示<!-- END_MODULE Touch_Index -->
<!-- BEGIN_MODULE Touch_Entry -->詳細ページに表示<!-- END_MODULE Touch_Entry -->

IFブロックの場合

<!-- BEGIN_IF [%{VIEW}/eq/top] -->トップページに表示
<!-- ELSE_IF [%{VIEW}/eq/index] -->一覧ページに表示
<!-- ELSE_IF [%{VIEW}/eq/entry] -->詳細ページに表示<!-- END_IF -->

テンプレートではIFブロックよりもモジュールの方が先に解決されます。このため、トップページはエントリーサマリー、詳細ページはエントリー本文などのモジュールの出し分けをIFブロックで行うと、モジュールの解決後にIFブロックで表示結果を消すことになり無駄な処理が動いてしまいます。モジュールの出し分けは、タッチモジュールやグローバル変数を使ったインクルードで行ってください。

インクルードの場合

top_parts.html・index_parts.html・entry_parts.html などのインクルードファイルを用意しておき、グローバル変数 %{VIEW} を使ってインクルード文を記述します。

<!--#include file="/include/%{VIEW}_parts.html" -->