【EC-CUBE 4】JavaScriptの簡単設定と反映方法

この記事では、EC-CUBEで『JavaScriptをカスタマイズする3つの方法』と『JavaScriptが反映されないトラブル対処法』を、実例を交えつつ解説しています。
CSSのカスタマイズについては こちらの記事 にまとめています。

【動作環境】
EC CUBEのバージョン：4.2.1
サーバー：Xserver

JavaScriptをカスタマイズする3つの方法

JavaScriptのカスタマイズは、主に冒頭で述べた3つの方法があります。

1. 管理画面の「JavaScript管理」から、カスタマイズ用JavaScript（customize.js）にコードを書く。
2. JavaScriptをカスタマイズしたいページ（Twigテンプレート）にコードを書く。
3. オリジナルのJavaScriptファイルを作成し、反映させたいページ（Twigテンプレート）にそれを読み込ませる。

デフォルトで用意されているJavaScriptファイル（html/template/default/assets/js下にある）を修正する方法もあります。
が、後で元に戻せなくなったり意図しないエラーが出たりすることもあるので、基本的にオススメできません。

基本的なカスタマイズ方法は、CSSと同じですね。

今回は管理画面から作成した以下のページを用意して、JavaScriptのカスタマイズを実践していきます。
CSSカスタマイズの記事で作成したページの一部を引き続き使います。

【Javascriptカスタマイズ前に用意したページはこちら】

URL

(ドメイン名)/user_data/test

Twig

app/template/user_data/test.twig

{% extends 'default_frame.twig' %}

{% block stylesheet %}
<style>
    #greeting,
    #custom-btn {
        font-size: 20px;
        color: red;
        font-weight: bold;
    }
    
    #custom-btn {
        margin: 30px 0;
        background-color: black;
        color: white;
        font-size: 20px;
        border-radius: 4px;
    }
</style>
{% endblock %}

{% block main %}
<h1>カスタムCSSとJavascriptのテストページです</h1>
<p id="greeting">こんにちは！</p>
<button id="custom-btn">テキストを変える</button>

{% endblock %}

Twigテンプレート内にCSSを書き込んで、デザインをカスタマイズしています。
また、テキストとボタンにはそれぞれ「id」を付与しています。

この時点では、以下のようなページが表示されるはずです。

本記事では、「テキストを変える」ボタンをクリックすることで実際にテキストを変えてみます。

JavaScript管理からカスタマイズ用JavaScriptファイルにコードを書く

1つ目は、『EC-CUBE管理画面 ＞ コンテンツ管理 ＞ JavaScript管理』で表示されるコード画面に記載する方法です。

通常のJavaScript同様にコードを記述することで、書かれたJavaScriptの内容がすべてのページに反映されます。
特別な操作は必要なく、CSS同様にもっとも簡単な方法かと思います。

【カスタマイズ用Javascriptファイルを用いたカスタマイズ例はこちら】

/* カスタマイズ用Javascript */
const greeting = document.getElementById('greeting');
const customBtn = document.getElementById('custom-btn');

// customBtn要素に'click'イベントリスナー（クリックすると、greeting要素のテキストを'HELLO！！！'に変更）を追加
customBtn.addEventListener('click', () => {
    greeting.textContent = 'HELLO！！！';
});

JavaScript変更前と変更後のページを比較してみると、ちゃんとJavaScriptが適用されました。

この方法の欠点もCSS同様、カスタマイズのファイル（costomize.js）がデフォルトでは一つしかないため、カスタマイズを進めれば進めるほどコードが長くなっていき、見通しが悪くなります。（どのJavaScriptがどのページに反映されているかわかりづらい。）

また、このファイルは基本的に全てのページで読み込まれるため、意図しないページでJavaScriptが反映されてしまったり、無駄なコードを読み込んでページの読み込み速度が落ちてしまったりなど、不具合の原因にもなり得ます。

そこで、次にページごとにJavaScriptを反映させる方法を紹介します。

ちなみに、ここで記述したファイルは「html/user_data/assets/js」下に保存されています。

JavaScriptを反映させたいページに書く

2つ目は、JavaScriptを反映させたいページ（Twigテンプレート）に記述する方法です。
この方法の良いところは以下の2つ。

• 反映させたいページのみに反映させられる
• 1つ目の方法よりJavaScriptの内容が確認しやすく、修正も簡単

やり方は、JavaScriptを反映させたいページ（Twigテンプレート）に以下コードを記述するだけです。

{% block javascript %}
<script>
  /* ここにJavaScriptコードを書く */
</script>
{% endblock %}

直接Twigテンプレートに記述するので、あとで確認や修正が簡単ですね。
コード量が少ないときはこの方法がオススメです。

【TwigファイルにJavaScriptコードを記述するカスタマイズ例はこちら】

{% extends 'default_frame.twig' %}

{% block stylesheet %}
<style>
    #greeting,
    #custom-btn {
        font-size: 20px;
        color: red;
        font-weight: bold;
    }
    
    #custom-btn {
        margin: 30px 0;
        background-color: black;
        color: white;
        font-size: 20px;
        border-radius: 4px;
    }
</style>
{% endblock %}

{% block main %}
<h1>カスタムCSSとJavascriptのテストページです</h1>
<p id="greeting">こんにちは！</p>
<button id="custom-btn">テキストを変える</button>

{% endblock %}

