👷

【a-blog cms】developテーマ：jQueryなしで組み込みJSを利用する方法と注意点

2023/02/16に公開

JavaScript

a-blog cms

tech

a-blog cmsには、「組み込みJS」と呼ばれるJSライブラリが用意されています。
このライブラリは、Webサイトによく実装される機能が多く盛り込まれています。

公式リファレンス：https://developer.a-blogcms.jp/document/reference/builtinjs/

しかし、便利な反面、制作するサイトによっては不要な機能が多いこと、またファイルサイズが大きいことも事実です。

そこで今回は、developテーマにあらかじめ用意されている記述をつかって、ほしい機能だけ、しかもjQueryなしで利用する方法をご紹介します。

組み込みJSの読み込み部分を確認

developテーマでは、<head>内でこのようにJSが読み込まれています。

include/head/js.html

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

Touch_SessionWithContributionを利用し、「ログイン中かつユーザー権限が投稿者以上」の場合のみ、組み込みJS（acms.js）・jQueryを読み込む記述になっています。

この記述になっている理由として、以下の2つが挙げられます。

エントリー編集などの管理アクションにおいて、組み込みJS（jQueryに依存）が必須である
→ 管理アクションができるのは投稿者以上の権限のみ
これら2つはファイルサイズが大きく、読み込むとパフォーマンスに影響する

つまり、サイト閲覧時のパフォーマンスを向上することを目的とした記述です。

では、組み込みJSに用意されている機能を使いたいときにはどうしたらよいのでしょうか？
Touch_SessionWithContributionを外して2つのファイルを常に読み込む状態にしてもよいのですが、なるべくパフォーマンスへの影響を小さくしたいものです。

この問題を解決するために、developテーマでは、組み込みJSのうち必要な機能だけを読み込んで使えるようになっています。

必要な機能のみ読み込む方法

developテーマでは、組み込みJSのうち使用頻度の高いものがそれぞれモジュール化されています。
この中から必要なものを、メインのJSファイルにimportすることで利用できます。

src/js/index.js

import {
  validator,
  linkMatchLocation,
  externalLinks,
  scrollTo,
  alertUnload,
  smartPhoto,
  lazyLoad,
  inView,
  modalVideo,
  scrollHint,
  googleMap,
  openStreetMap,
  datePicker,
  postInclude,
  pdfPreview,
  focusedImage,
} from './lib/build-in'; // ToDo: いらないものはコメントアウト

// ~~~~~~ 中略 ~~~~~~

/**
 * BuildInJs
 * ToDo: 使わない組み込みJSはコメントアウト
 */
if (window.ACMS === undefined) {
  window.dispatch = (context) => {
    validator(context);
    linkMatchLocation(context);
    externalLinks(context);
    scrollTo(context);
    alertUnload(context);
    smartPhoto(context);
    lazyLoad(context);
    inView(context);
    modalVideo(context);
    scrollHint(context);
    googleMap(context);
    openStreetMap(context);
    datePicker(context);
    postInclude(context);
    pdfPreview(context);
    focusedImage(context);
  };
  window.dispatch(document);
}

モジュール化して提供されている機能は、基本的には jQuery に依存していません。
追加で jQuery を読み込む必要がないため、ファイルサイズを抑えることができます。

初期状態ではすべての組み込みJSが読み込まれる記述になっているので、不要なものはコメントアウトすると外すことができます。
外す際は、import部分と有効化部分の2箇所でコメントアウトすることをお忘れなく！

import {
  // validator, ← ①import部分

if (window.ACMS === undefined) {
  window.dispatch = (context) => {
    // validator(context); ← ②有効化部分

注意点

モジュール化されて格段に利用しやすくなった組み込みJSですが、利用方法や環境によってはいくつか注意点があります。

組み込みJSの設定を編集する場合

組み込みJSの設定は、専用のイベントハンドラ（ACMS.xxx()）を利用することで編集できます。

しかし、パッケージやモジュールの形では提供されていないため、ACMSをimportして使うことはできません。
このままイベントハンドラを利用すると、ESLint のエラーによりコンパイルができなくなってしまいます。

エラー：'ACMS'が未定義

ERROR in 
/path-to-file/themes/develop/src/js/index.js
  97:3  error  'ACMS' is not defined  no-undef
  98:5  error  'ACMS' is not defined  no-undef

✖ 2 problems (2 errors, 0 warnings)

解決方法

ESLintの設定を編集し、ACMSをグローバル変数として定義しましょう。
.eslintrc を開き、globalsに項目を追加するだけでかんたんに設定可能です。

.eslintrc

{
// ~~~~~~ 中略 ~~~~~~
  "globals": {
    "document": true,
    "window": true,
    "event": true,
    "$": true,
    "jQuery": true,  // ← 末尾にカンマを追加
    "ACMS": true  // 追加
  },

バリデーターを利用する場合（v3.0.20 以前）

a-blog cms v3.0.20 以前の場合、組み込みJSのバリデーション（validator）を利用する際に jQuery を読み込む必要があります。
これは、バリデーションの判定処理（src/js/lib/buildIn/validator-operator.js内）の一部が jQuery に依存しているためです。

解決方法

npm installの際に jQuery のパッケージがインストールされるので、JSファイル内でimportするだけで利用可能です。
メインのJSファイルもしくは validator-operator.js に jQuery をimportしましょう。

import $ from 'jquery';

まとめ

組み込みJSはモジュール化されているため、必要なものだけ選んで使うことができる。
組み込みJSの設定を編集して使う際は、ESLint の設定を確認！
モジュール化された組み込みJSの利用には jQuery 不要
※バリデーター使用時はCMSのバージョンに注意

組み込みJSは全ての機能を使う必要はなく、必要な機能だけを読み込むことでより便利に使うことができます。
今回紹介した方法がよりパフォーマンスのよいサイトを構築する手助けになれば幸いです。

組み込みJSの読み込み部分を確認

必要な機能のみ読み込む方法

注意点

組み込みJSの設定を編集する場合

解決方法

バリデーターを利用する場合（v3.0.20 以前）

解決方法

まとめ

Discussion