初めてのa-blog cms拡張アプリ制作！

2020年12月17日(木)

a-blog cms 拡張アプリ

こんにちは！3月からApplepleでインターンとして働いている田島と申します。
この度a-blog cms Advent Calendar 2020に記事を投稿することになりましたので、僕がこれまで半年ほど行なってきましたa-blog cms拡張アプリの開発について、これから取り組む人の参考になれるような記事を書きました。

拡張アプリとは

拡張アプリは、独自GETモジュールやPOSTモジュール、テンプレートなどを機能単位でまとめて運用できるようにしたものです。1つのアプリとしてまとめることによって、ブログ単位での機能追加が簡単になり、保守もしやすいです。

拡張機能は、エントリー閲覧履歴リストなど、applepleから販売されているものが代表的ですが、自分でも簡単に作成することができます。この記事では、拡張アプリの作成方法について、基本的な作り方と、応用的なTipsについてまとめます。

拡張アプリの作成方法

拡張アプリの作成手順を説明するために、ここでは「HelloAppleple」拡張アプリを作成してみます。HelloApplepleは、「Hello Appleple!」と表示するシンプルなGETモジュールを提供します。

1. ディレクトリの作成

/extension/pluginsディレクトリに、HelloApplepleというディレクトリを作成します。今後作成する拡張アプリのファイルはこのディレクトリの下に追加することになります。

2. ServiceProvider.phpの作成

ServiceProvider.phpは拡張アプリについての情報やインストールの際の処理など、拡張アプリに必須となるファイルです(このファイルがあれば、インストールが可能となります)。

HelloApplepleディレクトリの直下にServiceProvider.phpを次のように記述し作成します。

<?php

namespace Acms\Plugins\HelloAppleple;

use ACMS_App;

class ServiceProvider extends ACMS_App
{
    /**
     * @var string
     */
    public $version = '1.0.0';

    /**
     * @var string
     */
    public $name = 'HelloAppleple';

    /**
     * @var string
     */
    public $author = 'com.appleple';

    /**
     * @var bool
     */
    public $module = false;

    /**
     * @var bool|string
     */
    public $menu = false;

    /**
     * @var string
     */
    public $desc = 'Hello Appleple！と表示する機能を提供するプラグインです。';

    /**
     * サービスの初期処理
     */
    public function init()
    {

    }

    /**
     * インストールする前の環境チェック処理
     *
     * @return bool
     */
    public function checkRequirements()
    {
        return true;
    }

    /**
     * インストールするときの処理
     * データベーステーブルの初期化など
     *
     * @return void
     */
    public function install()
    {

    }

    /**
     * アンインストールするときの処理
     * データベーステーブルの始末など
     *
     * @return void
     */
    public function uninstall()
    {

    }

    /**
     * アップデートするときの処理
     *
     * @return bool
     */
    public function update()
    {
        return true;
    }

    /**
     * 有効化するときの処理
     *
     * @return bool
     */
    public function activate()
    {
        return true;
    }

    /**
     * 無効化するときの処理
     *
     * @return bool
     */
    public function deactivate()
    {
        return true;
    }
}

この時点で管理画面の拡張アプリを見ると次のようになっており、拡張アプリが認識されていることがわかります。

拡張アプリ一覧

3. GETモジュールの作成

GETモジュールは、HelloApplepleディレクトリの直下にGETディレクトリを作成し、さらにその直下にHelloApplepleディレクトリを作成し、その下に作成します。

＊ GETディレクトリの下にさらにHelloApplepleディレクトリを作成するのは、GETモジュールの名前管理を楽にするためです。(GETの直下に作成しても正常に動作します)

作成したGET/HelloApplepleディレクトリの直下にGreeting.phpファイルを作成します。

<?php

namespace Acms\Plugins\HelloAppleple\GET\HelloAppleple;

use ACMS_GET;
use Template;
use ACMS_Corrector;

/**
 * テンプレート上では、標準のGETモジュールと同様に、
 * '<!-- BEGIN_MODULE Sample --><!--END_MODULE Sample -->' で呼び出されます。
 */
