モジュール

目次

モジュールの基本

モジュールとは?

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系タッチモジュールがあります。
各タッチモジュールの役割を越える複雑な条件はIFブロックを使うことで実現できます。

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

POST_2GET・POST_2GET_Ajax

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

パラメータを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_Ajax(Ver. 3.1.17以降)を指定する事により動くようになります。パラメータには 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="tag[]" value="bbb">

<!-- フィールドを指定 -->
<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-desc"> <!-- 日時 ( 降順 ) -->
<input type="hidden" name="order" value="code-asc"> <!-- ファイル名 ( 昇順 ) -->
<input type="hidden" name="order" value="code-desc"> <!-- ファイル名 ( 降順 ) -->
<input type="hidden" name="order" value="id-asc"> <!-- ID ( 昇順 ) -->
<input type="hidden" name="order" value="id-desc"> <!-- ID ( 降順 ) -->
<input type="hidden" name="order" value="sort-asc"> <!-- 表示順 ( 昇順 ) -->
<input type="hidden" name="order" value="sort-desc"> <!-- 表示順 ( 降順 ) -->
<input type="hidden" name="order" value="field-asc"> <!-- フィールド ( 昇順 ) -->
<input type="hidden" name="order" value="field-desc"> <!-- フィールド ( 降順 ) -->
<input type="hidden" name="order" value="intfield-asc"> <!-- 数値フィールド ( 昇順 )	 -->
<input type="hidden" name="order" value="intfield-desc"> <!-- 数値フィールド ( 降順 ) -->
<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 00:00:00">
<input type="hidden" name="span" value="span">
<input type="hidden" name="end" value="2015-12-31 23:59:59">

<!-- 日付を指定 -->
<input type="hidden" name="date" value="2015/12">
<input type="hidden" name="date[0]" value="2015"> <!-- 年を指定 -->
<input type="hidden" name="date[1]" value="12"> <!-- 月を指定 -->
<input type="hidden" name="date[2]" value="31"> <!-- 日を指定 -->


<!-- クエリストリングを指定 ?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">

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

キーワード検索(全文検索)について詳しく知りたい方はキーワード検索フォーム(全文検索フォーム)をご確認ください

POST_2GET と POST_2GET_Ajax モジュールとの違い

tpl指定した場合の挙動が異なります。「ACMS_POST_2GET」モジュールの場合、tpl指定されていても、URLにtplコンテキストが入らない場合があります。

以下の例でURLの違いを見てみます。ここで「%{CID}」は「news」カテゴリーを指定しているものとします。

<input type="text" name="keyword" value="" size="15" />
<input type="hidden" name="bid" value="%{BID}" />
<input type="hidden" name="cid" value="%{CID}" />
<input type="hidden" name="tpl" value="search.html" />

ACMS_POST_2GETの場合

https://example.com/news/search.html?keyword=xxxxxx

ACMS_POST_2GET_Ajaxの場合

https://example.com/news/tpl/search.html?keyword=xxxxxx

この場合「ACMS_POST_2GET」の場合は「themes/ご利用テーマ/news/search.html」テンプレートがないと404になりますが、「ACMS_POST_2GET_Ajax」の場合は、tpl指定されているので「themes/ご利用テーマ/search.html」があれば取得できることになります。

「ACMS_POST_2GET」の場合でも、テンプレートをカテゴリディレクトリに設置すれば解決しますが、多くのカテゴリがある場合は同じテンプレートをカテゴリー毎に設置しないといけなくなります。

ダウンロードモジュール

ダウンロードモジュールとは、任意のファイルをダウンロードできるようにするモジュールです。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ファイルにこれら各モジュールのスニペットを貼り付けて、必要な形に整形していくという流れを取るとスムーズに制作できるでしょう。

各種モジュールの設定

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

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



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


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



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


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

関連エントリー機能

任意の記事に関連した情報のエントリーを表示する機能として、登録されているタグの一致数に応じて関連記事を表示するタグリレーショナル(Entry_TagRelational)というモジュールがあります。
a-blog cms Ver.2.6.0からは(Admin_Entry_Autocomplete)モジュールが追加されています。エントリーの登録・編集時に、関連するエントリーを検索し、紐付け登録をします。より柔軟な関連記事登録が可能になります。



