Magentoのエクステンションを作ってみよう〜初中級編〜

前回は管理画面で設定した文字列をフッターに表示するエクステンションを作成しました。
今回は前回作ったエクステンションを拡張して、エクステンション独自のページを表示する機能を追加してみましょう。

今回の目的
今回作成するもの
Controllerクラスを作成しよう
routes.xmlの作成
レイアウトXMLを定義する
LESSファイルを作成して、デザインをカスタマイズしよう
終わりに

今回の目的

今回の目的は以下のとおりです。

Controllerの作成方法を理解する
URLとControllerのマッピング方法を理解する
画面レイアウトの定義方法を理解する
LESSファイルの作成方法

Controllerの定義方法がわかってくると、標準では存在しない構成のページを作成できるようになり、カスタマイズの幅が広がります。

今回作成するもの

今回作成するものは以下のとおりです。

Controllerクラス
エクステンション専用のURLを定義する routes.xml
Controllerが表示する画面レイアウトを定義したレイアウトXML
LESSファイル

前回のものを土台に拡張するので、作成するファイル数は少ないですが、理解することは増えますので、じっくり理解しながら進めましょう。

Controllerクラスを作成しよう

Controllerとは

Controllerは、ブラウザやHTTPクライアントからのリクエストを受け付け、リクエストされた内容に基づいた結果を返す役割を担っています。Magento2系では、1つのControllerは1つの役割しか担えない構造になっているため、処理ごとにControllerクラスを定義する必要があります。

Controllerの作成

Controllerを作成するには、エクステンションのディレクトリの中で、以下の手順を行います。

Controllerディレクトリを作成する
Controllerディレクトリの中に、ディレクトリを作成する（ここではIndexを作成します）
Indexディレクトリの中に、Controllerクラスを記述するファイルを作成する（ここではIndex.phpを作成します）

3までできたら、Index.phpを開いて、次のように記述します。

<?php
namespace My\Example\Controller\Index;

use \Magento\Framework\App\Action\Action;

class Index extends Action
{

    public function execute()
    {
        $this->_view->loadLayout();
        $this->_view->renderLayout();
    }
}

記述できたら保存しておいてください。

Controllerクラスの仕組み

Magento2系におけるControllerクラスは、以下のルールに沿って作成することになっています。

\Magento\Framework\App\ActionInterface を実装していること（あるいは実装したクラスを継承しても構いません）
1つの public function execute() があること

executeメソッドにそのControllerに担わせたい処理を記述するため、Magento2系のControllerは、原則1クラス1機能となっています。executeメソッドのなかでいろいろな分岐を書いても構いませんが、プログラムの簡潔さが損なわれ、テストもしにくくなりますので、やめておいたほうがよいでしょう。

routes.xmlの作成

routes.xmlは、Controllerクラス群に対し、エクステンション固有のURLを割り当てるために使用します。今回はフロントエンド用のroutes.xmlを作成するので、エクステンションのディレクトリの中で、以下の手順を行います。

etc/frontendディレクトリを作成する
etc/frontendディレクトリの中にroutes.xmlという名前のファイルを作成する

2までできたら、routes.xmlを開いて、次のように記述します。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <route id="example" frontName="example">
            <module name="My_Example" />
        </route>
    </router>
</config>

routes.xmlの仕組み

routes.xmlはかなりシンプルなXMLファイルです。基本的にはXSDファイル(XMLスキーマ定義ファイル)の定義どおり記述することになりますが、各タグの属性は以下の意味を持ちます。

タグ	属性	説明
router	id	使用するルーターを指定する。フロントエンド用はstandard。管理画面用はadmin。
route	id	レイアウトXML定義で使う名称を定義する
	frontName	URLで使う値を定義する
module	name	この経路を使用するモジュールを指定する。エクステンション名を正しく指定すること。

Magento2はXSDの定義に沿ってXMLファイルを評価するので、未定義のタグや属性は使用できません。

レイアウトXMLを定義する

さて、ここまできたらいよいよControllerに対応するレイアウトXMLの定義です。Magento2系では、1つのControllerに対して1つのレイアウトXMLを定義します。

Magento1系のときは、1つのレイアウトXMLの中に複数の画面定義が記述できていたため、ファイルの内容が肥大化しがちで見通しがあまり良くありませんでした。Magento2系では基本的には1つの画面定義は1つのファイルにまとまるようになっているので、見通しは良くなっています。

レイアウトXMLの作成

では、レイアウトXMLを作成しましょう。前回はdefault.xmlを作成しましたが、今回は新しいファイルを作成します。

Controllerと紐付けるレイアウトXMLを作成する場合、以下のルールに沿ってファイル名が定まるようになっています。

<Controllerのフロント名>_<アクションのグループ名>_<アクション名>.xml

Controllerのフロント名は、routes.xmlのrouteタグで定義したid属性の値。
アクションのグループ名は、Controllerクラスを作成するときに作成したディレクトリ名を小文字にしたもの。
アクション名はControllerクラスのファイル名を小文字にしたもの。

ルールがきちんと決まっているので、うまく動かない場合はここまでの定義をよく見直してみてください。

今回はroutes.xmlでフロント名をexampleと定義しているので、ファイル名はexample_index_index.xmlとなります。

レイアウト定義の記述

example_index_index.xmlを作成したら、ファイルを開いて、次のように記述します。

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <title>My Example Page</title>
    </head>
    <body>
        <referenceContainer name="content">
            <container name="exmaple.message" htmlTag="div" htmlClass="example-message" before="-">
                <block class="My\Example\Block\Message" name="my.example.message" template="My_Example::message.phtml" />
            </container>
        </referenceContainer>
    </body>
</page>

とりあえずここまでで前回フッターに表示したものと同じ内容が表示できるはずです。

ファイルを保存し、Magentoのキャッシュをクリアしたあと、

http(s)://<ホスト名>/example/index/index

にブラウザでアクセスして、次のような画面が表示されればOKです。

LESSファイルを作成して、デザインをカスタマイズしよう

Magento2のCSSは現時点ではLESSを用いて定義する仕組みになっています。（もちろん普通のCSSも使えます）

当然ながら、エクステンションで独自の定義を追加して、デザインをカスタマイズすることができます。

LESSファイルを追加してみよう

LESSファイルの追加は、エクステンションのディレクトリ下で以下の手順で行います。

view/frontend/web/css/sourceディレクトリを作成
そのディレクトリに _module.less ファイルを作成

あとはこのファイルに必要な定義を書いていきます。

今回は今表示されているメッセージの文字サイズを大きくしてみます。_module.lessを開いて、以下の定義を書き込んでください。

.example-index-index {
  .example-message {
    font-size: 2em;
  }
}

保存したら、以下の操作を実行します。

generatedディレクトリ以下をすべて削除
var/view_preprocessedディレクトリ以下をすべて削除
pub/static/frontendディレクトリ以下をすべて削除
ページを再読込

正しく定義ができていれば、先程よりも文字が次のように大きく表示されると思います。

あとはテンプレートにいろいろ追記したり、LESSファイルを調整したりしていくことで、いろいろと見た目を調整できます。

終わりに

今回はControllerと独自レイアウトのページ定義、LESSファイルの書き方を紹介しました。
次回はデータベースを使った処理をご紹介したいと思います。