独自のレンダラ
導入
独自のレンダラを書くことで、Structures_DataGrid の出力をあらゆる面で改良することができます。
データグリッドの内容を、サポートされていない書式で出力することになったとしましょう。 その場合は独自のレンダラを書かなければなりません。
そうではなく、既存のレンダラをちょっと変化させたものが必要となる場合もあるでしょう。 例えば、独特な形式の HTML などです。この場合は二通りの選択肢があります。 新しいドライバを最初から書き上げるか、あるいは既存のドライバを改造する (サブクラスを作成する) のいずれかです。
このドキュメントでは、レンダリングドライバのインターフェイスとその実装方法を説明します。 独自のレンダラによって Structures_DataGrid がいかに柔軟に拡張できるか、 そしてそれがいかに簡単にできるのかがわかるでしょう。
用語定義
レンダリングドライバ は、 Structures_DataGrid_Renderer クラスを継承したものです。 これは レンダラインターフェイス を実装しています。
レンダラ は、 レンダリングドライバ と同じ意味で使用します。
レンダラインターフェイス には、 ドライバがオーバーロードするメソッド群が含まれます。また、 ドライバが使用できる protected なプロパティや推奨する実装が含まれます。
レンダリングコンテナ はレンダリングエンジンを含むオブジェクトあるいは任意の型 (string, array, object など) の変数で、レンダラ の出力内容が含まれます。
コンテナをサポート している レンダラ のドライバは、指定した レンダリングコンテナ に固有のもので、 そのコンテナを処理する方法を知っています。
ドライバが コンテナをサポート しているとは、 指定された型の レンダリングコンテナ をドライバが処理できるということを意味します。 コンテナをサポート しているドライバは、public メソッド setContainer() および getContainer() を実装していなければなりません。 これらのメソッドは、ユーザが setContainer() で指定した レンダリングコンテナ を使用できなければなりません。 また、ユーザが何も指定しなかった場合には、自分で レンダリングコンテナ を作成して初期化しなければなりません。
ドライバが 出力バッファリング 機能を提供しているとは、 そのドライバが出力内容を溜め込めること、そして flatten() メソッドを実装しており、溜め込んだ内容を flatten() で出力できることを意味します。
ダイレクトレンダリング ドライバは、 最も単純な形式のレンダラです。これはすべての出力を標準出力に直接送ります。 これまでの定義により、このようなドライバは コンテナをサポート しませんし、また 出力バッファリング もサポートしません。
レンダラのインターフェイス
ドライバのプロパティ
これらのプロパティはすべて 読み込み専用 です。 ドライバからその値にアクセスすることはできますが、それを直接変更してはいけません。
array $_options - 共通のオプションおよびドライバ固有のオプション。
array $_columns - カラムのフィールド名およびラベル。
int $_columnsNum - カラム数。
array $_records - レコードの内容。
int $_recordsNum - 現在のページのレコード件数。
int $_totalRecordsNum - データソースから取得した、 レコードの総数。
int $_firstRecord - 現在のページの最初のレコードのレコード番号 (1 から数えます)。
int $_lastRecord - 現在のページの最後のレコードのレコード番号 (1 から数えます)。
int $_page - 現在のページ番号 (1 から数えます)。
int $_pageLimit - 1 ページあたりのレコード件数。
int $_pagesNum - ページの数。
string $_requestPrefix - GET/POST/Cookie パラメータのプレフィックス。
array $_currentSort - 現在並べ替えの基準になっているフィールドと 並べ替えの方向。
array $_sortableFields - データグリッドで並べ替えの対象となるフィールド。
ドライバで実装しなければならない (あるいはすることのできる) メソッド
以下のすべてのメソッドは、必須 ではありません。
constructor (
( void
)
コンストラクタでは、もしデフォルトのオプションがあればそれを _addDefaultOptions() 設定する必要があります。 その後で親クラスのコンストラクタをコールします。
object setContainer (
mixed container
)
setContainer() は、渡されたレンダリングコンテナ container をアタッチします。 失敗した場合には PEAR_Error オブジェクトを返す必要があります。
object getContainer (
( void
)
getContainer() は、ドライバが使用しているコンテナへの参照を返します。 失敗した場合には PEAR_Error オブジェクトを返す必要があります。
void init (
( void
)
init() はレンダリング処理の初期化を行います。 また、コンテナが setContainer()で指定されていない場合は コンテナを作成する必要があります。
void buildHeader (
array columns
)
buildHeader() は見出しを作成します。 $columns は、 $_columns プロパティへの便利な参照です。
ドライバが使用できる protected メソッド群
void _addDefaultOptions (
array options
)
_addDefaultOptions() は、 もしドライバ固有のオプションがある場合に、そのオプションとデフォルト値を指定します。 これはコンストラクタからコールされなければなりません。
void setOptions (
array options
)
setOptions() は、オプションを設定するために使用する public メソッドです。オプションを変更したい場合に、 ドライバはこのメソッドを使用します。
シンプルなドライバ
近日公開予定
ドライバのテスト
近日公開予定
新しいドライバの使用法
近日公開予定
忘却曲線を使ってこの知識を確実に記憶に残す
