2021年12月01日（水）

基本的な a-blog cms の組み込みJS の使い方をおさらいする

今回は、a-blog cms に用意されている組み込みJSについて基本的な使い方についておさらいしたいと思います。

組み込みJS とは

組み込みJSは、a-blog cmsに同梱されているJavaScriptライブラリのことです。a-blog cms ではよくWebサイト制作で使いそうなJavaScriptライブラリを組み込みJSとして同梱しています。なので、JavaScriptのライブラリやjQueryプラグインなどをよく使う方は、そういったライブラリがデフォルトで入っているという認識でOKです。

組み込みJSの中には一般的にJavaScriptライブラリとして公開されているものを組み込みJSとして同梱していたりもしますが、中にはa-blog cms 独自の仕様に沿って提供している独自のものもあります。

一般的にJavaScriptライブラリとして公開されているもの	日付選択のUI（FlatpickrやjQuery UI）やイメージビューアー（prettyPhoto）など
a-blog cms 独自の仕様に沿って提供しているもの	ポストインクルードや、現在位置に装飾をつけるlink_match_location、検索結果のキーワードをハイライトする機能など

JavaScriptライブラリを使うのが苦手な方だったり、ちょっとした装飾を実装するのに便利に使えます。

組み込みJSを読み込む

組み込みJSを使うためには、まずは組み込みJSを使用したいサイトに下記のように記述し、acms.jsを読み込みます。
公式テーマではSite2020、Beginner2020、Bootstrap2020、Blog2020テーマであればデフォルトですでに読み込まれています。

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

このacms.jsは、ドキュメントで公開されている組み込みJSだけではなく、管理画面で使用しているJavaScriptを有効にするファイルになります。管理画面では必ず読み込む必要があります。

基本的な書き方

a-blog cms の各組み込みJSのドキュメントを参考に、デフォルト設定のままで良ければHTMLを修正すれば基本的な動作が実行されるようになっています。

例えば、クリックしたらコンテンツが開閉するフェーダーも以下のようにHTMLを記述するだけで実装できます。

<p><a href="#fadeSample" class="js-fader">クリックする</a></p>
<p id="fadeSample">クリックしたら表示されるコンテンツです</p>

ただ、お仕事をしているとデフォルトの設定のままではなく、カスタマイズしたいケースが出てきます。その場合は、/js/config.jsに書いてある値を、別のJSファイルを用意して上書きしていきます。

組み込みJSをカスタマイズする際には別途JavaScriptファイルを使用中のテーマ内に作成する必要があります。作成したJavaScriptファイルは、acms.jsより後に実行してください。
下記のソースコードでは2行目に当たります。

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

config.js とは

組み込みJSの各種設定が記述されているファイルです。場所は、/js/config.jsにあります。このファイルは基本的に直接編集することはありません。

config.jsを直接編集きしてはいけない理由

特別な理由がない限り、基本的には config.js は直接編集してはいけないとされています。なぜかというと、config.jsが設置されている場所がルートディレクトリのjsフォルダなので、アップデート時に上書きされてしまうからです。

直接config.jsを上書きするのではなく、使用中のテーマ内に別途JSファイルを作成して、config.jsの内容を上書きするようにしましょう。

config.js の記述の例

config.jsには以下のような記述で、各種組み込みJSのオプションが設定されています。

ACMS.Config({
  ... （省略） ...
  searchKeywordHighlightMark: '.entry, .entryColumn, .entryTitle', // セレクタ要素内に検索ワードが含まれる時、該当箇所がハイライトされます。
  ... （省略） ...
});

私が初心者の時に config.js を少し厄介に感じた点になるのですが、テーマ内に用意したJSファイルにこのソースコードをそのままコピペして記述してもJavaScriptが動きません。/js/config.jsの設定を参考にしつつ、少し書き変えてあげる必要があります。

config.jsを上書きする書き方

config.jsの値を上書きしたい場合は、テーマ内に用意したJSファイルに下記のように記述します。

ACMS.Ready(function() {
    ACMS.Config.searchKeywordHighlightMark  = '.entry-title, .search .summary, .select-keyword';
});

1行目と3行目には、ACMS.Readyという関数の記述になります。ACMS.Readyで囲んでおくと、ブラウザがconfig.jsを読み込んでから、ACMS.Readyの中身を実行します。

2行目で、searchKeywordHighlightMarkの値を上書きしています。
記述方法の変更点としては、以下の3つです。

config.jsに記載されていたsearchKeywordHighlightMarkの頭にACMS.Config.を付け足す
:を=にする
,を;にする

書き換える際にはよくチェックしてください（私もうっかりしてよく間違えています）。

このようにテーマ内のJSファイルに記述することによって、config.jsを上書きしなくても利用しているテーマのJSファイルからconfig.jsの内容を上書きすることができます。

配列の書き方

