概要

concrete5パッケージ形式は、concrete5のマーケットプレイスで使われている形式で、concrete5の機能を統合し、かんたんにアップデートを行なえる機能を開発者に提供します。マーケットプレイスでテーマを配布したい開発者は、テーマをパッケージ形式にする必要があります。パッケージはconcrete5の様々な機能(テーマ、ブロック、シングルページとコントローラー、カスタムコード、その他)を含むことができます。ただ、このページでは、テーマをパッケージ形式にする方法のみ解説します。

訳注:このページの解説は下記のビデオ(英語)の解説を文字に起こしたものです。

このドキュメントで作り方を解説してきた「Urbanic」テーマがインストールされている状態です。そして、このテーマは「themes」フォルダーにあります。管理画面の「テーマ」ページからも確認することができます。もしすでにインストールされていたら、アンインストールしてください。

まず、これから作成するパッケージのためのフォルダを作成しましょう。「packages」ディレクトリ内に作成します。フォルダ名は、他のパッケージと重複しないようにしてください。一般的な単語は避けてください。テーマの名前が「Urbanic」なので、パッケージのハンドルネームを「theme_urbanic」としました。パッケージのハンドルネームと同名のフォルダを作成します。

 次に、2つのファイルを作成したフォルダに作成します。最初に、パッケージを表すアイコン画像を作成します。歴史的に97x97ピクセルであることが多いですが、バージョン5.7からはピクセルの制限はなくなり、正方形であれば問題ありません。また、通常角丸のアイコンになります。テーマ内の thumbnail.png とは別の画像であることに注意してください(比率も違います)。

次に、パッケージにとって最も重要なファイル、controller.php を作成します。このファイルはパッケージに関する情報(名前、バージョン、ハンドルネーム、インストール&アップグレード時の処理内容)を含みます。アンインストール処理は必須ではありません。パッケージに関連するデータは、パッケージのアンインストール時にconcrete5が自動で同時にアンインストールします。まず、最初にクラスを作成し、パッケージ共通のクラスを継承し、名前空間を指定します。

namespace Concrete\Package\ThemeUrbanic;
 
use Concrete\Core\Package\Package;
use Concrete\Core\Page\Theme\Theme;
 
defined('C5_EXECUTE') or die(_("Access Denied."));
 
class Controller extends Package
{
 
}

名前空間(namespace)の指定に注目してください。concrete5のパッケージの名前空間は、次の形式を使用します。

\Concrete\Package\YourCamelCasedPackageHandle

次に、use 演算子でパッケージコントローラーから使用するクラスを参照しています。

パッケージコントローラーで記述するクラスは、必ず \Concrete\Core\Package\Package クラスを継承してください。このクラスに、インストール時やアンインストール時の処理が記載されています。

\Concrete\Core\Page\Theme\Theme クラスは、テーマをPHPからインストールする際に必要になります。

それでは、このパッケージにいくつかのメタ情報を追加して行きましょう。これらは、クラスの内部の先頭に記述します。

protected $pkgHandle = 'theme_urbanic';
protected $appVersionRequired = '5.7.1';
protected $pkgVersion = '1.0';
 
public function getPackageDescription()
{
    return t("Adds Urbanic Theme.");
}
 
public function getPackageName()
{
    return t("Urbanic");
}

$pkgHandle パラメーターで、パッケージのハンドルネームを指定します。パッケージのハンドルネームは、パッケージのフォルダ名と一致している必要があることに注意してください。次に、$appVersionRequired パラメーターで、このパッケージをインストールするのに必要なconcrete5のバージョンを指定します。このバージョン未満のconcrete5では、このパッケージをインストールすることができません。次に、$pkgVersion パラメーターで、このパッケージのバージョンを指定します。このバージョン番号は、パッケージのバージョンアップの際に参照されます。最後に、getPackageDescription() メソッドでパッケージの説明を、getPackageName() メソッドでパッケージの名前を指定します。これらは管理画面のパッケージの一覧で表示されます。

次に、インストール処理を記述して行きましょう。非常にシンプルなものです。

public function install()
{
    $pkg = parent::install();
    Theme::add('urbanic', $pkg);
}

パッケージの install() メソッドは、パッケージがインストールされる際に自動的に実行されます。最初に、parent::install() を使って、$pkg 変数に、インストールするこのパッケージ自身を代入します。次に、Theme クラスの add() メソッドを使ってテーマをインストールします。第1引数はテーマのハンドルです。第2引数に先ほどの $pkg 変数を渡します。これは非常に重要です。この変数が渡されないと、concrete5はインストールしようとしているテーマが application/themes/ ディレクトリーにあるものと思ってしまいます。$pkg 変数を渡すことで、テーマファイルがどこにあるのかをconcrete5に知らせる必要があるのです。

テーマ以外でもパッケージ形式でインストールするものは全て、同様に $pkg 変数を add() または instlal() メソッドに渡す必要があります。

それでは、テーマを application/themes/ ディレクトリからパッケージディレクトリに移しましょう。移動するまえに、テーマ内のファイルも変更する必要があります。このページで名前空間について説明しましたが、テーマの中にも名前空間が使われているファイルがあります。PageTheme クラスです。packages/theme_urbanic/themes/urbanic/page_theme.php を開いて、この部分を

namespace Application\Theme\Urbanic;

次のように変更します。

namespace Concrete\Package\ThemeUrbanic\Theme\Urbanic;

「ThemeUrbanic」は、パッケージのハンドルネーム「theme_urbanic」と対応しています。ハンドルがもし「urbanic_us_great」だったら、名前空間は \Concrete\Package\UrbanicIsGreat\Theme\Urbanic になります。

これで以上です!パッケージ化されたテーマは、マーケットプレイスに申請することができますし、他のconcrete5サイトでインストールすることも簡単になります。

原文:Overview & Full Screencast