「開発:ブロック/付録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で持つことになる必須属性を指定します。

@@ 1行目: / 1行目: @@
-作成中です - [[利用者:Mitsuhiro Yoshida|Mitsuhiro Yoshida]] 2009年5月26日 (火) 15:50 (UTC)
 == 付録A: ''block_base'' 参照 ==
-この付録では、他のすべてのブロッククラスが導き、渡し、そしてすべてのメソッドが開発者により詳細にオーバーライドすることのできる、ベースクラス'''block_base'''に関して説明します。オーバーライド'''すべきではない'''メソッドに関しては、明確に言及します。この別表を読んだ後、ブロック機能実装に関して、あなたがオーバーライドすべき、またはオーバーライドできる、すべてのメソッドを明確に理解できます。
+この付録では、他のすべてのブロッククラスが導き、渡し、そしてすべてのメソッドが開発者により詳細にオーバーライドすることのできる、ベースクラス'''block_base'''に関して説明します。オーバーライド'''すべきではない'''メソッドに関しては、明確に言及します。この付録を読んだ後、ブロック機能実装に関して、あなたがオーバーライドすべき、またはオーバーライドできる、すべてのメソッドを明確に理解できます。
-メソッドは、3つのカテゴリに分けられます: 「あなたのブロックで使用およびオーバーライドするメソッド」、「あなたにはオーバーライドできませんが、使用したいメソッド」、「使用およびオーバーライドできない内部メソッド」です。それぞれのカテゴリでは、メソッドをアルファベット順に表示します。
+メソッドは、3つのカテゴリに分けられます: 「あなたが自由に使用およびオーバーライドできるメソッド」「あなたがオーバーライドすべきではない、しかし使用しても良いメソッド」「あなたが、オーバライドおよび使用してはならないメソッド」です。それぞれのカテゴリでは、メソッドをアルファベット順に表示します。
 == あなたが自由に使用およびオーバーライドできるメソッド: ==
@@ 31行目: / 29行目: @@
 </code>
-Moodle 1.5またはそれ移行のバージョンで利用可
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method allows you to control which pages your block can be added to. Page formats are formulated from the full path of the script that is used to display that page. You should return an array with the keys being page format names and the values being booleans (true or false). Your block is only allowed to appear in those formats where the value is true.
+このメソッドでは、どのページにブロックを追加することができるか、あなたがコントロールできます。ページフォーマットは、そのページを表示されるために使用されるスクリプトのフルパスにより構成されます。あなたは、ページフォーマット名およびブール値 (trueまたはfalse) のキーを含む配列を戻す必要があります。あなたのブロックは、値が「true」の場合のみ、それらのフォーマットで表示することができます。
-Example format names are: '''course-view''', '''site-index''' (this is an exception, referring front page of the Moodle site), '''course-format-weeks''' (referring to a specific course format), '''mod-quiz''' (referring to the quiz module) and '''all''' (this will be used for those formats you have not explicitly allowed or disallowed).
+フォーマット名のサンプルは次のとおりです: '''course-view'''、'''site-index''' (これは例外です。Moodleサイトのフロントページを参照します)、'''course-format-weeks''' (特定のコースフォーマットを参照します)、'''mod-quiz''' (小テストモジュールを参照します)、'''all''' (あなたが明確に許可または許可しない場合に使用されます)。
-The full matching rules are:
+完全に合致するルールは、以下のとおりです:
-# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
+# フォーマット名の接頭辞は、フォーマット名と合致します。例えば、'''mod'''は、すべての活動モジュールに合致します。コースフォーマットにかかわらず、'''course-view'''は、あらゆるコースに合致します。最後に、'''site'''もまた、フロントページに合致します ('''site'''のフルフォーマット名が'''site-index'''であることを思い出してください)。
-# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
+# フォーマット名が私たちのページに合致するよう特化されるほど、ブロックが許可された場合の優先度が高くなります。例えば、'''mod'''、'''mod-quiz'''および'''mod-quiz-view'''すべてが小テストを表示するページ (quiz view page) に合致します。しかし、3つすべてが存在する場合、合致する度合いが高いため、他の2つにくらべて、'''mod-quiz-view'''の優先度が上がります。
-# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
+# '''<nowiki>*</nowiki>'''文字は、すべての言葉の代わりに使用することができます。例えば、'''mod'''および'''mod-*'''は、同じです。このドキュメントを執筆している時点では、この「ワイルドカード合致」機能を利用する実際の理由はありませんが、将来的な利用のため存在していると思われます。
-# The order that the format names appear does not make any difference.
+# フォーマット名が表示される順番には、違いはありません。
 === before_delete() ===