組み込みJSには、複数設定を追加できるものがあります。オプション名は大体Arrayと入っているものが「配列」と呼ばれるものになります。[]で囲まれているものですね。

先ほどと少し記述が異なるのでこちらも少し書き換えてあげる必要があります。

/js/config.jsでは、高さを揃えるjs-autoheight-rはデフォルトでは下記のように記述されています。

ACMS.Config({
  // ... （省略） ...
  autoHeightRMark : '.js-autoheight-r',
  autoHeightRConf : {
    style   : 'min-height',
    element : '',
    offset  : 0,
    parent  : 'parent',
    list    : ''
  },
  autoHeightRArray: [ // ここの記述が配列です
      //    {
      //        'mark'    : '',
      //        'config'  : {}
      //    }
  ],
 //  ... （省略） ...
});

以下はjs-autoheight-rをテーマ内で使用しているJSファイルから配列を上書きして、使用できるようにした記述の例です。

ACMS.Ready(function() {
  ACMS.Config.autoHeightRArray = [
  {
      mark: '.js-autoheight-r',
      config: {
        style: 'height',
        element: '',
        offset: 0,
        parent: '',
        list: ''
      }
    },
    {
      mark: '.js-autoheight-r2',
      config: {
        style: 'height',
        element: '',
        offset: 0,
        parent: '.js-autoheight-r2-parent',
        list: '.js-autoheight-r2-item'
      }
    }
  ];
});

記述方法の変更点としては、以下の3つです。

ACMS.Config.autoHeightRArrayのすぐ後の:を=に変更する（2行目）
config:{ ... } の中身をautoHeightRConfの中身を参考に記述する（6行目〜10行目）
1つ目のオブジェクト（{}）と2つ目のオブジェクトの繋ぎに,を追加する（12行目）

配列はpushするとちょっと便利なときがある

上記のコードは/js/config.jsの値を上書きする書き方をしていますが、pushして値を渡してあげると既存の設定に新しく設定を追加することができます。

使用する組み込みJSによってはその度に設定をリセットした方がいいケースもあるかもしれませんが、 push して値を追加すると既存の設定が上書きされません。既存の設定を削除しなくてもいい場合や保持したい場合は、より便利に使えるケースがあります。

例えば、以下のように記述します。

ACMS.Ready(function(){
  ACMS.Config.autoHeightRArray.push({
      mark: '.js-autoheight-r3',
      config: {
        style: 'height',
        element: '',
        offset: 0,
        parent: '.js-autoheight-r3-parent',
        list: '.js-autoheight-r3-item'
      }
    });
});

ACMS.Config.autoHeightRArray = [{ ... }];としていたところを、ACMS.Config.autoHeightRArray.push({...});に書き換えています。

`push`を使わずにjs-autoheight-r3を記述する	js-autoheight-r3しか使えなくなってしまう
`push`を使って記述する	例えば1つ前のソースコード例を同時に読み込んだ場合はjs-autoheight-r、js-autoheight-r2、さらにjs-autoheight-r3が使えるようになる

以上の項目を知っておけば、基本的な組み込みJSの設定はカスタマイズは可能だと思います。
いろいろ設定を変更して試してみていただけたらと思います。

まとめ

作成したJavaScriptファイルは、acms.jsより後に実行する
使用中のテーマ内に別途JavaScriptファイルを作成して、config.jsの内容を上書きする
配列を使用するとは上書きしてもいいけど、既存の設定を引き継ぐならpushも便利

今回、私が a-blog cms を使い始めてよく理解できなかった組み込みJSを改めて解説したいと思って記事を書きました。
組み込みJSをカスタマイズすることに苦手意識を感じている方の役に立てるとうれしいです！
この記事に続いて書こうとしていた中級編になりそうな組み込みJSのことについては、少し記事の対象が変わりそうだったのでまた7日目に書きたいと思います。

明日のa-blog cms Advent Calendar 2021 - Adventar 2日目は株式会社データファーム　勝又孝幸さんです！楽しみにしています！

月	火	水	木	金	土	日
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30

基本的な a-blog cms の組み込みJS の使い方をおさらいする

組み込みJS とは

組み込みJSを読み込む

基本的な書き方

config.js とは

config.jsを直接編集きしてはいけない理由

config.js の記述の例

config.jsを上書きする書き方

配列の書き方

配列はpushするとちょっと便利なときがある

まとめ

おすすめ記事

a-blog cms で行う3つテンプレートの条件分岐

テンプレートの継承機能を使ってアップデートに考慮した管理画面にしよう

a-blog cms の自動返信メールでFromに日本語名とメールアドレスを設定する方法

ユニットの管理UIのちょっとしたカイゼン

WCAN 2018 Winterで登壇しました

a-blog cms のカスタムフィールドグループでフェーダーを実装する

他の方法で記事を探す

2024年4月

カテゴリーリスト

タグ一覧