登録されたエントリーは下記のピンクの線で囲まれたハンドルを掴んでドラッグアンドドロップすることで表示順を変更することも可能です。また、右の確認ボタンを押すことで、実際にそのエントリーのページに移動して内容を確認することもできます。



紐づけられたエントリーはテンプレートをカスタマイズすることで下の図のように表示することが可能です



関連エントリー機能の有効化・設定

この機能を使用するためにはテンプレート側のカスタマイズおよび管理画面の設定が必要になってきます。

関連エントリー機能を有効にする

関連エントリー機能を使用可能にするために、 管理画面 > コンフィグ > 編集設定 より下の図のように 関連エントリー のチェックボックスにチェックを入れます。



関連記事グループの設定

「関連記事グループ」の機能では、関連エントリーをグルーピングすることが可能です。 この機能を使えば、1つの記事に対して複数の関連エントリーのグループを表示できます。 初期状態では、サイト全体から記事を選択することになり、1つの記事に対して1つのグループしか設定できません。



関連記事グループの設定項目

  • タイプ: グループを識別する値(英数字で入力)
  • ラベル: 編集画面でグループに表示される値
  • モジュールID: 関連記事選択UIでの選択肢を表示するためのモジュール「Admin_Entry_Autocomplete」のモジュールID名を指定します。
  • URLコンテキスト(ctx): ここで設定されたURLコンテキストで関連記事選択UIの選択肢を絞り込みます
  • 登録制限: ここで設定された数だけ関連記事を選定できます


タイプ グループを識別する値(英数字で入力)
ラベル  編集画面でグループに表示される値
モジュールID 関連記事選択UIでの選択肢を表示するためのモジュール「Admin_Entry_Autocomplete」のモジュールID名を指定します。
URLコンテキスト(ctx) 設定されたURLコンテキストで関連記事選択UIの選択肢を絞り込みます
登録制限 設定された数だけ関連記事を選定できます
上記の設定をした場合の編集画面例

設定された関連記事を表示する

エントリーに登録した関連記事を表示する方法を解説します。表示する方法は大きくわけて2つあります。

Entry_Body, Entry_Summaryの変数で出力する

1つ目の方法は、Entry_BodyやEntry_Summaryの entry:loop 内で、対応する関連記事を出力する方法です。一覧ページなどでエントリーに合わせて関連記事も表示する時に有効です。

変数の有効化

Entry_Bodyまたは、Entry_SummaryのモジュールIDの「表示設定」で「関連エントリーを表示する」にチェックをつけます。


変数表

Entry_Bodyまたは、Entry_Summaryの変数表を見ると、関連記事の出力変数がありますので、変数表をみてテンプレートに変数を記入します。

Entry_Bodyの変数表

https://developer.a-blogcms.jp/document/acms-code/vars/Entry_Body.html?cache=off

Entry_Summaryの変数表

https://developer.a-blogcms.jp/document/acms-code/vars/Entry_Summary.html


「default」タイプの関連記事の場合の例

<!-- BEGIN relatedEntry -->
  <!-- BEGIN relatedEntry.default -->
  <ul>
    <!-- BEGIN relatedEntry.default:loop -->
    <li><a href="{url}">{categoryName}: {title}</a></li>
    <!-- END relatedEntry.default:loop -->
  </ul>
  <!-- END relatedEntry.default -->
<!-- END relatedEntry -->

Entry_Summary 自体の出力内容を関連エントリーにする

2つめの方法は、Entry_Summaryモジュールの表示内容を、関連記事の内容にしてしまう方法です。詳細ページなどで、エントリーに付随する関連記事一覧を表示するのに便利です。

設定方法

まず、引数のエントリーIDにチェックをつけてEntry_SummaryのモジュールIDを作成します。


次に「表示設定」で、「関連エントリーのサマリーを表示する」にチェックをつけて、表示する関連記事グループを選択します。


モジュールIDを作成したら、Entry_Summaryのスニペットをテンプレートに記述し、作成したモジュールIDを適用します。そのエントリーで設定した関連記事を表示します。

位置情報を使って記事を絞り込むEntry_GeoList

この記事で紹介するのは、位置情報によるエントリーの絞り込み、並び替えをする機能です。この機能はVer.2.7.0より使用できます。

