concrete5 ブロックの基本

concrete5 には、記事やモジュール、サイドバー等の他のCMSで一般的なコンセプトはなく、全てがブロックという単位で扱われています (シングルページを除く)。

concrete5 デフォルトブロックや、マーケットプレイスで配布・販売されている以外のブロックを作成されたい方に、 concrete5 ブロックの基本と作成方法を紹介します。

このドキュメントはPHP初級者以上の方向けに作成しました。

尚、マーケットプレイス等で、作成されたブロックを配布されたい方は、このページ以外にも、ブロックのパッケージ化が必要となって来ます。後日パッケージ化については詳しく説明させていただきます。

このドキュメントは、v5.3.2を基本とし、開発元の原文に手を加えたものです。

 

サンプルブロック

このページの為に、サンプルブロックを作成しました。 

サンプルファイル (2KB ZIP圧縮 ファイル)

上記のファイルをダウンロード、解凍し、お使いの concrete5 テストサイトにインストールします。追って説明します。

＊ 尚、このサンプルブロックは、あくまでも学習用に作成されており、絶対に、実運用している concrete5 で使用しない様にお願いします。

 

はじめに

ブロックは、「blocks」「/concrete/blocks」「/packages/パッケージハンドル/blocks/」ディレクトリー以下に配置されています。

これらが、concrete5 サイト上でいろいろな機能を持ったブロックとして機能し、サイト運用者はそれらのブロックを積み上げて行きます。

尚、「/concrete/blocks」配下に設置されているコアブロックは、今後のアップグレードの事等を考え、上書きしないでください。

concrete5 には優秀なローダー機能が搭載され、ユーザー領域にコアブロックと同じディレクトリー名、ファイル名のファイルが存在すると、そちらを優先される様に出来ています。

システムファイルを維持したまま、コアブロックの改造が出来ますので、是非、そちらをご覧下さい。

詳しくは「ブロックの修正の仕方、カスタムテンプレートの仕組み」をご覧下さい。

 

ブロックのファイル構成

add.php

必須ファイルです。このファイルは、ユーザーがブロックの新規追加を選択した時に読み込まれるファイルです。

edit.php

オプションのファイルですが、将来的には必須になる予定です。このファイルは、既存のブロックを編集する時に読み込まれます。

controller.php

必須ファイルです。このファイルは、ブロックの名前、説明、編集画面のサイズなどのパラメーターを記入し、そして、必要ならばプログラム処理を書き込む場所になります。

独自のプログラム・データ処理を行う場合、POST変数が、きちんとブロックのデータベースのテーブルコラムにマッピングされる様にして下さい。

db.xml

ブロックがデータベースにデータを保存しなければ行けないのであれば、必須ファイルです。このファイルには、ブロックがインストールされる際と、[管理画面] - [機能を追加] - [編集] - [更新]をクリックした際に読み込まれ、テーブルを新規作成もしくは更新されます。

ADOXMLS フォーマット形式で記述（英語マニュアル）。詳しくは後ほど。

auto.js

オプションです。このファイルが存在すると、ブロックの新規追加もしくは、編集ウインドウを開いた時に自動的に読み込まれます。

icon.png

オプションです。16x16ピクセスのPNG形式で保存して下さい。ブロックの一覧が表示される際にこのアイコンが表示されます。

tools/ディレクトリー

オプションです。ブロックのいろいろな追加機能のプログラムを格納するファイルを格納するのに使用して下さい。デフォルトブロックでは「オートナビ」ブロック等を参考にされてください。

templates/ディレクトリー

オプション。view.php をカスタマイズしたファイルが格納されています。これ以下のファイルは、「カスタムテンプレート」で設定する事により、HTMLコードの出力を変えたりする為に使われます。詳しくは、「ブロックの修正の仕方、カスタムテンプレートの仕組み」を参考にされて下さい。

 

ブロックのインストール

ブロックを作成する前に、上記のサンプルブロックをインストールして下さい。

  • zipファイルを解凍
  • ディレクトリー共、/blocks/フォルダーにコピー &  アップロード
  • concrete5 管理画面にログイン
  • 「機能を追加」をクリック
  • ページ右側に「ダウンロードされ、インストール準備ができました」のリストに「Basic Block」という選択肢が現れていると思います。
  • 「インストール」をクリックして下さい

