/js/config.jsの以下の箇所に設定内容が記載されています。

//--------------
// post include
postIncludeOnsubmitMark     : '.js-post_include',
postIncludeOnreadyMark      : '.js-post_include-ready',
postIncludeOnBottomMark     : '.js-post_include-bottom',
postIncludeOnIntervalMark   : '.js-post_include-interval',
postIncludeMethod           : 'replace', // ( 'swap' | 'replace' )
postIncludeEffect           : 'slide', // ( 'slide' | 'fade' | '' )
postIncludeEffectSpeed      : 'slow', // ( 'slow' | 'fast' )
postIncludeOffset           : 60,
postIncludeReadyDelay       : 0,
postIncludeIntervalTime     : 20000,
postIncludeArray  : [{
//  'mark'       : '.js-post_include-original',
//  'type'       : 'submit',
//  'method'     : 'swap',
//  'effect'     : 'slide',
//  'effectSpeed': 'slow'
}],

Ver. 2.8.0よりpostIncludeEvalValueMarkの設定ではキャッシュさせないポストインクルードが動作しなくなりました。詳しい実装方法については「post includeの結果をキャッシュさせない方法」の代替案をご覧ください。（2020年11月19日）

Ver. 2.11.25よりデフォルトの設定だと tplコンテキストが無効になりました。ポストインクルードを利用する際には ポストインクルードの準備 をご覧ください。（2021年6月16日）

<!-- BEGIN_MODULE Entry_List -->
<ul><!-- BEGIN entry:loop -->
<li><a href="{url}">{title}</a></li><!-- END entry:loop -->
</ul>
<!-- END_MODULE Entry_List -->

<!-- BEGIN_MODULE Entry_List id="searchResultSample" -->
<ul><!-- BEGIN entry:loop -->
<li><a href="{url}">{title}</a></li><!-- END entry:loop -->
</ul>
<!-- END_MODULE Entry_List -->

<form action="" method="post">
  <input type="text" name="keyword" value="" size="15" />
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" value="検索" />
</form>

target属性がない場合は、form自体が検索結果表示に置き換わります。

<form action="" method="post" class="js-post_include" target="#jsChangeContents">
  <input type="text" name="keyword" value="" size="15" />
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" value="検索" />
</form>

<form action="" method="post" class="js-post_include" target="#jsChangeContents">
  <input type="text" name="keyword" value="" size="15" />
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="hidden" name="tpl" value="include/searchResultSample.html" />
  <input type="submit" name="ACMS_POST_2GET" value="検索" />
</form>

<div id="jsChangeContents">
<p>この部分が置き換わります。</p>
</div>

<form action="" method="post" class="js-post_include" target="#jsChangeContents">
  <input type="text" name="keyword" value="" size="15" />
  <input type="hidden" name="tpl" value="include/searchResultSample.html" />
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" value="検索" />
</form>
<div id="jsChangeContents">
  <p>この部分が置き換わります。</p>
</div>

<!-- BEGIN_MODULE Entry_List -->
<ul><!-- BEGIN entry:loop -->
<li><a href="{url}">{title}</a></li><!-- END entry:loop -->
</ul>
<!-- END_MODULE Entry_List -->

<!-- BEGIN_MODULE Entry_List id="searchResultSample" -->
<ul><!-- BEGIN entry:loop -->
<li><a href="{url}">{title}</a></li><!-- END entry:loop -->
</ul>
<!-- END_MODULE Entry_List -->

<form action="" method="post">
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

<form action="" method="post" class="js-post_include-ready">
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

<form action="" method="post" class="js-post_include-ready">
  <input type="hidden" name="tpl" value="include/searchResultSample.html" />
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

<form action="" method="post" class="js-post_include-ready">
  <input type="hidden" name="keyword" value="サマリー" size="15" />
  <input type="hidden" name="tpl" value="include/searchResultSample.html" />
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

ポストインクルードを使うことで、検索結果など別コンテンツをページを移動することなく引っ張ってくることができます。技術的にはAjaxを使って実現しています。

このポストインクルードはJavaScriptで動いているため、端末の位置情報を取得して、ポストインクルード先に位置情報を渡すことができます。そうすることで、現在位置から近い店舗を表示するなどといった、ユーザーに優しい機能を作ることができます。（Ver. 2.7.0 以上）

注意点

最近のブラウザは https（SSL/TLS対応）でないと、位置情報を取得できない事が多くなっています。この機能を使用する場合は、httpsの環境をご用意ください。

また、最初にアクセスするときにブラウザが、位置情報を取得してもいいか、許可を求めてきます。ここでユーザーが許可を行わないと、位置情報の取得はできません。

実装方法

ポストインクルードの formのデータ属性に 「data-geo="true"」 を追加する事で、自動的に組み込みJSが自動で位置情報を取得してポストインクルードしてくれます。

位置情報の指定のされ方

formのデータ属性に 「data-geo="true"」 を追加する事で、位置情報を付加して指定されたテンプレートにアクセスするのですが、以下のようにクエリストリングとして付加されます。

