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

EC-CUBE 4で JavaScript を動かす方法は3つあります。「全ページに効かせたい」のか「1ページだけ」なのかで選ぶものが変わるので、それぞれの使いどころと、反映されないときの対処法をまとめました。

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

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

3つの方法の使い分け 早見表

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

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

{% 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 */
const greeting = document.getElementById('greeting');
const customBtn = document.getElementById('custom-btn');

customBtn.addEventListener('click', () => {
    greeting.textContent = 'HELLO！！！';
});

customBtn 要素にクリックイベントを追加し、クリックすると greeting 要素のテキストを「HELLO！！！」へ変更する、という内容です。

JavaScript変更後（ボタンを押すとテキストが変わる）

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

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

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

customize.js の保存場所

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

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

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

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

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

直接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 %}

{% 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特有の記法については以下の記事にて。

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

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

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

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

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

1. STEP1
   JavaScriptファイルを用意する

   Visual Studio Code などのエディターを使って、JavaScriptファイルを用意します。ここでは test.js という名前で以下の内容を書きました。

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

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

2. STEP2
   サーバーへアップロードする

   用意したJavaScriptファイルを『EC-CUBE管理画面 ＞ コンテンツ管理 ＞ ファイル管理 ＞ assets ＞ js』の下にアップロードします。ファイルサーバーから html/user_data/assets/js の下へ直接アップしても構いません。

3. STEP3
   Twigテンプレートから読み込ませる

   Twigテンプレートに以下のコードを記述し、適用したいJavaScriptファイルを読み込ませます。

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

   ついでにCSSも別ファイルへ移すと、テンプレートがすっきりします。

   {% extends 'default_frame.twig' %}
   
   {% block stylesheet %}
       <link rel="stylesheet" href="{{ asset('assets/css/test.css', 'user_data') }}">
   {% 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ファイルの移し方は こちら をご覧ください。

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

JavaScript変更後（アラートが表示される）

JavaScriptファイルを事前に用意する必要があるので少し煩雑に感じるかもしれませんが、これで通常1個しかないJavaScriptファイルを複数用意できます。機能ごとにまとめられてメンテナンスしやすくなるので、がっつりカスタマイズする場合はこの方法が一番おすすめです。

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

コードを記載したのに、なぜかJavaScriptが適用されない。そんなときに確認する順番です。

キャッシュが残っている

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

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

ブラウザ側は、すべてのキャッシュを削除して再読み込みを行う スーパーリロード が手軽です。

Bootstrapのバージョンが違う

EC-CUBEでは Bootstrap という フレームワーク を採用しています。EC-CUBEのバージョンにより読み込んでいるBootstrapのバージョンが異なり、使用できるクラスなども異なります。

たとえば、新しいバージョンのEC-CUBEで作成されたコードを古いバージョンのEC-CUBEへコピー＆ペーストした場合、Bootstrapが読み込めずCSSやJavaScriptが反映されないことがあります。現在使用しているBootstrapのバージョンを確認し、適切なクラスなどを使用するようにしましょう。

コードの記述ミス

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

まとめ

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

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

EC-CUBEのカスタマイズに関する記事

• カスタマイズのまとめ
• CSSの簡単設定と反映方法
• Twig まとめ(1) ～継承やブロックについて～
• デバッグモードの設定/解除方法

この記事に出てきた用語

• JavaScriptとは？
• DOMとは？
• キャッシュとは？
• フレームワークとは？
• CSSとは？