＊尚、これは、ブロックのインストール方法であり、パッケージではありません。もし、ブロックがパッケージとして提供され、パッケージのフォーマットに基づき作成されているのであれば、「/packages」フォルダーにインストール必要があります。

データベースに該当テーブルが自動的に作成され、インストールが完了されたはずです。

それでは、インストール時に、concrete5システムにきちんと情報が行き渡るための基本を紹介します。

 

controller.php 内のブロック情報

controller.php には、そのブロックのプログラム処理に加えて、ブロックに関する情報が含まれています。

class ○○○Controller extends BlockController {
〜省略〜
} 

とブロックの基礎となるクラスを定義し、そのクラス内に以下の設定項目を宣言して下さい。

 

必須項目

  • btDescription
    • ブロックの説明文。管理画面や、ブロック一覧リストに表示されます。
  • btName
    • ブロックの名前

オプション項目

  • btTable
    • ブロックの基本テーブル、データベースを使用するのであれば必須です。
    • ブロックがこのデータベーステーブルのみを使用しているのであれば、情報が自動的にこのテーブルに保存されます。
    • ブロックの入力フォームで指定されたデータベースのコラムに保存されます。
  • btInterfaceWidth
    • ブロック新規作成・編集時にポップアップされるウインドウの横幅サイズ(px)を指定します
  • btInterfaceHeight
    • ブロック新規作成・編集時にポップアップされるウインドウの縦幅サイズ(px)を指定します

サンプルブロックの、controller.php を開いてみて下さると、これらの情報が記入されている事が分かると思います。

 

db.xml ブロックのデータベース情報

次に、データベースのコラム等の情報を記入し、インストール時に正常にデータベーステーブルやコラムが生成される様に指定します。

サンプルブロックでは、以下の様にXMLが記述されています。

以上のように、「btBasicTest」と命名されたテーブルのコラム (フィールド) を記入して行きます。

"bID" フィールド (必須)

テーブルが定義され、最初のフィールド (4〜7行目) にある「bID」は、concrete5 がサイト全体のブロックを管理する為の ブロックID番号 です。プライマリーKeyである事と、unsignedである事を定義します。この最初のフィールドは、絶対にこのように記述して下さい。

新たなテーブルを作成される際でも、そのテーブル全てに、この「bID」を、プライマリーキーとして宣言して下さい。concrete5はこのbIDの情報を利用し、システムでブロックの場所やメタデータ等を管理しています。

"content" フィールド

次に、このサンプルブロック独自のフィールドで、ロングテキストであることを示す「X2」が定義されています。

定義についての詳しくは、「ADOdb Data Dictionary Library for PHP」をご覧下さい。以下に早見表を作成しました。

 

ADOdb 早見表

以下に、よく使われそうなタイプを紹介します。この早見表は、2009年9月11日時点で作成されたものです。

フィールドタイプ