{% block javascript %}
<script>
    const greeting = document.getElementById('greeting');
    const customBtn = document.getElementById('custom-btn');
    
    customBtn.addEventListener('click', () => {
        greeting.textContent = 'HELLO！！！';
        greeting.style.color = 'blue';
    });
</script>
{% endblock %}

• コードの前半にCSSを記述して、デザインをカスタマイズしています。
• コードの後半にJavaScriptを記述しています。
  ボタンをクリックすると、「こんにちは！」のテキストを「HELLO!!!」に変え、さらにテキストの色を「赤」→「青」に変えられます。

「テキストを変える」ボタンを押すとテキストが変わり、JavaScriptが適用されていることを確認できました！

なお、{% block 名前 %} 〜 {% endblock %} というTwig特有の記法については以下記事にて。

あわせて読みたい

【EC-CUBE 4】Twig まとめ(1)　～継承やブロックについて～ {% extends ‘default_frame.twig’ %} {% block main %}{% endblock %} Twigテンプレート特有の、これらの記法ってどういう意味？ 本記事では、EC-CUBE（Symfony）で用い…

TwigテンプレートにJavaScriptを直接書くことのデメリット

再利用性の低下

JavaScriptをテンプレートに直接書くと、その機能はそのテンプレートに固定されます。
従って、他のテンプレートで再利用することが難しくなります。

可読性の低下

HTMLとJavaScriptが混在するため、コードの可読性が下がり、メンテナンスとデバッグが難しくなります。

このように、後々のメンテナンスなどを考慮すると、あまり望ましくないカスタマイズ方法とも言えます。
そこで最後に紹介するのは、JavaScriptを複数のファイルに分けて保存し、Twigテンプレートから特定のJavaScriptファイルを読み込んで適用させる方法です。

ファイル管理にオリジナルのJavaScriptファイルを作成し、それを読み込ませる

3つ目は、JavaScriptファイルを複数用意しておいて、JavaScriptを追加したいページ（Twigテンプレート）から適用したいJavaScriptファイルを読み込む方法です。

この方法を使うことでTwigテンプレートとJavaScriptを分けることができ、よりコードの可読性が上がります。
また、別のページでも同じJavaScriptを反映させたい場合、同じJavaScriptファイルを読み込ませるだけで済むのも利点ですね。

{% block javascript %}
    <script src="{{ asset('assets/js/test.js', 'user_data') }}"></script>
{% endblock %}

JavaScriptファイルを事前に用意する必要があるので少し煩雑に感じるかもしれません。
が、これで通常1個しかないJavaScriptファイルを複数用意することができます。

機能がまとめられてメンテナンスしやすくなり、がっつりカスタマイズする場合はこの方法が一番オススメです。

【JavaScriptファイルを複数に分けてTwigテンプレートから読み込ませるカスタマイズ例はこちら】

以下のJavaScriptファイル（test.js）を作成し、『EC-CUBE管理画面 ＞ コンテンツ管理 ＞ ファイル管理 ＞ assets ＞ js』下にアップ。

続いてTwigテンプレートを以下のように修正。

const greeting = document.getElementById('greeting');
const customBtn = document.getElementById('custom-btn');

customBtn.addEventListener('click', () => {
    greeting.textContent = 'HELLO！！！';
    greeting.style.color = 'blue';
    alert('テキストが変更されました');
});

ボタンをクリックすることでテキストの内容と色を変更し、さらに「テキストが変更されました」というアラートを表示させるJavaScriptです。

{% extends 'default_frame.twig' %}

{% block stylesheet %}
    <link rel="stylesheet" href="/html/user_data/assets/css/test.css">
{% endblock %}

{% block main %}
<h1>カスタムCSSとJavascriptのテストページです</h1>
<p id="greeting">こんにちは！</p>
<button id="custom-btn">テキストを変える</button>

{% endblock %}

{% block javascript %}
    <script src="{{ asset('assets/js/test.js', 'user_data') }}"></script>
{% endblock %}

ついでにCSSも別ファイルに移し、コードをスッキリさせました。
（CSSファイルの移し方はこちら）

適用前後のページを比較してみると、ちゃんとJavaScriptが適用されてアラームが表示されました。

JavaScriptが反映されないときの対処法

コードを記載したのに、なぜかJavaScriptが適用されない！？

JavaScriptやCSSなどのカスタマイズが反映されない主要因は、「キャッシュ」が残っていることによるものです。
キャッシュが残っていると、いくら画面をリロード（更新）してもページが変わりません。

EC-CUBE管理画面からキャッシュを削除することに加えて、ブラウザ側のキャッシュも削除してみましょう。

キャッシュの削除は『EC-CUBE管理画面 ＞ コンテンツ管理 ＞ キャッシュ管理』から削除できます。
ブラウザ側のキャッシュはブラウザの設定画面から行うか、全てのキャッシュを削除して再読み込みを行う『スーパーリロード』を行います。

上記の方法で解決しない場合は、シンプルにコードの記述ミスが原因と思われます。
ここは一概にいえませんが、「ページを右クリック→検証」で状況を確認しながら、地道にコードを確認していきましょう。

まとめ

以上、EC-CUBEでJavaScriptをカスタマイズする方法と、そのトラブルについて解説しました。

JavaScriptのカスタマイズ方法は複数あり、それぞれにメリットがあるので、どの方法でもカスタマイズできるようになっておくとベターです。
ぜひ、いろいろ試してみてください！