https://docs.moodle.org/dev/api.php?action=feedcontributions&feedformat=atom&user=DanissMoodleDocs - User contributions [en]2026-08-19T10:12:28ZUser contributionsMediaWiki 1.43.5https://docs.moodle.org/dev/index.php?title=User:Daniele_Cordella&diff=22035User:Daniele Cordella2009-09-10T12:20:08Z<p>Daniss: New page: .</p>
<hr />
<div>.</div>Danisshttps://docs.moodle.org/dev/index.php?title=Plugin_contribution&diff=7835Plugin contribution2009-03-06T08:32:21Z<p>Daniss: /* How to submit code */</p>
<hr />
<div>This page describes the various ways to share and work collaboratively on contributed code.<br />
#Submit code in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].<br />
#Work with submitted code in [http://cvs.moodle.org Moodle's CVS server]<br />
#Document features and install instructions in [https://docs.moodle.org Moodle Docs]<br />
#Share and distribute code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database] <br />
#Talk and support code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]<br />
#Maintain and further develop code with the [http://tracker.moodle.org Moodle Tracker]<br />
<br />
==The Frequently asked question==<br />
'''Question:''' I have written a new block, activity, patch or theme to share with the Moodle community. What is the process for contributing the code? <br />
<br />
'''Answer:''' First, thank you for your generosity and desire to share your work with the rest of the Moodle community. Code contributions are highly valued and Moodle wants to encourage creativity and generosity in keeping with its constructivist tradition and pedagogical approach. To support this, there are several tools will support your contribution by allowing the code to be more easily found, tested, used, maintained, documented, and evaluated by fellow Moodlers and developers. Learning to use the various tools common among Moodle developers will help you to efficiently and effectively develop, share and maintain the contributed code. <br />
<br />
==How to submit code==<br />
You have created some code that you would like to contribute to the Moodle community. The first step is to create a login in [[Tracker]]. You should create a new issue as a "non- core contributed module" project and a "New Feature" issue type. Here is a link to tracker with [http://tracker.moodle.org/secure/CreateIssue!default.jspa?pid=10033 those fields filled in]. <br />
<br />
Your issue will be a request that the code be evaluated and uploaded into CVS. Provide a clear description of what the code does and the functionality that it adds to Moodle. Attach the contributed code as a zip (or tar.gz) file to the tracker issue. At that point, the Contrib Coordinator will work directly with the code contributor to help evaluate the code, work on resolving any questions/issues found, etc. <br />
<br />
*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].<br />
*A list of current tracker [http://tracker.moodle.org/secure/BrowseProject.jspa contributed projects is here].<br />
<br />
==How to work with code in CVS==<br />
Once the code has been added to the CONTRIB section of Moodle's [[CVS (developer)| CVS]], the contributor will request CVS write access via http://moodle.org/cvs/ and thus be able to make changes to the contributed code. <br />
<br />
Contributors are encouraged to maintain a branch for each major Moodle release (i.e. 1.8, 1.9, etc.). The HEAD branch should be used as the development branch. Once CVS write access is approved, the maintainer will be able to make whatever changes are needed to maintain the code. <br />
<br />
That being said, contributors are encouraged to associate each change made to an issue in the tracker. This is accomplished automatically by beginning the CVS commit comment with the issue number. By doing so, the contributor helps to document the reason for the change in the code back to the issue requesting for a change. More information on working with CVS is available at: [[CVS (developer)]]. <br />
<br />
:''Tip:'' Eclipse is an example of an Integrated Development Environment (IDE) that integrates and facilitates many of the common CVS tasks involved in working with Moodle CVS. Instructions for setting up and using Eclipse are available at: [[Eclipse]]. Experienced developers are free to use the tools they are most comfortable/productive with.<br />
<br />
==How to provide documentation==<br />
Having great code available to the community is wonderful. It is also important to educate users about how to use the code with documentation in [[Main Page|Moodle Docs]]. See [[MoodleDocs:Guidelines for contributors|guidelines for contributors]] for more help. <br />
<br />
A documentation page for a contributed module should have some basic elements. A brief introduction of what the code does, a "Features" heading, perhaps a "Installation", "Tips and tricks" and "See also" headings, all with content of course. Sometimes a screenshot is worth 1000 words. In the "See also" put a link to the Modules and Plug database, with a note that this is the place to download versions, and the forum where questions can be answered at moodle.org.<br />
<br />
Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. We suggest placing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.<br />
<br />
==Share code with modules and plugins database==<br />
Now you have a place for users to get your code, how will they know it exists? Moodle users can easily find information about contributed code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]. When you add an entry to this database, remember that it is searchable by any field. Every field is not required, but providing as much information as possible will help people who would like to find, read about, and then install your contribution. In particular, the name of the module and the description of its function are important. Screen shots are helpful (but please, not larger than 350px wide!). Links to discussion (on Moodle.org or other forum) and documentation (link to your page in the [https://docs.moodle.org Moodle docs] or another location) should be included if possible. <br />
<br />
If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code. <br />
<br />
Users may leave comments on your entry, so please check it periodically for questions and bug reports. If you include contact information or a link to a discussion, your users may be able to contact you more directly. The comments are not emailed automatically.<br />
<br />
Keep in mind that entries added to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database] require approval by a moderator before they will be visible to other Moodle users.<br />
<br />
==Support code and get feedback with forums==<br />
As users become familiar with the contributed code, discussions about the code are likely to emerge. We strongly urge you to place links to at least one forum at moodle.org in your Modules and Plugins entry as well as in MoodleDocs. <br />
<br />
It is important to respond to users who have questions about how to use the code, suggestions for how to make it better, etc. If it looks like there is sufficient need for some contributed code to have its own forum, please create a request via the tracker in the MDL-SITE section. Moodle has included many contributed code projects and ideas into its core. <br />
<br />
*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".<br />
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects. <br />
*[http://moodle.org/course/ A list of] other language forums and special areas in Moodle<br />
<br />
==Maintain and refine code with Tracker==<br />
<br />
In order to facilitate keeping track of feature requests, bugs, and other code issues, the contributor may request that a component be created in the CONTRIB section of the Moodle tracker. (This is the section where you initially made the request to have code included in CVS.moodle.org.)<br />
<br />
The contributor can be added to the group of CONTRIB developers in the tracker to manage the issues assigned to them and better coordinate with other developers. Users of the contributed code can then add issues which can be assigned directly to the maintainer. The tracker helps to manage the work flow involved in fixing bugs, working through feature requests, and maintaining the code. When committing changes, maintainers are strongly encouraged to begin the commit comment with a tracker number. <br />
<br />
We strongly encourage users to involve themselves in the process of creating a useful issue in tracker. For the developer and code contributor, describing the fix can help clarify the need for the code change. Further, it helps to establish good documentation about how the code developed. Others will be able to identify the issues addressed and understand why a particular decision was made.<br />
<br />
==Summary==<br />
<br />
It is hoped that following this procedure, will help guide contributors of code in the process of learning the tools and skills used by the Moodle developers. Learning to submit code by using the tracker, work the code with CVS, support the code by providing documentation, share code in Modules and Plugins, maintain the code by using the tracker, and evolve the code by using the Moodle.org forums will assist you in successfully contributing to the Moodle community and working with Moodle's developers. <br />
<br />
Throughout this process, the CONTRIB Coordinator is here to encourage and support those contributing code to the Moodle community and fostering the development of tomorrow's Moodle developers.<br />
<br />
Eventually, the community may wish for the code to become part of the Moodle core. By following the steps above, the developers will be able to evaluate the merit of the contributed code, understand how users have used the code, see the issues that have emerged and thus have more information to make an informed decision about whether or not to incorporate the contributed code into core.<br />
<br />
==Most common recommendations for contributed code==<br />
<br />
There are several small issues that the CONTRIB Coordinator will typically check for when reviewing the code prior to committing to the CVS server. These issues help to ensure consistency and quality of code. Any suggestions made by the CONTRIB Coordinator should be considered recommendations aimed to help folks new to the Moodle community collaborate in a way consistent with standard practices within the Moodle community. The suggestions are meant to help avoid potential issues and facilitate the acceptance of your code.<br />
<br />
# Does the file structure conform to Moodle standards? - Generally speaking, each file should have an appropriate extension (i.e. php, html, css, txt, etc.). To avoid issues with case sensitivity, folders and files are normally lower case; however, there are exceptions to this. Another common recommendation is to place the lang folder within the block or module rather than asking the user to copy files into the main lang folder. Changes made in the get_string function for Moodle 1.9 and onward make it possible to do this which goes a long way in keeping things modular. <br />
# Does the code work without any obvious errors - The CONTRIB Coordinator will try to install the block or module on a fresh Moodle installation and report back any errors. This testing is done with Debugging set to show All PHP notices and errors (not developer mode). The most common notices have to do with attempting to use a variable that has not been initialized or checked for existence. <br />
# Does the code use the config_plugins table? - Contributed blocks and modules are encouraged to make use of the config_plugins table rather than the config table. Maintainers are encouraged to read the documentation provided for the get_config and set_config functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated. <br />
# Does the code follow the [[Coding|Coding Guidelines]]? - The CONTRIB Coordinator will look at the code for general readability and point out any obvious deviations from the [[Coding|Coding Guidelines]]. While not all code needs to conform with each and every guideline, maintainers are encouraged to follow those guidelines as closely as possible.<br />
<br />
==See also==<br />
<br />
*[[contrib]] CONTRIB is an area in the Moodle CVS <br />
*[[Translation]] for information on the translation of contributed code<br />
*[[Overview]]<br />
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion<br />
<br />
[[Category:Guidelines for contributors]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Validation&diff=6089lib/formslib.php Validation2009-03-03T11:43:20Z<p>Daniss: /* moodleform::validation() */</p>
<hr />
<div>{{Formslib}}<br />
<br />
There are two ways to add validation in the forms lib.<br />
<br />
== MoodleQuickForm::addRule() ==<br />
<br />
You use this typically inside your moodleform::definition method. For example to set a field as required.<br />
<br />
<pre><br />
$mform->addElement('text','shortname', get_string('shortname'),'maxlength="15" size="10"');<br />
$mform->setHelpButton('shortname', array('courseshortname', get_string('shortname')), true);<br />
$mform->setDefault('shortname', get_string('defaultcourseshortname'));<br />
$mform->addRule('shortname', null, 'required', null, 'client');<br />
$mform->setType('shortname', PARAM_MULTILANG);<br />
</pre><br />
<br />
There is good documentation for this on the [http://pear.php.net/manual/en/package.html.html-quickform.intro-validation.php PEAR web site]<br />
<br />
In Moodle formslib you can set certain rules' error message to null and a default error message will automatically be used. The default messages are defined in lang/{language}/form.php. Here are the English definitions :<br />
<br />
<pre><br />
$string['err_alphanumeric']='You must enter only letters or numbers here.';<br />
$string['err_email']='You must enter a valid email address here.';<br />
$string['err_lettersonly']='You must enter only letters here.';<br />
$string['err_maxlength']='You must enter not more than $a->format characters here.';<br />
$string['err_minlength']='You must enter at least $a->format characters here.';<br />
$string['err_nopunctuation']='You must enter no punctuation characters here.';<br />
$string['err_nonzero']='You must enter a number not starting with a 0 here.';<br />
$string['err_numeric']='You must enter a number here.';<br />
$string['err_rangelength']='You must enter between {$a->format[0]} and {$a->format[1]} characters here.';<br />
$string['err_required']='You must supply a value here.';<br />
</pre><br />
<br />
== moodleform::validation() ==<br />
<br />
Define a method validation on your moodleform child to make your own custom validation for the form. This is done on the server side. And data_submitted will return null until the function returns no errors. You return an array of errors if there is any error or an empty array if there are no errors.<br />
<br />
<pre><br />
class course_edit_form extends moodleform {<br />
<br />
function definition() {<br />
blah blah;<br />
}<br />
<br />
<br />
/// perform some extra moodle validation<br />
function validation($data) {<br />
$errors= array();<br />
if ($foundcourses = get_records('course', 'shortname', $data['shortname'])) {<br />
if (!empty($data['id'])) {<br />
unset($foundcourses[$data['id']]);<br />
}<br />
if (!empty($foundcourses)) {<br />
foreach ($foundcourses as $foundcourse) {<br />
$foundcoursenames[] = $foundcourse->fullname;<br />
}<br />
$foundcoursenamestring = implode(',', $foundcoursenames);<br />
$errors['shortname']= get_string('shortnametaken', '', $foundcoursenamestring);<br />
}<br />
}<br />
<br />
if (empty($data['enrolenddisabled'])){<br />
if ($data['enrolenddate'] <= $data['enrolstartdate']){<br />
$errors['enroldateendgrp'] = get_string('enrolenddaterror');<br />
}<br />
}<br />
return $errors;<br />
}<br />
}<br />
?><br />
</pre><br />
<br />
{{Moodle 1.9}}There is a new parameter $files in Moodle 1.9, it allows validation of uploaded files too.<br />
<pre><br />
function validation($data, $files) {<br />
$errors = parent::validation($data, $files);<br />
if (empty($files['userfile'])) {<br />
if (array_key_exists('url', $data)) {<br />
$errors['url'] = get_string('required');<br />
}<br />
}<br />
return $errors;<br />
}<br />
</pre><br />
<br />
{{Moodle 1.9}}To validate a recaptcha element use the following code inside the function validation($data) {<br />
:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre></div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5822lib/formslib.php Form Definition2009-03-03T11:41:16Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To check whether recaptcha is enabled at site level use:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
//recaptcha is enabled<br />
}<br />
</pre><br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Validation&diff=6088lib/formslib.php Validation2009-03-03T11:40:22Z<p>Daniss: /* moodleform::validation() */</p>
<hr />
<div>{{Formslib}}<br />
<br />
There are two ways to add validation in the forms lib.<br />
<br />
== MoodleQuickForm::addRule() ==<br />
<br />
You use this typically inside your moodleform::definition method. For example to set a field as required.<br />
<br />
<pre><br />
$mform->addElement('text','shortname', get_string('shortname'),'maxlength="15" size="10"');<br />
$mform->setHelpButton('shortname', array('courseshortname', get_string('shortname')), true);<br />
$mform->setDefault('shortname', get_string('defaultcourseshortname'));<br />
$mform->addRule('shortname', null, 'required', null, 'client');<br />
$mform->setType('shortname', PARAM_MULTILANG);<br />
</pre><br />
<br />
There is good documentation for this on the [http://pear.php.net/manual/en/package.html.html-quickform.intro-validation.php PEAR web site]<br />
<br />
In Moodle formslib you can set certain rules' error message to null and a default error message will automatically be used. The default messages are defined in lang/{language}/form.php. Here are the English definitions :<br />
<br />
<pre><br />
$string['err_alphanumeric']='You must enter only letters or numbers here.';<br />
$string['err_email']='You must enter a valid email address here.';<br />
$string['err_lettersonly']='You must enter only letters here.';<br />
$string['err_maxlength']='You must enter not more than $a->format characters here.';<br />
$string['err_minlength']='You must enter at least $a->format characters here.';<br />
$string['err_nopunctuation']='You must enter no punctuation characters here.';<br />
$string['err_nonzero']='You must enter a number not starting with a 0 here.';<br />
$string['err_numeric']='You must enter a number here.';<br />
$string['err_rangelength']='You must enter between {$a->format[0]} and {$a->format[1]} characters here.';<br />
$string['err_required']='You must supply a value here.';<br />
</pre><br />
<br />
== moodleform::validation() ==<br />
<br />
Define a method validation on your moodleform child to make your own custom validation for the form. This is done on the server side. And data_submitted will return null until the function returns no errors. You return an array of errors if there is any error or an empty array if there are no errors.<br />
<br />
<pre><br />
class course_edit_form extends moodleform {<br />
<br />
function definition() {<br />
blah blah;<br />
}<br />
<br />
<br />
/// perform some extra moodle validation<br />
function validation($data) {<br />
$errors= array();<br />
if ($foundcourses = get_records('course', 'shortname', $data['shortname'])) {<br />
if (!empty($data['id'])) {<br />
unset($foundcourses[$data['id']]);<br />
}<br />
if (!empty($foundcourses)) {<br />
foreach ($foundcourses as $foundcourse) {<br />
$foundcoursenames[] = $foundcourse->fullname;<br />
}<br />
$foundcoursenamestring = implode(',', $foundcoursenames);<br />
$errors['shortname']= get_string('shortnametaken', '', $foundcoursenamestring);<br />
}<br />
}<br />
<br />
if (empty($data['enrolenddisabled'])){<br />
if ($data['enrolenddate'] <= $data['enrolstartdate']){<br />
$errors['enroldateendgrp'] = get_string('enrolenddaterror');<br />
}<br />
}<br />
return $errors;<br />
}<br />
}<br />
?><br />
</pre><br />
<br />
{{Moodle 1.9}}There is a new parameter $files in Moodle 1.9, it allows validation of uploaded files too.<br />
<pre><br />
function validation($data, $files) {<br />
$errors = parent::validation($data, $files);<br />
if (empty($files['userfile'])) {<br />
if (array_key_exists('url', $data)) {<br />
$errors['url'] = get_string('required');<br />
}<br />
}<br />
return $errors;<br />
}<br />
</pre><br />
<br />
{{Moodle 1.9}}To validate a recaptcha element use the following code:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre></div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Validation&diff=6087lib/formslib.php Validation2009-03-03T11:39:27Z<p>Daniss: /* moodleform::validation() */</p>
<hr />
<div>{{Formslib}}<br />
<br />
There are two ways to add validation in the forms lib.<br />
<br />
== MoodleQuickForm::addRule() ==<br />
<br />
You use this typically inside your moodleform::definition method. For example to set a field as required.<br />
<br />
<pre><br />
$mform->addElement('text','shortname', get_string('shortname'),'maxlength="15" size="10"');<br />
$mform->setHelpButton('shortname', array('courseshortname', get_string('shortname')), true);<br />
$mform->setDefault('shortname', get_string('defaultcourseshortname'));<br />
$mform->addRule('shortname', null, 'required', null, 'client');<br />
$mform->setType('shortname', PARAM_MULTILANG);<br />
</pre><br />
<br />
There is good documentation for this on the [http://pear.php.net/manual/en/package.html.html-quickform.intro-validation.php PEAR web site]<br />
<br />
In Moodle formslib you can set certain rules' error message to null and a default error message will automatically be used. The default messages are defined in lang/{language}/form.php. Here are the English definitions :<br />
<br />
<pre><br />
$string['err_alphanumeric']='You must enter only letters or numbers here.';<br />
$string['err_email']='You must enter a valid email address here.';<br />
$string['err_lettersonly']='You must enter only letters here.';<br />
$string['err_maxlength']='You must enter not more than $a->format characters here.';<br />
$string['err_minlength']='You must enter at least $a->format characters here.';<br />
$string['err_nopunctuation']='You must enter no punctuation characters here.';<br />
$string['err_nonzero']='You must enter a number not starting with a 0 here.';<br />
$string['err_numeric']='You must enter a number here.';<br />
$string['err_rangelength']='You must enter between {$a->format[0]} and {$a->format[1]} characters here.';<br />
$string['err_required']='You must supply a value here.';<br />
</pre><br />
<br />
== moodleform::validation() ==<br />
<br />
Define a method validation on your moodleform child to make your own custom validation for the form. This is done on the server side. And data_submitted will return null until the function returns no errors. You return an array of errors if there is any error or an empty array if there are no errors.<br />
<br />
<pre><br />
class course_edit_form extends moodleform {<br />
<br />
function definition() {<br />
blah blah;<br />
}<br />
<br />
<br />
/// perform some extra moodle validation<br />
function validation($data) {<br />
$errors= array();<br />
if ($foundcourses = get_records('course', 'shortname', $data['shortname'])) {<br />
if (!empty($data['id'])) {<br />
unset($foundcourses[$data['id']]);<br />
}<br />
if (!empty($foundcourses)) {<br />
foreach ($foundcourses as $foundcourse) {<br />
$foundcoursenames[] = $foundcourse->fullname;<br />
}<br />
$foundcoursenamestring = implode(',', $foundcoursenames);<br />
$errors['shortname']= get_string('shortnametaken', '', $foundcoursenamestring);<br />
}<br />
}<br />
<br />
if (empty($data['enrolenddisabled'])){<br />
if ($data['enrolenddate'] <= $data['enrolstartdate']){<br />
$errors['enroldateendgrp'] = get_string('enrolenddaterror');<br />
}<br />
}<br />
return $errors;<br />
}<br />
}<br />
?><br />
</pre><br />
<br />
{{Moodle 1.9}}There is a new parameter $files in Moodle 1.9, it allows validation of uploaded files too.<br />
<pre><br />
function validation($data, $files) {<br />
$errors = parent::validation($data, $files);<br />
if (empty($files['userfile'])) {<br />
if (array_key_exists('url', $data)) {<br />
$errors['url'] = get_string('required');<br />
}<br />
}<br />
return $errors;<br />
}<br />
</pre><br />
<br />
{{Moodle 1.9}}To validate the recaptcha element use the following code:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre></div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5821lib/formslib.php Form Definition2009-02-27T08:45:26Z<p>Daniss: /* htmleditor & format */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To check whether recaptcha is enabled at site level use:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
//recaptcha is enabled<br />
}<br />
</pre><br />
<br />
To validate the recaptcha element add the following code to the function validation($data) { in your form:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre><br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5820lib/formslib.php Form Definition2009-02-27T08:44:23Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To check whether recaptcha is enabled at site level use:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
//recaptcha is enabled<br />
}<br />
</pre><br />
<br />
To validate the recaptcha element add the following code to the function validation($data) { in your form:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre><br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5819lib/formslib.php Form Definition2009-02-27T08:41:49Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To check whether recaptcha is enabled at site level use:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
//recaptcha is enabled<br />
}<br />
</pre><br />
<br />
To validate the recaptcha element add the following code to the function validation($data) { in your form:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre><br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5818lib/formslib.php Form Definition2009-02-27T08:39:26Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To validate the recaptcha element add the following code to the function validation($data) { in your form:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) { // alias if recaptcha is enabled<br />
$recaptcha_element = $this->_form->getElement('recaptcha_field_name');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_field_name'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_field_name'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre><br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5817lib/formslib.php Form Definition2009-02-27T08:35:47Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To validate the recaptcha element add the following code to the function validation($data) { in your form:<br />
<pre><br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) { // alias if recaptcha is enabled<br />
$recaptcha_element = $this->_form->getElement('recaptcha_element');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_element'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_element'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
</pre><br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5816lib/formslib.php Form Definition2009-02-27T08:34:43Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To validate the recaptcha element add the following code to the function validation($data) { in your form:<br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) { // alias if recaptcha is enabled<br />
$recaptcha_element = $this->_form->getElement('recaptcha_element');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_element'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_element'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5815lib/formslib.php Form Definition2009-02-27T08:34:24Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
To validate the recaptcha ellement add the following code to the function validation($data) { in your form:<br />
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) { // alias if recaptcha is enabled<br />
$recaptcha_element = $this->_form->getElement('recaptcha_element');<br />
if (!empty($this->_form->_submitValues['recaptcha_challenge_field'])) {<br />
$challenge_field = $this->_form->_submitValues['recaptcha_challenge_field'];<br />
$response_field = $this->_form->_submitValues['recaptcha_response_field'];<br />
if (true !== ($result = $recaptcha_element->verify($challenge_field, $response_field))) {<br />
$errors['recaptcha_element'] = $result;<br />
}<br />
} else {<br />
$errors['recaptcha_element'] = get_string('missingrecaptchachallengefield');<br />
}<br />
}<br />
<br />
===tags===<br />
<br />
Moodle 2.0+ only. <br />
<br />
<pre><br />
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);<br />
</pre><br />
<br />
Used for editing a list of tags, for example on a blog post.<br />
<br />
There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.<br />
<br />
The value should be set/returned as an array of tags.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5813lib/formslib.php Form Definition2009-01-15T13:28:49Z<p>Daniss: /* recaptcha */</p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'field_name', $attributes);<br />
</pre><br />
<br />
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5812lib/formslib.php Form Definition2009-01-15T13:27:55Z<p>Daniss: </p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'field_name', $attributes);<br />
</pre><br />
<br />
A recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&diff=5811lib/formslib.php Form Definition2009-01-15T13:26:40Z<p>Daniss: </p>
<hr />
<div>{{Formslib}}<br />
==definition()==<br />
<br />
The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'<br />
<br />
definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.<br />
<br />
The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.<br />
<br />
==Use Fieldsets to group Form Elements==<br />
<br />
You use code like this to open a fieldset with a legend.<br />
<br />
<pre><br />
//-------------------------------------------------------------------------------<br />
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));<br />
</pre><br />
<br />
You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.<br />
<br />
You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :<br />
<br />
<pre><br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
==addElement==<br />
<br />
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.<br />
<br />
Some examples are below :<br />
===button===<br />
<br />
<pre><br />
$mform->addElement('button', 'intro', get_string("buttonlabel"));<br />
</pre><br />
<br />
A button element. If you want a submit or cancel button see 'submit' element. <br />
<br />
===checkbox===<br />
<pre><br />
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));<br />
</pre><br />
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.<br />
<br />
====advcheckbox====<br />
<pre><br />
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));<br />
</pre><br />
Similar to the checkbox above, but with a couple of important improvements:<br />
<br />
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]<br />
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.<br />
<br />
===choosecoursefile===<br />
<pre><br />
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));<br />
<br />
</pre><br />
<br />
Choose a file from the course files area. The fourth option is a list of options for the element. <br />
<br />
<pre><br />
array('courseid'=>null,//if it is null (default then use global $COURSE<br />
'height'=>500,// height of the popup window<br />
'width'=>750, // width of the popup window<br />
'options'=>'none');//options string for the pop up window <br />
//eg. 'menubar=0,location=0,scrollbars,resizable'<br />
<br />
</pre><br />
<br />
===date_selector===<br />
<pre><br />
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));<br />
</pre><br />
<br />
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'optional'=>false);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===date_time_selector===<br />
<pre><br />
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));<br />
</pre><br />
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:<br />
<br />
<pre>array('startyear'=>1970, 'stopyear'=>2020,<br />
'timezone'=>99, 'applydst'=>true, 'step'=>5);<br />
</pre><br />
<br />
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.<br />
<br />
===file===<br />
<br />
File upload input box with browse button. In the form definition type<br />
<pre><br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
</pre><br />
<br />
after form submission and validation use<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
...<br />
}<br />
</pre><br />
<br />
If you need advanced settings such as required file, different max upload size or name of uploaded file<br />
<pre><br />
<br />
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));<br />
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));<br />
$mform->addRule('attachment', null, 'required');<br />
<br />
</pre><br />
<br />
<pre><br />
if ($data = $mform->get_data()) {<br />
...<br />
$mform->save_files($destination_directory);<br />
$newfilename = $mform->get_new_filename();<br />
...<br />
}<br />
</pre><br />
<br />
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.<br />
<br />
Please note that if using set_upload_manager() it must be before addElement('file',..).<br />
<br />
{{Moodle 2.0}}<br />
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.<br />
<br />
===filepicker===<br />
{{Moodle 2.0}}<br />
General replacement of ''file'' element.<br />
<br />
===hidden===<br />
<pre><br />
$mform->addElement('hidden', 'reply', 'yes');<br />
</pre><br />
<br />
A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').<br />
<br />
===htmleditor & format===<br />
<pre><br />
<br />
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));<br />
$mform->setType('text', PARAM_RAW);<br />
$mform->addRule('text', null, 'required', null, 'client');<br />
<br />
$mform->addElement('format', 'format', get_string('format'));<br />
</pre><br />
You can supply a fourth param to htmleditor of an array of options :<br />
<br />
<pre><br />
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, <br />
'width'=>0,'height'=>0, 'course'=>0);<br />
//options same as print_textarea params<br />
//use rows and cols options to control htmleditor size.<br />
</pre><br />
<br />
===modgrade===<br />
<pre><br />
$mform->addElement('modgrade', 'scale', get_string('grade'), false);<br />
</pre><br />
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.<br />
<br />
A helpbutton is automatically added.<br />
<br />
<br />
===password===<br />
<pre><br />
$mform->addElement('password', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element. Fourth param is an array or string of attributes.<br />
<br />
===passwordunmask===<br />
{{Moodle 1.9}}<br />
<pre><br />
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);<br />
</pre><br />
<br />
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.<br />
<br />
===radio===<br />
<pre><br />
$radioarray=array();<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);<br />
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);<br />
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);<br />
</pre><br />
<br />
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.<br />
<br />
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.<br />
<br />
====setDefault====<br />
<br />
To set the default for a radio button group as above use the following :<br />
<br />
<pre><br />
$mform->setDefault('yesno', 0);<br />
</pre><br />
<br />
This would make the default 'no'.<br />
<br />
===select===<br />
<pre><br />
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);<br />
</pre><br />
<br />
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.<br />
<br />
====multi-select====<br />
<pre><br />
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);<br />
$select->setMultiple(true);<br />
</pre><br />
<br />
===selectyesno===<br />
<pre><br />
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));<br />
</pre><br />
<br />
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.<br />
<br />
===static===<br />
<pre><br />
$mform->addElement('static', 'description', get_string('description', 'exercise'),<br />
get_string('descriptionofexercise', 'exercise', $COURSE->students));<br />
<br />
</pre><br />
<br />
This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.<br />
<br />
===submit, reset and cancel===<br />
<br />
<pre><br />
//normally you use add_action_buttons instead of this code<br />
$buttonarray=array();<br />
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));<br />
$buttonarray[] = &$mform->createElement('cancel');<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
$mform->closeHeaderBefore('buttonar');<br />
</pre><br />
<br />
A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.<br />
<br />
You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.<br />
<br />
====add_action_buttons($cancel = true, $submitlabel=null);====<br />
<br />
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').<br />
<br />
===text===<br />
<br />
<pre><br />
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);<br />
</pre><br />
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :<br />
<pre><br />
$attributes='size="20"';<br />
$attributes=array('size'=>'20');<br />
</pre><br />
<br />
Generally you are encouraged to use CSS instead of using attributes for styling.<br />
<br />
<br />
A format element can be used as a format select box. It will be non-selectable if you're using an html editor.<br />
<br />
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.<br />
<br />
===textarea===<br />
<br />
<pre><br />
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');<br />
</pre><br />
<br />
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.<br />
<br />
===recaptcha===<br />
<br />
<pre><br />
$mform->addElement('recaptcha', 'field_name', $attributes);<br />
</pre><br />
<br />
A recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes.<br />
<br />
==addGroup==<br />
<br />
A 'group' in formslib is just a group of elements that will have a label and will be included on one line. <br />
<br />
For example typical code to include a submit and cancel button on the same line : <br />
<br />
<pre><br />
$buttonarray=array();<br />
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));<br />
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));<br />
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);<br />
</pre><br />
<br />
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).<br />
<br />
Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:<br />
<br />
<pre><br />
$availablefromgroup=array();<br />
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');<br />
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));<br />
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), '&nbsp;', false);<br />
$mform->disabledIf('availablefromgroup', 'availablefromenabled');<br />
<br />
</pre><br />
<br />
==setHelpButton==<br />
<pre><br />
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));<br />
</pre><br />
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :<br />
<br />
<pre><br />
* @param string $page The keyword that defines a help page<br />
* @param string $title The title of links, rollover tips, alt tags etc<br />
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.<br />
* @param string $module Which module is the page defined in<br />
* @param mixed $image Use a help image for the link? (true/false/"both")<br />
* @param boolean $linktext If true, display the title next to the help icon.<br />
* @param string $text If defined then this text is used in the page, and<br />
* the $page variable is ignored.<br />
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.<br />
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif<br />
</pre><br />
Make sure you don't set boolean $return to false. <br />
<br />
You need to do use this method after addElement();<br />
<br />
==setDefault==<br />
<br />
<pre><br />
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);<br />
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));<br />
$mform->setDefault('grade', 100);<br />
</pre><br />
<br />
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.<br />
<br />
==disabledIf==<br />
<br />
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.<br />
<br />
You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)<br />
<br />
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.<br />
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.<br />
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.<br />
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js<br />
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.<br />
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.<br />
<br />
Examples:<br />
// Disable my control unless a checkbox is checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox');<br />
<br />
// Disable my control if a checkbox '''is''' checked.<br />
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');<br />
<br />
// Disable my control unless a dropdown has value 42.<br />
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);<br />
<br />
''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''<br />
<br />
==setType==<br />
<br />
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).<br />
<br />
<br />
<br />
===Most Commonly Used PARAM_* Types===<br />
<br />
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.<br />
<br />
* PARAM_CLEAN is deprecated and you should try to use a more specific type.<br />
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.<br />
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.<br />
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().<br />
* PARAM_INT should be used for integers.<br />
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.<br />
<br />
==References==<br />
<br />
* [http://web.archive.org/web/20080214041550/http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com (via archive.org as original now dead)]<br />
<br />
[[Category:Formslib]]</div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Validation&diff=6085lib/formslib.php Validation2008-05-21T16:27:18Z<p>Daniss: /* moodleform::validation() */</p>
<hr />
<div>{{Formslib}}<br />
<br />
There are two ways to add validation in the forms lib.<br />
<br />
== MoodleQuickForm::addRule() ==<br />
<br />
You use this typically inside your moodleform::definition method. For example to set a field as required.<br />
<br />
<pre><br />
$mform->addElement('text','shortname', get_string('shortname'),'maxlength="15" size="10"');<br />
$mform->setHelpButton('shortname', array('courseshortname', get_string('shortname')), true);<br />
$mform->setDefault('shortname', get_string('defaultcourseshortname'));<br />
$mform->addRule('shortname', null, 'required', null, 'client');<br />
$mform->setType('shortname', PARAM_MULTILANG);<br />
</pre><br />
<br />
There is good documentation for this on the [http://pear.php.net/manual/en/package.html.html-quickform.intro-validation.php PEAR web site]<br />
<br />
In Moodle formslib you can set certain rules' error message to null and a default error message will automatically be used. The default messages are defined in lang/{language}/form.php. Here are the English definitions :<br />
<br />
<pre><br />
$string['err_alphanumeric']='You must enter only letters or numbers here.';<br />
$string['err_email']='You must enter a valid email address here.';<br />
$string['err_lettersonly']='You must enter only letters here.';<br />
$string['err_maxlength']='You must enter not more than $a->format characters here.';<br />
$string['err_minlength']='You must enter at least $a->format characters here.';<br />
$string['err_nopunctuation']='You must enter no punctuation characters here.';<br />
$string['err_nonzero']='You must enter a number not starting with a 0 here.';<br />
$string['err_numeric']='You must enter a number here.';<br />
$string['err_rangelength']='You must enter between {$a->format[0]} and {$a->format[1]} characters here.';<br />
$string['err_required']='You must supply a value here.';<br />
</pre><br />
<br />
== moodleform::validation() ==<br />
<br />
Define a method validation on your moodleform child to make your own custom validation for the form. This is done on the client side. And data_submitted will return null until the function returns no errors. You return an array of errors if there is any error or an empty array if there are no errors.<br />
<br />
<pre><br />
class course_edit_form extends moodleform {<br />
<br />
function definition() {<br />
blah blah;<br />
}<br />
<br />
<br />
/// perform some extra moodle validation<br />
function validation($data) {<br />
$errors= array();<br />
if ($foundcourses = get_records('course', 'shortname', $data['shortname'])) {<br />
if (!empty($data['id'])) {<br />
unset($foundcourses[$data['id']]);<br />
}<br />
if (!empty($foundcourses)) {<br />
foreach ($foundcourses as $foundcourse) {<br />
$foundcoursenames[] = $foundcourse->fullname;<br />
}<br />
$foundcoursenamestring = implode(',', $foundcoursenames);<br />
$errors['shortname']= get_string('shortnametaken', '', $foundcoursenamestring);<br />
}<br />
}<br />
<br />
if (empty($data['enrolenddisabled'])){<br />
if ($data['enrolenddate'] <= $data['enrolstartdate']){<br />
$errors['enroldateendgrp'] = get_string('enrolenddaterror');<br />
}<br />
}<br />
return $errors;<br />
}<br />
}<br />
?><br />
</pre><br />
<br />
{{Moodle 1.9}}There is a new parameter $files in Moodle 1.9, it allows validation of uploaded files too.<br />
<pre><br />
function validation($data, $files) {<br />
$errors = parent::validation($data, $files);<br />
if (empty($files['userfile'])) {<br />
if (array_key_exists('url', $data)) {<br />
$errors['url'] = get_string('required');<br />
}<br />
}<br />
return $errors;<br />
}<br />
</pre></div>Danisshttps://docs.moodle.org/dev/index.php?title=lib/formslib.php_Validation&diff=6084lib/formslib.php Validation2008-05-21T12:41:04Z<p>Daniss: /* moodleform::validation() */</p>
<hr />
<div>{{Formslib}}<br />
<br />
There are two ways to add validation in the forms lib.<br />
<br />
== MoodleQuickForm::addRule() ==<br />
<br />
You use this typically inside your moodleform::definition method. For example to set a field as required.<br />
<br />
<pre><br />
$mform->addElement('text','shortname', get_string('shortname'),'maxlength="15" size="10"');<br />
$mform->setHelpButton('shortname', array('courseshortname', get_string('shortname')), true);<br />
$mform->setDefault('shortname', get_string('defaultcourseshortname'));<br />
$mform->addRule('shortname', null, 'required', null, 'client');<br />
$mform->setType('shortname', PARAM_MULTILANG);<br />
</pre><br />
<br />
There is good documentation for this on the [http://pear.php.net/manual/en/package.html.html-quickform.intro-validation.php PEAR web site]<br />
<br />
In Moodle formslib you can set certain rules' error message to null and a default error message will automatically be used. The default messages are defined in lang/{language}/form.php. Here are the English definitions :<br />
<br />
<pre><br />
$string['err_alphanumeric']='You must enter only letters or numbers here.';<br />
$string['err_email']='You must enter a valid email address here.';<br />
$string['err_lettersonly']='You must enter only letters here.';<br />
$string['err_maxlength']='You must enter not more than $a->format characters here.';<br />
$string['err_minlength']='You must enter at least $a->format characters here.';<br />
$string['err_nopunctuation']='You must enter no punctuation characters here.';<br />
$string['err_nonzero']='You must enter a number not starting with a 0 here.';<br />
$string['err_numeric']='You must enter a number here.';<br />
$string['err_rangelength']='You must enter between {$a->format[0]} and {$a->format[1]} characters here.';<br />
$string['err_required']='You must supply a value here.';<br />
</pre><br />
<br />
== moodleform::validation() ==<br />
<br />
Define a method validation on your moodleform child to make your own custom validation for the form. This is done on the client side. And data_submitted will return null until the function returns no errors. You return an array of errors if there is any error or an empty array if there are no errors.<br />
<br />
<pre><br />
class course_edit_form extends moodleform {<br />
<br />
function definition() {<br />
blah blah;<br />
}<br />
<br />
<br />
/// perform some extra moodle validation<br />
function validation($data) {<br />
$errors= array();<br />
if ($foundcourses = get_records('course', 'shortname', $data['shortname'])) {<br />
if (!empty($data['id'])) {<br />
unset($foundcourses[$data['id']]);<br />
}<br />
if (!empty($foundcourses)) {<br />
foreach ($foundcourses as $foundcourse) {<br />
$foundcoursenames[] = $foundcourse->fullname;<br />
}<br />
$foundcoursenamestring = implode(',', $foundcoursenames);<br />
$errors['shortname']= get_string('shortnametaken', '', $foundcoursenamestring);<br />
}<br />
}<br />
<br />
if (empty($data['enrolenddisabled'])){<br />
if ($data['enrolenddate'] <= $data['enrolstartdate']){<br />
$errors['enroldateendgrp'] = get_string('enrolenddaterror');<br />
}<br />
}<br />
return $errors;<br />
}<br />
}<br />
?><br />
</pre><br />
<br />
{{Moodle 1.9}}There is a new parameter $files in Moodle 1.9, it allows validation of uploaded files too.<br />
<pre><br />
function validation($data, $files) {<br />
$errors = parent::validate($data, $files);<br />
if (empty($files['userfile'])) {<br />
if (array_key_exists('url', $data)) {<br />
$errors['url'] = get_string('required');<br />
}<br />
}<br />
return $errors;<br />
}<br />
</pre></div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8379NEWMODULE Adding capabilities2008-04-07T16:49:33Z<p>Daniss: /* Create one access.php file in the <<NEWMODULE>>/db directory. */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
Just change the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of course, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
And follow the instruction on the monitor.<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it the definition of the $context variable<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8378NEWMODULE Adding capabilities2008-04-07T16:21:10Z<p>Daniss: /* Add to your code the right triggger */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
Just change the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of course, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
And follow the instruction on the monitor.<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it the definition of the $context variable<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8377NEWMODULE Adding capabilities2008-04-07T16:19:04Z<p>Daniss: /* Add to your code the right triggger */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
Just change the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of course, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
And follow the instruction on the monitor.<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it define the $context variable<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8376NEWMODULE Adding capabilities2008-04-07T16:18:37Z<p>Daniss: /* Visit the "notification page" of the Site Administration block */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
Just change the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of course, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
And follow the instruction on the monitor.<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it define the variable $context<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8375NEWMODULE Adding capabilities2008-04-07T14:42:33Z<p>Daniss: /* Add to your code the right triggger */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
Just change the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of course, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it define the variable $context<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8374NEWMODULE Adding capabilities2008-04-07T14:40:49Z<p>Daniss: /* Change the version number of your <<NEWMODULE>> */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
Just change the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of course, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it define the variable $context<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8373NEWMODULE Adding capabilities2008-04-07T14:40:26Z<p>Daniss: /* Add to your code the right triggger */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
just chenge the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of vcourse, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {<br />
<br />
In order to let it works, just add before it define the variable $context<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8372NEWMODULE Adding capabilities2008-04-07T14:37:07Z<p>Daniss: /* Add to your code the right triggger */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
just chenge the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of vcourse, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/support:confirm', $context)) {<br />
<br />
In order to let it works, just add before it define the variable $context<br />
<br />
global $COURSE;<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8371NEWMODULE Adding capabilities2008-04-07T14:36:31Z<p>Daniss: /* Add to your code the right triggger */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
just chenge the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of vcourse, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
==Add to your code the right triggger==<br />
<br />
Add to your code something like:<br />
<br />
if (has_capability('mod/support:confirm', $context)) {<br />
<br />
In order to let it works, just add before it define the variable $context<br />
<br />
if (! $cm = get_record("course_modules", "id", $COURSE->id)) {<br />
error("Course Module ID was incorrect");<br />
}<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8370NEWMODULE Adding capabilities2008-04-07T14:33:51Z<p>Daniss: /* Visit the "notification page" of the Admin block */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
just chenge the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of vcourse, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Site Administration block==<br />
<br />
==Add to your code the right triggger==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8369NEWMODULE Adding capabilities2008-04-07T14:33:21Z<p>Daniss: /* Change the version number of your <<NEWMODULE>> */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==<br />
just chenge the version number of your <<NEWMODULE>> by editing the file mod/version.php. Of vcourse, you have to change it with a bigger one. :-)<br />
<br />
==Visit the "notification page" of the Admin block==<br />
<br />
==Add to your code the right triggger==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8368NEWMODULE Adding capabilities2008-04-07T14:30:58Z<p>Daniss: /* Create one access.php file in the <<NEWMODULE>>/db directory. */</p>
<hr />
<div>In order to add a capabilities your <<NEWMODULE>> you have to:<br />
<br />
==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8367NEWMODULE Adding capabilities2008-04-07T14:30:08Z<p>Daniss: </p>
<hr />
<div>==Create one access.php file in the <<NEWMODULE>>/db directory.==<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.<br />
<br />
== Change the version number of your <<NEWMODULE>> ==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8366NEWMODULE Adding capabilities2008-04-07T14:29:21Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8365NEWMODULE Adding capabilities2008-04-07T14:28:50Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of these four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This defines the default selected radio button in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8364NEWMODULE Adding capabilities2008-04-07T14:27:34Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
<br />
The element 'contextlevel' is ???<br />
<br />
The element 'legacy' defines the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8363NEWMODULE Adding capabilities2008-04-07T14:27:02Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page.<br />
<br />
You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all,<br />
just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8362NEWMODULE Adding capabilities2008-04-07T14:26:24Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8361NEWMODULE Adding capabilities2008-04-07T14:25:40Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8360NEWMODULE Adding capabilities2008-04-07T14:25:19Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
and you are supposed to iterate the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
close the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8359NEWMODULE Adding capabilities2008-04-07T14:24:28Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
iterating the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure described before and, at the end,<br />
closing the main array with<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8358NEWMODULE Adding capabilities2008-04-07T14:23:51Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
iterating the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' <br />
for each <<CAPABILITYNAME>> you want to add<br />
following the same structure and, at the end, closing the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8357NEWMODULE Adding capabilities2008-04-07T14:23:28Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
iterating the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' for each <<CAPABILITYNAME>> you want to add following the same structure and, at the end, closing the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8356NEWMODULE Adding capabilities2008-04-07T14:23:12Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
iterating the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' for each <<CAPABILITYNAME>> you want to add following the same structure and, at the end, closing the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8355NEWMODULE Adding capabilities2008-04-07T14:21:47Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
<br />
iterate the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' for each <<CAPABILITYNAME>> you want to add following the same structure and, at the end, close the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8354NEWMODULE Adding capabilities2008-04-07T14:21:27Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
<br />
iterate the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' for each <<CAPABILITYNAME>> you want to add following the same structure and, at the end, close the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8353NEWMODULE Adding capabilities2008-04-07T14:20:50Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
<br />
iterate the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' for each <<CAPABILITYNAME>> you want to add following the same structure and, at the end, close the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Adding_capabilities&diff=8352NEWMODULE Adding capabilities2008-04-07T14:19:48Z<p>Daniss: </p>
<hr />
<div>Create one access.php file in the <<NEWMODULE>>/db directory.<br />
It must contain<br />
*the capabilities to be installed and<br />
*the defaults for each standard role.<br />
<br />
A model of what has to be added is: <br />
$mod_glossary_capabilities = array(<br />
<br />
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(<br />
<br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
<br />
'captype' => 'write',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
<br />
iterate the array 'mod/<<NEWMODULE>>:<<PERMISSIONNAME>>' for each <<CAPABILITYNAME>> you want to add following the same structure and, at the end, close the array<br />
)<br />
<br />
The element 'riskbitmask' will be reflected in the list of icons of each row of the 'Override permissions'->roles page. You should add the right number of icon ranging from<br />
*all four icons <br />
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,<br />
*up to no icon at all, just removing the element 'riskbitmask' from the array 'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>'<br />
<br />
The element 'captype' is ???<br />
The element 'contextlevel' is ???<br />
The element 'legacy' define the legacy default for that permission. It is an array and for each each element you are allowed to choose one (and only one) of this four elements: CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (if you don't set it). This define the default radio button selected in the 'Legacy roles' page.</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Reference&diff=8181NEWMODULE Reference2008-04-04T17:02:49Z<p>Daniss: </p>
<hr />
<div>[[NEWMODULE Documentation|NEWMODULE Documentation]] > Reference<br />
----<br />
{{Template:Work in progress}}<br />
<br />
This is a first draft of the list ot the functions more frequently used into Moodle modules. Between brakets the number of occurrences of each function in the following list of 20 modules: assignment, chat, choice, data, exercise, feedback, forum, glossary, hotpot, journal, label, lams, lesson, questionnaire, quiz, resource, scorm, survey, wiki, workshop.<br />
<br />
== newmodule_add_instance (20) ==<br />
Create a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will create a new instance and return the id number<br />
of the new instance.<br />
The due data is added to the calendar.<br />
This is common to all assignment types.<br />
<br />
== newmodule_delete_instance (20) ==<br />
Deletes an assignment activity<br />
<br />
Deletes all database records, files and calendar events for this newmodule.<br />
This is common to all assignment types.<br />
== newmodule_update_instance (20) ==<br />
Updates a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will update the newmodule instance and return the id number<br />
The due date is updated in the calendar<br />
This is common to all assignment types.<br />
<br />
== newmodule_get_participants (19) ==<br />
Returns the users with data in one newmodule<br />
<br />
(users with records in ???)<br />
<br />
== newmodule_user_complete (19) ==<br />
Print complete information about the user's interaction with the newmodule<br />
<br />
== newmodule_user_outline (19) ==<br />
Return an outline of the user's interaction with the assignment.<br />
<br />
The default method prints the grade and timemodified.<br />
<br />
== newmodule_get_post_actions (18) ==<br />
== newmodule_get_view_actions (18) ==<br />
== newmodule_cron (15) ==<br />
== newmodule_reset_userdata (12) ==<br />
This function is used by the reset_course_userdata function in moodlelib.<br />
<br />
This function will remove all posts from the specified newmodule and clean up any related data.<br />
<br />
== newmodule_print_recent_activity (11) ==<br />
== newmodule_reset_course_form_defaults (10) ==<br />
== newmodule_reset_course_form_definition (10) ==<br />
Implementation of the function for printing the form elements that control<br />
whether the course reset functionality affects the assignment.<br />
<br />
== newmodule_get_user_grades (8) ==<br />
== newmodule_grade_item_delete (8) ==<br />
== newmodule_grade_item_update (8) ==<br />
== newmodule_grades (8) ==<br />
== newmodule_update_grades (8) ==<br />
== newmodule_reset_gradebook (7) ==<br />
== newmodule_scale_used (7) ==<br />
== newmodule_scale_used_anywhere (6) ==<br />
== newmodule_get_recent_mod_activity (5) ==<br />
== newmodule_log_info (5) ==<br />
== newmodule_print_overview (5) ==<br />
== newmodule_print_recent_mod_activity (5) ==<br />
== newmodule_refresh_events (5) ==<br />
== newmodule_file_area (4) ==<br />
== newmodule_file_area_name (4) ==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Reference&diff=8180NEWMODULE Reference2008-04-04T17:01:55Z<p>Daniss: /* user_complete (19) */</p>
<hr />
<div>[[NEWMODULE Documentation|NEWMODULE Documentation]] > Reference<br />
----<br />
{{Template:Work in progress}}<br />
<br />
This is a first draft of the list ot the functions more frequently used into Moodle modules. Between brakets the number of occurrences of each function in the following list of 20 modules: assignment, chat, choice, data, exercise, feedback, forum, glossary, hotpot, journal, label, lams, lesson, questionnaire, quiz, resource, scorm, survey, wiki, workshop.<br />
<br />
== add_instance (20) ==<br />
Create a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will create a new instance and return the id number<br />
of the new instance.<br />
The due data is added to the calendar.<br />
This is common to all assignment types.<br />
<br />
== delete_instance (20) ==<br />
Deletes an assignment activity<br />
<br />
Deletes all database records, files and calendar events for this newmodule.<br />
This is common to all assignment types.<br />
== newmodule_update_instance (20) ==<br />
Updates a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will update the newmodule instance and return the id number<br />
The due date is updated in the calendar<br />
This is common to all assignment types.<br />
<br />
== newmodule_get_participants (19) ==<br />
Returns the users with data in one newmodule<br />
<br />
(users with records in ???)<br />
<br />
== newmodule_user_complete (19) ==<br />
Print complete information about the user's interaction with the newmodule<br />
<br />
== user_outline (19) ==<br />
Return an outline of the user's interaction with the assignment.<br />
<br />
The default method prints the grade and timemodified.<br />
<br />
== get_post_actions (18) ==<br />
== get_view_actions (18) ==<br />
== cron (15) ==<br />
== reset_userdata (12) ==<br />
This function is used by the reset_course_userdata function in moodlelib.<br />
<br />
This function will remove all posts from the specified newmodule and clean up any related data.<br />
<br />
== print_recent_activity (11) ==<br />
== reset_course_form_defaults (10) ==<br />
== reset_course_form_definition (10) ==<br />
Implementation of the function for printing the form elements that control<br />
whether the course reset functionality affects the assignment.<br />
<br />
== get_user_grades (8) ==<br />
== grade_item_delete (8) ==<br />
== grade_item_update (8) ==<br />
== grades (8) ==<br />
== update_grades (8) ==<br />
== reset_gradebook (7) ==<br />
== scale_used (7) ==<br />
== scale_used_anywhere (6) ==<br />
== get_recent_mod_activity (5) ==<br />
== log_info (5) ==<br />
== print_overview (5) ==<br />
== print_recent_mod_activity (5) ==<br />
== refresh_events (5) ==<br />
== file_area (4) ==<br />
== file_area_name (4) ==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Reference&diff=8179NEWMODULE Reference2008-04-04T17:01:22Z<p>Daniss: /* <<newmodule>>_update_instance (20) */</p>
<hr />
<div>[[NEWMODULE Documentation|NEWMODULE Documentation]] > Reference<br />
----<br />
{{Template:Work in progress}}<br />
<br />
This is a first draft of the list ot the functions more frequently used into Moodle modules. Between brakets the number of occurrences of each function in the following list of 20 modules: assignment, chat, choice, data, exercise, feedback, forum, glossary, hotpot, journal, label, lams, lesson, questionnaire, quiz, resource, scorm, survey, wiki, workshop.<br />
<br />
== add_instance (20) ==<br />
Create a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will create a new instance and return the id number<br />
of the new instance.<br />
The due data is added to the calendar.<br />
This is common to all assignment types.<br />
<br />
== delete_instance (20) ==<br />
Deletes an assignment activity<br />
<br />
Deletes all database records, files and calendar events for this newmodule.<br />
This is common to all assignment types.<br />
== newmodule_update_instance (20) ==<br />
Updates a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will update the newmodule instance and return the id number<br />
The due date is updated in the calendar<br />
This is common to all assignment types.<br />
<br />
== newmodule_get_participants (19) ==<br />
Returns the users with data in one newmodule<br />
<br />
(users with records in ???)<br />
<br />
== user_complete (19) ==<br />
Print complete information about the user's interaction with the newmodule<br />
<br />
== user_outline (19) ==<br />
Return an outline of the user's interaction with the assignment.<br />
<br />
The default method prints the grade and timemodified.<br />
<br />
== get_post_actions (18) ==<br />
== get_view_actions (18) ==<br />
== cron (15) ==<br />
== reset_userdata (12) ==<br />
This function is used by the reset_course_userdata function in moodlelib.<br />
<br />
This function will remove all posts from the specified newmodule and clean up any related data.<br />
<br />
== print_recent_activity (11) ==<br />
== reset_course_form_defaults (10) ==<br />
== reset_course_form_definition (10) ==<br />
Implementation of the function for printing the form elements that control<br />
whether the course reset functionality affects the assignment.<br />
<br />
== get_user_grades (8) ==<br />
== grade_item_delete (8) ==<br />
== grade_item_update (8) ==<br />
== grades (8) ==<br />
== update_grades (8) ==<br />
== reset_gradebook (7) ==<br />
== scale_used (7) ==<br />
== scale_used_anywhere (6) ==<br />
== get_recent_mod_activity (5) ==<br />
== log_info (5) ==<br />
== print_overview (5) ==<br />
== print_recent_mod_activity (5) ==<br />
== refresh_events (5) ==<br />
== file_area (4) ==<br />
== file_area_name (4) ==</div>Danisshttps://docs.moodle.org/dev/index.php?title=NEWMODULE_Reference&diff=8178NEWMODULE Reference2008-04-04T17:01:05Z<p>Daniss: /* update_instance (20) */</p>
<hr />
<div>[[NEWMODULE Documentation|NEWMODULE Documentation]] > Reference<br />
----<br />
{{Template:Work in progress}}<br />
<br />
This is a first draft of the list ot the functions more frequently used into Moodle modules. Between brakets the number of occurrences of each function in the following list of 20 modules: assignment, chat, choice, data, exercise, feedback, forum, glossary, hotpot, journal, label, lams, lesson, questionnaire, quiz, resource, scorm, survey, wiki, workshop.<br />
<br />
== add_instance (20) ==<br />
Create a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will create a new instance and return the id number<br />
of the new instance.<br />
The due data is added to the calendar.<br />
This is common to all assignment types.<br />
<br />
== delete_instance (20) ==<br />
Deletes an assignment activity<br />
<br />
Deletes all database records, files and calendar events for this newmodule.<br />
This is common to all assignment types.<br />
== <<newmodule>>_update_instance (20) ==<br />
Updates a new newmodule activity<br />
<br />
Given an object containing all the necessary data,<br />
(defined by the form in mod.html) this function<br />
will update the newmodule instance and return the id number<br />
The due date is updated in the calendar<br />
This is common to all assignment types.<br />
<br />
== newmodule_get_participants (19) ==<br />
Returns the users with data in one newmodule<br />
<br />
(users with records in ???)<br />
<br />
== user_complete (19) ==<br />
Print complete information about the user's interaction with the newmodule<br />
<br />
== user_outline (19) ==<br />
Return an outline of the user's interaction with the assignment.<br />
<br />
The default method prints the grade and timemodified.<br />
<br />
== get_post_actions (18) ==<br />
== get_view_actions (18) ==<br />
== cron (15) ==<br />
== reset_userdata (12) ==<br />
This function is used by the reset_course_userdata function in moodlelib.<br />
<br />
This function will remove all posts from the specified newmodule and clean up any related data.<br />
<br />
== print_recent_activity (11) ==<br />
== reset_course_form_defaults (10) ==<br />
== reset_course_form_definition (10) ==<br />
Implementation of the function for printing the form elements that control<br />
whether the course reset functionality affects the assignment.<br />
<br />
== get_user_grades (8) ==<br />
== grade_item_delete (8) ==<br />
== grade_item_update (8) ==<br />
== grades (8) ==<br />
== update_grades (8) ==<br />
== reset_gradebook (7) ==<br />
== scale_used (7) ==<br />
== scale_used_anywhere (6) ==<br />
== get_recent_mod_activity (5) ==<br />
== log_info (5) ==<br />
== print_overview (5) ==<br />
== print_recent_mod_activity (5) ==<br />
== refresh_events (5) ==<br />
== file_area (4) ==<br />
== file_area_name (4) ==</div>Daniss