Form API
Overview
Web Forms in moodle are created using forms API. Form API supports all html elements (checkbox, radio, textbox etc), with improved accessibility and security.
Highlights
- Tested and optimised for use on major screen-readers Dragon and JAWS.
- Tableless layout.
- Process form data securely, with required_param, optional_param and session key.
- Supports client-side validation
- Facility to add Moodle help buttons to forms.
- Support for file repository using File_API
- Support for many custom moodle specific and non-specific form elements.
- Addition for repeated elements.
- Addition for form elements in advance group
Usage
For creating a form in moodle, you have to create class extending moodleform class and override definition for including form elements.
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");
class simplehtml_form extends moodleform {
//Add elements to form
function definition() {
global $CFG;
$mform =& $this->_form; // Don't forget the underscore!
$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
Then instantiate form (in this case simplehtml_form) on your page.
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');
//Instantiate simplehtml_form
$mform = new simplehtml_form();
//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.
//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
Form elements
Basic form elements
- button
- checkbox
- radio
- select
- multi-select
- password
- hidden
- html - div element
- static - Display a static text.
- text
- textarea
Custom form elements
- advcheckbox - Advance checkbox
- passwordunmask - A password element with option to show the password in plaintext.
- recaptcha
- selectyesno
- selectwithlink
- date_selector
- date_time_selector
- duration
- editor
- [1] - upload single file
- filemanager - upload multiple files
- tags
- addGroup
- modgrade
- modvisible
- choosecoursefile
- grading
- questioncategory
Commonly used functions
add_action_buttons($cancel = true, $submitlabel=null);
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'). Note the $this not $mform
$this->add_action_buttons();
setDefault()
To set the default value for an element.
disableif()
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.
addRule()
Add rule for server/client side validation. Like text field is required element and is of type email.
setHelpButton()
Sets pop-up help button to a form element.
addHelpButton()
Adds pop-up help button to a form element
setType()
PARAM_* types are used to specify how a submitted variable should be cleaned.
See
Core_APIs lib/formslib.php_Usage lib/formslib.php_Form_Definition