?lat=xxxxxx&lng=xxxxxx

位置情報のグローバル変数

a-blog cms では、クエリストリングを自動的にグローバル変数化しますので、ポストインクルード先で、 %{lat}, %{lng} などとすることにより、位置情報が取得できます。

サンプル

以下、緯度・経度を表示するサンプルになります。

ポストインクルード

<h2>位置情報</h2>
<form action="" method="post" class="js-post_include" data-geo="true">
  <input type="hidden" name="bid" value="%{BID}">
  <input type="hidden" name="tpl" value="/include/geo.html">
  <input type="submit" name="ACMS_POST_2GET" value="緯度・経度を取得">
</form>

読み込みテンプレート

<ul>
	<li>緯度: %{lat}</li>
	<li>経度: %{lng}</li>
</ul>

動作サンプル（緯度・経度を表示）

Entry_GeoListとの組み合わせ

Entry_GeoListモジュールは、エントリーに位置情報を付加して、ある場所（エントリーや個別指定）から近い順番でエントリーを表示できるモジュールです。このEntry_GeoListと位置情報付きのポストインクルードを使うことで、現在位置から近いエントリーを引っ張ってくる事ができるようになります。

実装方法

Entry_GeoListモジュールIDを作成し、設定の基準点を「URLコンテキストを参照」から「URLクエリストリングを参照（?lat=xxx&lng=xxx）」に変更してください。これでモジュールは、エントリー基準ではなくURLの情報から基準点をとってくるようになります。

そして、Entry_GeoListモジュールが書かれたテンプレートを、位置情報付きのポストインクルードで読み込めば、現在位置から近い順で表示する事ができるようになります。

ポストインクルードを使うことにより、現在表示しているURLとは関係ない情報を好きに引っ張ってくることができます。 モジュールIDを使えば、同じようにURLと関係ない情報を出力することはできるのですが、エントリーの情報を使って、引っ張ってくる値が変わる場合はどは、ポストインクルードが便利です。

例: エントリー詳細ページで、そのエントリーのカスタムフィールドの値を元に、関連する記事一覧を引っ張ってくるなど。

実装方法

POST_2GETモジュールを使用します。POST_2GETモジュールは、POSTデータにa-blog cmsの様々なパラメータを渡して送信すると、そのパラメータを元にURLを組み立て、好きなページを表示できるようになります。（ポストインクルードを使わない場合は、組み立てられたページに移動します）

例: カテゴリーの情報で絞り込み、include/category.html テンプレートを使って表示しています。

<form action="" method="post" class="js-post_include-ready">
  <input type="hidden" name="bid" value="%{BID}" />
  <input type="hidden" name="cid" value="%{CID}" />
  <input type="hidden" name="tpl" value="include/category.html" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

様々なパラメーター

<!-- ID を指定 IDに沿ったURLが生成されます。 -->
<input type="hidden" name="bid" value="1"> <!-- ブログIDを指定 -->
<input type="hidden" name="aid" value="1"> <!-- エイリアスIDを指定 -->
<input type="hidden" name="uid" value="1"> <!-- ユーザーIDを指定 -->
<input type="hidden" name="cid" value="1"> <!-- カテゴリーIDを指定 -->
<input type="hidden" name="eid" value="1"> <!-- エントリーIDを指定 -->
<input type="hidden" name="cmid" value="1"> <!-- コメントIDを指定 -->

<!-- キーワードを指定 -->
<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-desc">
<!-- ファイル名 ( 昇順 ) -->
<input type="hidden" name="order" value="code-asc">
<!-- ファイル名 ( 降順 ) -->
<input type="hidden" name="order" value="code-desc">
<!-- ID ( 昇順 ) -->
<input type="hidden" name="order" value="id-asc">
<!-- ID ( 降順 ) -->
<input type="hidden" name="order" value="id-desc">
<!-- 表示順 ( 昇順 ) -->
<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">
<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">

このようなパラメータを使うことにより好きなページの情報を取得することができるようになります。 実装に困った時は、一度ポストインクルードで出来ないか検討してみてください。

通常は続きを読むのリンク部分をクリックすると1つの記事が表示されるようになりますが、Entry_Continue というモジュールとポストインクルード機能を組み合わせることで、ページの遷移無しに続き部分を読み込んでくる事ができるようになります。

続きを読む部分を表示するテンプレートを準備します。

<!-- BEGIN_MODULE Entry_Continue -->

<!-- BEGIN unit:veil -->
@include("/include/unit.html")
<hr class="clearHidden" />
<!-- END unit:veil -->
				
<!-- END_MODULE Entry_Continue -->

そして、一覧のテンプレートファイルにある continueLink 部分を探してみて下さい。

<!-- BEGIN continueLink:veil -->
<p class="continueLink clear"><a href="{continueUrl}">「{continueName}」の続きを読む</a></p>
<!-- END continueLink:veil -->

の部分を、以下のように修正します。

