PHP コントローラー
controller.php はブロック自身の情報と、ブロックについて実行されるアクションに応じて自動的に実行されるメソッドで成り立っています。
名前空間
まず、ブロックに正しい名前空間を設定しましょう。このブロックは concrete5 の application/ ディレクトリに設置されますので、最初のセグメントは Application になります。次に、Block を追加し(全てのブロックの2つ目のセグメントは同じです)、最後にブロックタイプハンドルをキャメルケースで整形したものを追加します。ですので、ハンドルが hello_world の場合、名前空間は次のようになります。
<?php namespace Application\Block\HelloWorld;
コアブロックコントローラーを継承する
次に、このブロックコントローラーを、concrete5 のコアブロックコントローラーから継承させます。
use Concrete\Core\Block\BlockController;
クラス定義
これで、クラスを開発する準備が整いました。
<?php namespace Application\Block\HelloWorld; use Concrete\Core\Block\BlockController; class Controller extends BlockController { }
クラスプロパティ
データベースパラメーター
$btTable
このブロックの主なデータベーステーブル名です。この値が定義されていて、ブロックがこのテーブルのみを使用する場合、ブロックのフォームのフィールドとデータベースのカラムを対応させて、ブロックはこのテーブルに自動的に情報を保存します。この値は db.xml でも定義します。
分類
$btDefaultSet
デフォルトは null です。正しいブロックタイプセットハンドルが指定されていると、ブロックタイプはそのセット内に自動的にインストールされ、ブロックを追加するインターフェースに表示されます。
インターフェース
$btSupportsInlineAdd
ブロックがインライン追加をサポートしているかどうかの真偽値です。特に指定しない場合はデフォルトの false になります。
$btSupportsInlineEdit
ブロックがインライン編集をサポートしているかどうかの真偽値です。特に指定しない場合はデフォルトの false になります。
$btInterfaceWidth
このブロックを追加または編集する際のモーダルポップアップダイアログボックスの横幅のピクセル数です。インライン編集をサポートするブロックではこの値は無視されます。
$btInterfaceHeight
このブロックを追加または編集する際のモーダルポップアップダイアログボックスの高さのピクセル数です。インライン編集をサポートするブロックではこの値は無視されます。
$btIgnorePagethemeGridFrameworkContainer
デフォルトは false です。true に設定されている場合、グリッドコンテナをサポートしたテーマのページにブロックが追加された際、このブロックはコンテナで囲まれません。水平線や画像スライダーなど、ページの全幅を使いたいブロックで便利です。
キャッシュ
$btCacheBlockRecord
デフォルトで true です。ブロックキャッシュが有効になっている場合、データベースに保存されているブロックのデータがキャッシュされます。この値はほとんどの場合 true が望ましいです。
$btCacheBlockOutput
デフォルトで false です。ブロックキャッシュが有効になっている場合、ブロックの表示結果をキャッシュしデータベースへのアクセスを減らします。
$btCacheBlockOutputLifetime
デフォルトで無制限(0)です。ブロックキャッシュが有効になっていてブロックキャッシュがこのブロックで有効になっている場合、この値はキャッシュがクリアされるまでの時間を秒で指定します。
$btCacheBlockOutputOnPost
デフォルトで false です。ページが POST リクエストで表示される場合もブロックのキャッシュを表示するかどうかを制御します。ブロックの中にはキャッシュしてもいいものもあるかと思いますが、POST リクエストの際にエラーメッセージを表示したり、何らかの反応を返す場合は false であるべきです。
$btCacheBlockOutputForRegisteredUsers
デフォルトで false です。ログインユーザーが表示している場合もキャッシュして良いのかどうかを制御します。ログインユーザーに個別にコンテンツを表示するブロックでは、false であるべきです。
拡張
$btExportPageColumns
Defaults to an empty array. When this block is exported, any database columns found in this array will automatically be swapped for links to specific pages. Upon import they will map to the specific page found at that path, regardless of its ID.
$btExportFileColumns
Defaults to an empty array. When this block is exported, any database columns found in this array will automatically be swapped for links to specific files, by file name. Upon import they will map to the specific file with that filename, regardless of its file ID.
$btExportPageTypeColumns
Defaults to an empty array. When this block is exported, any database columns found in this array will automatically be swapped for references to a particular page type. Upon import they will map to that specific page type ID based on the handle specified.
$btExportPageFeedColumns
Defaults to an empty array. When this block is exported, any database columns found in this array will automatically be swapped for a reference to a specific RSS feed object. Upon import they will map to the specific feed, regardless of its ID in the database.
$btIncludeAll
Defaults to false. Determines whether this block should include itself as is on all versions of a page. This will disable versioning for this block type. Note: this is not recommended, but sometimes it is necessary given the architecture of a block type.
$btCopyWhenPropagate
Defaults to false. When a block is aliased from page defaults or from another location, setting this to true will cause that block to copy itself, rather than alias back to the original block.
必須メソッド
getBlockTypeName()
ブロックタイプの名前を返します。管理画面や追加パネルで表示されます。通常この値は t() 関数を使って翻訳可能な形で返すべきです。
getBlockTypeDescription()
ブロックタイプの説明を返します。
<?php namespace Application\Block\HelloWorld; use Concrete\Core\Block\BlockController; class Controller extends BlockController { public function getBlockTypeName() { return t('Hello World'); } public function getBlockTypeDescription() { return t('This is my sample block.'); } }
オプションメソッド
add()
If present, this method will automatically be run when the add template is rendered (whether in the page for inline editing or through the dialog for traditional Concrete5 block adding.) If no add template is present, this method will not be excuted.
edit()
If present, this method will automatically be run when the edit template is rendered (whether in the page for inline editing or through the dialog for traditional Concrete5 block adding.) Like add(), if no edit template is present, this method will not be excuted.
validate()
This method will be run automatically any time add or edit interface is submitted to the backend to be saved. If this block returns a Concrete\Core\Error\Error() object with any messages inside it, those will be displayed to the user and the block will not be saved.
save($data)
This method is automatically run when a block is submitted to the backend to be saved. If this method is omitted, the block will be saved based on the variables found in the $data array. This $data array is populated from entries in the POST. These variables will be mapped directly to columns found in the $btTable database table, and attempted to be saved automatically. This can be extended or overridden entirely by defining a save() method in the controller. That means that if your add.php or edit.php file contains a form element with a particular input name, that name parameter will be found in the $data array of the save() method.
duplicate($newBlockID)
This method is automatically run any time a block is duplicated. This happens automatically in Concrete5 when versioning blocks and pages. If this method is omitted then the data row in the $btTable database table will be duplicated with the bID parameter found in that table getting the value of the $newBlockID parameter. Duplication operations can be extended for blocks that use multiple tables by specifying a custom duplicate() handler.
export(SimpleXMLElement $blockNode), import($page, $areaHandle, SmpleXMLElement $blockNode)
These methods are run automatically when exporting and importing blocks of this type. Most of the time these can be omitted but custom import/export routines are possible.
delete()
This method is automatically run when a block is deleted. Note: this may not happen very often since a block is only completed deleted when all versions that reference that block, including the original, have themselves been deleted. If this is omitted the delete() operation simply deletes the row from the $btTable database table that has the block ID parameter of the current block ($bID).
getSearchableContent()
If present, this method provides text for the page search indexing routine. This method should return simple, unformatted plain text, not HTML.