開発:lib/formslib.php Form Definition
definition()
「タイプ」(PARAM_*)、インクルードされたヘルプボタンなど、フォームにインクルードされる要素の定義はすべて、definition() クラスの中で定義しなければならない機能に含まれています。
definition() はフォームの中の要素を定義するために使用されます。また、この定義は提出されたデータを検証するためやフォームを印刷するためにも同様に使用されます。選択とチェックボックスタイプの要素については、選択できたデータだけが許可されるでしょう。また、defintionの中のフォーム要素と一致するデータだけが提出されたデータとして認められるでしょう。
definition()は、フォームで使用されるであろう要素をすべて含んでいるべきです、いくつかの要素は後でdefinition_after_data()の中で削除されたり調整されたりするかもしれません。definition()に条件付きの要素を作成しないでください、definition()は直接提出されたデータに依存するべきではありません。
フォーム要素をグループ化するためにフィールドセットを使用する
伝説をもつフィールドセットを開くためにこのようなコードを使用します。
//-------------------------------------------------------------------------------
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
残念ながらこれらの可視のフィールドセットをネストにすることはまだできません。しかし事実として要素のグループは目に見えないフィールドセットの中で包まれます。
moodle_formのcloseHeaderBeforeメソッドでフィールドセットを閉じます。あなたがフィールドセットを終了したいときはその前にcloseHeaderBeforeに要素を伝えます。あなたが新しいフィールドセットを開くと、フィールドセットは自動的に閉じられます。 あなたがフィールドセットを閉じたく、続くフォーム要素が可視フィールドセット（それらはまだ伝説のない見えないフィールドセットに囲われています）によって囲われないときのみ、このコードを使用する必要があります。
：
$mform->closeHeaderBefore('buttonar');
addElement
フォームに要素を加えるにはaddElementメソッドを使用します。最初のいくつかの引数は常に同じです。第1引数は加える要素のタイプです。第2引数はフォーム中の要素の普通のhtml名に使用する要素名です。第3引数は多くの場合要素のラベルとなるテキストです。
いくつかの例を以下に示します：
button
$mform->addElement('button', 'intro', get_string("buttonlabel"));
ボタン要素。提出かキャンセルのボタンについては'submit'要素を参照。
checkbox
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
これは単純なチェックボックスです。この要素の第3引数はフォームの左側にラベルを表示するためのものです。さらに、要素の右側に現われるラベルを指定する第4引数として、文字列を与えることができます。チェックボックスとラジオボタンはグループ化し、それらの右側に個々のラベルを持つことができます。
advcheckbox
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
上のcheckboxと似ていますが、2つの重要な改良がなされています：
- 第5引数は普通の$attributes配列です。<入力>要素にHTML属性をセットするために通常使用されます。しかしながら、'group'の特別の値は与えることができます、それは要素にクラス名を加えて、
チェックボックス・コントローラーへのグルーピングを可能にします。
- 第6引数は、チェックボックスのチェックされたかまたはチェックされていないかの状態に関係するだろう値の配列です。通常のチェックボックスでは、あなたはその値を選ぶことができません。また、実際、チェックされていないチェックボックスはフォームデータで送られることもありません。
choosecoursefile
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
コースファイルエリアからファイルを選びます。第4引数は要素へのオプションのリストです。
array('courseid'=>null,//もしこれがnullなら (デフォルトなら global $COURSE を使う
'height'=>500,// ポップアップウィンドウの高さ
'width'=>750, // ポップアップウィンドウの幅
'options'=>'none');//ポップアップウィンドウのためのオプションの文字列
//例. 'menubar=0,location=0,scrollbars,resizable'
date_selector
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
これはデータセレクタです。セレクトボックスのグループを使用してDay、Month、Yearを選択することができます。第4引数はオプションの配列です。オプションのデフォルトは次の通りです：
array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true, 'optional'=>false);
第4引数としてデフォルトを上書きする値をもつ1つ以上のキーをもつ配列を与えることによって、これらのデフォルトを書き換えることができます。同様に第5引数で属性を与えることができます。
date_time_selector
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
これは、日付(日、月、年)と時間(時間と分)を選択するセレクトボックスのグループです。提出された時、提出されたデータが処理され、タイムスタンプが$form->get_data()に渡されます。これの第4番引数はオプションの配列です。オプションのためのデフォルトは次のとおりです：
array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true, 'step'=>5);
第4引数としてデフォルトを上書きする値をもつ1つ以上のキーをもつ配列を与えることによって、これらのデフォルトを書き換えることができます。同様に第5引数で属性を与えることができます。
file
フォーム定義タイプの中のブラウズボタンによるファイルアップロード入力ボックス。
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
フォームの提出と検証が仕様した後
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
必須ファイル、異なる最大アップロードサイズ、名前といった高度なセッティングを必要とする場合
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
古いコードを移植する場合、さらに、アップロードされたファイルの処理にアップロード・マネージャーを直接使用することが可能です。
set_upload_manager()を使用する場合、それが必ずaddElement('file',...)の前にあることに注意してください。
Moodle 2.0
ファイルアップロードは2.0で書き直されました。今のところインラインのドキュメントを参照してください。新しいAPIが安定した時、このページが更新されるでしょう。
filepicker
Moodle 2.0
file要素の一般的な置換
$mform->addElement('hidden', 'reply', 'yes');
隠れた要素。要素名(今回の場合reply)を、明記された値(今回の場合yes)にセットする。
htmleditor & format
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');
$mform->addElement('format', 'format', get_string('format'));
オプションの配列のhtmleditorに第4引数を与えることができる：
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65,
'width'=>0,'height'=>0, 'course'=>0);
//print_textarea引数と同じオプション
//htmleditorのサイズをコントロールするために行と列のオプションを使用する。
modgrade
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
これは、任意の活動モジュールのグレードを選ぶためのカスタム要素です。第4引数は値0を持っている等級のないものに対するオプションを含むかどうかです。この選択した箱は規模を含んでいます。デフォルトは真で、等級オプションを含んでいません。
ヘルプボタンは自動的に追加されます。
password
$mform->addElement('password', 'password', get_string('label'), $attributes);
パスワード要素。第4引数は属性の文字列または配列。
passwordunmask
Moodle 1.9
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
プレーンテキストでパスワードを表すためのオプションをもつパスワード要素。第4引数は属性の文字列または配列。
radio
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
第2引数はラジオボタンを指定し、正確に留めるためにグループ中の各ボタンに対して同じであるべきです。第3引数はフォーム要素のラベルになりますが、この要素が常に独自のラベルをもつグループにあるように、一般に無視されます。第4引数は、要素の右側に表示されるラベルとなる文字列です。第5引数はこのラジオボタンのための値です。$attributesは属性の配列か文字列になりえます。
個々のラジオボタンにヘルプを追加することは可能ですが、これは、カスタムテンプレートがグループ要素のために定義される必要があります。MDL-15571を参照してください。
setDefault
上のようにラジオボタングループにデフォルト値をセットするために以下を使用します：
$mform->setDefault('yesno', 0);
これはデフォルト'no'を作成します。
select
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
この要素の第4引数はセレクトボックスに対するオプションの配列です。キーはオプションのための値で、配列の値はオプションのためのテキストです。第5引数$attributesはオプションで、属性引数の記述用のテキスト要素を見ます。
multi-select
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
selectyesno
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
あなたが必要ならばyes/noセレクトボックスは、それ自身を自動翻訳しyesに1、noに0の値を持ちます。
static
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));
これは静的な要素です。それはラベルを備えた静的な1片のテキストを表示するために使用されることに注意して使用するべきです。第3引数はラベルで、第4引数はそれ自身の静的なテキストです。
submit, reset and cancel
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
'Submit'タイプエレメントはフォームを提出する提出タイプのフォーム要素です。'Reset'はフォームを提出しませんが、ユーザがフォームの内容に加えたあらゆる変更をリセットします。'Cancel'要素はフォームの提出を取り消します。提出がis_cancelled()で取り消されたかどうかをチェックするためにget_data()をチェックする前に、コードに分岐を持つ必要があります。使用法のページで例を参照してください。
提出およびリセットボタンを'submitbutton'、'resetbutton'あるいは類似した('submit'と'reset'でない)ものに名付けるべきです。これは、JavaScriptでのフォーム要素名とフォームオブジェクトのJavaScriptメソッド名の間の衝突問題を回避します。
add_action_buttons($cancel = true, $submitlabel=null);
あなたのフォームの終わりに'action'ボタンをすべて追加するために、通常moodleformのメソッドであるこのヘルパー機能を使用します。ブーリアン引数ーは、キャンセルボタンを含んで提出ボタン(get_stringの結果を渡す)のためのラベルを指定するかどうかを指定することを可能にします。提出ボタンのラベルのためのデフォルトはget_string('savechanges')です。
text
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
シンプルなテキスト要素のためのものです。ここでの第4引数がテキスト要素のための属性の配列か文字列になりえます。以下はそれに相当するものです：
$attributes='size="20"';
$attributes=array('size'=>'20');
一般に、スタイルには属性を使用する代わりにCSSを使用することが推奨されています。
フォーマット要素はフォーマットセレクトボックスとして使用することができます。あなたがhtmlエディタを使用していれば、選択可能ではなくなります。
この要素の第3引数は$useHtmlEditorで、ブラウザとユーザプロフィールがそれをサポートする場合は、htmlエディタが使用され、その中でそれはnullをデフォルトとします。
textarea
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
テキストエリア要素。htmlエディタが必要な場合はhtmlエディタ要素を使用します。ここの第4の要素は文字列あるいは属性の配列です。
addGroup
formslibの中の'group'は、ラベルを持ち、1行に含まれる単なる要素のグループです。
例えば提出とキャンセルのボタンを同じ行に含む典型的なコード：
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
createElementのために、addElementのために使用するのと同じ引数を使用します。第3引数であるどんな要素のラベルも通常無視されます(しかし第3引数がラベルのためではなくボタンのためのテキストである、上の提出ボタンの場合は違います)。
ここに、同じ行にdate_selector(それ自体が要素のグループ)およびチェックボックスを置く例を示します、あなたがグループ名'availablefromgroup'を使用して、グループ中のすべての要素を無効にすることができるが、'availablefromenabled'チェックボックスが要素のコントロールを無効にしないことに注意してください：
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');
setHelpButton
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
第1引数は要素名で、第2引数はweblib.phpの中のhelpbuttonに渡されるパラメータの配列です。パラメータは次のとおりです：
* @param string $page The keyword that defines a help page * @param string $title The title of links, rollover tips, alt tags etc * 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped. * @param string $module Which module is the page defined in * @param mixed $image Use a help image for the link? (true/false/"both") * @param boolean $linktext If true, display the title next to the help icon. * @param string $text If defined then this text is used in the page, and * the $page variable is ignored. * @param boolean $return If true then the output is returned as a string, if false it is printed to the current page. * @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
ブールの$retutnを偽にセットしないことを確かめてください。
addElement()の後にこのメソッドを使用する必要があります。
setDefault
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
setDefault($elementname,$value)でフォームの値のデフォルトをセットします。ここでの要素名は、あなたがそのデフォルトにセットしたい要素名で、$valueはセットするためのデフォルトです。私たちはdefinition()の中でフォームのためにデフォルトをセットします。このデフォルトは、set_data()でデータがフォームにロードされない場合に使用されるものです。例えば、'update'よりもむしろ'add'機能のためのフォームの表示の場合。
disabledIf
フォームの任意の要素や要素のグループについて、条件に依存するグループか個々の要素を条件付きで無効にすることができます。
あなたは $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null) を使用することができます。
- 要素名はグループをとりえます。あなたがグループを指定すれば、グループ中の要素がすべて無効になります(dependentOnが、無視され無効でない要素名グループにある場合)。これらは、addElementまたはaddGroupの中で第1引数として使用した要素名です。
- dependentOnは、それがhtmlに現われるような要素の実際の名前です。これは特にaddGroupの中で使用される名前とは異なることができます、また、date_selectorのように複雑な要素を加えているaddElementでもそうです。
あなたのページのhtmlをチェックしてください。depedentOnをチェックボックスかセレクトボックスにするのが典型的です。
- $conditionはnotchecked、checked、selected、eqになり、それ以外の場合のときはneqかどうかテストします。
- $conditionがeqまたはneqの場合、私たちは、dependentOnフィールドの値をチェックをし、jsの中で等しい(==)あるいは等しくない(! =)かどうかをチェックします。
- $conditionがcheckedかnotcheckedの場合、私たちは、チェックボックスがチェックされるかどうかを見るチェックをします。
- $conditionがselectedの場合、私たちは、特別のオプションがドロップダウンリストから選ばれているかどうかを見るチェックをします。
注：私は、このセクションが完全かどうか分かりません。私は1つのミスケースを見つけて加えただけです、しかし、他のものがあるかもしれません--Tim Hunt2007年10月15日06:04(CDT)
setType
PARAM_*タイプは、提出された変数がどのようにきれいにされなければならないか指定するために使用されます。 これらはid、コースなどのような、ページをロードするために使用されるパラメーターとsetType()メソッドによるものを得るために使用されるべきです。すべてのフォーム要素はタイプ、選択、ラジオボックスおよびチェックボックス要素以外に指定されたタイプを持つべきです。これらの要素は、それら自身をきれいにするのによいはたらきをします(指定されたオプションだけがユーザ入力として許可されます)。
最も一般的に使用される PARAM_* タイプ
これらは最も一般に使用されているPARAM_*タイプおよびそれらの適切な用途です。より多くのタイプはmoodlelib.phpの100行目あたりから始まるものを見ることができます。
- PARAM_CLEANは非難されます。また、より特殊なタイプを使用しようとするべきです。
- PARAM_TEXTはプレーンテキストであると予想されるデータをきれいにするために使用されるべきです。それはhtmlタグをすべてはぎとるでしょう。しかし、まだマルチランゲージをサポートするためにタグを通します。
- PARAM_NOTAGSはプレーンテキストであると予想されるデータをきれいにするために使用されるべきです。それは*全ての* htmlタイプのタグをはぎとります。これはマルチランゲージをサポートするためにタグを*通しません*。これは、適切にマルチランゲージをサポートしない電子メールアドレスのためのインスタンスに使用されるべきです。
- PARAM_RAWは何もきれいにしないことを意味します、それはほとんどhtmlエディタからのデータに使用されます。エディタからのデータは後でformat_text()機能を使用して表示される前にきれいされます。PARAM_RAWもまた、p()かs()によって印刷される方法や他のいくつかの方法によって検証されたデータに使用することができます。
- PARAM_INTは整数に使用されるべきです。
- PARAM_ACTIONはPARAM_ALPHAのエアリアスで、フォームの動きを指定する隠れたフィールドのために使用されます。
