Moodle Quick Forms

Moodle - lib/formslib

Contents

Introduction to Moodle_QuickForm

Usage

Definition

Validation

Introduction to Moodle_QuickForm

Accessibility improvements : Input fields labeled Tableless layout.

Process form data securely done through required_param, optional_param, etc

Process submitted data themselves and

Check the submitted data

Cont…

Form validation with custom validation() or addRule QuickForms validation

Feedback to the user about required input and errors in user input.

Facility to add Moodle help buttons to forms.

upload_manager processes uploaded files securely.

Cont…

Custom Moodle specific and non specific form elements

Specific elements modgrade, modvisible, modgroupmode and choosecoursefile, format

Non specific elements htmleditor, dateselector, datetimeselector, selectyesno

Lots of modification to regular elements.

Easy to define your own custom elements.

Usage

Definition addElement() closeHeaderBefore() setHelpButton() addGroup() setType() setDefault() addRule() add_action_buttons() Other

definition()

addElement()

Syntax : $form->addElement ( type, name, label, …)

Example :

$form->addElement ( 'header', 'General', get_string('generalheader'));

$form->addElement ( 'checkbox', 'mycheck', get_string('mycheckbutton'), array('group' => 1), array(0,1));

$form->addElement ( 'date_time_selector', 'd_t', get_string('d_t'));

$mform->addElement ('choosecoursefile', 'mediafile', 'Course file upload', array('courseid'=>null, 'height'=>500, 'width'=>750, 'options'=>'none')

closeHeaderBefore()

Syntax : $form->closeHeaderBefore ( element_name )

setHelpButton()

Syntax : $form->setHelpButton ( element_name,

array( help_filename, title, module), supress_check )

$mform->setHelpButton('questionsperpage',

array( 'questionsperpage', get_string( 'questionsperpage', 'quiz' ), 'quiz' ) )

Example :

addGroup()

$buttonarray = array();

$buttonarray[] =& $mform->createElement(‘submit’, ‘save', get_string('save'));

$buttonarray[] =& $mform->createElement(‘submit’, 'cancel', get_string('cancel'));

$mform->addGroup($buttonarray, 'buttonar', ‘’, array(' '), false);

$buttonarray = array();

$buttonarray[] =& $mform->createElement(‘submit’, ‘save', get_string('save'));

$buttonarray[] =& $mform->createElement(‘submit’, 'cancel', get_string('cancel'));

$mform->addGroup($buttonarray, 'buttonar', ‘’, array(' '), false);

A 'group' in formslib is just a group of elements that will have a

label and will be included on one line.

Def :

setType()

Some elements other than checkbox, radio, select clean themselves but other requires cleaning

PARAM_* types are used to specify how a submitted variable should be cleaned.

Syntax : $form->setType ( element_name, type)

Example :

Most Commonly Used PARAM_* Types :

PARAM_CLEAN Deprecated

PARAM_TEXT Cleaning the plain text data. Strips all html tags.

PARAM_NOTAGS

1. cleaning data that is expected to be plain text.

2. It will strip *all* html type tags. It will still *not* let tags for

multilang support through.

3. This should be used for instance for email addresses where no

multilang support is appropriate.

PARAM_RAW

1. no cleaning whatsoever (Data coming from HTML editor)

2. Data from the editor is later cleaned before display using

format_text() function

PARAM_INT Used for Integers

PARAM_ACTIONalias of PARAM_ALPHA and is used for hidden fields specifying form

actions

setDefault()

Syntax : $form->setDefault ( element_name, default value)

Example :

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

addRule()

$mform->addRule ( ‘elementname’, ‘error_message’, ‘ruletype’, ‘external_ruledata’, ‘server/client’, ‘reset(bool)’ , ‘force(bool)’ )

Syntax :

Common Rule Types

required maxlength minlength rangelength

email regex lettersonly

alphanumeric numeric nopunctuation

nonzero callback compare

Cont…

add_action_buttons

$this->add_action_buttons ($cancel = true, $submitlabel=null)

Syntax :

• param: boolean $cancel whether to show cancel button, default true

• param: string $submitlabel label for submit button, defaults to get_string('savechanges')

• Note: Should be always present at the end of all the form elements.

Other

setMultiple(bool) - used with select element

save_files() After submitting a form, all the form information is get through get_data() function.

save_files() function used for that FORM saves all the files uploaded to specified directory.

Cont… registerRule()

$mform->registerRule ($name , $type , $data1 , $data2 )

$name = name of function / name of validation rule

$type = 'regex' or 'callback' ('function' is also kept for backward compatibility)

$data1 = Name of function, regular expression, classname , callback function needs to return true or false

$data2 = Object parent of above function, name of the file

Where,

Cont…

disabledIf()$mform->disabledIf ( $elementName, $dependentOn,

$condition = 'notchecked', $value=null)

elementname – Name of the group or name of the element.

dependentOn –

is the actual name of the element as it will appear in html. Can be different for addGroup elements. You typically make the depedentOn a checkbox or select box.

disabledif() Cont…

$condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, 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.

If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Validation

Two ways : MoodleQuickForm::addRule() moodleform::validation()

validation()

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.

MoodleQuickForm::addRule()

Default error messages are defined in lang/{language}/form.php

moodleform::validation() $data = contains all the

values set on submitting

the value.

$data is array which

contains value in following

form:

$data[‘elementname’]

Example:

$s = $data[‘shortname’];

$error = is an array which stores error, while validating the submitted data.

Syntax: $error[‘elementname’]

Where, elementname should be same as name given while creating form.

Cont…

$files in validation function is extra parameter for validating

the files which are to be uploaded to system

References

http://docs.moodle.org/en/Category:Formslibhttp://www.moodle.org/http://pear.php.net/