class Greeting extends ACMS_GET
{
    public function get()                                                                                               
    {                                                                                                                   
        $Tpl = new Template($this->tpl, new ACMS_Corrector());

        $obj = [
            'greeting' => 'Hello Appleple!'
        ];
        return $Tpl->render($obj);
    }
}

これで、HelloAppleple拡張アプリは完成です。次に、実際に作成したGETモジュールを呼び出してみます。

拡張アプリを使う

ここでは、先ほど作成したHelloAppleple拡張アプリをテンプレートで呼び出してみます。

使用しているテーマにHelloAppleple.htmlを作成し、以下のように記述します。

<!-- BEGIN_MODULE HelloAppleple_Greeting -->
<p>{greeting}</p>
<!-- END_MODULE  HelloAppleple_Greeting -->

作成した拡張アプリをインストールします。

先ほど作成したgreeting.htmlをブラウザで表示すると、作成したGETモジュールであるGreetingが正常に動作していることが確認できました！

拡張アプリ作成のTips

ここまでは、拡張アプリの基本的な作成方法について見てきました。ここからは、より応用的な機能を実装しようとした際に役立つかもしれないTipsについていくつか紹介します。

1. SQLを記述する

・Whereの条件を()で囲む

Whereで複数の条件を指定する場合など、ANDやORの優先順位を適切に定めたい場合があると思います。そのような時は、次のように記述できます。

作成したいSQL
WHERE
AND (status <> 1 OR status IS NULL)
AND form_name = 'お問い合わせフォーム'

$SQL = SQL::newSelect('あるテーブル');

$where = SQL::newWhere();
$where->addWhereOpr('status', 1, '<>');
$where->addWhereOpr('status', null, '=', 'OR');

$SQL->addWhere($where, 'AND');

・複数の条件で外部結合を行う

外部結合を複数の条件で行いたい場合、addLeftJoinを次のように使います。

作成したいSQL
Select あるテーブル1 AS table1
LEFT JOIN あるテーブル2 AS table2 ON
table1.id = table2.id
AND table1.bid = table2.bid
AND table1.eid = table2.eid

$SQL = SQL::newSelect('あるテーブル1', 'table1');

$where = SQL::newWhere();
$where->addWhereOpr('bid', SQL::newField('bid'), '=', 'AND', 'table2');
$where->addWhereOpr('eid', SQL::newField('eid'), '=', 'AND', 'table2');

$SQL->addLeftJoin('あるテーブル2', 'id', 'id', 'table2', 'table1', $where);

2. Ajax通信を行う

JavaScriptで非同期処理を行なってa-blog cmsのPOSTモジュールを動作させる方法です。

・POSTモジュールを動作させる

非同期処理でPOSTモジュールにデータを送るには、データをform dataに変換して送信します。その際、そのクエリ文字列にモジュール名とformTokenを含めることで、任意のPOSTモジュールを動作させることができます。

POSTモジュール「Sample」を動作させたい場合

const params = new URLSearchParams();          // クエリ文字列の作成にURLSearchParamsを使用します
params.append('ACMS_POST_Sample', 'true'); // 通信するacmsのモジュール名
params.append('formToken', 'true');                   // モジュールの実行に必要な値

axios({  // ここでは非同期処理にaxiosを使用しています
  method: 'POST',
  url: '/',
  responseType: 'json',
  data: params
}).then(response => {
  ....

・非同期処理でJSONを受け取りたい場合

非同期処理でJSONを受け取りたい場合、通信したPOSTモジュールで次のように記述します。

Common::responseJson(
    連想配列
);

例えば、POSTモジュールに次のように記述した場合

Common::responseJson([
    'greeting' =>  'おはようございます'
]);

クライアント側では次のようなJSONを受け取ることができます。

{
  'greeting': 'おはようございます'
}

まとめ

いかがでしたでしょうか？この記事が少しでもこれからa-blog cmsの拡張アプリを作成しようとしている方の手助けとなれたら幸いです。これからも、applepleのインターンとして、皆様のお役に立てる拡張アプリを作って行きたいと思っておりますので、どうかよろしくお願いします！