Form API - Revision history

Devdocsbot: Protected "Form API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-06-17T06:40:12Z

Protected "Form API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 06:40, 17 June 2022
(No difference)

Devdocsbot: Update migration status and path

2022-06-17T06:38:12Z

Update migration status and path

← Older revision		Revision as of 06:38, 17 June 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/subsystems/form/}}
	==Overview==		==Overview==
	[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.		[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.

Systemovich: /* Usage */

2022-02-04T09:48:16Z

Usage

← Older revision		Revision as of 09:48, 4 February 2022
Line 12:		Line 12:
	# Facility for form elements in advanced group		# Facility for form elements in advanced group
	==Usage==		==Usage==
	~~For creating~~ a form in ~~moodle~~, you have to create class ~~extending~~ moodleform class and ~~override~~ [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.		To create a form in Moodle, you have to create a class that extends the moodleform class and overrides the [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] member function for including form elements.
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	//moodleform is defined in formslib.php		//moodleform is defined in formslib.php
Line 24:		Line 24:
	$mform = $this->_form; // Don't forget the underscore!		$mform = $this->_form; // Don't forget the underscore!

	$mform->addElement('text', 'email', get_string('email')); // Add elements to your form		$mform->addElement('text', 'email', get_string('email')); // Add elements to your form.
	$mform->setType('email', PARAM_NOTAGS); //Set type of element		$mform->setType('email', PARAM_NOTAGS); // Set type of element.
	$mform->setDefault('email', 'Please enter email'); //Default value		$mform->setDefault('email', 'Please enter email'); // Default value.
	...		...
	}		}
Line 35:		Line 35:
	}		}
	</syntaxhighlight>		</syntaxhighlight>
	Then instantiate form (in this case simplehtml_form) on your page.		Then instantiate the form (in this case simplehtml_form) on your page.
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	//include simplehtml_form.php		//include simplehtml_form.php

Systemovich: /* Highlights */

2022-02-04T09:37:36Z

Highlights

Systemovich: /* Overview */

2022-02-04T09:34:13Z

Overview