concrete5 でよく使われるタイプは「C」「I」「X2」「T」です。

  • B
    • BLOB (Binary Large Object)
    • バイナリーデータ保存用
  • C
    • 255文字以内のテキスト用
    • concrete5では、ファイル名や短いパラメータを格納する時によく使われます
  • C2
    • マルチバイト文字キャラクター用
  • F
    • 浮遊小数点
  • I
    • 整数値 (I4にマップされています）
    • concrete5 では、bID、fIDなどの数字のID情報関連で使われています
  • I1, I2, I4, & I8
    • 1, 2, 4, 8バイトの整数値
    • concrete5 では、各自のパラメーターのID情報を格納するのに使われています
  • L
    • ブーリアンを格納するのに適した整数値
  • X
    • 4000文字以内のテキスト
  • X2
    • Multibyte varchar - 文字キャラクター（大きいサイズ）
    • concrete5 では、記事ブロック等長い文章を保存する時に使われます
  • XL
    • 一番大きいキャラクター文字フィールド
  • D
    • 日付
  • T
    • 日付と時刻（タイムスタンプ）
  • N
    • 数値

フィールドオプション

フィールドの中(<field ○○></field>)に 以下のパラメーターを<○○></○○>という形で挟みます。

以下に良く使われそうなオプションを紹介します（MySQL用のオプションのみ記載しています）

  • "auto" & "autoincrement"
    • Auto Increment です
  • "key" & "primary"
    • プライマリキー
  • "def" & "default"
    • 間に入る値をデフォルト値をします
  • "defdate"
    • 生成された日付をデフォルトして自動生成します
  • "deftimestamp"
    • 生成された日付と時刻をタイムスタンプ形式で自動生成します
  • "unsigned"
  • "unique"
    • ユニークインデックスを生成します

 

 

ブロック構成ファイルの説明

add.php

サンプルブロックの「add.php」を開いて下さい。以下のようなコードになっています。

このサンプルブロックでは、一番上に、テキストを表示したあと、concrete5 のフォームライブラリーを読み込み、ラベルやインプットフィールドを生成する為の簡単なコードが記述されています。

'content' とは、先ほどの db.xml で指定したテーブルのフィールド「content」です。

$form->label とは、インプットのラベル表示

$form->text で、テキストのインプットフィールドを出力するという指示で、そして、横幅を320pxにするというスタイルの指示を array しています。

もちろん、直接 HTML コードを記載されても構いませんが、この concrete5 ライブラリを使用する事により、formの宣言等を省略出来ます。

今現在では、concrete5 のフォームライブラリを使用せずに、ご自分で直接フォームのHTMLコードを書き込まれても構いません。

しかし、将来、このフォームライブラリーを使用する事を必須にする予定ですので、特に理由がない限り、concrete5のフォームライブラリを使用して下さい。

フォームライブラリーのオプション等は、concrete5 開発元のAPIライブラリ中、ページ右上のプルダウンメニューから、「Helpers」パッケージを選択。そして、「FormHelper」のこのページで閲覧可能です。

save() メソッドについて

「○○に追加」から各ブロックを選択した際、concrete5は自動的にシステム内のブロックコントローラーの のsave()を実行する様に設定してあります。

ですので、フォームから送信されたデータをそのままデータベースに保存する場合は、自分のブロックに、save()を宣言する必要はありません。

 

edit.php

edit.php では以下の事に注意して下さい。

add.php とほとんど同じですが、add.phpとの違いは、4行目に、"$content"パラメータが追加されていることです。

concrete5 の典型的なブロックコントローラーでは、データベースのコラムの値が自動的にローカルスコープに読み込まれています。そして4行目で、フォームヘルパーに引き渡す処理をしています。

つまり、concrete5 では、ブロック編集時、特別な処理をしているブロック以外は、bIDに関連するブロックのデータをPHPの変数として引き渡す処理を自動的に行っています。

 

view.php

view.phpはサイト上に結果を表示されるのに使います。edit.phpにあるように、concrete5 は、特に特別な処理が必要でない限り、自動的に該当のデータベーステーブルからデータを読み込み、変数に値を与えている処理を行っています。

サンプルにあるように、シンプルなブロックであれば、その変数をechoするだけで、データが表示されます。

「オートナビ」ブロックでは、<ul><li>を挟む処理をしているだけです。

 

controllerオプション一覧

シンプルなブロックのほとんどは必要はありませんが、ブロックがより複雑な処理を必要とする場合、concrete5 では、以下の関数をcontroller.phpに定義する事により処理を追加する事が出来ます。

install ()

ブロックのインストール時に自動的に実行されます。デフォルトでは、 db.xml ファイルを読み込み、データベースのテーブルを作成しますが、サーバーに新しいディレクトリーを作成されたり、別のデータベーステーブルにデータを書き込まれたい場合等に使って下さい。

save ($args)

ブロックを追加、編集の保存を実行する際に、関係する配列のキーと一緒に自動的にコールされます。

dupulicate ($newBlockID)

このメソッドは、既存のブロックが、新しいブロックにコールされた時に、既存のブロックのデータを全て新しいブロックに複製する処理を行っています。

concrete5 でよく使われているのは、ページタイプのデフォルトブロックから、ユーザーが、各ページ毎に編集したい時に行われます。

delete ()

これは、ブロックを削除する時に呼ばれます。

重要：オリジナルのコードをcontrollerで作られる方へ

controller.php に新たなfunctionをsave() install()などにマップされたい場合、

parent::メソッド名();

を、新たなfunctionのコードの一番最後で宣言する事を忘れないで下さい。「オートナビ」「記事」ブロック等のcontroller.php を参考にして下さい。

 

この他にも、 concrete5 のデフォルトブロック等を参考に、ブロックを作成されてみて下さい。