Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
MoodleQuickForm Class Reference
Inheritance diagram for MoodleQuickForm:

Public Member Functions

 __construct ($formName, $method, $action, $target='', $attributes=null, $ajaxformdata=null)
 Class constructor - same parameters as HTML_QuickForm_DHTMLRulesTableless. More...
 
 _getElNamesRecursive ($element)
 Get names of element or elements in a group. More...
 
 _registerCancelButton ($addfieldsname)
 Registers a button as cancel button. More...
 
 _setDefaultRuleMessages ()
 Sets default error message.
 
 accept (&$renderer)
 Accepts a renderer. More...
 
 addAdvancedStatusElement ($headerid, $showmore=false)
 Use this method to add show more/less status element required for passing over the advanced elements visibility status on the form submission. More...
 
 addGroupRule ($group, $arg1, $type='', $format=null, $howmany=0, $validation='server', $reset=false)
 Adds a validation rule for the given group of elements. More...
 
 addHelpButton ($elementname, $identifier, $component='moodle', $linktext='', $suppresscheck=false)
 Add a help button to element, only one button per element is allowed. More...
 
 addRule ($element, $message, $type, $format=null, $validation='server', $reset=false, $force=false)
 Adds a validation rule for the given field. More...
 
 closeHeaderBefore ($elementName)
 Adds one or more element names that indicate the end of a fieldset. More...
 
 disable_form_change_checker ()
 Call this method if you don't want the formchangechecker JavaScript to be automatically initialised for this form.
 
 disabledIf ($elementName, $dependentOn, $condition='notchecked', $value='1')
 Adds a dependency for $elementName which will be disabled if $condition is met. More...
 
 enable_form_change_checker ()
 If you have called disable_form_change_checker() then you can use this method to re-enable it. More...
 
 exportValues ($elementList=null)
 export submitted values More...
 
 getAdvancedHTML ()
 Returns HTML for advanced elements. More...
 
 getCleanedValue ($value, $type)
 Return the cleaned value using the passed type(s). More...
 
 getCleanType ($elementname, $value, $default=PARAM_RAW)
 Return the type(s) to use to clean an element. More...
 
 getLockOptionObject ()
 Get list of attributes which have dependencies. More...
 
 getReqHTML ()
 Returns HTML for required elements. More...
 
 getShowAdvanced ()
 This function has been deprecated. More...
 
 getValidationScript ()
 Returns the client side validation script. More...
 
 hardFreeze ($elementList=null)
 Displays elements without HTML input tags. More...
 
 hardFreezeAllVisibleExcept ($elementList)
 Hard freeze all elements in a form except those whose names are in $elementList or hidden elements in a form. More...
 
 hideIf ($elementname, $dependenton, $condition='notchecked', $value='1')
 Adds a dependency for $elementName which will be hidden if $condition is met. More...
 
 is_dirty ()
 Is the form currently set to dirty? More...
 
 is_form_change_checker_enabled ()
 
 is_new_repeat ($name)
 Check if the element with the given name has just been added by clicking on the 'Add repeating elements' button. More...
 
 isNoSubmitButton ($buttonname)
 Checks if button is a no submit button, i.e it doesn't submit form. More...
 
 isSubmitted ()
 Tells whether the form was already submitted. More...
 
 MoodleQuickForm ($formName, $method, $action, $target='', $attributes=null)
 Old syntax of class constructor. More...
 
 note_new_repeat ($name)
 Add the element name to the list of newly-created repeat elements (So that elements that interpret 'no data submitted' as a valid state can tell when they should get the default value instead). More...
 
 optional_param ($name, $default, $type)
 Checks if a parameter was passed in the previous form submission. More...
 
 registerNoSubmitButton ($buttonname)
 Registers button as no submit button. More...
 
 set_initial_dirty_state ($state=false)
 Set the initial 'dirty' state of the form. More...
 
 setAdvanced ($elementName, $advanced=true)
 Use this method to indicate an element in a form is an advanced field. More...
 
 setConstant ($elname, $value)
 Set constant value not overridden by _POST or _GET note: this does not work for complex names with [] :-(. More...
 
 setDefault ($elementName, $defaultValue)
 Initializes a default form value. More...
 
 setDisableShortforms ($disable=true)
 Use this method to indicate that the form will not be using shortforms. More...
 
 setExpanded ($headername, $expanded=true, $ignoreuserstate=false)
 Use this method to indicate that the fieldset should be shown as expanded. More...
 
 setForceLtr ($elementname, $value=true)
 Set an element to be forced to flow LTR. More...
 
 setShowAdvanced ($showadvancedNow=null)
 This function has been deprecated. More...
 
 setType ($elementname, $paramtype)
 Should be used for all elements of a form except for select, radio and checkboxes which clean their own data. More...
 
 setTypes ($paramtypes)
 This can be used to set several types at once. More...
 
 updateSubmission ($submission, $files)
 Updates submitted values. More...
 

Public Attributes

array $_advancedElements = array()
 Array whose keys are element names. More...
 
array $_cancelButtons =array()
 Array of buttons that if pressed do not result in the processing of the form.
 
array $_collapsibleElements = array()
 Array whose keys are element names and values are the desired collapsible state. More...
 
array $_dependencies = array()
 dependent state for the element/'s
 
boolean $_disableShortforms = false
 Whether to enable shortforms for this form.
 
string $_formName = ''
 The form name is derived from the class name of the wrapper minus the trailing form It is a name with words joined by underscores whereas the id attribute is words joined by underscores.
 
array $_noSubmitButtons =array()
 Array of buttons that if pressed do not result in the processing of the form.
 
string $_pageparams = ''
 String with the html for hidden params passed in as part of a moodle_url object for the action. More...
 
array $_types = array()
 type (PARAM_INT, PARAM_TEXT etc) of element value
 
const DEP_DISABLE = 0
 Is this a 'disableIf' dependency ?
 
const DEP_HIDE = 1
 Is this a 'hideIf' dependency?
 

Protected Member Functions

 prepare_fixed_value ($name, $value)
 This is a bit of a hack, and it duplicates the code in HTML_QuickForm_element::_prepareValue, but I could not think of a way or reliably calling that code. More...
 

Protected Attributes

array $_ajaxformdata
 $_ajaxformdata submitted form data when using mforms with ajax
 
array $_hideifs = array()
 elements that will become hidden based on another element
 
bool $_initial_form_dirty_state = false
 The initial state of the dirty state.
 
array $_newrepeats = array()
 names of new repeating elements that should not expect to find submitted data
 
bool $_use_form_change_checker = true
 whether to automatically initialise M.formchangechecker for this form.
 
bool $clientvalidation = false
 Whether the form contains any client-side validation or not.
 

Constructor & Destructor Documentation

◆ __construct()

MoodleQuickForm::__construct (   $formName,
  $method,
  $action,
  $target = '',
  $attributes = null,
  $ajaxformdata = null 
)

Class constructor - same parameters as HTML_QuickForm_DHTMLRulesTableless.

@staticvar int $formcounter counts number of forms

Parameters
string$formNameForm's name.
string$methodForm's method defaults to 'POST'
string | moodle_url$actionForm's action
string$target(optional)Form's target defaults to none
mixed$attributes(optional)Extra attributes for <form> tag
array$ajaxformdataForms submitted via ajax, must pass their data here, instead of relying on _GET and _POST.

Member Function Documentation

◆ _getElNamesRecursive()

MoodleQuickForm::_getElNamesRecursive (   $element)

Get names of element or elements in a group.

Parameters
HTML_QuickForm_group | element$elementelement group or element object
Return values
array

◆ _registerCancelButton()

MoodleQuickForm::_registerCancelButton (   $addfieldsname)

Registers a button as cancel button.

Parameters
string$addfieldsnamename of the button

◆ accept()

MoodleQuickForm::accept ( $renderer)

Accepts a renderer.

Parameters
HTML_QuickForm_Renderer$rendererAn HTML_QuickForm_Renderer object

◆ addAdvancedStatusElement()

MoodleQuickForm::addAdvancedStatusElement (   $headerid,
  $showmore = false 
)

Use this method to add show more/less status element required for passing over the advanced elements visibility status on the form submission.

Parameters
string$headerNameheader element name.
boolean$showmoredefault false sets the advanced elements to be hidden.

◆ addGroupRule()

MoodleQuickForm::addGroupRule (   $group,
  $arg1,
  $type = '',
  $format = null,
  $howmany = 0,
  $validation = 'server',
  $reset = false 
)

Adds a validation rule for the given group of elements.

Only groups with a name can be assigned a validation rule Use addGroupRule when you need to validate elements inside the group. Use addRule if you need to validate the group as a whole. In this case, the same rule will be applied to all elements in the group. Use addRule if you need to validate the group against a function.

Parameters
string$groupForm group name
array | string$arg1Array for multiple elements or error message string for one element
string$type(optional)Rule type use getRegisteredRules() to get types
string$format(optional)Required for extra rule data
int$howmany(optional)How many valid elements should be in the group
string$validation(optional)Where to perform validation: "server", "client"
bool$resetClient-side: whether to reset the element's value to its original state if validation failed.

◆ addHelpButton()

MoodleQuickForm::addHelpButton (   $elementname,
  $identifier,
  $component = 'moodle',
  $linktext = '',
  $suppresscheck = false 
)

Add a help button to element, only one button per element is allowed.

This is new, simplified and preferable method of setting a help icon on form elements. It uses the new $OUTPUT->help_icon().

Typically, you will provide the same identifier and the component as you have used for the label of the element. The string identifier with the _help suffix added is then used as the help string.

There has to be two strings defined: 1/ get_string($identifier, $component) - the title of the help page 2/ get_string($identifier.'_help', $component) - the actual help page text

Since
Moodle 2.0
Parameters
string$elementnamename of the element to add the item to
string$identifierhelp string identifier without _help suffix
string$componentcomponent name to look the help string in
string$linktextoptional text to display next to the icon
bool$suppresscheckset to true if the element may not exist

◆ addRule()

MoodleQuickForm::addRule (   $element,
  $message,
  $type,
  $format = null,
  $validation = 'server',
  $reset = false,
  $force = false 
)

Adds a validation rule for the given field.

If the element is in fact a group, it will be considered as a whole. To validate grouped elements as separated entities, use addGroupRule instead of addRule.

Parameters
string$elementForm element name
string$messageMessage to display for invalid data
string$typeRule type, use getRegisteredRules() to get types
string$format(optional)Required for extra rule data
string$validation(optional)Where to perform validation: "server", "client"
bool$resetClient-side validation: reset the form element to its original value if there is an error?
bool$forceForce the rule to be applied, even if the target form element does not exist

◆ closeHeaderBefore()

MoodleQuickForm::closeHeaderBefore (   $elementName)

Adds one or more element names that indicate the end of a fieldset.

Parameters
string$elementNamename of the element

◆ disabledIf()

MoodleQuickForm::disabledIf (   $elementName,
  $dependentOn,
  $condition = 'notchecked',
  $value = '1' 
)

Adds a dependency for $elementName which will be disabled if $condition is met.

If $condition = 'notchecked' (default) then the condition is that the $dependentOn element is not checked. If $condition = 'checked' then the condition is that the $dependentOn element is checked. If $condition is something else (like "eq" for equals) then it is checked to see if the value of the $dependentOn element is $condition (such as equal) to $value.

When working with multiple selects, the dependentOn has to be the real name of the select, meaning that it will most likely end up with '[]'. Also, the value should be an array of required values, or a string containing the values separated by pipes: array('red', 'blue') or 'red|blue'.

Parameters
string$elementNamethe name of the element which will be disabled
string$dependentOnthe name of the element whose state will be checked for condition
string$conditionthe condition to check
mixed$valueused in conjunction with condition.

◆ enable_form_change_checker()

MoodleQuickForm::enable_form_change_checker ( )

If you have called disable_form_change_checker() then you can use this method to re-enable it.

It is enabled by default, so normally you don't need to call this.

◆ exportValues()

MoodleQuickForm::exportValues (   $elementList = null)

export submitted values

Parameters
string$elementListlist of elements in form
Return values
array

◆ getAdvancedHTML()

MoodleQuickForm::getAdvancedHTML ( )

Returns HTML for advanced elements.

Return values
string

◆ getCleanedValue()

MoodleQuickForm::getCleanedValue (   $value,
  $type 
)

Return the cleaned value using the passed type(s).

Parameters
mixed$valuevalue that has to be cleaned.
int | array$typeconstant value to use to clean (PARAM_...), typically returned by self::getCleanType().
Return values
mixedcleaned up value.

◆ getCleanType()

MoodleQuickForm::getCleanType (   $elementname,
  $value,
  $default = PARAM_RAW 
)

Return the type(s) to use to clean an element.

In the case where the element has an array as a value, we will try to obtain a type defined for that specific key, and recursively until done.

This method does not work reverse, you cannot pass a nested element and hoping to fallback on the clean type of a parent. This method intends to be used with the main element, which will generate child types if needed, not the other way around.

Example scenario:

You have defined a new repeated element containing a text field called 'foo'. By default there will always be 2 occurence of 'foo' in the form. Even though you've set the type on 'foo' to be PARAM_INT, for some obscure reason, you want the first value of 'foo', to be PARAM_FLOAT, which you set using setType: $mform->setType('foo[0]', PARAM_FLOAT).

Now if you call this method passing 'foo', along with the submitted values of 'foo': array(0 => '1.23', 1 => '10'), you will get an array telling you that the key 0 is a FLOAT and 1 is an INT. If you had passed 'foo[1]', along with its value '10', you would get the default clean type returned (param $default).

Parameters
string$elementnamename of the element.
mixed$valuevalue that should be cleaned.
int$defaultdefault constant value to be returned (PARAM_...)
Return values
string|arrayconstant value or array of constant values (PARAM_...)

◆ getLockOptionObject()

MoodleQuickForm::getLockOptionObject ( )

Get list of attributes which have dependencies.

Return values
array

◆ getReqHTML()

MoodleQuickForm::getReqHTML ( )

Returns HTML for required elements.

Return values
string

◆ getShowAdvanced()

MoodleQuickForm::getShowAdvanced ( )

This function has been deprecated.

Show advanced has been replaced by "Show more.../Show less..." in the shortforms javascript module.

Deprecated:
since Moodle 2.5
Return values
bool(Always false)

◆ getValidationScript()

MoodleQuickForm::getValidationScript ( )

Returns the client side validation script.

The code here was copied from HTML_QuickForm_DHTMLRulesTableless who copied it from HTML_QuickForm and slightly modified to run rules per-element Needed to override this because of an error with client side validation of grouped elements.

Return values
stringJavascript to perform validation, empty string if no 'client' rules were added

◆ hardFreeze()

MoodleQuickForm::hardFreeze (   $elementList = null)

Displays elements without HTML input tags.

This method is different to freeze() in that it makes sure no hidden elements are included in the form. Note: If you want to make sure the submitted value is ignored, please use setDefaults().

This function also removes all previously defined rules.

Parameters
string | array$elementListarray or string of element(s) to be frozen
Return values
object|boolif element list is not empty then return error object, else true

◆ hardFreezeAllVisibleExcept()

MoodleQuickForm::hardFreezeAllVisibleExcept (   $elementList)

Hard freeze all elements in a form except those whose names are in $elementList or hidden elements in a form.

This function also removes all previously defined rules of elements it freezes.

Exceptions
HTML_QuickForm_Error
Parameters
array$elementListarray or string of element(s) not to be frozen
Return values
boolreturns true

◆ hideIf()

MoodleQuickForm::hideIf (   $elementname,
  $dependenton,
  $condition = 'notchecked',
  $value = '1' 
)

Adds a dependency for $elementName which will be hidden if $condition is met.

If $condition = 'notchecked' (default) then the condition is that the $dependentOn element is not checked. If $condition = 'checked' then the condition is that the $dependentOn element is checked. If $condition is something else (like "eq" for equals) then it is checked to see if the value of the $dependentOn element is $condition (such as equal) to $value.

When working with multiple selects, the dependentOn has to be the real name of the select, meaning that it will most likely end up with '[]'. Also, the value should be an array of required values, or a string containing the values separated by pipes: array('red', 'blue') or 'red|blue'.

Parameters
string$elementnamethe name of the element which will be hidden
string$dependentonthe name of the element whose state will be checked for condition
string$conditionthe condition to check
mixed$valueused in conjunction with condition.

◆ is_dirty()

MoodleQuickForm::is_dirty ( )

Is the form currently set to dirty?

Return values
booleanInitial dirty state.
Since
Moodle 3.7.1

◆ is_form_change_checker_enabled()

MoodleQuickForm::is_form_change_checker_enabled ( )
Return values
boolwhether this form should automatically initialise formchangechecker for itself.

◆ is_new_repeat()

MoodleQuickForm::is_new_repeat (   $name)

Check if the element with the given name has just been added by clicking on the 'Add repeating elements' button.

Parameters
string$namethe name of the element being checked
Return values
booltrue if the element is newly added

◆ isNoSubmitButton()

MoodleQuickForm::isNoSubmitButton (   $buttonname)

Checks if button is a no submit button, i.e it doesn't submit form.

Parameters
string$buttonnamename of the button to check
Return values
bool

◆ isSubmitted()

MoodleQuickForm::isSubmitted ( )

Tells whether the form was already submitted.

This is useful since the _submitFiles and _submitValues arrays may be completely empty after the trackSubmit value is removed.

Return values
bool

◆ MoodleQuickForm()

MoodleQuickForm::MoodleQuickForm (   $formName,
  $method,
  $action,
  $target = '',
  $attributes = null 
)

Old syntax of class constructor.

Deprecated in PHP7.

Deprecated:
since Moodle 3.1

◆ note_new_repeat()

MoodleQuickForm::note_new_repeat (   $name)

Add the element name to the list of newly-created repeat elements (So that elements that interpret 'no data submitted' as a valid state can tell when they should get the default value instead).

Parameters
string$namethe name of the new element

◆ optional_param()

MoodleQuickForm::optional_param (   $name,
  $default,
  $type 
)

Checks if a parameter was passed in the previous form submission.

Parameters
string$namethe name of the page parameter we want
mixed$defaultthe default value to return if nothing is found
string$typeexpected type of parameter
Return values
mixed

◆ prepare_fixed_value()

MoodleQuickForm::prepare_fixed_value (   $name,
  $value 
)
protected

This is a bit of a hack, and it duplicates the code in HTML_QuickForm_element::_prepareValue, but I could not think of a way or reliably calling that code.

(Think about date selectors, for example.)

Parameters
string$namethe element name.
mixed$valuethe fixed value to set.
Return values
mixedthe appropriate array to add to the $unfiltered array.

◆ registerNoSubmitButton()

MoodleQuickForm::registerNoSubmitButton (   $buttonname)

Registers button as no submit button.

Parameters
string$buttonnamename of the button

◆ set_initial_dirty_state()

MoodleQuickForm::set_initial_dirty_state (   $state = false)

Set the initial 'dirty' state of the form.

Parameters
bool$state
Since
Moodle 3.7.1

◆ setAdvanced()

MoodleQuickForm::setAdvanced (   $elementName,
  $advanced = true 
)

Use this method to indicate an element in a form is an advanced field.

If items in a form are marked as advanced then 'Hide/Show Advanced' buttons will automatically be displayed in the form so the user can decide whether to display advanced form controls.

If you set a header element to advanced then all elements it contains will also be set as advanced.

Parameters
string$elementNamegroup or element name (not the element name of something inside a group).
bool$advanceddefault true sets the element to advanced. False removes advanced mark.

◆ setConstant()

MoodleQuickForm::setConstant (   $elname,
  $value 
)

Set constant value not overridden by _POST or _GET note: this does not work for complex names with [] :-(.

Parameters
string$elnamename of element
mixed$value

◆ setDefault()

MoodleQuickForm::setDefault (   $elementName,
  $defaultValue 
)

Initializes a default form value.

Used to specify the default for a new entry where no data is loaded in using moodleform::set_data()

note: $slashed param removed

Parameters
string$elementNameelement name
mixed$defaultValuevalues for that element name

◆ setDisableShortforms()

MoodleQuickForm::setDisableShortforms (   $disable = true)

Use this method to indicate that the form will not be using shortforms.

Parameters
boolean$disabledefault true, controls if the shortforms are disabled.

◆ setExpanded()

MoodleQuickForm::setExpanded (   $headername,
  $expanded = true,
  $ignoreuserstate = false 
)

Use this method to indicate that the fieldset should be shown as expanded.

The method is applicable to header elements only.

Parameters
string$headernameheader element name
boolean$expandeddefault true sets the element to expanded. False makes the element collapsed.
boolean$ignoreuserstateoverride the state regardless of the state it was on when the form was submitted.
Return values
void

◆ setForceLtr()

MoodleQuickForm::setForceLtr (   $elementname,
  $value = true 
)

◆ setShowAdvanced()

MoodleQuickForm::setShowAdvanced (   $showadvancedNow = null)

This function has been deprecated.

Show advanced has been replaced by "Show more.../Show less..." in the shortforms javascript module.

Deprecated:
since Moodle 2.5
Parameters
bool$showadvancedNowif true will show advanced elements.

◆ setType()

MoodleQuickForm::setType (   $elementname,
  $paramtype 
)

Should be used for all elements of a form except for select, radio and checkboxes which clean their own data.

Parameters
string$elementname
int$paramtypedefines type of data contained in element. Use the constants PARAM_*. lib/moodlelib.php for defined parameter types

◆ setTypes()

MoodleQuickForm::setTypes (   $paramtypes)

This can be used to set several types at once.

Parameters
array$paramtypestypes of parameters.
See also
MoodleQuickForm::setType

◆ updateSubmission()

MoodleQuickForm::updateSubmission (   $submission,
  $files 
)

Updates submitted values.

Parameters
array$submissionsubmitted values
array$fileslist of files

Member Data Documentation

◆ $_advancedElements

array MoodleQuickForm::$_advancedElements = array()

Array whose keys are element names.

If the key exists this is a advanced element

◆ $_collapsibleElements

array MoodleQuickForm::$_collapsibleElements = array()

Array whose keys are element names and values are the desired collapsible state.

True for collapsed, False for expanded. If not present, set to default in self::accept().

◆ $_pageparams

string MoodleQuickForm::$_pageparams = ''

String with the html for hidden params passed in as part of a moodle_url object for the action.

Output in the form.


The documentation for this class was generated from the following file: