ドキュメントdocument

モジュール

モジュールの基本

モジュールとは?

a-blog cms では、ブラウザ上から更新できる部分には、モジュールと呼ばれるパーツが表示用テンプレートのHTMLファイルに貼り付けられています。
a-blog cmsでは多くのモジュールがありますが、このモジュールがa-blog cmsに登録した様々なデータを表示することでサイトを構成するパーツとなっています。
どのようなモジュールがあるのかを知る事が、a-blog cms のカスタマイズの上達の近道です。同梱テーマのsite2015のトップページでは、以下のようなモジュールが使われています。理解を深めるためには、テンプレートファイルでどのように記述されているか確認してみてください。


siteテーマにどんなモジュールが使われているか


モジュールは大きく分けると、テンプレートを組み立てるためのGETモジュール、サーバーにデータを送信するためのPOSTモジュールがあります。
GETモジュールには、ビルトインモジュール・フィールドモジュール・タッチモジュールの3種類のモジュールがあります。
POSTモジュールにはPOST_2GETモジュール・ダウンロードモジュールという2種類のモジュールがあります。
それぞれの用途については後述します。

モジュールはテンプレートにいくつでも貼り付けできます。ですが、たくさんのモジュールが動作すると、それだけ実行する時間がかかることも覚えておいてください。例えば0.1秒で動くモジュールが100個テンプレートに貼ってあると、ページの表示には10秒かかる事になります。モジュールの貼り過ぎには注意しましょう。
なお、a-blog cmsでは、標準搭載のキャッシュ機能で最初の表示に10秒かかるページも、2回目以降はキャッシュ機能により瞬時に表示できますので、ご安心ください。


ビルトインモジュール

基本的にモジュールと言えば、このビルトインモジュールの事になります。多くはエントリー系の情報を表示させるモジュールで、カテゴリー、ナビゲーション、バナー、トピックパス等、サイト制作にはいろいろなビルトインモジュールを利用することになります。

<!-- 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 -->

<!-- BEGIN_MODULE モジュール名 --> から <!-- END_MODULE モジュール名 --> を1つのモジュールとして動作します。モジュールの中にモジュールを書く事もでき、モジュールの実行順としては、内側のモジュールが実行され、その後に外側のモジュールが動作するようになっています。

各種ビルトインモジュールの機能や変数表・スニペットについてはリファレンス内のビルトインモジュールのページをご覧ください。


フィールドモジュール

登録したカスタムフィールドのデータを表示させるためのモジュールです。
カスタムフィールドは、基本的に対応するカスタムフィールドのモジュール内に記述する必要があります。

<!-- BEGIN_MODULE Category_Field -->
	<!-- BEGIN headimage:veil -->
		<img src="{headimage@path}" width="" height="" />
	<!-- END headimage:veil -->
<!-- END_MODULE Category_Field -->

例外として、ビルトインモジュール内で利用ができるカスタムフィールドもあります。

各種フィールドモジュールの機能や変数表・スニペットについてはリファレンス内のフィールドモジュールのページをご覧ください。


タッチモジュール

様々な条件で表示をコントロールしたい

タッチモジュールは、様々な条件によって動作(表示)するモジュールで、ページ(テンプレート)がその条件にあてはまる時だけ表示されます。
以下の例では、Touch_Login というモジュールを使うことで、ログインしている状態の場合のみユーザー名を表示します。ログインしていない状態では何も表示されません。

<!-- BEGIN_MODULE Touch_Login -->
    <!-- BEGIN_MODULE Admin_ActionMenu -->
    <p>ユーザー名:{name}</p>
    <!-- END_MODULE Admin_ActionMenu -->
<!-- END_MODULE Touch_Login -->

表示ページによって「トップページ」「一覧ページ」の場合や、ユーザーの権限によって「管理者」「編集者」「投稿者」で別の内容を表示したりという使い方が考えられます。

タッチモジュールは大きく3つに分けられ、条件に合致する場合に動作するタッチモジュール、条件に合致しない場合に動作するNot系タッチモジュール、Facebookページに関連して動作するFacebook系タッチモジュールがあります。
各タッチモジュールの役割を越える複雑な条件はIFブロックを使うことで実現できます。

各種タッチモジュールの機能や変数表・スニペットについてはリファレンス内のタッチモジュールのページをご覧ください。


POST_2GET

パラメータを指定してリダイレクト

パラメータをPOSTで送信する事により、パラメーターに沿ったURLを組み立ててリダイレクトする事ができます。

以下の例では、bid=1(news)cid=3(economy)を指定して http://sample.com/news/economy/ にリダイレクトします。

<!-- ボタンを押すと /news/economy/ にリダイレクトされる -->
<form action="" method="post">
  <input type="hidden" name="bid" value="1">
  <input type="hidden" name="cid" value="3">
  <input type="submit" name="ACMS_POST_2GET" value="経済ニュースに移動">
</form>

パラメータをhiddenで指定して、submitのname属性ACMS_POST_2GET を指定する事により動くようになります。パラメータには acmsパス が利用できます。

POST_2GETの例
<!-- ID を指定 IDに沿ったURLが生成されます。 -->
<input type="hidden" name="bid" value="1">
<input type="hidden" name="aid" value="1">
<input type="hidden" name="uid" value="1">
<input type="hidden" name="cid" value="1">
<input type="hidden" name="eid" value="1">
<input type="hidden" name="cmid" value="1">
<input type="hidden" name="tdid" value="1">

<!-- キーワードを指定 -->
<input type="text" name="keyword" value="%{KEYWORD}">

<!-- タグを指定 -->
<input type="hidden" name="tag" value="aaa">

<!-- フィールドを指定 -->
<input type="hidden" name="hoge" value="aaa">
<input type="hidden" name="field[]" value="hoge">

<!-- 表示順を指定 -->
<input type="hidden" name="order" value="datetime-asc"> <!-- 日時 ( 昇順 ) -->
<input type="hidden" name="order" value="datetime-asc"> <!-- 日時 ( 降順 ) -->
<input type="hidden" name="order" value="code-asc"> <!-- ファイル名 ( 昇順 ) -->
<input type="hidden" name="order" value="code-asc"> <!-- ファイル名 ( 降順 ) -->
<input type="hidden" name="order" value="id-asc"> <!-- ID ( 昇順 ) -->
<input type="hidden" name="order" value="id-asc"> <!-- ID ( 降順 ) -->
<input type="hidden" name="order" value="sort-asc"> <!-- 表示順 ( 昇順 ) -->
<input type="hidden" name="order" value="sort-asc"> <!-- 表示順 ( 降順 ) -->
<input type="hidden" name="order" value="field-asc"> <!-- フィールド ( 昇順 ) -->
<input type="hidden" name="order" value="field-asc"> <!-- フィールド ( 降順 ) -->
<input type="hidden" name="order" value="intfield-asc"> <!-- 数値フィールド ( 昇順 )	 -->
<input type="hidden" name="order" value="intfield-asc"> <!-- 数値フィールド ( 降順 ) -->
<input type="hidden" name="order" value="random"> <!-- ランダム -->

<!-- テンプレートを指定 -->
<input type="hidden" name="tpl" value="/include/sample.html">

<!-- ページを指定 -->
<input type="hidden" name="page" value="3">

<!-- 表示数を指定 -->
<input type="hidden" name="limit" value="50">

<!-- 期間を指定 -->
<input type="hidden" name="start" value="2014-01-01">
<input type="hidden" name="span" value="span">
<input type="hidden" name="end" value="2015-12-31">

<!-- 日付を指定 -->
<input type="hidden" name="date" value="2015-12">

<!-- クエリストリングを指定 ?key1=aaa&key2=bbb-->
<input type="hidden" name="key1" value="aaa">
<input type="hidden" name="key2" value="bbb">
<input type="hidden" name="query[]" value="key1">
<input type="hidden" name="query[]" value="key2">

フィールドの指定にはもっと細かい指定ができますので、カスタムフィールドの検索 を参考ください。


ダウンロードモジュール

ダウンロードモジュールとは、任意のファイルをダウンロードできるようにするモジュールです。a-blog cmsのデータベースに格納されているデータを取り出して任意の形式のファイルに出力し、そのファイルをダウンロードできるようにします。

出力するファイルは、CSVやXML形式など任意の形式で作成でき、モジュールやグローバル変数などを記述してカスタマイズが可能です。

このダウンロードモジュールはv1.3.1より利用できます。

任意の形式のファイルをダウンロードできるようにする

1. ダウンロードするファイルのテンプレートを用意する

ダウンロードさせたいファイルのテンプレートを作成します。CSVやXMLなど任意のテキスト形式のテンプレートファイルを作成できます。テンプレートですので、モジュールやグローバル変数を記述できます。

例として以下のようなCSVファイルを作成するとします。これは、ユーザープロフィールモジュールを使用して、ユーザーの情報の一覧をCSV形式のファイルに出力する場合の例です。

<!-- BEGIN_MODULE User_Profile --><!-- BEGIN user:loop -->"{name}[escquot]","{mail}[escquot]"<!-- END user:loop --><!-- END_MODULE User_Profile -->

CSV形式では、ダブルクォーテーションで囲まれた中にダブルクォーテーションが含まれている時のために、ダブルクォーテーションをエスケープする校正オプション[escquot]を指定しています。(CSVの仕様につきましては、他のWebサイトを参照してください。)

上記のソースを記述したら、ファイル名を「user.csv」として保存します。ここでは例として「csv」というディレクトリを作成し、/csv/user.csv とします。

2. ダウンロードするボタンを作成する

次に、ファイルをダウンロードするためのフォームボタンを作成します。テンプレートの任意の場所にフォームボタンを設置できます。手順1で作成したCSVファイルをダウンロードする場合は、以下のようなソースを記述します。

<form action="ユーザーリスト.csv" method="post">
    <input type="hidden" name="bid" value="%{BID}" />
    <input type="hidden" name="tpl" value="csv/user.csv" />
    <input type="hidden" name="charset" value="Shift_JIS" />
    <input type="submit" name="ACMS_POST_Download" value="CSVをダウンロード" />
</form>
1行目(必須):<form action="ダウンロードするファイル名" method="post">

フォームボタンを押してダウンロードするファイルのファイル名を、拡張子含めて記述します。

2行目(必須):<input type="hidden" name="bid" value="%{BID}" />

出力するデータ内容のブログを指定します。

3行目(必須):<input type="hidden" name="tpl" value="テンプレートファイル名" />

ダウンロードするファイル名を、拡張子含めて記述します。

4行目:<input type="hidden" name="charset" value="文字コード名" />

ダウンロードするファイルの文字コードを指定します。ダウンロードするファイルが生成される時に、この部分で指定した文字コードに変換されてファイルが生成されます。文字コードを指定しない場合は、ダウンロードするファイルのテンプレートで出力された文字コードとなります。

5行目(必須):<input type="submit" name="ACMS_POST_Download" value="ボタンのラベル" />

ファイルをダウンロードするボタンです。ACMS_POST_Downloadというモジュールを動作させてダウンロードする記述です。

これで、ボタンを押すとaction属性で指定したファイル名のファイルがダウンロードされるようになります。

ユーザーの情報など個人情報に関わるものや機密性のあるデータを取り扱う場合には、管理ページに記述したり、Touch_SessionWithAdministrationモジュールを使用するなどして、管理者のみがダウンロードできるような配慮も可能です。


変数表とスニペット

モジュールの記述のための情報

モジュールには出力する内容によって様々なものがあるため、全く何もない状態からテンプレート上に正確に記述していくのは大変です。そこで、a-blog cmsではこの制作者向け情報サイトや、a-blog cmsの管理ページ内にも該当モジュール内で使用できる変数表、基本的な記述方法となるスニペットを用意しています。


カスタマイズ管理>コンフィグ

カスタマイズ管理>コンフィグ

a-blog cmsの管理ページで左側メニュー内、カスタマイズ管理>コンフィグへ進むと、各モジュールの設定への一覧がありますが、各モジュールの右側に変数表とスニペットへのリンクがあります。
この各リンクから、それぞれ変数表、スニペットが別ウィンドウで開きます。


変数表


Entry_Bodyモジュールの変数表

Entry_Bodyモジュールの変数表

各モジュールの変数表では、どのブロック内にどのような変数を表示させることができるかをまとめています。
いずれも白背景の二重線で囲まれた部分が変数名となっており、モジュール内の各ブロックで使えることを表しています。変数の具体的な内容は表中に日本語で補足しています。


スニペット


Entry_Bodyモジュールのスニペット

Entry_Bodyモジュールのスニペット

スニペットとは、よく使用するコードをまとめたデータです。各モジュールの出力に必要なコードがスニペットとして用意してありますので、必要に応じてコピー&ペーストや独自に変更を加えてお使いください。

独自のテンプレートを作成する場合には、元になるHTMLファイルにこれら各モジュールのスニペットを貼り付けて、必要な形に整形していくという流れを取るとスムーズに制作できるでしょう。


Dreamweaverにスニペットを追加する


a-blog cmsのパッケージには「omake」フォルダ内にDreamweaverで使用する拡張機能ファイルをご用意しています。Dreamweaverのスニペットパネルにa-blog cmsで使用する各モジュールのスニペットを追加するファイルとなります。この拡張機能を使うことで、Dreamweaver上で1クリック(ドラッグ&ドロップ)でスニペットを追加できるようになります。管理ページ内のデータと合わせて是非ご利用ください。「omake」フォルダの内容、使用方法につきましては、a-blog cmsに同梱されている新規インストールマニュアル内の「omakeフォルダについて」をご覧ください。


各種モジュールの設定

ブログ単位でモジュールの表示を制御する

a-blog cmsでは、様々な情報を表示するのに適した各モジュールがありますが、さらにその表示を制御するために各モジュールのコンフィグ(=設定)があります。管理ページ内の左側メニューのカスタマイズ管理 > コンフィグ から各モジュールを含めた設定への一覧があります。各モジュール名から設定画面へリンクしています。



ブログ内で共通した設定を行うには


各モジュールの管理画面では、表示順や件数など、モジュールごとに表示に関する設定ができるようになっています。各設定項目についての詳しい内容は、項目右にある[?]リンクをご確認ください。



同一モジュールで別の設定をしたい場合には


これらの設定は該当ブログ内で使用されるモジュール全てに適用されます。しかし、同じモジュールを使う場合でも、必ずしも同じ表示をしたいとは限りません。また、個別のカテゴリーだけ、といったように表示の設定ではなく条件の設定がしたい場合もあります。このような場合には、モジュールの設定とは別に固有のIDを付与したモジュールであるモジュールIDをご利用ください。モジュールIDについては、このドキュメント内のモジュールIDのページで解説しています。