Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

lib/formslib.php Form Definition

From MoodleDocs
Revision as of 13:30, 1 December 2006 by Jamie Pratt (talk | contribs) (setHelpButton & setDefault section added)

definition()

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();

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.

Use Fieldsets to group Form Elements

You use code like this to open a fieldset with a legend.

//-------------------------------------------------------------------------------
        $mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with this code. You tell addStopFieldsetElements 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 fieldset  :

        //possibly at the start of definition();
	$mform    =& $this->_form;
        $renderer =& $mform->defaultRenderer();


        $renderer->addStopFieldsetElements('buttonar');



disabledIf

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

  • 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.
  • 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.
  • $condition will be notchecked, checked, eq or if it is anything else then we test for neq.
  • If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
  • If $condition is checked or notchecked then we check to see if a checkbox is checked or not.

setType

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).

Most Commonly Used PARAM_* Types

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

  • PARAM_CLEAN is deprecated and you should try to use a more specific type.
  • 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.
  • 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.
  • 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().
  • PARAM_INT should be used for integers.
  • PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

addElement

Use the addElement method to add a 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.

Some examples are below :

button

            $mform->addElement('button', 'intro', get_string("buttonlabel"));

A button element. If you want a submit or cancel button see 'submit' element.

checkbox

        $mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));

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.

choosecoursefile

        $mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));

Choose a file from the course files area. The fourth option is a list of options for the element.

array('courseid'=>null,\\if it is null (default then use globabl $COURSE
 'height'=>500,\\ height of the popup window
 'width'=>750, \\ width of the popup window
'options'=>'none');\\options string for the pop up window 
                   \\eg. 'menubar=0,location=0,scrollbars,resizable'


date_selector

        $mform->addElement('date_selector', 'assesstimefinish', get_string('to'));

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 :

array('startyear'=>1970, 'stopyear'=>2020,
                    'timezone'=>99, 'applydst'=>true);

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.

date_time_selector

        $mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));

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->data_submitted(); The fourth param here is an array of options. The defaults for the options are :

array('startyear'=>1970, 'stopyear'=>2020,
                    'timezone'=>99, 'applydst'=>true, 'step'=>5);

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.

hidden

         $mform->addElement('hidden', 'reply');

A hidden element.

htmleditor & format


        $mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
        $mform->setType('text', PARAM_RAW);
	$mform->addRule('text', null, 'required', null, 'client');

        $mform->addElement('format', 'format', get_string('format'));

You can supply a fourth param to htmleditor of an array of options :

array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65, 
'width'=>0,'height'=>0, 'course'=>0);
//options same as print_textarea params
//use rows and params to control htmleditor size.

modgrade

        $mform->addElement('modgrade', 'scale', get_string('grade'), false);

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.

A helpbutton is automatically added.


password

         $mform->addElement('password', 'password', get_string('label'), $attributes);

A password element. Fourth param is an array or string of attributes.

radio

        $radioarray=array();
        $radioarray[] = &MoodleQuickForm::createElement('radio', 'yes', '', get_string('yes'), 1, $attributes);
        $radioarray[] = &MoodleQuickForm::createElement('radio', 'no', '', get_string('no'), 0, $attributes);
        $mform->addGroup($radioarray, 'radioar', '', array(' '), false);

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.

select

        $mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES);

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.

selectyesno

        $mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

static

         $mform->addElement('static', 'description', get_string('description', 'exercise'),
                  get_string('descriptionofexercise', 'exercise', $COURSE->students));

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.

submit

        $buttonarray=array();
        $buttonarray[] = &MoodleQuickForm::createElement('submit', 'submitbutton', get_string('savechanges'));
        $buttonarray[] = &MoodleQuickForm::createElement('submit', 'cancel', get_string('cancel'));
        $mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
		$renderer->addStopFieldsetElements('buttonar');

A submit type form element which will submit the form.


text

        $mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);

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 :

        $attributes='size="20"';
        $attributes=array('size'=>'20');

Generally you are encouraged to use css instead of using attributes for styling.


A format element can be used as a format select box. It will be non selectable if you're using a html editor.

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.

textarea

            $mform->addElement('textarea', 'intro', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

setHelpButton

            $mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));

First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

 * @param string $page  The keyword that defines a help page
 * @param string $title The title of links, rollover tips, alt tags etc
 *           'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
 * @param string $module Which module is the page defined in
 * @param mixed $image Use a help image for the link?  (true/false/"both")
 * @param boolean $linktext If true, display the title next to the help icon.
 * @param string $text If defined then this text is used in the page, and
 *           the $page variable is ignored.
 * @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
 * @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif

Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

setDefault

        $mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
        $mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
        $mform->setDefault('grade', 100);

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_default(); eg. on display of the form for an 'add' rather than 'update' function.

addGroup

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

        $buttonarray=array();
        $buttonarray[] = &MoodleQuickForm::createElement('submit', 'submitbutton', get_string('savechanges'));
        $buttonarray[] = &MoodleQuickForm::createElement('submit', 'cancel', get_string('cancel'));
        $mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);

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).

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:

        $availablefromgroup=array();
	$availablefromgroup[]=&MoodleQuickForm::createElement('date_selector', 'availablefrom', '');
	$availablefromgroup[]=&MoodleQuickForm::createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
        $mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
        $mform->disabledIf('availablefromgroup', 'availablefromenabled');