@@ 50行目: / 48行目: @@
 </code>
-Available in Moodle 1.7 and later
+Moodle 1.7またはそれ以降のバージョンで利用可
-This method is called when an administrator removes a block from the Moodle installation, immediately before the relevant database tables are deleted.  It allows block authors to perform any necessary cleanup - removing temporary files and so on - before the block is deleted.
+このメソッドは、管理者がMoodleからブロックを削除した時点でコールされます。また、直前に関連するデータベーステーブルも削除されます。ブロックの作者は、一時ファイルの削除等、ブロックが削除される前に、必要なクリーンアップを実施することができます。
 === config_print() ===
@@ 72行目: / 70行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method allows you to choose how to display the global configuration screen for your block. This is the screen that the administrator is presented with when he chooses "Settings..." for a specific block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:
+このメソッドでは、あなたのブロックでグローバル設定画面がどのように表示されるか選択することができます。これは、「設定 ...」を使った特定のブロックの選択時、管理者に表示される画面です。あなたがデフォルトの実装をさらに複雑にしたい場合、オーバーライドしてください。しかし、以下の点に留意してください:
-* If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
+* あなたが設定オプションを$CFGに保存している場合、あらゆるHTML設定画面をインクルードする前に、恐らく「global $CFG;」を使用する必要があります。
-* The HTML <input> elements that you include in your method's output will be automatically enclosed in a <form> element. You do not need to worry about where and how that form is submitted; however, you '''must''' provide a way to submit it (i.e., an <input type="submit" />.
+* あなたのメソッドのアウトプットに含まれているHTML<input>要素は、自動的に<form>エレメントで囲まれます。あなたは、どこで、どのようにformが送信されるか心配する必要はありません。しかし、あなたは送信する方法を'''提供しなければなりません''' (例 <input type="submit" />)。メソッドの動作の成功または失敗を示すため、あなたはブール値を返す必要があります。
-You should return a boolean value denoting the success or failure of your method's actions.
 === config_save() ===
@@ 93行目: / 90行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method allows you to override the storage mechanism for your global configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values. The default implementation saves everything as Moodle $CFG variables.
+このメソッドでは、あなたのグローバル設定データのストレージメカニズムをオーバーライドすることができます。受け取る変数は、キーにnames、値にvaluesが設定されている連想配列です。デフォルトの実装では、すべてをMoodle $CFGの値として保存します。Moodleの処理に、いくつかの隠しフィールドをフォームに追加するため、送信されたPOSTデータすべてを$dataが保持するわけではないことに留意してください。しかし、このメソッドをコールする前、受信されたデータから隠しフィールドが取り除かれます。そのため、このメソッドがコールされた場合、「実」設定データのみが残ります。
-Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
-You should return a boolean value denoting the success or failure of your method's actions.
+メソッドの成功または失敗を示すため、あなたはブール値を返す必要があります。
 === get_content() ===
@@ 109行目: / 105行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should, when called, populate the [[Blocks_Howto#variable_content| $this->content]] variable of your block. Populating the variable means:
+コールされる場合、このメソッドでは、あなたのブロックの$this->content変数を投入すべきです。変数の投入は以下を意味します:
-'''EITHER'''<br />
+'''下記内容'''<br />
-defining $this->content->text and $this->content->footer if your block derives from '''block_base'''. Both of these should be strings, and can contain arbitrary HTML.
+あなたのブロックが'''block_base'''から派生している場合、$this->content->text および $this->content->footer を定義します。両方ともストリングにすべきであり、任意のHTMLを含むことができます。
-'''OR'''<br />
+'''または'''<br />
-defining $this->content->items, $this->content->icons and $this->content->footer if your block derives from '''block_list'''. The first two should be numerically indexed arrays having the exact same number of elements. $this->content->items is an array of strings that can contain arbitrary HTML while $this->content->icons also contains should strings, but those must be fully-qualified HTML <img> tags '''and nothing else'''. $this->content->footer is a string, as above.
+あなたのブロックが'''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 />'''を意味します。'''
-If you set ''all'' of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will '''not''' be displayed at all except to editing users. This is a good way of having your block hide itself to unclutter the screen if there is no reason to have it displayed.
+あなたがこれらすべての変数を「空」の値に (配列には空の配列を、文字列には空の文字列を) 設定した場合、編集中のユーザを除いて、ブロックは全く表示されなくなります。これは、表示する理由のないブロックを表示して、画面を混乱させることを防ぐため、あなたのブロックを隠すための手っ取り早い方法だと言えます。
-Before starting to populate [[Blocks_Howto#variable_content| $this->content]], you should also include a simple caching check. If [[Blocks_Howto#variable_content| $this->content]] is exactly equal to NULL then proceed as normally, while if it is not, return the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.
+[[開発:ブロック/付録A#.24this-.3Econfig|$this->content]]を実装する前、あなたはシンプルなキャッシングのチェックをする必要があります。[[開発:ブロック/付録A#.24this-.3Econfig|$this->content]]がNULLではない場合、もう一度計算する代わりに既存の値を返すのに対して、厳密にNULLの場合、正常終了として前に進みます。あなたがこれを実施しない場合、Moodleには、余分に負荷が掛かることになります。
-In any case, your method should return the fully constructed [[Blocks_Howto#variable_content| $this->content]] variable.
+どのような場合でも、あなたのメソッドは、完全に構成された[[開発:ブロック/付録A#.24this-.3Econfig|$this->content]]変数を返す必要があります。
 === has_config() ===
@@ 133行目: / 130行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should return a boolean value that denotes whether your block wants to present a configuration interface to site admins or not. The configuration that this interface offers will impact all instances of the block equally.
+あなたのブロックの設定インターフェースをサイト管理者に提供するかどうか指定するため、このメソッドではブール値を返す必要があります。このインターフェースが提供する設定では、すべてのブロックのインスタンスに等しく影響を及ぼします。
-To actually implement the configuration interface, you will either need to rely on the default [[Blocks_Howto#method_instance_config_print| config_print]] method or override it. The full guide contains [[Blocks_Howto#section_effects_of_globalization| more information on this]].
+実際に設定インターフェースを実装するには、あなたは、[[開発:ブロック/付録A#config_print.28.29|config_print()]]メソッドに頼るか、オーバーライドする必要があります。詳細は、[[開発:ブロック| こちらをご覧ください]]。
 === hide_header() ===
@@ 147行目: / 144行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should return a boolean value that denotes whether your block wants to hide its header (or title). Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.
+このメソッドでは、あなたのブロックがヘッダ (またはタイトル) を隠すかどうか示すため、ブール値を返します。従って、「true」を返すようオーバーライドした場合、ユーザが編集モードに入っている以外、あなたのブロックはタイトルを表示しないようになります。
 === html_attributes() ===
@@ 160行目: / 157行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.
+このメソッドでは、MoodleがアウトプットHTMLを構築する場合、あなたのブロックコンテナ要素に与えられるHTML属性の連想配列を返します。これらの要素に関しては、サニタイズは一切実施されません。
-If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:
+このメソッドをオーバーライドする場合、あなたが追加する内容と共にデフォルト属性を返す必要があります。推奨される方法は、以下のとおりです:
 <code php>
@@ 184行目: / 181行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method must be implemented for all blocks. It has to assign meaningful values to the object variables [[Blocks_Howto#variable_title| $this->title]] and [[Blocks_Howto#variable_version| $this->version]] (which is used by Moodle for performing automatic updates when available).
+このメソッドは、すべてのブロックに実装されるべきです。また、意味のある値をオブジェクト変数 (利用可能な場合、Moodleが自動アップグレードを実施するため使用されます) を [[開発:ブロック/付録A#.24this-.3Etitle| $this->title]] および [[開発:ブロック/付録A#.24this-.3Eversion| $this->version]] に割り当てるべきです。
-No return value is expected from this method.
+このメソッドからは、戻り値は必要ではありません。
 === instance_allow_config() ===
@@ 198行目: / 195行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should return a boolean value. True indicates that your block wants to have per-instance configuration, while false means it does not. If you do want to implement instance configuration, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
+このメソッドでは、ブール値を返す必要があります。falseが設定なしに対して、trueでは、あなたのブロックがインスタンスごとに設定したいことを意味します。インスタンス設定を実装したい場合、このメソッドをオーバーライドするのと別に、あなたはいくつかの追加的な対策を講じる必要があります。さらなる情報は、[[開発:ブロック#設定しよう|こちらをご覧ください]]。
-This method's return value is irrelevant if [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] returns true; it is assumed that if you want multiple instances then each instance needs its own configuration.
+[[開発:ブロック/付録A#instance_allow_multiple.28.29| instance_allow_multiple]]がtrueを戻す場合、このメソッドの戻り値は適切ではなくなります。あなたが複数インスタンスを設定したい場合、それぞれのインスタンスには独自の設定が必要だと考えられるからです。
 === instance_allow_multiple() ===
@@ 214行目: / 211行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should return a boolean value, indicating whether you want to allow multiple instances of this block in the same page or not. If you do allow multiple instances, it is assumed that you will also be providing per-instance configuration for the block. Thus, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
+このメソッドでは、同一ページでこのブロックの複数インスタンスを許可するかどうか指定するため、ブール値を返す必要があります。あなたが複数インスタンスを許可する場合、ブロックのプレインスタンス設定も同時に提供することになります。従って、あなたが、このメソッドをオーバーライドするのとは別にして、いくつかの追加的なステップが必要となります。詳細は、[[Blocks_Howto#section_configure_that_out|こちらをご覧ください]]。
 === instance_config_print() ===
@@ 241行目: / 238行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method allows you to choose how to display the instance configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. Keep in mind that whatever you do output from [[Blocks_Howto#method_instance_config_print| config_print]], it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.
+このメソッドでは、あなたのブロックにインスタンス設定画面を表示する方法を選択できるようにします。あなたがデフォルトの実装をさらに複雑にしたい場合、オーバーライドしてください。あなたが[[Blocks_Howto#method_instance_config_print| config_print]]からどのようにアウトプットしたとしても、HTMLフォームにより囲まれることに留意してください。あなたに必要なことは、フォームの送信方法を手供するのみです。
-You should return a boolean value denoting the success or failure of your method's actions.
+あなたのメソッドの正否を示すブール値を返す必要があります。
 === instance_config_save() ===
@@ 258行目: / 255行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method allows you to override the storage mechanism for your instance configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values.
+このメソッドでは、あなたのインスタンス設定データの保存メカニズムをオーバーライドすることができます。受け取ることになる引数は、設定名のキーおよび設定値の値を持った連想配列となります。
-The configuration must be stored in the "configdata" field of your instance record in the database so that Moodle can auto-load it when your block is constructed. However, you may still want to override this method if you need to take some additional action apart from saving the data. In that case, you really should do what data processing you want and then call parent::instance_config_save($data) with your new $data array. This will keep your block from becoming broken if the default implementation of instance_config_save changes in the future.
+あなたのブロックが構築される場合、Moodleがオートロードできるよう、設定をデータベース内のインスタンスレコードの「configdata」フィールドに保存する必要があります。しかし、あなたがデータの保存以外に、さらに動作を追加したい場合、このメソッドをオーバーライドすることもできます。その場合、あなたが望むデータ処理を実行すべきで、その後、新しい$data配列を使って、parent::instance_config_save($data)をコールしてください。これは、将来的にinstance_config_saveのデフォルトが変更された場合、あなたのブロックが壊れることを防ぎます。
-Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
+Moodleが処理できるよう、いくつかの隠しフィールドをフォームに追加するため、送信されたPOSTデータすべてを$dataが保持するわけではないことに留意してください。しかし、このメソッドをコールする前、受信したデータより隠しフィールドを取り除きます。ですから、このメソッドがコールされる場合、「実」設定データのみ残ることになります。
-If you want to update the stored copy of the configuration data at run time (for example to persist some changes you made programmatically), you should not use this method. The correct procedure for that purpose is to call [[Blocks_Howto#method_instance_config_commit| instance_config_commit]].
+実行時間に保存された設定データを更新したい場合 (例 あなたが変更したプログラムを保持する)、あなたは、このメソッドを使うべきではありません。この目的に関する正しい処理は、[[開発:ブロック/付録A#instance_config_commit.28.29| instance_config_commit]]をコールすることです。
-You should return a boolean value denoting the success or failure of your method's actions.
+あなたのメソッドの正否を示すブール値を返す必要があります。
 === preferred_width() ===
@@ 279行目: / 276行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should return an integer value, which is the number of pixels of width your block wants to take up when displayed. Moodle will try to honor your request, but this is actually up to the implementation of the format of the page your block is being displayed in and therefore no guarantee is given. You might get exactly what you want or any other width the format decides to give you, although obviously an effort to accomodate your block will be made.
+このメソッドでは、あなたのブロックが表示される時に取得する幅のピクセル値を整数値として返すべきです。Moodleは、あなたのリクエストを尊重しますが、これは実際のところ、ブロックが表示されるページのフォーマット次第となりますので、保証されるわけではありません。あなたが希望する幅で厳密に表示されることもありますし、フォーマットが決定した幅で表示されることもあります。しかし、明らかに、あなたの希望するブロック幅に適合するよう、努力されます。
-Most display logic at this point allocates the maximum width requested by the blocks that are going to be displayed, bounding it both downwards and upwards to avoid having a bad-behaving block break the format.
+この時点での表示ロジックは、上限および下限に調整しながら、フォーマットを崩さないよう、ブロックからリクエストされた最大幅に割り当てます。
 === refresh_content() ===
@@ 295行目: / 292行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method should cause your block to recalculate its content immediately. If you follow the guidelines for [[Blocks_Howto#get_content| get_content]], which say to respect the current content value unless it is NULL, then the default implementation will do the job just fine.
+このメソッドでは、あなたのブロックにそのコンテンツを再計算させます。あなたが、現在のコンテンツの値がNULLでない限り尊重するという[[Blocks_Howto#get_content| get_content]]のガイドラインに従う場合、デフォルトの処理は、素晴らしい仕事を実行します。リフレッシュした後、[[Blocks_Howto#variable_content| $this->content]]の新しい値を返す必要があります。
-You should return the new value of [[Blocks_Howto#variable_content| $this->content]] after refreshing it.
 === specialization() ===
@@ 308行目: / 304行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method is automatically called by the framework immediately after your instance data (which includes the page type and id and all instance configuration data) is loaded from the database. If there is some action that you need to take as soon as this data becomes available and which cannot be taken earlier, you should override this method.
+あなたの (ページタイプ、IDおよびすべてのインスタンス設定データを含む) インスタンスデータがデータベースからロードされるとすぐに、このメソッドがフレームワークからコールされます。このデータが利用可能な状態になった直後に実行したい処理があって、すぐには処理を開始できない場合、あなたは、このメソッドをオーバーライドすることができます。
-The instance data will be available in the variables [[Blocks_Howto#variable_instance| $this->instance]] and [[Blocks_Howto#variable_config| $this->config]].
+インスタンスデータは、変数[[Blocks_Howto#variable_instance| $this->instance]]および[[Blocks_Howto#variable_config| $this->config]]で利用可能です。
-This method should not return anything at all.
+このメソッドでは、何も返す必要は全くありません。
-== Methods which you should ''not'' override but may want to use: ==
+== あなたがオーバーライドすべきではない、しかし使用しても良いメソッド: ==
@@ 327行目: / 323行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method returns the value of [[Blocks_Howto#variable_content_type| $this->content_type]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
+このメソッドは、[[Blocks_Howto#variable_content_type| $this->content_type]]の値を返します。そして、変数にアクセスする推奨方法は、戻り値を取得することです。また、このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。
 === get_title() ===
@@ 339行目: / 335行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method returns the value of [[Blocks_Howto#variable_title| $this->title]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
+このメソッドでは、[[Blocks_Howto#variable_title| $this->title]]の値を返します。また、この値にアクセスするための、推奨方法でもあります。このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。
 === get_version() ===
@@ 350行目: / 346行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method returns the value of [[Blocks_Howto#variable_version| $this->version]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
+このメソッドでは、 [[Blocks_Howto#variable_version| $this->version]]の値を返します。また、この値にアクセスするための、推奨方法でもあります。このメソッドは、常に動作することが保証されています。変数に直接アクセスすることは、推奨されません。将来的なライブラリの変更により、コードの互換性が壊れてしまう可能性があります。
 === instance_config_commit() ===
@@ 362行目: / 358行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method saves the current contents of [[Blocks_Howto#variable_config| $this->config]] to the database. If you need to make a change to the configuration settings of a block instance at run time (and not through the usual avenue of letting the user change it), just make the changes you want to [[Blocks_Howto#variable_config| $this->config]] and then call this method.
+このメソッドでは、[[Blocks_Howto#variable_config| $this->config]]の現在のコンテンツをデータベースに保存します。あなたが実行時に、ブロックインスタンスの設定を変更したい場合 (そして、一般的な手段でユーザに変更させない場合)、[[Blocks_Howto#variable_config| $this->config]]を変更して、このメソッドをコールしてください。
 === is_empty() ===
-For blocks that extend class '''block_base'''<nowiki>:</nowiki>
+クラス'''block_base'''を拡張するブロック<nowiki>:</nowiki>
 <code php>
@@ 377行目: / 373行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-For blocks that extend class '''block_list'''<nowiki>:</nowiki>
+クラス'''block_list'''を拡張するブロック<nowiki>:</nowiki>
 <code php>
@@ 388行目: / 384行目: @@
 </code>
-This method returns the a boolean true/false value, depending on whether the block has any content at all to display. Blocks without content are not displayed by the framework.
+このメソッドでは、表示するコンテンツがあるかどうかにより、ブール値 (true/false ) を返します。コンテンツがないブロックは、フレームワークにより表示されることはありません。
 === name() ===
@@ 403行目: / 399行目: @@
 </code>
-Available in Moodle 1.5 and later
+Moodle 1.5またはそれ以降のバージョンで利用可
-This method returns the internal name of your block inside Moodle, without the '''block_''' prefix. Obtaining the name of a block object is sometimes useful because it can be used to write code that is agnostic to the actual block's name (and thus more generic and reusable). For an example of this technique, see the [[Blocks_Howto#method_config_print| config_print]] method.
+このメソッドでは、Moodle内にある、あなたのブロックの内部名を '''block_''' 接頭辞なしで返します。実際のブロック名を使用できない状況でコードを書くときに使用することができるため、ブロックオブジェクト名を取得できることは、時々有用となります (そのため、さらに標準的かつ再利用可能となります)。この技術に関する詳細は、[[Blocks_Howto#method_config_print| config_print]]メソッドをご覧ください。
-== Methods which you should ''not'' override and ''not'' use at all: ==
+== あなたが、オーバライドおよび使用してはならないメソッド:: ==
 === _add_edit_controls() ===
-This is a private method; no description is given.
+これは、プライベートメソッドです。説明はありません。
 === _load_instance() ===
-This is a private method; no description is given.
+これは、プライベートメソッドです。説明はありません。
 === _print_block() ===
-This is a private method; no description is given.
+これは、プライベートメソッドです。説明はありません。
 === _print_shadow() ===
-This is a private method; no description is given.
+これは、プライベートメソッドです。説明はありません。
 === _self_test() ===
-This is a private method; no description is given.
+これは、プライベートメソッドです。説明はありません。
-The class '''block_base''' also has a few standard member variables which its methods manipulate. These variables, the purpose of each and the type of data they are expected to hold is explained in the next section of this Appendix.
+また、クラス'''block_base'''には、メソッドをコントロールするため、少数の標準メンバー変数があります。これらの変数、それぞれの目的、保持するデータのタイプは、この付録の次のセクションで説明します。
-== Class variables: ==
+== クラス変数: ==
 === $this->config ===
-This variable holds all the specialized instance configuration data that have been provided for this specific block instance (object). It is an object of type stdClass, with member variables directly corresponding to the HTML <input> elements in the block's <span class="filename">config_instance.html</span> file.
+この変数では、このブロックインスタンス (オブジェクト) 用に提供された、すべての特別インスタンス設定データを保持します。これは、ブロックの<span class="filename">config_instance.html</span>ファイル内のHTML <input> エレメントに直接相当する、メンバ変数を持ったstdClassオブジェクトタイプです。
-The variable is initialized just after the block object is constructed, immediately before [[Blocks_Howto#method_specialization| specialization]] is called for the object. It is possible that the block has no instance configuration, in which case the variable will be NULL.
+ブロックオブジェクトが作成された直後、[[Blocks_Howto#method_specialization| specialization]]が要求される直前に、変数が初期化されます。ブロックにインスタンス設定を持たせないことも可能です。この場合、変数は、NULLになります。
-It is obvious that there is a direct relationship between this variable and the configdata field in the mdl_block_instance table. However, it is ''strongly'' advised that you refrain from accessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method [[Blocks_Howto#method_instance_config_commit| instance_config_commit]] to do the actual work.
+この値とmdl_block_instanceテーブル内のconfigdataフィールドとは、明らかに直接の関係があります。しかし、あなた自身が「configdata」フィールドにアクセスすることは、「決して」お勧めできません。あなたが、本当にその値を更新する必要がある場合、実際の作業には、[[Blocks_Howto#method_instance_config_commit| instance_config_commit]]メソッドをコールしてください。
 === $this->content ===
-This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables set as explained below. Normally, it begins life with a value of NULL and it becomes fully constructed (i.e., an object) when [[Blocks_Howto#method_get_content| get_content]] is called.
+この変数では、それぞれのブロック内に表示される実コンテンツすべてを保持します。有効な値は、NULLまたは下記で説明される特定のメンバー変数を持つオブジェクトクラスstdClassValidのどちかかを使用できます。通常、NULLから始まり、 [[Blocks_Howto#method_get_content| get_content]]がコールされた時点で、完全に構築されます。
-After it is fully constructed, this object is expected to have certain properties, depending on the value of [[Blocks_Howto#variable_content_type| $this->content_type]].
+完全に構築された後、このオブジェクトでは、[[Blocks_Howto#variable_content_type| $this->content_type]]の値に応じて、特定のプロパティを持ちます。
-Specifically:
+特に:
-* If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
+* [[Blocks_Howto#variable_content_type| $this->content_type]]が[[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]]の場合、[[Blocks_Howto#variable_content| $this->content]]は、以下のメンバー変数を持ちます:
-# '''text''' This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
+# '''text''' これは、自由な長さおよびコンテンツを持つことのできる文字列です。ブロックのメインエリアに表示され、HTMLを含むことができます。
-# '''footer''' This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
+# '''footer''' これは、自由な長さおよびコンテンツを持つことのできる文字列です。これは、小さなフォントサイズを使用して、テキストの下に表示されます。また、HTMLを含むこともできます。
-* If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
+* [[Blocks_Howto#variable_content_type| $this->content_type]]が[[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]]の場合、[[Blocks_Howto#variable_content| $this->content]]は、以下のメンバー変数を持ちます:
-# '''items''' This is a numerically indexed array of strings which holds the title for each item in the list that will be displayed in the block's area. Since usually such lists function like menus, the title for each item is normally a fully qualified HTML <a> tag.
+# '''items''' これは、ブロックエリアに表示されるリスト内アイテムのタイトルを保持する文字列の数値索引配列です。このようなリストは、メニューに似ているため、それぞれのアイテムのタイトルは、省略されていないHTML <a> タグとなります。
-# '''icons''' This is a numerically indexed array of strings which represent the images displayed before each item of the list. It therefore follows that it should have the exact number of elements as the items member variable. Each item in this array should be a fully qualified HTML <img> tag.
+# '''icons''' これは、それぞれのリスト内アイテムが表示される前のイメージを示す文字列の数値索引配列です。そのため、アイテムメンバー変数として、エレメントの明確な数を持つべきです。この配列内のそれぞれのアイテムは、省略されていないHTML <img> タグにすべきです。
-# '''footer''' This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
+# '''footer''' これは、自由な長さおよびコンテンツを持つことのできる文字列です。これは、小さなフォントサイズを使用して、テキストの下に表示されます。また、HTMLを含むこともできます。
 === $this->content_type ===
-This variable instructs Moodle on what type of content it should assume the block has, and is used to differentiate text blocks from list blocks. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the variable [[Blocks_Howto#variable_content| $this->content]]. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
+この変数では、どのようなコンテンツがブロックに含まれているか、Moodleに伝えます。そしてまた、リストブロックからテキストブロックを差別化するためにも使用されます。Moodleが画面にブロックを表示する上で、この値に依存するため、意味のある値を持つべきです。そのため、この値は、厳密に変数[[Blocks_Howto#variable_content| $this->content]]と同値となります。それぞれのブロックにおいて、フレームワークが[[Blocks_Howto#method_init| init]]メソッドをコールした後、変数が有効な値を持つ必要があります。
-The only valid values for this variable are the two named constants [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]] and [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]].
+この変数に対する有効な値は、[[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]]および [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]]という名称を持った2つの定数のみです。
 === $this->instance ===
-This member variable holds all the specific information that differentiates one block instance (i.e., the PHP object that embodies it) from another. It is an object of type stdClass retrieved by calling get_record on the table mdl_block_instance. Its member variables, then, directly correspond to the fields of that table. It is initialized immediately after the block object itself is constructed.
+このメンバー変数では、1つのブロックインスタンスを他のブロックインスタンスと区別するため、使用されます (例 ブロックインスタンスを具体化するPHPオブジェクト)。これは、get_recordをコールして、テーブル「mdl_block_instance」で検索される、stdClassタイプのオブジェクトです。そして、メンバー変数は、テーブル「mdl_block_instance」のフィールドに直接合致します。ブロックオブジェクト自身が構築された直後、メンバー変数が初期化されます。
 === $this->title ===
-This variable is a string that contains the human-readable name of the block. It is used to refer to blocks of that type throughout Moodle, for example in the administrator's block configuration screen and in the editing teacher's add block menu. It is also the title that is printed when the block is displayed on screen, although blocks can specifically change this title to something else if they wish (see below). The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each object.
+この変数は、人間に解読可能なブロック名を含む文字列です。これは、そのタイプのブロックをMoodle内で参照する場合に使用されます。例えば、管理者ブロックの設定ページ、および教師の編集モード時のブロック追加メニュー等です。また、必要であれば、ブロックがタイトルを変更することができますが、これは、ブロックが画面に表示される場合のタイトルでもあります (下記参照)。フレームワークが、それぞれのオブジェクトの[[Blocks_Howto#method_init| init]]メソッドをコールした後、この変数は、有効な値を持つ必要があります。
-In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside [[Blocks_Howto#method_init| init]]. This title may then be overridden when the [[Blocks_Howto#method_specialization| specialization]] method is called by the framework:
+インスタンス設定を通して、ブロックのタイトルを動的に設定したい場合、[[Blocks_Howto#method_init| init]]内に有効なタイトルを持つことは、まだ必要ではあります。[[Blocks_Howto#method_specialization| specialization]]メソッドがフレームワークよりコールされた場合、このタイトルをオーバーライドすることができます:
 <code php>
@@ 479行目: / 475行目: @@
 </code>
-A lot of blocks seem to use
+ブロックタイトルを設定するため、多くのブロックでは、
 <code php>
@@ 485行目: / 481行目: @@
 </code>
-to set the title of the block (and then put a more specific title inside the language file).
+を使用するようです (そして、さらに特別なタイトルを言語ファイルの中に置きます)。
-If there is no proper language string, the title of the block will then be set to ''blockname''. If there is another block with the same generic title, then an error will show up: Naming conflict.
+適切な言語ストリングがない場合、ブロックタイトルは「blockname」に設定されます。同じ一般名のブロックがある場合、「Naming conflict」というエラーが表示されます。
-To avoid this error on installations with missing language strings, use a more specific name when calling the language string...
+不明の言語ストリンクのインストール中のエラーを避けるには、言語ストリングの呼び出し時に、さらに明確なストリング名を使用します ...
 <code php>
@@ 495行目: / 491行目: @@
 </code>
-That way all blocks will show up with a unique title in the admin area, even if people have not yet succeeded in placing language files in the correct location
+正しい場所に言語ファイルを置けなかったとしても、このようにして、すべてのブロックが独自のタイトルで管理エリアに表示されます。
 === $this->version ===
-This variable should hold each block's version number in the form '''YYYYMMDDXX''', as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
+この変数では、Moodleの慣習により、それぞれのブロックのバージョンナンバーを'''YYYYMMDDXX'''の形で持ちます。バージョンナンバーは、ブロックがいつアップグレードされたか認識するため、Moodleによって使用されます。また、その結果として、「古い」バージョンのブロックを最新のブロックにアップグレードするためにも使用されます。フレームワークが、それぞれのオブジェクトの[[Blocks_Howto#method_init| init]]メソッドをコールした後、この変数は、有効な値を持つ必要があります。
-Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily identify the exact version of the block they are working with.
+多くのブロックでは、モジュールのように複雑なデータを独自のデータベースに保存することありません。そのため、多くの場合、ブロックのバージョンアップ時、実際には何も起きません。しかし、ブロックの管理インターフェースに、バージョンナンバーが表示されます。そのため、新しい機能を加えたり、重要なバグフィックスを取得する場合、使用しているブロックの実際のバージョンをサイト管理者が容易に認識できるよう、あなたのブロックのバージョンナンバーを変更することは、良い実践となります。
-Appearing throughout the code related to the Blocks API, there is a number of predefined constants that are utilized to avoid the use of "magic numbers" in the code. These constants are:
+ブロックAPIに関連するコードが様々なところで出現するため、コード内で「マジックナンバー」の使用を避けることを目的に定義された多くの定数があります。これらの定数は:
-== Named constants: ==
+== 名前付き定数: ==
 === BLOCK_TYPE_LIST ===
-This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].
+これは、すべてのブロックの[[Blocks_Howto#variable_content_type|$this->content_type]]メンバー変数に関する2つの有効値の内の1つです。この値は、Moodleが[[Blocks_Howto#variable_content| $this->content]]で持つことになる必須属性を指定します。
 === BLOCK_TYPE_TEXT ===
-This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].
+これは、すべてのブロックの[[Blocks_Howto#variable_content_type|$this->content_type]]メンバー変数に関する2つの有効値の内の1つです。この値は、Moodleが[[Blocks_Howto#variable_content| $this->content]]で持つことになる必須属性を指定します。
-[[Category:開発|ブロック]]
+[[Category:開発者|ブロック]]
 [[Category:チュートリアル]]
 [[en:Development:Blocks/Appendix_A]]

Documentation

「開発:ブロック/付録A」の版間の差分

2009年8月22日 (土) 16:52時点における最新版

付録A: block_base 参照

あなたが自由に使用およびオーバーライドできるメソッド:

after_install()

applicable_formats()

before_delete()

config_print()

config_save()

get_content()

has_config()

hide_header()

html_attributes()

init()

instance_allow_config()

instance_allow_multiple()

instance_config_print()

instance_config_save()

preferred_width()

refresh_content()

specialization()

あなたがオーバーライドすべきではない、しかし使用しても良いメソッド:

get_content_type()

get_title()

get_version()

instance_config_commit()

is_empty()

name()

あなたが、オーバライドおよび使用してはならないメソッド::

_add_edit_controls()

_load_instance()

_print_block()

_print_shadow()

_self_test()

クラス変数:

$this->config

$this->content

$this->content_type

$this->instance

$this->title

$this->version

名前付き定数:

BLOCK_TYPE_LIST

BLOCK_TYPE_TEXT