guttally.net

Hello World の解説

 前回作成した Hello World なブロックタイプについて解説していきます。

ディレクトリ・ファイル構成

 前回作成した Hello World なブロックタイプのディレクトリ (便宜上,以下 「ブロックタイプ・ディレクトリ」 と呼びます) は,concrete5 インストールディレクトリ配下にある blocks ディレクトリの中に作成しました。 ブロックタイプを単体で作成する場合には,この blocks ディレクトリ内にブロックタイプ・ディレクトリを作り,そこにブロックタイプの構成要素となるファイルを格納していくことになります。

DIR_BASE  // concrete5 のインストールディレクトリ
|
|---blocks
    |
    |---guttally_hello_world // 作成したディレクトリ
            controller.php   // 追加したファイル その 1
            view.php         // 追加したファイル その 2

 ブロックタイプを作成する上で注意すべき情報として,ファイルの命名規則があります。 concrete5 では,すべてのファイル名は語句をアンダースコア ("_") 区切った小文字であるべき (should) で,大文字は認められない (No uppercase permitted) とされています。 ブロックタイプ・ディレクトリにもこれが適用されます。 したがって,"HelloWorld" や "helloWorld","hello-world"  などは,ブロックタイプ・ディレクトリの名称としては不適切で,"hello_world" が正解です。 つまるところ,ブロックタイプ・ディレクトリはスネークケースで命名することになります。

 また,他のユーザが作成したブロックとの名前の衝突を避けるため,ブロックタイプの頭に本家 concrete5.org のユーザアカウント名を付加することとされています。 私は guttally というアカウントを取得しているので,私が作成するブロックタイプ・ディレクトリは全て guttally_ で始まることになります。 もっともこのようなクラスのプレフィックスは,自作したブロックタイプを公開する場合に重要になるものです。 自分だけで利用する場合には,あまり気にしなくても良いと思います。

 以上の命名規則が適用された結果,前回作成したブロックタイプ・ディレクトリの名称は,guttally_hello_world となったわけです。

 なお,ブロックタイプ・ディレクトリの名称は,そのブロックタイプの 「ハンドル」 とも呼ばれます。 以降,ブロックタイプのハンドルといった場合には,ブロックタイプ・ディレクトリの名称と同じだと思ってください。

 さて,ブロックタイプ・ディレクトリの中には controller.php と view.php という 2 個のファイルを作成しました。 これら 2 個のファイルは,ブロックタイプを作成する上で最低限必要なファイルです。 以下,controller.php と view.php それぞれについて詳しく見ていきます。

controller.php

 前回作成したブロックは 2 つの php ファイルから構成されていました。 controller.php と view.php です。

 初めに,controller.php から見ていきましょう。 controller.php は以下のような内容のファイルでした。

controller.php
<?php
defined('C5_EXECUTE') or die('Access Denied.');
class GuttallyHelloWorldBlockController extends BlockController {
	protected $btName = 'Hello World';
	protected $btDescription = "文字列 Hello World を表示します。";
}

 1 行目の php 宣言後,2 行目で何やら文句が並んでいます。 これは,この php スクリプトが concrete5 を経由しないで呼び出された場合にスクリプトの実行を停止するための記述で,concrete5 の配下で動作する php スクリプトには必ず記述するようにします。 というのも,concrete5 配下で使用する php スクリプトは,オブジェクトの初期化など多くの部分が concrete5 の動作に依存します。したがって,これらのスクリプトが単体で実行された場合,一般には期待通りの動作をしてくれないのです。 予期しない動作でセキュリティホールを作らないためにも,以後 concrete5 配下に作成する php スクリプトには必ずこの記述をするようにします。