<!-- BEGIN continueLink:veil -->
<form action="{continueUrl}" method="post" class="js-post_include">
<input type="hidden" name="tpl" value="include/entry/continue.html" />
<input type="submit" name="ACMS_POST_2GET" value=" {continueName}の続きを読む " />
</form>
<!-- END continueLink:veil -->

以上のカスタマイズで「xxxの続きを読む」ボタンを押すと、ページ遷移なしで記事の続きが表示されるようにすることができます。

ポストインクルードでは通常「ACMS_POST_2GET」モジュールを利用します。

<form action="" method="post" class="js-post_include-ready">
  <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="include/search.html" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

ACMS_POST_2GETモジュールは、POSTする情報（ブログ情報、エントリ情報、テンプレート、キーワードなど）から、URLに変換してリダイレクトします。ポストインクルードではこのリダイレクトされたURLのHTMLを取得して表示します。

POST_2GET_Ajax

Ver. 3.1.17 から新しいモジュール「ACMS_POST_2GET_Ajax」が利用できるようになりました。

ACMS_POST_2GETモジュールとの違い

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

以下のポストインクルードを例に実際に取得するHTMLのURLの違いを見てみます。ここで「%{CID}」は「news」カテゴリーを指定しているものとします。

<form action="" method="post" class="js-post_include-ready">
  <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" />
  <input type="submit" name="ACMS_POST_2GET" />
</form>

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

「ACMS_POST_2GET_Ajax」であれば、必ずURLに「tplコンテキスト」が入るので、1つのテンプレートで済みます。

Ver. 3.1.17 以降のバージョンの場合、ポストインクルードで指定するモジュールは「ACMS_POST_2GET_Ajax」をご利用ください。

Ver. 2.11.25 以降のバージョンでデフォルトで tplコンテキストの設定が無効になるような設定になりました。

ポストインクルードで引っ張ってくるテンプレートは、基本テンプレートを指定してインクルードするので、上記の制限によりうまくインクルードされない可能性があります。 CMSのバージョンによって対応が変わりますので、以下ご確認ください。

Ver. 3.1.16 以下 & Ver. 2.11.25 以上の場合

例えば以下のようなTPL指定をするとURLは「https://example.com/xxxx.html/tpl/include/thumbnail.html」になり、URLでtpl指定をしてしまうことになります。

<input type="hidden" name="eid" value="%{EID}" />
<input type="hidden" name="tpl" value="include/thumbnail.html" />

このままでは制限をうけて正常にインクルードできないので、以下の方法により回避します。

private/cofig.system.yaml にある forbid_tpl_url_context を off に設定します。

forbid_tpl_url_context: off

private/cofig.system.yaml にある allow_tpl_path にポストインクルードで利用するファイルを指定します。複数ある場合にはカンマで区切って設定します。

allow_tpl_path: [inlcude/search.html, hoge/custom.html]

Ver. 3.1.17 以上の場合

Ver. 3.1.17で、特に意識・設定することなく、ポストインクルードを利用できるように改善されました。

改善内容

private/config.system.yaml の「ajax_security_level」の設定に応じて、ポストインクルード（Ajax）のアクセスを認証することにより、直接のGETリクエストと、ポストインクルード（Ajax）でのリクエストを区別することが出来るようになり、tpl指定の制限をしたまま、ポストインクルード（Ajax）のリクエストは許可するということが出来るようになりました。

ajax_security_level: 2 # ajaxリクエストのセキュリティレベルを設定します。（0: チェックなし 1: RefererとHttpヘッダーを確認 2: CSRFトークン確認）

Ajaxセキュリティレベル

レベル0

ajax_security_level: 0

レベル0は、特になにも認証をしないので、基本的には設定しないでください。

レベル1

ajax_security_level: 1

レベル1は、RefererとHttpヘッダーを確認して、Ajaxリクエストであることを確認します。ポストインクルードを利用すれば自動でHTTPヘッダーは付与されるので、特に意識する必要はありません。

もしポストインクルードではなく独自のAjaxリクエストで、HTMLを取得する場合は以下HTTPヘッダーを付与ください。

Referer: https://example.com/xxxxx/xxxx.html
X-Requested-With: XMLHttpRequest

レベル2

ajax_security_level: 2

レベル2は、レベル１のチェックに加え、CSRFトークンを使った認証を行います。ポストインクルードを利用すれば自動でHTTPヘッダーにCSRFトークンが付与されるので、特に意識する必要はありません。

もしポストインクルードではなく独自のAjaxリクエストで、HTMLを取得する場合は以下HTTPヘッダーを付与ください。

Referer: https://example.com/xxxxx/xxxx.html
X-Requested-With: XMLHttpRequest
X-Csrf-Token: xxxxxxxxxxxxxxxxxxx

X-Csrf-Token に設定する値は、テンプレートに「check-csrf-token」文字列を追加することにより、CMSで追加できます。例えばクラス名で指定するなどです。

<div class="check-csrf-token">
...
</div>

CSRFトークンは、metaタグに生成されています。JavaScriptなどでこの値を取得してご利用ください。

<meta name="csrf-token" content="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">

const csrfToken = document.querySelector('meta[name="csrf-token"]').content