← Older revision		Revision as of 09:34, 4 February 2022
Line 1:		Line 1:
	==Overview==		==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.		[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.
	==Highlights==		==Highlights==
	# Tested and optimised for use on major screen-readers Dragon and JAWS.		# Tested and optimised for use on major screen-readers Dragon and JAWS.
Line 11:		Line 11:
	# Addition for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].		# Addition for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].
	# Addition for form elements in advance group		# Addition for form elements in advance group

	==Usage==		==Usage==
	For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.		For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
Line 59:		Line 58:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	If you wish to use the form within a block then you should consider using the render method, as demonstrated below:		If you wish to use the form within a block then you should consider using the render method, as demonstrated below:

	Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.		Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.

	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	class block_yourblock extends block_base{		class block_yourblock extends block_base{
Line 97:		Line 94:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	==Form elements==		==Form elements==
	===Basic form elements===		===Basic form elements===
Line 112:		Line 108:
	# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]		# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]
	# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements header]		# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements header]

	=== Advanced form elements===		=== Advanced form elements===

	# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.		# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.
	# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox		# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
Line 135:		Line 129:
	# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]		# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
	# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]		# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]

	===Custom form elements===		===Custom form elements===

	If you need a custom form element you can dynamical register new elements and then use them like this:		If you need a custom form element you can dynamical register new elements and then use them like this:

Line 148:		Line 140:
	$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);		$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);
	</syntaxhighlight>		</syntaxhighlight>

	See:		See:

Line 154:		Line 145:

	https://github.com/moodle/moodle/blob/master/admin/tool/lp/classes/course_competency_rule_form_element.php		https://github.com/moodle/moodle/blob/master/admin/tool/lp/classes/course_competency_rule_form_element.php

	==Commonly used functions==		==Commonly used functions==

	====add_action_buttons($cancel = true, $submitlabel=null);====		====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'''		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'''

	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$this->add_action_buttons();		$this->add_action_buttons();
	</syntaxhighlight>		</syntaxhighlight>

	====[[lib/formslib.php_Form_Definition#setDefault_2\|setDefault()]]====		====[[lib/formslib.php_Form_Definition#setDefault_2\|setDefault()]]====
	To set the default value for an element.		To set the default value for an element.

	====[[lib/formslib.php_Form_Definition#disabledIf\|disabledIf()]]====		====[[lib/formslib.php_Form_Definition#disabledIf\|disabledIf()]]====
	For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.		For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

	====[[lib/formslib.php_Form_Definition#hideIf\|hideif()]]====		====[[lib/formslib.php_Form_Definition#hideIf\|hideif()]]====
	For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.		For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
	Same syntax as disabledIf. Can do a simple search and replace on disabledIf. Added in Moodle 3.4.		Same syntax as disabledIf. Can do a simple search and replace on disabledIf. Added in Moodle 3.4.

	====[[lib/formslib.php_Form_Definition#addRule\|addRule()]]====		====[[lib/formslib.php_Form_Definition#addRule\|addRule()]]====
	Add rule for server/client side validation. Like text field is required element and is of type email.		Add rule for server/client side validation. Like text field is required element and is of type email.

	====setHelpButton()====		====setHelpButton()====
	DEPRECATED - Sets pop-up help button to a form element. Use addHelpButton() instead.		DEPRECATED - Sets pop-up help button to a form element. Use addHelpButton() instead.

	====[[lib/formslib.php_Form_Definition#addHelpButton\|addHelpButton()]]====		====[[lib/formslib.php_Form_Definition#addHelpButton\|addHelpButton()]]====
	Adds pop-up help button to a form element		Adds pop-up help button to a form element

	====[[lib/formslib.php_Form_Definition#setType\|setType()]]====		====[[lib/formslib.php_Form_Definition#setType\|setType()]]====
	PARAM_* types are used to specify how a submitted variable should be cleaned.		PARAM_* types are used to specify how a submitted variable should be cleaned.

	====[[lib/formslib.php_Form_Definition#disable_form_change_checker\|disable_form_change_checker()]]====		====[[lib/formslib.php_Form_Definition#disable_form_change_checker\|disable_form_change_checker()]]====
	By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.		By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.

	==FAQ==		==FAQ==
	[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]		[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
	==See also==		==See also==

	* [[Core_APIs]]		* [[Core_APIs]]
	* [[lib/formslib.php_Usage]]		* [[lib/formslib.php_Usage]]
Line 200:		Line 177:
	* [[Fragment]]		* [[Fragment]]
	* [[MForm_Modal]]		* [[MForm_Modal]]

	[[Category:API]]		[[Category:API]]

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:34:29Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:34, 14 July 2021
				
Line 14:
Line 14:
==Usage== ==Usage==
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements. For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
<code php> <syntaxhighlight lang="php">
//moodleform is defined in formslib.php //moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php"); require_once("$CFG->libdir/formslib.php");
Line 37:
Line 37:
</syntaxhighlight> </syntaxhighlight>
Then instantiate form (in this case simplehtml_form) on your page. Then instantiate form (in this case simplehtml_form) on your page.
<code php> <syntaxhighlight lang="php">
//include simplehtml_form.php //include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php'); require_once('PATH_TO/simplehtml_form.php');
Line 64:
Line 64:
Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form. Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.



<code php> <syntaxhighlight lang="php">
class block_yourblock extends block_base{ class block_yourblock extends block_base{
	public function init(){ 	public function init(){
Line 161:
Line 161:
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''' 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'''



<code php> <syntaxhighlight lang="php">
    $this->add_action_buttons();     $this->add_action_buttons();
</syntaxhighlight> </syntaxhighlight>

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:09:51Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:09, 14 July 2021
Line 35:		Line 35:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>
	Then instantiate form (in this case simplehtml_form) on your page.		Then instantiate form (in this case simplehtml_form) on your page.
	<code php>		<code php>
Line 58:		Line 58:
	$mform->display();		$mform->display();
	}		}
	</~~code~~>		</syntaxhighlight>

	If you wish to use the form within a block then you should consider using the render method, as demonstrated below:		If you wish to use the form within a block then you should consider using the render method, as demonstrated below:
Line 96:		Line 96:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	==Form elements==		==Form elements==
Line 147:		Line 147:
	// Reuse the same options.		// Reuse the same options.
	$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);		$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);
	</~~code~~>		</syntaxhighlight>

	See:		See:
Line 163:		Line 163:
	<code php>		<code php>
	$this->add_action_buttons();		$this->add_action_buttons();
	</~~code~~>		</syntaxhighlight>

	====[[lib/formslib.php_Form_Definition#setDefault_2\|setDefault()]]====		====[[lib/formslib.php_Form_Definition#setDefault_2\|setDefault()]]====

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:03:08Z
Text replacement - "<code>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:03, 14 July 2021
				
Line 141:
Line 141:






<code> <syntaxhighlight lang="php">
     MoodleQuickForm::registerElementType('course_competency_rule',      MoodleQuickForm::registerElementType('course_competency_rule',
                                          "$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",                                           "$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",



Bencellis: /* setHelpButton() */
2020-12-12T10:23:21Z
setHelpButton()

				
				
				
				
				
				← Older revision
				Revision as of 10:23, 12 December 2020
				
Line 179:
Line 179:



====setHelpButton()==== ====setHelpButton()====
DEPRECATED - Sets pop-up help button to a form element. DEPRECATED - Sets pop-up help button to a form element.  Use addHelpButton() instead.



====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]==== ====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====



Bencellis: /* setHelpButton() */
2020-12-12T10:22:48Z
setHelpButton()

				
				
				
				
				
				← Older revision
				Revision as of 10:22, 12 December 2020
				
Line 178:
Line 178:
Add rule for server/client side validation. Like text field is required element and is of type email. Add rule for server/client side validation. Like text field is required element and is of type email.



====[[lib/formslib.php_Form_Definition#setHelpButton|setHelpButton()]]==== ====setHelpButton()====
Sets pop-up help button to a form element. DEPRECATED - Sets pop-up help button to a form element.



====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]==== ====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====

← Older revision		Revision as of 09:37, 4 February 2022
Line 2:		Line 2:
	[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.		[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.
	==Highlights==		==Highlights==
	# Tested and optimised for use on major screen-readers Dragon and JAWS.		# Tested and optimised for use on major screen-readers like Dragon and JAWS.
	# Tableless layout.		# Tableless layout.
	# ~~Process~~ form data securely, with required_param, optional_param and session key.		# Processes form data securely, with required_param, optional_param and session key.
	# Supports client-side validation		# Supports client-side validation.
	# Facility to add Moodle help buttons to forms.		# Facility to add Moodle help buttons to forms.
	# Support for file repository using [[File_API]]		# Support for file repository using [[File_API]] .
	# Support for many custom ~~moodle~~ specific and non-specific form elements.		# Support for many custom Moodle specific and non-specific form elements.
	# ~~Addition~~ for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].		# Facility for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].
	# ~~Addition~~ for form elements in ~~advance~~ group		# Facility for form elements in advanced group
	==Usage==		==Usage==
	For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.		For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.

← Older revision		Revision as of 13:34, 14 July 2021
Line 14:		Line 14:
	==Usage==		==Usage==
	For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.		For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
	<~~code~~ php>		<syntaxhighlight lang="php">
	//moodleform is defined in formslib.php		//moodleform is defined in formslib.php
	require_once("$CFG->libdir/formslib.php");		require_once("$CFG->libdir/formslib.php");
Line 37:		Line 37:
	</syntaxhighlight>		</syntaxhighlight>
	Then instantiate form (in this case simplehtml_form) on your page.		Then instantiate form (in this case simplehtml_form) on your page.
	<~~code~~ php>		<syntaxhighlight lang="php">
	//include simplehtml_form.php		//include simplehtml_form.php
	require_once('PATH_TO/simplehtml_form.php');		require_once('PATH_TO/simplehtml_form.php');
Line 64:		Line 64:
	Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.		Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.

	<~~code~~ php>		<syntaxhighlight lang="php">
	class block_yourblock extends block_base{		class block_yourblock extends block_base{
	public function init(){		public function init(){
Line 161:		Line 161:
	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'''		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'''

	<~~code~~ php>		<syntaxhighlight lang="php">
	$this->add_action_buttons();		$this->add_action_buttons();
	</syntaxhighlight>		</syntaxhighlight>

← Older revision		Revision as of 13:03, 14 July 2021
Line 141:		Line 141:


	<~~code~~>		<syntaxhighlight lang="php">
	MoodleQuickForm::registerElementType('course_competency_rule',		MoodleQuickForm::registerElementType('course_competency_rule',
	"$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",		"$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",

← Older revision		Revision as of 10:23, 12 December 2020
Line 179:		Line 179:

	====setHelpButton()====		====setHelpButton()====
	DEPRECATED - Sets pop-up help button to a form element.		DEPRECATED - Sets pop-up help button to a form element. Use addHelpButton() instead.

	====[[lib/formslib.php_Form_Definition#addHelpButton\|addHelpButton()]]====		====[[lib/formslib.php_Form_Definition#addHelpButton\|addHelpButton()]]====

← Older revision		Revision as of 10:22, 12 December 2020
Line 178:		Line 178:
	Add rule for server/client side validation. Like text field is required element and is of type email.		Add rule for server/client side validation. Like text field is required element and is of type email.

	====~~[[lib/formslib.php_Form_Definition#setHelpButton\|~~setHelpButton()]]====		====setHelpButton()====
	Sets pop-up help button to a form element.		DEPRECATED - Sets pop-up help button to a form element.

	====[[lib/formslib.php_Form_Definition#addHelpButton\|addHelpButton()]]====		====[[lib/formslib.php_Form_Definition#addHelpButton\|addHelpButton()]]====

Form API - Revision history

Devdocsbot: Protected "Form API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

Devdocsbot: Update migration status and path

Systemovich: /* Usage */

Systemovich: /* Highlights */

Systemovich: /* Overview */

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Bencellis: /* setHelpButton() */

Bencellis: /* setHelpButton() */

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""

Mudrd8mz: Text replacement - "`" to ""`