コントローラ・クラスの命名規則

 3 行目からは,クラスの定義が始まります。 これは,コントローラ・クラスと呼ばれるブロックタイプの中核となるクラスで,concrete5 側で定義されている BlockController クラスを継承します。

 コントローラ・クラスには命名規則があって,「ブロックタイプのハンドルをキャメルケースに変換したものの末尾に BlockController を付加する」とされています。 この命名規則に違反した場合,ブロックタイプとして concrete5 から認識されないので注意が必要です。

 前回作成したブロックタイプのハンドルは "guttally_hello_world" です。 これをキャメルケースに変換すると,"guttallyHelloWorld" になります。 で,その後ろに BlockController を付加すると,コントローラ・クラスの名称 "guttallyHelloWorldBlockController" になります。

 ところで,controller.php を改めてみると,コントローラ・クラス名の先頭は小文字の g ではなく,大文字の G になっています。 私が試してみた限り,コントローラ・クラス名の先頭の文字は大文字でも小文字でも問題なく動作します。 先頭を大文字にしたキャメルケースをアッパーキャメルケース (またはパスカルケース),先頭を小文字にしたキャメルケースをロワーキャメルケースと言ったりもしますが,そのどちらでも問題なく動くようです。 アッパーだろうがロワーだろうが,キャメルケースなら OK といったところでしょうか。 concrete5 に組み込まれているブロックなどを見ると,アッパーキャメルケースで命名されているようなので,私はコントローラ・クラスの命名にはアッパーキャメルケースを採用しています (アッパーキャメルケースを使うのは適切じゃないよ,っていう仕様をご存じの方がいらっしゃいましたら,教えていただけると幸いです。)。

ブロックの表示名と説明

 先のクラス内には 2 つのプロパティが定義されています。

 $btName は,ブロックタイプの名称として concrete5 のユーザインタフェース上に表示される文字列です。 前回,"インストール待ちのブロックタイプ" やブロックタイプの情報ダイアログなどに表示されていた "Hello World" という文字列は,ここの記述から定義されていたわけです。 $btName で定義される名称は,あくまでもユーザインタフェース上に表示されるだけのものなので,命名規則などといったシステム面からの制約はありません。 他のブロックと紛らわしくならない名前を決めてあげれば OK です。

 次に $btDescription ですが,これはブロックタイプの情報ダイアログに表示される,ブロックタイプの説明の文言です。 これも表示名と同様,特に制約はありません。 後でなんだか分からなくなることのないように,理解しやすい説明を記述しておきます。

 さて,試しにこれらのプロパティを変更して,ブロックタイプを更新してみましょう。

controller.php
<?php
defined('C5_EXECUTE') or die('Access Denied.');
class GuttallyHelloWorldBlockController extends BlockController {
	protected $btName = 'ぐったり Hello World';
	protected $btDescription = "文字列 Hello World を,ぐったりと表示します。";
}

 controller.php を上記のように変更して,ブロックタイプの情報ダイアログを開き,右下の更新ボタンを押すと下のようになります (もしかすると,更新ボタンを押した後,F5 キーを押下して,再度ページを読み込む必要があるかもしれません)。

名前と説明の変更

 ちゃんと表示が変わることが確認できました。 

 ところで,今後ブロックタイプを作成していく場合,一度インストールしたブロックタイプを更新していくこともあるかと思います。 controller.php など重要なファイルを更新した場合には,必ず上記ブロックタイプの更新を行うようにしてください。 今後追加していくファイルの中には,上記の更新操作を行わなくても更新が即時反映されるものもありますが,そうでないものも多くあります。 私の経験ですが,更新操作を忘れていたことに気づかず,半日時間を無駄にしてしまったこともあるので,同じ轍を踏まないようにご注意ください (><;

view.php

 最後に,view.php について説明を加えます。

view.php
<?php
defined('C5_EXECUTE') or die('Access Denied.');
echo "<p>Hello World</p>";

 2 行目の記述は,controller.php の項で説明したのと同じものです。 例えば外部から直接 view.php へアクセスがあったとしても,何も実行されません。

 ページにブロックが挿入されると,挿入された個所には view.php の実行結果が出力されます。 この view.php では,3 行目の echo の結果が出力されることになります。 したがって view.php の記述を変えることで,ページ上に表示を変えることができます。 では,実際に試してみましょう。

view.php
<?php
defined('C5_EXECUTE') or die('Access Denied.');
echo "<p>Hello ぐったり World</p>";

 ↑のように php スクリプトを変更した上で,ブロックを挿入すると,↓のような結果が出力されます。

Hello ぐったり World

 こうして,ページに任意の結果を出力することができるわけです。 

 以上,今回はこの辺で……。

コメントを残す



(このメールアドレスは表示されません。)


Captcha認証コード

Captchaをクリックすると違う文字候補が出てきます。