たとえば、記事に位置情報を付加して記事詳細ページに近くの記事を出すことや、ブラウザから位置情報(GPS)を取得して現在位置から近くの記事を表示することが可能です。

注意事項

最近のブラウザは、位置情報(Geolocation API)を利用するために、SSL/TLS(https://)が必須になってきています。

Entry_GeoListの使い方

まずは、エントリー詳細ページで近くの位置情報が設定されているエントリーを表示します。この実装は、たとえば物件詳細ページで近くの物件を表示するような場合に便利に使えます。

位置情報の設定を利用可能にする

エントリーに位置情報を登録するためには、各ブログの機能設定で位置情報の利用を有効にする必要があります。
管理ページ > コンフィグ > 機能設定のページの順に移動し、位置情報の利用を有効化します。



有効化すると、エントリーの編集画面で下の図のように「位置情報」を登録するためのセクションが出現します。


エントリー編集画面の日付の項目の後に「位置情報」の項目が追加されている様子

図のように位置情報の項目が追加されます


地図の入力インターフェースが表示されている図

「位置情報を追加」をクリックした様子


モジュールIDの設定

ここでは、Entry_GeoListを使って、「見ている記事に地理的に近い記事一覧を表示」する方法と「GPS情報をもとに現在地に近い記事一覧を表示」する方法をご紹介します。どちらもモジュールIDの作成が必要です。 管理ページ > モジュールID の モジュールID作成ボタン を押してモジュールIDを新規作成します。ここでは以下のようにモジュールでEntry_GeoListを設定にします。

見ている記事に地理的に近い記事一覧を表示

位置情報を登録したエントリーの一覧を表示します。ここでは見ている記事に地理的に近い順の記事一覧を表示します。 エントリーIDの引数にチェックを入れることで各詳細ページで、その記事の近くの位置に登録されているエントリーリストを表示できます。



モジュールIDの表示設定

位置オプションの設定にて 基準点 をURLコンテキストを参照に設定してください。 この基準点の設定は、現在のエントリーの位置情報をもとにするか、URLのクエリの値をもとにするか選択しています。今回は記事詳細ページに地理的に近い記事を探してくるので、「URLコンテキスト」を参照にしています。

テンプレートの設定

モジュールIDの準備ができたので、次はテンプレート側の設定です。 管理ページ > コンフィグ > エントリー位置リストのスニペット をコピーしてエントリー詳細ページのテンプレートを貼ります。モジュールIDの指定を忘れないようにしましょう。こちらが、エントリー位置リストのスニペットになります。

Entry_GeoListのスニペット

GPS情報をもとに現在地に近い記事一覧を表示

先ほど行ったカスタマイズでは、現在表示している記事をもとに近くの記事を引っ張ってきました。このカスタマイズを少し変更して、現在いる場所(GPS情報)からの近くの記事を引っ張ってくる事をしてみたいと思います。

ポストインクルードのテンプレート作成

次にポストインクルード用のformを作成してください。js-post_include-readyが設定されているform要素に対して、「data-geo="true"」 を追加すれば組み込みJSが自動で位置情報を取得して、ポストインクルードが動作します。 この際に、form内にある「name="tpl"」のinput要素には、先ほど作成したEntry_GeoListのスニペットが記述されたHTMLのテーマ内のパスを指定します。

<h2>位置情報</h2>
<form action="" method="post" class="js-post_include-ready" data-geo="true">
  <input type="hidden" name="bid" value="1">
  <input type="hidden" name="tpl" value="/include/geo.html">
  <input type="hidden" name="ACMS_POST_2GET" value="send">
</form>

モジュールIDの表示設定

先ほどのポストインクルードにより、URLのクエリストリングに、緯度経度の情報が入っていますので、モジュールIDの設定の基準点を「URLコンテキストを参照」から「URLクエリストリングを参照(?lat=xxx&lng=xxx)」に変更してください。これでモジュールは、エントリー基準ではなくURLの情報から基準点をとってくるようになります。



実際に確認してみてください。現在の位置をもとに近い順でエントリーを引張てきている事がわかると思います。 注意: 最近のブラウザはhttpsでないと位置情報を取得できなくなっています。

JSONを使って専用モジュールを作ってみよう

a-blog cms ではビルドインモジュール(Entry_BodyやCategory_List...)と呼ばれる最初から入っているモジュールを使って動的にコンテンツを出力していきます。一般的なサイトを作るうえでは、ビルドインモジュールがあればそこまで困らないのですが、a-blog cmsで管理していないデータを出力したり、特殊な絞り込みをしたい場合は、PHPを書いて専用モジュールを開発する必要がありました。

そこで、Ver. 2.7.0 から導入される新しいビルドインモジュール Json_2Tpl を使う事でJSONさえ用意できれば、PHPを1行も書かずに思い通りのモジュールを作る事ができるようになります。

また、JSONがインターフェイスとなるので外部サービスとの連携もしやすくなります。

基礎編

まずは、モジュールIDの作成を行います。 管理ページ > モジュールID の モジュールID作成ボタン を押してモジュールIDを新規作成します。ここでは以下のような設定にしましょう。

  • モジュール: Json_2Tpl
  • id: sampleJson2Tpl
  • 名前: Json_2Tplの練習

モジュールID作成画面

モジュールID作成画面


出力をしたいJSONファイルを用意します。自分でJSONファイルを書く、外部サービスのJSONファイルを読む混むなどをするのですが、まずは練習用に以下のJSONファイルを使います。

http://ablogcms.io/sample.json

商品の一覧を出力しているJSONファイルです。これをa-blog cmsのテンプレートで出力してみましょう。

{
    "items": [
        {
            "id": "001",
            "name": "商品A",
            "color": "red",
    "size": ["S", "M", "L"],
            "price": {
                "tax_included": 108,
                "without_tax": 100
            }
        },
       ...
}

練習用のJSONファイルを、先ほど作成したモジュールIDに設定してみましょう。先ほど作成したモジュールIDの設定画面に移動します。表示設定のタブに移動して JSONファイル の入力欄に http://ablogcms.io/sample.json を入力しましょう。

Json_2Tplのモジュール設定には以下のものがあります。

  • キャッシュタイム: JSONファイルをキャッシュする時間を設定します。
  • JSONファイル: データもとであるJSONファイルを指定します。URLもしくはパスで指定できます。(Ver.2.7.7よりグローバル変数もパスの指定に利用できるようになりました)

Json_2TplモジュールID設定画面

Json_2TplモジュールID設定画面


モジュールの準備ができたので、実際にテンプレートに出力をしてみましょう。まずはモジュールブロックを書きます。 idは先ほど作成したモジュールIDのものを指定ください。

<!-- BEGIN_MODULE Json_2Tpl id="sampleJson2Tpl" -->
<h2>商品</h2>

<!-- END_MODULE Json_2Tpl -->

JSON

次に実際にデータを表示していくのですが、その前にJSONファイルについてちょっと学んでおきましょう。

JSONは 名前/値のペア の集まりで構成されています。: の前にあるのが名前です。また、{ } で囲まれている部分をオブジェクトと呼びます。様々なデータを持っているセットと考えていただければ大丈夫です。次に [ ] で囲まれている部分が配列になります。データを複数持つことができます。これらは互いに入れ子にする事ができるようになっています。

ではサンプルのデータを見ながら、どのようなデータになっているか見てみましょう。

{
    "items": [
        {
            "id": "001",
            "name": "商品A",
            "color": "red",
    "size": ["S", "M", "L"],
            "price": {
                "tax_included": 108,
                "without_tax": 100
            }
        },
       ...
}

まず、 items ですが、: のあとは [ になっていますので、Itemsは配列とわかります。配列の中身ですが、{ } で囲まれているのでオブジェクトを複数持っている事がわかります。

オブジェクトの中身ですが、id, name, color は文字列の値になっていますが、 price{ } で囲まれているのでオブジェクトです。そのオブジェクトの中身は 数値の値になっています。

JSON -> a-blog cmsテンプレート

これを踏まえてa-blog cmsのテンプレートを作っていきます。以下のようなルールがあります。

ここでのサンプルのコードは一部分を表示しているだけになります。全体のコード(動作するコード)は下のほうにあります。

配列の場合は、ループブロックで表現されます。ループブロックとは <!-- BEGIN 名前:loop --> という形のブロックになります。

ループブロックの中では、 glueブロック <!-- 名前:glue --> も利用できるようになります。glueブロックは ループ回数 - 1回 出力されるブロックになります。カンマで区切りたい場合などに利用すると便利です。

特殊な変数として {名前.i} という変数も利用できます。これは現在の配列番号を出力できます。

また配列の中身が、値の場合は(ここでゆうsize)配列の名前(ラベル)がそのまま変数名としても使えます。

<!-- BEGIN items:loop -->
{items.i}
<!-- BEGIN items:glue -->, <!-- END items:glue -->
...
<!-- END items:loop -->

<!-- BEGIN size:loop -->
<!-- BEGIN size:glue -->, <!-- END size:loop -->
{size.i} : {size}
<!-- END size:loop -->

名前(ラベル)がついたオブジェクト(例: "price": { ... })の場合は、ブロックで表現できます。ブロックとは <!-- BEGIN 名前 --> の形のブロックです。

<!-- BEGIN price -->
...
<!-- END price -->

名前(ラベル)のあとが値の場合、変数として出力できます。変数は {名前} で表現されます。 もちろんこの変数には校正オプションも利用できます。

{id}
{name}
{color}
{tax_included}[number_format]
など
  • 配列 -> ループブロック(例 <!-- BEGIN items:loop -->)
  • 名前(ラベル)がついたオブジェクト -> ブロック(例: <!-- BEGIN price -->)
  • 名前(ラベル)のあとが配列でもオブジェクトでもない値 -> 変数(例: {color})

では以上のルールにしたがって練習用JSONのすべての値を出力してみましょう。以下のようなテンプレートになれば正解です。

<!-- BEGIN_MODULE Json_2Tpl id="sampleJson2Tpl" -->
<h2>商品</h2>
<ul>
    <!-- BEGIN items:loop -->
    <li>
        {items.i}: {id}: {name}<br>
        color: {color}<br>
        size: <!-- BEGIN size:loop --><!-- BEGIN size:glue -->, <!-- END size:glue -->{size}<!-- END size:loop --><br>
        <!-- BEGIN price -->
            税込: {tax_included}円
            税別: {without_tax}円
        <!-- END price -->
    </li>
    <!-- END items:loop -->
</ul>
<!-- END_MODULE Json_2Tpl -->

表示結果

表示結果

メディアに登録された画像を利用するメディアバナーモジュール

メディアバナーモジュールとは

Ver.2.10のメディア機能のアップデートに伴い、登録したメディアを有効活用できるように バナーモジュールの後継としてメディアバナーモジュールをあらたに追加しました。このモジュールを使うとメディアに登録した画像の中から画像を選択して、バナーモジュールのように利用することができます。 バナーモジュールよりも画像を登録する際の使い勝手が大きく向上しており、エントリー編集ページのようなユニット形式で画像を登録することができます。 モジュール側で利用できる変数はバナーモジュールと同じです。

バナーモジュールよりも優れている点

バナーモジュールでは同じ画像を別のバナーモジュールでも利用したい場合、そのモジュールのためにわざわざ画像をアップロードする必要がありました。メディアバナーモジュールではすでにアップロードされた画像をメディアから選択できるので、同じ画像をわざわざモジュールごとにアップロードする手間が省けます。 また複数の画像をドラッグ&ドロップで一度に登録することができます。

使い方

管理画面 > モジュールIDより、「モジュールIDを作成」ボタンをクリックします。新規モジュールID作成ボタンにてモジュールに「Media_Banner」を選択し、他の項目は任意に設定し作成します。


作成後は 表示設定に以下のようにバナーを登録するための項目が追加されています。


エントリー作成画面と非常に似たUIになっており、追加ボタンから「メディア」を追加し、項目を増やしていくことができます。 追加した項目同士はエントリーと同じでドラッグ&ドロップで順番を変えることができるようになっています。


ファイルのドラッグ&ドロップ

またファイルをドラッグ&ドロップして一度に複数枚アップロードすることも可能になっています。


アップロードしたファイルの編集

また、Media_Bannerモジュールはメディア機能をそのまま利用しているため、その場でアップロードしたメディアを編集できるのも特徴です。



メディア編集モーダルウィンドウを表示

Open Graph Protocol(OGP)モジュール

Open Graph Protocol(OGP)モジュールとは、meta要素やOGPの情報を表示する機能のことです。カスタムフィールドのSEO設定に登録された情報を表示します。

この機能は、管理画面>コンフィグ >OGPまたは管理画面>モジュールID のページで新規モジュールを作成することで利用できます。

タイトル設定

<title>要素やOGPのタイトル表示で使用されるタイトルに関する設定です。



項目 概要 初期値
優先順序 タイトルで使われるパーツの優先順序を設定します。
利用可能パーツ (entry, page, tag, keyword, date, admin, 404, category, blog, rootBlog) 
entry, page, tag, keyword, date, admin, 404, category, blog, rootBlog
パーツの区切り文字 タイトルの区切り文字を設定します。  | 
エントリーのカスタムフィールド名 タイトルで使われるカスタムフィールド名を設定します。このフィールドがない場合は、エントリーのタイトルが使われます。 entry_meta_title
カテゴリーのカスタムフィールド名 タイトルで使われるカスタムフィールド名を設定します。このフィールドがない場合は、カテゴリー名が使われます。 category_meta_title
ブログのカスタムフィールド名 タイトルで使われるカスタムフィールド名を設定します。このフィールドがない場合は、ブログ名が使われます。 blog_meta_title
階層表示 ブログとカテゴリーの階層構造をタイトルに含めるか指定します。
空のエントリーコード 空のエントリーコードの場合はそのタイトルを含めないようにします。
ページのフォーマット ページ番号を出力するテキストのフォーマットを設定します。ページ番号は{page}で表示されます。 {page}ページ目
タグの区切り文字 タグの区切り文字を設定します。
日付の書式 日付の書式を設定します。PHPのdateに準拠しています。 Y/m/d
管理ページのタイトル 管理ページのタイトルを設定します。 管理ページ
404のタイトル 404エラー時のタイトルを設定します。 お探しのページは見つかりませんでした

画像設定

OGPのサムネイル画像に関する設定です。

表示する優先度は下記になります。

  1. エントリーのカスタムフィールド画像
  2. エントリーのユニット画像(「ユニットのメイン画像は含めない」項目でオフを選択した場合)
  3. カテゴリーのカスタムフィールド画像
  4. ブログのカスタムフィールド画像
  5. ルートブログのカスタムフィールド画像


項目 概要 初期値
ユニットのメイン画像は含めない(Ver.2.11から利用可能) チェックをすると、ユニットのメイン画像はOGP画像に含まれなくなります。 オフ
エントリーのカスタムフィールド名 エントリーのカスタムフィールド名を設定します。 ogp_image
カテゴリーのカスタムフィールド名 カテゴリーのカスタムフィールド名を設定します。 ogp_image
ブログのカスタムフィールド名 ブログのカスタムフィールド名を設定します。 ogp_image

ディスクリプション設定

OGPのディスクリプションに関する設定です。

ディスクリプションを表示する優先度は下記になります。

  1. エントリーのカスタムフィールド
  2. エントリーのサマリー(フルテキスト)
  3. カテゴリーのカスタムフィールド
  4. ブログのカスタムフィールド
  5. ルートブログのカスタムフィールド


項目 概要 初期値
エントリーのディスクリプションの表示設定 チェックすると、エントリーのカスタムフィールドに値が設定されていない場合はエントリーのディスクリプションを表示しません。 オフ
エントリーのカスタムフィールド名 エントリーのカスタムフィールド名を設定します。 entry_meta_description
カテゴリーのカスタムフィールド名 カテゴリーのカスタムフィールド名を設定します。 category_meta_description
ブログのカスタムフィールド名 ブログのカスタムフィールド名を設定します。 blog_meta_description

キーワード設定

meta要素で指定できるkeywordに関する設定です。

キーワードを表示する優先度は下記になります。

  1. エントリーのカスタムフィールド
  2. カテゴリーのカスタムフィールド
  3. ブログのカスタムフィールド
  4. ルートブログのカスタムフィールド


項目 概要 初期値
エントリーのカスタムフィールド名 エントリーのカスタムフィールド名を設定します。 entry_meta_keywords
カテゴリーのカスタムフィールド名 カテゴリーのカスタムフィールド名を設定します。 category_meta_keywords
ブログのカスタムフィールド名 ブログのカスタムフィールド名を設定します。 blog_meta_keywords