「開発:ブロック/付録A」の版間の差分
Mitsuhiro Yoshida (トーク | 投稿記録) |
Mitsuhiro Yoshida (トーク | 投稿記録) (Done :)) |
||
(同じ利用者による、間の93版が非表示) | |||
1行目: | 1行目: | ||
== 付録A: ''block_base'' 参照 == | == 付録A: ''block_base'' 参照 == | ||
この付録では、他のすべてのブロッククラスが導き、渡し、そしてすべてのメソッドが開発者により詳細にオーバーライドすることのできる、ベースクラス'''block_base'''に関して説明します。オーバーライド'''すべきではない''' | この付録では、他のすべてのブロッククラスが導き、渡し、そしてすべてのメソッドが開発者により詳細にオーバーライドすることのできる、ベースクラス'''block_base'''に関して説明します。オーバーライド'''すべきではない'''メソッドに関しては、明確に言及します。この付録を読んだ後、ブロック機能実装に関して、あなたがオーバーライドすべき、またはオーバーライドできる、すべてのメソッドを明確に理解できます。 | ||
メソッドは、3つのカテゴリに分けられます: | メソッドは、3つのカテゴリに分けられます: 「あなたが自由に使用およびオーバーライドできるメソッド」「あなたがオーバーライドすべきではない、しかし使用しても良いメソッド」「あなたが、オーバライドおよび使用してはならないメソッド」です。それぞれのカテゴリでは、メソッドをアルファベット順に表示します。 | ||
== あなたが自由に使用およびオーバーライドできるメソッド: == | == あなたが自由に使用およびオーバーライドできるメソッド: == | ||
74行目: | 72行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、あなたのブロックでグローバル設定画面がどのように表示されるか選択することができます。これは、「設定 ... | このメソッドでは、あなたのブロックでグローバル設定画面がどのように表示されるか選択することができます。これは、「設定 ...」を使った特定のブロックの選択時、管理者に表示される画面です。あなたがデフォルトの実装をさらに複雑にしたい場合、オーバーライドしてください。しかし、以下の点に留意してください: | ||
* あなたが設定オプションを$CFGに保存している場合、あらゆるHTML設定画面をインクルードする前に、恐らく「global $CFG;」を使用する必要があります。 | * あなたが設定オプションを$CFGに保存している場合、あらゆるHTML設定画面をインクルードする前に、恐らく「global $CFG;」を使用する必要があります。 | ||
94行目: | 92行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、あなたのグローバル設定データのストレージメカニズムをオーバーライドすることができます。受け取る変数は、キーにnames、値にvaluesが設定されている連想配列です。デフォルトの実装では、すべてをMoodle $ | このメソッドでは、あなたのグローバル設定データのストレージメカニズムをオーバーライドすることができます。受け取る変数は、キーにnames、値にvaluesが設定されている連想配列です。デフォルトの実装では、すべてをMoodle $CFGの値として保存します。Moodleの処理に、いくつかの隠しフィールドをフォームに追加するため、送信されたPOSTデータすべてを$dataが保持するわけではないことに留意してください。しかし、このメソッドをコールする前、受信されたデータから隠しフィールドが取り除かれます。そのため、このメソッドがコールされた場合、「実」設定データのみが残ります。 | ||
メソッドの成功または失敗を示すため、あなたはブール値を返す必要があります。 | |||
=== get_content() === | === get_content() === | ||
109行目: | 107行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
コールされる場合、このメソッドでは、あなたのブロックの$this-> | コールされる場合、このメソッドでは、あなたのブロックの$this->content変数を投入すべきです。変数の投入は以下を意味します: | ||
''' | '''下記内容'''<br /> | ||
あなたのブロックが'''block_base'''から派生している場合、$this->content->text および $this->content->footer を定義します。両方ともストリングにすべきであり、任意のHTMLを含むことができます。 | あなたのブロックが'''block_base'''から派生している場合、$this->content->text および $this->content->footer を定義します。両方ともストリングにすべきであり、任意のHTMLを含むことができます。 | ||
'''または'''<br /> | '''または'''<br /> | ||
あなたのブロックが'''block_list'''から派生している場合、$this->content->items、$this->content->iconsおよび$this->content->footerを定義します。最初の2つは、正確にエレメントの番号を持った、数字インデックス付きの配列です。 $this->content-> | あなたのブロックが'''block_list'''から派生している場合、$this->content->items、$this->content->iconsおよび$this->content->footerを定義します。最初の2つは、正確にエレメントの番号を持った、数字インデックス付きの配列です。 $this->content->iconsが文字列を含む必要があるのに対して、$this->content->itemsでは任意のHTMLを含むことができます。しかし、この任意のHTMLは、省略なしのHTML <img> タグである必要があります。$this->content->footerは、上記と同じように文字列を含みます。 | ||
<br />'''を意味します。''' | <br />'''を意味します。''' | ||
135行目: | 133行目: | ||
あなたのブロックの設定インターフェースをサイト管理者に提供するかどうか指定するため、このメソッドではブール値を返す必要があります。このインターフェースが提供する設定では、すべてのブロックのインスタンスに等しく影響を及ぼします。 | あなたのブロックの設定インターフェースをサイト管理者に提供するかどうか指定するため、このメソッドではブール値を返す必要があります。このインターフェースが提供する設定では、すべてのブロックのインスタンスに等しく影響を及ぼします。 | ||
実際に設定インターフェースを実装するには、あなたは、[[開発:ブロック/付録A#config_print.28.29|config_print()]]メソッドに頼るか、オーバーライドする必要があります。詳細は、[[開発:ブロック| こちらをご覧ください]]。 | |||
=== hide_header() === | === hide_header() === | ||
161行目: | 159行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、MoodleがアウトプットHTMLを構築する場合、あなたのブロックコンテナ要素に与えられるHTML属性の連想配列を返します。これらの要素に関しては、サニタイズは一切実施されません。 | |||
このメソッドをオーバーライドする場合、あなたが追加する内容と共にデフォルト属性を返す必要があります。推奨される方法は、以下のとおりです: | |||
<code php> | <code php> | ||
185行目: | 183行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドは、すべてのブロックに実装されるべきです。また、意味のある値をオブジェクト変数 (利用可能な場合、Moodleが自動アップグレードを実施するため使用されます) を [[開発:ブロック/付録A#.24this-.3Etitle| $this->title]] および [[開発:ブロック/付録A#.24this-.3Eversion| $this->version]] に割り当てるべきです。 | |||
このメソッドからは、戻り値は必要ではありません。 | |||
=== instance_allow_config() === | === instance_allow_config() === | ||
199行目: | 197行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、ブール値を返す必要があります。falseが設定なしに対して、trueでは、あなたのブロックがインスタンスごとに設定したいことを意味します。インスタンス設定を実装したい場合、このメソッドをオーバーライドするのと別に、あなたはいくつかの追加的な対策を講じる必要があります。さらなる情報は、[[開発:ブロック#設定しよう|こちらをご覧ください]]。 | |||
[[開発:ブロック/付録A#instance_allow_multiple.28.29| instance_allow_multiple]]がtrueを戻す場合、このメソッドの戻り値は適切ではなくなります。あなたが複数インスタンスを設定したい場合、それぞれのインスタンスには独自の設定が必要だと考えられるからです。 | |||
=== instance_allow_multiple() === | === instance_allow_multiple() === | ||
215行目: | 213行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、同一ページでこのブロックの複数インスタンスを許可するかどうか指定するため、ブール値を返す必要があります。あなたが複数インスタンスを許可する場合、ブロックのプレインスタンス設定も同時に提供することになります。従って、あなたが、このメソッドをオーバーライドするのとは別にして、いくつかの追加的なステップが必要となります。詳細は、[[Blocks_Howto#section_configure_that_out|こちらをご覧ください]]。 | |||
=== instance_config_print() === | === instance_config_print() === | ||
242行目: | 240行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、あなたのブロックにインスタンス設定画面を表示する方法を選択できるようにします。あなたがデフォルトの実装をさらに複雑にしたい場合、オーバーライドしてください。あなたが[[Blocks_Howto#method_instance_config_print| config_print]]からどのようにアウトプットしたとしても、HTMLフォームにより囲まれることに留意してください。あなたに必要なことは、フォームの送信方法を手供するのみです。 | |||
あなたのメソッドの正否を示すブール値を返す必要があります。 | |||
=== instance_config_save() === | === instance_config_save() === | ||
259行目: | 257行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、あなたのインスタンス設定データの保存メカニズムをオーバーライドすることができます。受け取ることになる引数は、設定名のキーおよび設定値の値を持った連想配列となります。 | |||
あなたのブロックが構築される場合、Moodleがオートロードできるよう、設定をデータベース内のインスタンスレコードの「configdata」フィールドに保存する必要があります。しかし、あなたがデータの保存以外に、さらに動作を追加したい場合、このメソッドをオーバーライドすることもできます。その場合、あなたが望むデータ処理を実行すべきで、その後、新しい$data配列を使って、parent::instance_config_save($data)をコールしてください。これは、将来的にinstance_config_saveのデフォルトが変更された場合、あなたのブロックが壊れることを防ぎます。 | |||
Moodleが処理できるよう、いくつかの隠しフィールドをフォームに追加するため、送信されたPOSTデータすべてを$dataが保持するわけではないことに留意してください。しかし、このメソッドをコールする前、受信したデータより隠しフィールドを取り除きます。ですから、このメソッドがコールされる場合、「実」設定データのみ残ることになります。 | |||
実行時間に保存された設定データを更新したい場合 (例 あなたが変更したプログラムを保持する)、あなたは、このメソッドを使うべきではありません。この目的に関する正しい処理は、[[開発:ブロック/付録A#instance_config_commit.28.29| instance_config_commit]]をコールすることです。 | |||
あなたのメソッドの正否を示すブール値を返す必要があります。 | |||
=== preferred_width() === | === preferred_width() === | ||
280行目: | 278行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、あなたのブロックが表示される時に取得する幅のピクセル値を整数値として返すべきです。Moodleは、あなたのリクエストを尊重しますが、これは実際のところ、ブロックが表示されるページのフォーマット次第となりますので、保証されるわけではありません。あなたが希望する幅で厳密に表示されることもありますし、フォーマットが決定した幅で表示されることもあります。しかし、明らかに、あなたの希望するブロック幅に適合するよう、努力されます。 | |||
この時点での表示ロジックは、上限および下限に調整しながら、フォーマットを崩さないよう、ブロックからリクエストされた最大幅に割り当てます。 | |||
=== refresh_content() === | === refresh_content() === | ||
296行目: | 294行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、あなたのブロックにそのコンテンツを再計算させます。あなたが、現在のコンテンツの値がNULLでない限り尊重するという[[Blocks_Howto#get_content| get_content]]のガイドラインに従う場合、デフォルトの処理は、素晴らしい仕事を実行します。リフレッシュした後、[[Blocks_Howto#variable_content| $this->content]]の新しい値を返す必要があります。 | |||
=== specialization() === | === specialization() === | ||
309行目: | 306行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
あなたの (ページタイプ、IDおよびすべてのインスタンス設定データを含む) インスタンスデータがデータベースからロードされるとすぐに、このメソッドがフレームワークからコールされます。このデータが利用可能な状態になった直後に実行したい処理があって、すぐには処理を開始できない場合、あなたは、このメソッドをオーバーライドすることができます。 | |||
インスタンスデータは、変数[[Blocks_Howto#variable_instance| $this->instance]]および[[Blocks_Howto#variable_config| $this->config]]で利用可能です。 | |||
このメソッドでは、何も返す必要は全くありません。 | |||
== | == あなたがオーバーライドすべきではない、しかし使用しても良いメソッド: == | ||
328行目: | 325行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドは、[[Blocks_Howto#variable_content_type| $this->content_type]]の値を返します。そして、変数にアクセスする推奨方法は、戻り値を取得することです。また、このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。 | |||
=== get_title() === | === get_title() === | ||
340行目: | 337行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、[[Blocks_Howto#variable_title| $this->title]]の値を返します。また、この値にアクセスするための、推奨方法でもあります。このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。 | |||
=== get_version() === | === get_version() === | ||
351行目: | 348行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、 [[Blocks_Howto#variable_version| $this->version]]の値を返します。また、この値にアクセスするための、推奨方法でもあります。このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。 | |||
=== instance_config_commit() === | === instance_config_commit() === | ||
363行目: | 360行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、[[Blocks_Howto#variable_config| $this->config]]の現在のコンテンツをデータベースに保存します。あなたが実行時に、ブロックインスタンスの設定を変更したい場合 (そして、一般的な手段でユーザに変更させない場合)、[[Blocks_Howto#variable_config| $this->config]]を変更して、このメソッドをコールしてください。 | |||
=== is_empty() === | === is_empty() === | ||
クラス'''block_base'''を拡張するブロック<nowiki>:</nowiki> | |||
<code php> | <code php> | ||
378行目: | 375行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
クラス'''block_list'''を拡張するブロック<nowiki>:</nowiki> | |||
<code php> | <code php> | ||
387行目: | 384行目: | ||
</code> | </code> | ||
このメソッドでは、表示するコンテンツがあるかどうかにより、ブール値 (true/false ) を返します。コンテンツがないブロックは、フレームワークにより表示されることはありません。 | |||
=== name() === | === name() === | ||
404行目: | 401行目: | ||
Moodle 1.5またはそれ以降のバージョンで利用可 | Moodle 1.5またはそれ以降のバージョンで利用可 | ||
このメソッドでは、Moodle内にある、あなたのブロックの内部名を '''block_''' 接頭辞なしで返します。実際のブロック名を使用できない状況でコードを書くときに使用することができるため、ブロックオブジェクト名を取得できることは、時々有用となります (そのため、さらに標準的かつ再利用可能となります)。この技術に関する詳細は、[[Blocks_Howto#method_config_print| config_print]]メソッドをご覧ください。 | |||
== | == あなたが、オーバライドおよび使用してはならないメソッド:: == | ||
=== _add_edit_controls() === | === _add_edit_controls() === | ||
これは、プライベートメソッドです。説明はありません。 | |||
=== _load_instance() === | === _load_instance() === | ||
これは、プライベートメソッドです。説明はありません。 | |||
=== _print_block() === | === _print_block() === | ||
これは、プライベートメソッドです。説明はありません。 | |||
=== _print_shadow() === | === _print_shadow() === | ||
これは、プライベートメソッドです。説明はありません。 | |||
=== _self_test() === | === _self_test() === | ||
これは、プライベートメソッドです。説明はありません。 | |||
また、クラス'''block_base'''には、メソッドをコントロールするため、少数の標準メンバー変数があります。これらの変数、それぞれの目的、保持するデータのタイプは、この付録の次のセクションで説明します。 | |||
== クラス変数: == | == クラス変数: == | ||
429行目: | 426行目: | ||
=== $this->config === | === $this->config === | ||
この変数では、このブロックインスタンス (オブジェクト) 用に提供された、すべての特別インスタンス設定データを保持します。これは、ブロックの<span class="filename">config_instance.html</span>ファイル内のHTML <input> エレメントに直接相当する、メンバ変数を持ったstdClassオブジェクトタイプです。 | |||
ブロックオブジェクトが作成された直後、[[Blocks_Howto#method_specialization| specialization]]が要求される直前に、変数が初期化されます。ブロックにインスタンス設定を持たせないことも可能です。この場合、変数は、NULLになります。 | |||
この値とmdl_block_instanceテーブル内のconfigdataフィールドとは、明らかに直接の関係があります。しかし、あなた自身が「configdata」フィールドにアクセスすることは、「決して」お勧めできません。あなたが、本当にその値を更新する必要がある場合、実際の作業には、[[Blocks_Howto#method_instance_config_commit| instance_config_commit]]メソッドをコールしてください。 | |||
=== $this->content === | === $this->content === | ||
この変数では、それぞれのブロック内に表示される実コンテンツすべてを保持します。有効な値は、NULLまたは下記で説明される特定のメンバー変数を持つオブジェクトクラスstdClassValidのどちかかを使用できます。通常、NULLから始まり、 [[Blocks_Howto#method_get_content| get_content]]がコールされた時点で、完全に構築されます。 | |||
完全に構築された後、このオブジェクトでは、[[Blocks_Howto#variable_content_type| $this->content_type]]の値に応じて、特定のプロパティを持ちます。 | |||
特に: | |||
* | * [[Blocks_Howto#variable_content_type| $this->content_type]]が[[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]]の場合、[[Blocks_Howto#variable_content| $this->content]]は、以下のメンバー変数を持ちます: | ||
# '''text''' | # '''text''' これは、自由な長さおよびコンテンツを持つことのできる文字列です。ブロックのメインエリアに表示され、HTMLを含むことができます。 | ||
# '''footer''' | # '''footer''' これは、自由な長さおよびコンテンツを持つことのできる文字列です。これは、小さなフォントサイズを使用して、テキストの下に表示されます。また、HTMLを含むこともできます。 | ||
* | * [[Blocks_Howto#variable_content_type| $this->content_type]]が[[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]]の場合、[[Blocks_Howto#variable_content| $this->content]]は、以下のメンバー変数を持ちます: | ||
# '''items''' | # '''items''' これは、ブロックエリアに表示されるリスト内アイテムのタイトルを保持する文字列の数値索引配列です。このようなリストは、メニューに似ているため、それぞれのアイテムのタイトルは、省略されていないHTML <a> タグとなります。 | ||
# '''icons''' | # '''icons''' これは、それぞれのリスト内アイテムが表示される前のイメージを示す文字列の数値索引配列です。そのため、アイテムメンバー変数として、エレメントの明確な数を持つべきです。この配列内のそれぞれのアイテムは、省略されていないHTML <img> タグにすべきです。 | ||
# '''footer''' | # '''footer''' これは、自由な長さおよびコンテンツを持つことのできる文字列です。これは、小さなフォントサイズを使用して、テキストの下に表示されます。また、HTMLを含むこともできます。 | ||
=== $this->content_type === | === $this->content_type === | ||
この変数では、どのようなコンテンツがブロックに含まれているか、Moodleに伝えます。そしてまた、リストブロックからテキストブロックを差別化するためにも使用されます。Moodleが画面にブロックを表示する上で、この値に依存するため、意味のある値を持つべきです。そのため、この値は、厳密に変数[[Blocks_Howto#variable_content| $this->content]]と同値となります。それぞれのブロックにおいて、フレームワークが[[Blocks_Howto#method_init| init]]メソッドをコールした後、変数が有効な値を持つ必要があります。 | |||
この変数に対する有効な値は、[[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]]および [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]]という名称を持った2つの定数のみです。 | |||
=== $this->instance === | === $this->instance === | ||
このメンバー変数では、1つのブロックインスタンスを他のブロックインスタンスと区別するため、使用されます (例 ブロックインスタンスを具体化するPHPオブジェクト)。これは、get_recordをコールして、テーブル「mdl_block_instance」で検索される、stdClassタイプのオブジェクトです。そして、メンバー変数は、テーブル「mdl_block_instance」のフィールドに直接合致します。ブロックオブジェクト自身が構築された直後、メンバー変数が初期化されます。 | |||
=== $this->title === | === $this->title === | ||
この変数は、人間に解読可能なブロック名を含む文字列です。これは、そのタイプのブロックをMoodle内で参照する場合に使用されます。例えば、管理者ブロックの設定ページ、および教師の編集モード時のブロック追加メニュー等です。また、必要であれば、ブロックがタイトルを変更することができますが、これは、ブロックが画面に表示される場合のタイトルでもあります (下記参照)。フレームワークが、それぞれのオブジェクトの[[Blocks_Howto#method_init| init]]メソッドをコールした後、この変数は、有効な値を持つ必要があります。 | |||
インスタンス設定を通して、ブロックのタイトルを動的に設定したい場合、[[Blocks_Howto#method_init| init]]内に有効なタイトルを持つことは、まだ必要ではあります。[[Blocks_Howto#method_specialization| specialization]]メソッドがフレームワークよりコールされた場合、このタイトルをオーバーライドすることができます: | |||
<code php> | <code php> | ||
478行目: | 475行目: | ||
</code> | </code> | ||
ブロックタイトルを設定するため、多くのブロックでは、 | |||
<code php> | <code php> | ||
484行目: | 481行目: | ||
</code> | </code> | ||
を使用するようです (そして、さらに特別なタイトルを言語ファイルの中に置きます)。 | |||
適切な言語ストリングがない場合、ブロックタイトルは「blockname」に設定されます。同じ一般名のブロックがある場合、「Naming conflict」というエラーが表示されます。 | |||
不明の言語ストリンクのインストール中のエラーを避けるには、言語ストリングの呼び出し時に、さらに明確なストリング名を使用します ... | |||
<code php> | <code php> | ||
494行目: | 491行目: | ||
</code> | </code> | ||
正しい場所に言語ファイルを置けなかったとしても、このようにして、すべてのブロックが独自のタイトルで管理エリアに表示されます。 | |||
=== $this->version === | === $this->version === | ||
この変数では、Moodleの慣習により、それぞれのブロックのバージョンナンバーを'''YYYYMMDDXX'''の形で持ちます。バージョンナンバーは、ブロックがいつアップグレードされたか認識するため、Moodleによって使用されます。また、その結果として、「古い」バージョンのブロックを最新のブロックにアップグレードするためにも使用されます。フレームワークが、それぞれのオブジェクトの[[Blocks_Howto#method_init| init]]メソッドをコールした後、この変数は、有効な値を持つ必要があります。 | |||
多くのブロックでは、モジュールのように複雑なデータを独自のデータベースに保存することありません。そのため、多くの場合、ブロックのバージョンアップ時、実際には何も起きません。しかし、ブロックの管理インターフェースに、バージョンナンバーが表示されます。そのため、新しい機能を加えたり、重要なバグフィックスを取得する場合、使用しているブロックの実際のバージョンをサイト管理者が容易に認識できるよう、あなたのブロックのバージョンナンバーを変更することは、良い実践となります。 | |||
ブロックAPIに関連するコードが様々なところで出現するため、コード内で「マジックナンバー」の使用を避けることを目的に定義された多くの定数があります。これらの定数は: | |||
== | == 名前付き定数: == | ||
=== BLOCK_TYPE_LIST === | === BLOCK_TYPE_LIST === | ||
これは、すべてのブロックの[[Blocks_Howto#variable_content_type|$this->content_type]]メンバー変数に関する2つの有効値の内の1つです。この値は、Moodleが[[Blocks_Howto#variable_content| $this->content]]で持つことになる必須属性を指定します。 | |||
=== BLOCK_TYPE_TEXT === | === BLOCK_TYPE_TEXT === | ||
これは、すべてのブロックの[[Blocks_Howto#variable_content_type|$this->content_type]]メンバー変数に関する2つの有効値の内の1つです。この値は、Moodleが[[Blocks_Howto#variable_content| $this->content]]で持つことになる必須属性を指定します。 | |||
[[Category: | [[Category:開発者|ブロック]] | ||
[[Category:チュートリアル]] | [[Category:チュートリアル]] | ||
[[en:Development:Blocks/Appendix_A]] | [[en:Development:Blocks/Appendix_A]] |
2009年8月22日 (土) 16:52時点における最新版
付録A: block_base 参照
この付録では、他のすべてのブロッククラスが導き、渡し、そしてすべてのメソッドが開発者により詳細にオーバーライドすることのできる、ベースクラスblock_baseに関して説明します。オーバーライドすべきではないメソッドに関しては、明確に言及します。この付録を読んだ後、ブロック機能実装に関して、あなたがオーバーライドすべき、またはオーバーライドできる、すべてのメソッドを明確に理解できます。
メソッドは、3つのカテゴリに分けられます: 「あなたが自由に使用およびオーバーライドできるメソッド」「あなたがオーバーライドすべきではない、しかし使用しても良いメソッド」「あなたが、オーバライドおよび使用してはならないメソッド」です。それぞれのカテゴリでは、メソッドをアルファベット順に表示します。
あなたが自由に使用およびオーバーライドできるメソッド:
after_install()
function after_install() {
}
Moodle 1.7またはそれ以降のバージョンで利用可
このメソッドは、ブロックサブクラスからオーバーライドされるため、またブロックのインストール後、あなたが特定のタスクを指定できるよう、デザインされました。例えば、ブロックのインストール後、あなたはデータを保存したいと考えるでしょう。しかしながら、それぞれのデータベースタイプは、現在の日付を取得する独自の方法を持っています。また、あなたのブロックインストール時、XMLDBを使用しますが、これらの処理も同様にサポートされていません。データベースアブストラクションのメンテナンス時、そのようなタスクを完了するためのベストな方法は、ブロックインストールにXMLDBを使用した後、ブロック使用前のデータ挿入にafter_install() メソッドを使用することです。
after_install() は、ブロックごとに1回のみコールされ、インスタンスごとにコールされるわけではないことに留意してください。
applicable_formats()
function applicable_formats() {
// デフォルトのケース: ブロックはコースおよびサイトインデックスで使用できますが、活動では使用できません。
return array('all' => true, 'mod' => false);
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、どのページにブロックを追加することができるか、あなたがコントロールできます。ページフォーマットは、そのページを表示されるために使用されるスクリプトのフルパスにより構成されます。あなたは、ページフォーマット名およびブール値 (trueまたはfalse) のキーを含む配列を戻す必要があります。あなたのブロックは、値が「true」の場合のみ、それらのフォーマットで表示することができます。 フォーマット名のサンプルは次のとおりです: course-view、site-index (これは例外です。Moodleサイトのフロントページを参照します)、course-format-weeks (特定のコースフォーマットを参照します)、mod-quiz (小テストモジュールを参照します)、all (あなたが明確に許可または許可しない場合に使用されます)。
完全に合致するルールは、以下のとおりです:
- フォーマット名の接頭辞は、フォーマット名と合致します。例えば、modは、すべての活動モジュールに合致します。コースフォーマットにかかわらず、course-viewは、あらゆるコースに合致します。最後に、siteもまた、フロントページに合致します (siteのフルフォーマット名がsite-indexであることを思い出してください)。
- フォーマット名が私たちのページに合致するよう特化されるほど、ブロックが許可された場合の優先度が高くなります。例えば、mod、mod-quizおよびmod-quiz-viewすべてが小テストを表示するページ (quiz view page) に合致します。しかし、3つすべてが存在する場合、合致する度合いが高いため、他の2つにくらべて、mod-quiz-viewの優先度が上がります。
- *文字は、すべての言葉の代わりに使用することができます。例えば、modおよびmod-*は、同じです。このドキュメントを執筆している時点では、この「ワイルドカード合致」機能を利用する実際の理由はありませんが、将来的な利用のため存在していると思われます。
- フォーマット名が表示される順番には、違いはありません。
before_delete()
function before_delete() {
}
Moodle 1.7またはそれ以降のバージョンで利用可
このメソッドは、管理者がMoodleからブロックを削除した時点でコールされます。また、直前に関連するデータベーステーブルも削除されます。ブロックの作者は、一時ファイルの削除等、ブロックが削除される前に、必要なクリーンアップを実施することができます。
config_print()
function config_print() {
// Default behavior: print the config_global.html file
// You don't need to override this if you're satisfied with the above
if (!$this->has_config()) {
return FALSE;
}
global $CFG, $THEME;
print_simple_box_start('center', , $THEME->cellheading);
include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
print_simple_box_end();
return TRUE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのブロックでグローバル設定画面がどのように表示されるか選択することができます。これは、「設定 ...」を使った特定のブロックの選択時、管理者に表示される画面です。あなたがデフォルトの実装をさらに複雑にしたい場合、オーバーライドしてください。しかし、以下の点に留意してください:
- あなたが設定オプションを$CFGに保存している場合、あらゆるHTML設定画面をインクルードする前に、恐らく「global $CFG;」を使用する必要があります。
- あなたのメソッドのアウトプットに含まれているHTML<input>要素は、自動的に<form>エレメントで囲まれます。あなたは、どこで、どのようにformが送信されるか心配する必要はありません。しかし、あなたは送信する方法を提供しなければなりません (例 <input type="submit" />)。メソッドの動作の成功または失敗を示すため、あなたはブール値を返す必要があります。
config_save()
function config_save($data) {
// Default behaviour: save all variables as $CFG properties
// You don't need to override this if you 're satisfied with the above
foreach ($data as $name => $value) {
set_config($name, $value);
}
return TRUE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのグローバル設定データのストレージメカニズムをオーバーライドすることができます。受け取る変数は、キーにnames、値にvaluesが設定されている連想配列です。デフォルトの実装では、すべてをMoodle $CFGの値として保存します。Moodleの処理に、いくつかの隠しフィールドをフォームに追加するため、送信されたPOSTデータすべてを$dataが保持するわけではないことに留意してください。しかし、このメソッドをコールする前、受信されたデータから隠しフィールドが取り除かれます。そのため、このメソッドがコールされた場合、「実」設定データのみが残ります。
メソッドの成功または失敗を示すため、あなたはブール値を返す必要があります。
get_content()
function get_content() {
// This should be implemented by the derived class.
return NULL;
}
Moodle 1.5またはそれ以降のバージョンで利用可
コールされる場合、このメソッドでは、あなたのブロックの$this->content変数を投入すべきです。変数の投入は以下を意味します:
下記内容
あなたのブロックがblock_baseから派生している場合、$this->content->text および $this->content->footer を定義します。両方ともストリングにすべきであり、任意のHTMLを含むことができます。
または
あなたのブロックがblock_listから派生している場合、$this->content->items、$this->content->iconsおよび$this->content->footerを定義します。最初の2つは、正確にエレメントの番号を持った、数字インデックス付きの配列です。 $this->content->iconsが文字列を含む必要があるのに対して、$this->content->itemsでは任意のHTMLを含むことができます。しかし、この任意のHTMLは、省略なしのHTML <img> タグである必要があります。$this->content->footerは、上記と同じように文字列を含みます。
を意味します。
あなたがこれらすべての変数を「空」の値に (配列には空の配列を、文字列には空の文字列を) 設定した場合、編集中のユーザを除いて、ブロックは全く表示されなくなります。これは、表示する理由のないブロックを表示して、画面を混乱させることを防ぐため、あなたのブロックを隠すための手っ取り早い方法だと言えます。
$this->contentを実装する前、あなたはシンプルなキャッシングのチェックをする必要があります。$this->contentがNULLではない場合、もう一度計算する代わりに既存の値を返すのに対して、厳密にNULLの場合、正常終了として前に進みます。あなたがこれを実施しない場合、Moodleには、余分に負荷が掛かることになります。
どのような場合でも、あなたのメソッドは、完全に構成された$this->content変数を返す必要があります。
has_config()
function has_config() {
return FALSE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
あなたのブロックの設定インターフェースをサイト管理者に提供するかどうか指定するため、このメソッドではブール値を返す必要があります。このインターフェースが提供する設定では、すべてのブロックのインスタンスに等しく影響を及ぼします。 実際に設定インターフェースを実装するには、あなたは、config_print()メソッドに頼るか、オーバーライドする必要があります。詳細は、 こちらをご覧ください。
hide_header()
function hide_header() {
//Default, false--> the header is shown
return FALSE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのブロックがヘッダ (またはタイトル) を隠すかどうか示すため、ブール値を返します。従って、「true」を返すようオーバーライドした場合、ユーザが編集モードに入っている以外、あなたのブロックはタイトルを表示しないようになります。
html_attributes()
function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、MoodleがアウトプットHTMLを構築する場合、あなたのブロックコンテナ要素に与えられるHTML属性の連想配列を返します。これらの要素に関しては、サニタイズは一切実施されません。
このメソッドをオーバーライドする場合、あなたが追加する内容と共にデフォルト属性を返す必要があります。推奨される方法は、以下のとおりです:
function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
init()
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドは、すべてのブロックに実装されるべきです。また、意味のある値をオブジェクト変数 (利用可能な場合、Moodleが自動アップグレードを実施するため使用されます) を $this->title および $this->version に割り当てるべきです。
このメソッドからは、戻り値は必要ではありません。
instance_allow_config()
function instance_allow_config() {
return FALSE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、ブール値を返す必要があります。falseが設定なしに対して、trueでは、あなたのブロックがインスタンスごとに設定したいことを意味します。インスタンス設定を実装したい場合、このメソッドをオーバーライドするのと別に、あなたはいくつかの追加的な対策を講じる必要があります。さらなる情報は、こちらをご覧ください。
instance_allow_multipleがtrueを戻す場合、このメソッドの戻り値は適切ではなくなります。あなたが複数インスタンスを設定したい場合、それぞれのインスタンスには独自の設定が必要だと考えられるからです。
instance_allow_multiple()
function instance_allow_multiple() {
// Are you going to allow multiple instances of each block?
// If yes, then it is assumed that the block WILL USE per-instance configuration
return FALSE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、同一ページでこのブロックの複数インスタンスを許可するかどうか指定するため、ブール値を返す必要があります。あなたが複数インスタンスを許可する場合、ブロックのプレインスタンス設定も同時に提供することになります。従って、あなたが、このメソッドをオーバーライドするのとは別にして、いくつかの追加的なステップが必要となります。詳細は、こちらをご覧ください。
instance_config_print()
function instance_config_print() {
// Default behavior: print the config_instance.html file
// You don't need to override this if you're satisfied with the above
if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
return FALSE;
}
global $CFG, $THEME;
if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
print_simple_box_start('center', , $THEME->cellheading);
include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
print_simple_box_end();
} else {
notice(get_string('blockconfigbad'),
str_replace('blockaction=', 'dummy=', qualified_me()));
}
return TRUE;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのブロックにインスタンス設定画面を表示する方法を選択できるようにします。あなたがデフォルトの実装をさらに複雑にしたい場合、オーバーライドしてください。あなたが config_printからどのようにアウトプットしたとしても、HTMLフォームにより囲まれることに留意してください。あなたに必要なことは、フォームの送信方法を手供するのみです。
あなたのメソッドの正否を示すブール値を返す必要があります。
instance_config_save()
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのインスタンス設定データの保存メカニズムをオーバーライドすることができます。受け取ることになる引数は、設定名のキーおよび設定値の値を持った連想配列となります。
あなたのブロックが構築される場合、Moodleがオートロードできるよう、設定をデータベース内のインスタンスレコードの「configdata」フィールドに保存する必要があります。しかし、あなたがデータの保存以外に、さらに動作を追加したい場合、このメソッドをオーバーライドすることもできます。その場合、あなたが望むデータ処理を実行すべきで、その後、新しい$data配列を使って、parent::instance_config_save($data)をコールしてください。これは、将来的にinstance_config_saveのデフォルトが変更された場合、あなたのブロックが壊れることを防ぎます。
Moodleが処理できるよう、いくつかの隠しフィールドをフォームに追加するため、送信されたPOSTデータすべてを$dataが保持するわけではないことに留意してください。しかし、このメソッドをコールする前、受信したデータより隠しフィールドを取り除きます。ですから、このメソッドがコールされる場合、「実」設定データのみ残ることになります。
実行時間に保存された設定データを更新したい場合 (例 あなたが変更したプログラムを保持する)、あなたは、このメソッドを使うべきではありません。この目的に関する正しい処理は、 instance_config_commitをコールすることです。
あなたのメソッドの正否を示すブール値を返す必要があります。
preferred_width()
function preferred_width() {
// Default case: the block wants to be 180 pixels wide
return 180;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのブロックが表示される時に取得する幅のピクセル値を整数値として返すべきです。Moodleは、あなたのリクエストを尊重しますが、これは実際のところ、ブロックが表示されるページのフォーマット次第となりますので、保証されるわけではありません。あなたが希望する幅で厳密に表示されることもありますし、フォーマットが決定した幅で表示されることもあります。しかし、明らかに、あなたの希望するブロック幅に適合するよう、努力されます。
この時点での表示ロジックは、上限および下限に調整しながら、フォーマットを崩さないよう、ブロックからリクエストされた最大幅に割り当てます。
refresh_content()
function refresh_content() {
// Nothing special here, depends on content()
$this->content = NULL;
return $this->get_content();
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、あなたのブロックにそのコンテンツを再計算させます。あなたが、現在のコンテンツの値がNULLでない限り尊重するという get_contentのガイドラインに従う場合、デフォルトの処理は、素晴らしい仕事を実行します。リフレッシュした後、 $this->contentの新しい値を返す必要があります。
specialization()
function specialization() {
// Just to make sure that this method exists.
}
Moodle 1.5またはそれ以降のバージョンで利用可
あなたの (ページタイプ、IDおよびすべてのインスタンス設定データを含む) インスタンスデータがデータベースからロードされるとすぐに、このメソッドがフレームワークからコールされます。このデータが利用可能な状態になった直後に実行したい処理があって、すぐには処理を開始できない場合、あなたは、このメソッドをオーバーライドすることができます。
インスタンスデータは、変数 $this->instanceおよび $this->configで利用可能です。
このメソッドでは、何も返す必要は全くありません。
あなたがオーバーライドすべきではない、しかし使用しても良いメソッド:
get_content_type()
function get_content_type() {
return $this->content_type;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドは、 $this->content_typeの値を返します。そして、変数にアクセスする推奨方法は、戻り値を取得することです。また、このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。
get_title()
function get_title() {
return $this->title;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、 $this->titleの値を返します。また、この値にアクセスするための、推奨方法でもあります。このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。
get_version()
function get_version() {
return $this->version;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、 $this->versionの値を返します。また、この値にアクセスするための、推奨方法でもあります。このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。
instance_config_commit()
function instance_config_commit() {
return set_field('block_instance','configdata', base64_encode(serialize($this->config)), 'id', $this->instance->id);
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、 $this->configの現在のコンテンツをデータベースに保存します。あなたが実行時に、ブロックインスタンスの設定を変更したい場合 (そして、一般的な手段でユーザに変更させない場合)、 $this->configを変更して、このメソッドをコールしてください。
is_empty()
クラスblock_baseを拡張するブロック:
function is_empty() {
$this->get_content();
return(empty($this->content->text) && empty($this->content->footer));
}
Moodle 1.5またはそれ以降のバージョンで利用可
クラスblock_listを拡張するブロック:
function is_empty() {
$this->get_content();
return (empty($this->content->items) && empty($this->content->footer));
}
このメソッドでは、表示するコンテンツがあるかどうかにより、ブール値 (true/false ) を返します。コンテンツがないブロックは、フレームワークにより表示されることはありません。
name()
function name() {
static $myname;
if ($myname === NULL) {
$myname = strtolower(get_class($this));
$myname = substr($myname, strpos($myname, '_') + 1);
}
return $myname;
}
Moodle 1.5またはそれ以降のバージョンで利用可
このメソッドでは、Moodle内にある、あなたのブロックの内部名を block_ 接頭辞なしで返します。実際のブロック名を使用できない状況でコードを書くときに使用することができるため、ブロックオブジェクト名を取得できることは、時々有用となります (そのため、さらに標準的かつ再利用可能となります)。この技術に関する詳細は、 config_printメソッドをご覧ください。
あなたが、オーバライドおよび使用してはならないメソッド::
_add_edit_controls()
これは、プライベートメソッドです。説明はありません。
_load_instance()
これは、プライベートメソッドです。説明はありません。
_print_block()
これは、プライベートメソッドです。説明はありません。
_print_shadow()
これは、プライベートメソッドです。説明はありません。
_self_test()
これは、プライベートメソッドです。説明はありません。
また、クラスblock_baseには、メソッドをコントロールするため、少数の標準メンバー変数があります。これらの変数、それぞれの目的、保持するデータのタイプは、この付録の次のセクションで説明します。
クラス変数:
$this->config
この変数では、このブロックインスタンス (オブジェクト) 用に提供された、すべての特別インスタンス設定データを保持します。これは、ブロックのconfig_instance.htmlファイル内のHTML <input> エレメントに直接相当する、メンバ変数を持ったstdClassオブジェクトタイプです。
ブロックオブジェクトが作成された直後、 specializationが要求される直前に、変数が初期化されます。ブロックにインスタンス設定を持たせないことも可能です。この場合、変数は、NULLになります。
この値とmdl_block_instanceテーブル内のconfigdataフィールドとは、明らかに直接の関係があります。しかし、あなた自身が「configdata」フィールドにアクセスすることは、「決して」お勧めできません。あなたが、本当にその値を更新する必要がある場合、実際の作業には、 instance_config_commitメソッドをコールしてください。
$this->content
この変数では、それぞれのブロック内に表示される実コンテンツすべてを保持します。有効な値は、NULLまたは下記で説明される特定のメンバー変数を持つオブジェクトクラスstdClassValidのどちかかを使用できます。通常、NULLから始まり、 get_contentがコールされた時点で、完全に構築されます。
完全に構築された後、このオブジェクトでは、 $this->content_typeの値に応じて、特定のプロパティを持ちます。
特に:
- $this->content_typeが BLOCK_TYPE_TEXTの場合、 $this->contentは、以下のメンバー変数を持ちます:
- text これは、自由な長さおよびコンテンツを持つことのできる文字列です。ブロックのメインエリアに表示され、HTMLを含むことができます。
- footer これは、自由な長さおよびコンテンツを持つことのできる文字列です。これは、小さなフォントサイズを使用して、テキストの下に表示されます。また、HTMLを含むこともできます。
- $this->content_typeが BLOCK_TYPE_LISTの場合、 $this->contentは、以下のメンバー変数を持ちます:
- items これは、ブロックエリアに表示されるリスト内アイテムのタイトルを保持する文字列の数値索引配列です。このようなリストは、メニューに似ているため、それぞれのアイテムのタイトルは、省略されていないHTML <a> タグとなります。
- icons これは、それぞれのリスト内アイテムが表示される前のイメージを示す文字列の数値索引配列です。そのため、アイテムメンバー変数として、エレメントの明確な数を持つべきです。この配列内のそれぞれのアイテムは、省略されていないHTML <img> タグにすべきです。
- footer これは、自由な長さおよびコンテンツを持つことのできる文字列です。これは、小さなフォントサイズを使用して、テキストの下に表示されます。また、HTMLを含むこともできます。
$this->content_type
この変数では、どのようなコンテンツがブロックに含まれているか、Moodleに伝えます。そしてまた、リストブロックからテキストブロックを差別化するためにも使用されます。Moodleが画面にブロックを表示する上で、この値に依存するため、意味のある値を持つべきです。そのため、この値は、厳密に変数 $this->contentと同値となります。それぞれのブロックにおいて、フレームワークが initメソッドをコールした後、変数が有効な値を持つ必要があります。
この変数に対する有効な値は、 BLOCK_TYPE_TEXTおよび BLOCK_TYPE_LISTという名称を持った2つの定数のみです。
$this->instance
このメンバー変数では、1つのブロックインスタンスを他のブロックインスタンスと区別するため、使用されます (例 ブロックインスタンスを具体化するPHPオブジェクト)。これは、get_recordをコールして、テーブル「mdl_block_instance」で検索される、stdClassタイプのオブジェクトです。そして、メンバー変数は、テーブル「mdl_block_instance」のフィールドに直接合致します。ブロックオブジェクト自身が構築された直後、メンバー変数が初期化されます。
$this->title
この変数は、人間に解読可能なブロック名を含む文字列です。これは、そのタイプのブロックをMoodle内で参照する場合に使用されます。例えば、管理者ブロックの設定ページ、および教師の編集モード時のブロック追加メニュー等です。また、必要であれば、ブロックがタイトルを変更することができますが、これは、ブロックが画面に表示される場合のタイトルでもあります (下記参照)。フレームワークが、それぞれのオブジェクトの initメソッドをコールした後、この変数は、有効な値を持つ必要があります。
インスタンス設定を通して、ブロックのタイトルを動的に設定したい場合、 init内に有効なタイトルを持つことは、まだ必要ではあります。 specializationメソッドがフレームワークよりコールされた場合、このタイトルをオーバーライドすることができます:
function specialization() {
// At this point, $this->instance and $this->config are available
// for use. We can now change the title to whatever we want.
$this->title = $this->config->variable_holding_the_title;
}
ブロックタイトルを設定するため、多くのブロックでは、
$this->title = get_string('blockname', ... );
を使用するようです (そして、さらに特別なタイトルを言語ファイルの中に置きます)。
適切な言語ストリングがない場合、ブロックタイトルは「blockname」に設定されます。同じ一般名のブロックがある場合、「Naming conflict」というエラーが表示されます。
不明の言語ストリンクのインストール中のエラーを避けるには、言語ストリングの呼び出し時に、さらに明確なストリング名を使用します ...
$this->title = get_string('simplehtml', ... );
正しい場所に言語ファイルを置けなかったとしても、このようにして、すべてのブロックが独自のタイトルで管理エリアに表示されます。
$this->version
この変数では、Moodleの慣習により、それぞれのブロックのバージョンナンバーをYYYYMMDDXXの形で持ちます。バージョンナンバーは、ブロックがいつアップグレードされたか認識するため、Moodleによって使用されます。また、その結果として、「古い」バージョンのブロックを最新のブロックにアップグレードするためにも使用されます。フレームワークが、それぞれのオブジェクトの initメソッドをコールした後、この変数は、有効な値を持つ必要があります。
多くのブロックでは、モジュールのように複雑なデータを独自のデータベースに保存することありません。そのため、多くの場合、ブロックのバージョンアップ時、実際には何も起きません。しかし、ブロックの管理インターフェースに、バージョンナンバーが表示されます。そのため、新しい機能を加えたり、重要なバグフィックスを取得する場合、使用しているブロックの実際のバージョンをサイト管理者が容易に認識できるよう、あなたのブロックのバージョンナンバーを変更することは、良い実践となります。
ブロックAPIに関連するコードが様々なところで出現するため、コード内で「マジックナンバー」の使用を避けることを目的に定義された多くの定数があります。これらの定数は:
名前付き定数:
BLOCK_TYPE_LIST
これは、すべてのブロックの$this->content_typeメンバー変数に関する2つの有効値の内の1つです。この値は、Moodleが $this->contentで持つことになる必須属性を指定します。
BLOCK_TYPE_TEXT
これは、すべてのブロックの$this->content_typeメンバー変数に関する2つの有効値の内の1つです。この値は、Moodleが $this->contentで持つことになる必須属性を指定します。