Moodle 3.9 XRef and Diffs

Class: moodleform - X-Ref

Wrapper that separates quickforms syntax from moodle code

Moodle specific wrapper that separates quickforms syntax from moodle code. You won't directly
use this class you should write a class definition which extends this class or a more specific
subclass such a moodleform_mod for each form you want to display and/or process with formslib.

You will write your own definition() method which performs the form set up.

__construct($action=null, $customdata=null, $method='post', $target='', $attributes=null, $editable=true,$ajaxformdata=null) X-Ref

The constructor function calls the abstract function definition() and it will then
process and clean and attempt to validate incoming data.

It will call your custom validate method to validate data and will also check any rules
you have specified in definition using addRule

The name of the form (id attribute of the form) is automatically generated depending on
the name you gave the class extending moodleform. You should call your class something
like

param: mixed $action the action attribute for the form. If empty defaults to auto detect the
param: mixed $customdata if your form defintion method needs access to data such as $course
param: string $method if you set this to anything other than 'post' then _GET and _POST will
param: string $target target frame for form submission. You will rarely use this. Don't use
param: mixed $attributes you can pass a string of html attributes here or an array.
param: bool $editable
param: array $ajaxformdata Forms submitted via ajax, must pass their data here, instead of relying on _GET and _POST.

moodleform($action=null, $customdata=null, $method='post', $target='', $attributes=null, $editable=true) X-Ref

Old syntax of class constructor. Deprecated in PHP7.

Class: name - X-Ref

get_form_identifier() X-Ref

It should returns unique identifier for the form.
Currently it will return class name, but in case two same forms have to be
rendered on same page then override function to get unique form identifier.
e.g This is used on multiple self enrollments page.

return: string form identifier.

focus($name=NULL) X-Ref

To autofocus on first form element or first element with error.

param: string $name if this is set then the focus is forced to a field with this name
return: string javascript to select form element with first error or

_process_submission($method) X-Ref

Internal method. Alters submitted data to be suitable for quickforms processing.
Must be called when the form is fully set up.

param: string $method name of the method which alters submitted data

_get_post_params() X-Ref

Internal method - should not be used anywhere.

return: array $_POST.

_validate_files(&$files) X-Ref

Internal method. Validates all old-style deprecated uploaded files.
The new way is to upload files via repository api.

param: array $files list of files to be validated
return: bool|array Success or an array of errors

validate_draft_files() X-Ref

Internal method. Validates filepicker and filemanager files if they are
set as required fields. Also, sets the error message if encountered one.

return: bool|array with errors

set_data($default_values) X-Ref

Load in existing data as form defaults. Usually new entry defaults are stored directly in
form definition (new entry form); this function is used to load in data where values
already exist and data is being edited (edit entry form).

note: $slashed param removed

param: stdClass|array $default_values object or array of default values

is_submitted() X-Ref

Check that form was submitted. Does not check validity of submitted data.

return: bool true if form properly submitted

no_submit_button_pressed() X-Ref

Checks if button pressed is not for submitting the form

return: bool

optional_param($name, $default, $type) X-Ref

Checks if a parameter was passed in the previous form submission

param: string $name the name of the page parameter we want
param: mixed $default the default value to return if nothing is found
param: string $type expected type of parameter
return: mixed

is_validated() X-Ref

Check that form data is valid.
You should almost always use this, rather than {@link validate_defined_fields}

return: bool true if form data valid

validate_defined_fields($validateonnosubmit=false) X-Ref

Validate the form.

You almost always want to call {@link is_validated} instead of this
because it calls {@link definition_after_data} first, before validating the form,
which is what you want in 99% of cases.

This is provided as a separate function for those special cases where
you want the form validated before definition_after_data is called
for example, to selectively add new elements depending on a no_submit_button press,
but only when the form is valid when the no_submit_button is pressed,

param: bool $validateonnosubmit optional, defaults to false. The default behaviour
return: bool true if form data valid

is_cancelled() X-Ref

Return true if a cancel button has been pressed resulting in the form being submitted.

return: bool true if a cancel button has been pressed

get_data() X-Ref

Return submitted data if properly submitted or returns NULL if validation fails or
if there is no submitted data.

note: $slashed param removed

return: object submitted data; NULL if not valid or not submitted or cancelled

get_submitted_data() X-Ref

Return submitted data without validation or NULL if there is no submitted data.
note: $slashed param removed

return: object submitted data; NULL if not submitted

save_files($destination) X-Ref

Save verified uploaded files into directory. Upload process can be customised from definition()

param: string $destination path where file should be stored
return: bool Always false

get_new_filename($elname=null) X-Ref

Returns name of uploaded file.

param: string $elname first element if null
return: string|bool false in case of failure, string if ok

save_file($elname, $pathname, $override=false) X-Ref

Save file to standard filesystem

param: string $elname name of element
param: string $pathname full path name of file
param: bool $override override file if exists
return: bool success

save_temp_file($elname) X-Ref

Returns a temporary file, do not forget to delete after not needed any more.

param: string $elname name of the elmenet
return: string|bool either string or false

get_draft_files($elname) X-Ref

Get draft files of a form element
This is a protected method which will be used only inside moodleforms

param: string $elname name of element
return: array|bool|null

save_stored_file($elname, $newcontextid, $newcomponent, $newfilearea, $newitemid, $newfilepath='/',$newfilename=null, $overwrite=false, $newuserid=null) X-Ref

Save file to local filesystem pool

param: string $elname name of element
param: int $newcontextid id of context
param: string $newcomponent name of the component
param: string $newfilearea name of file area
param: int $newitemid item id
param: string $newfilepath path of file where it get stored
param: string $newfilename use specified filename, if not specified name of uploaded file used
param: bool $overwrite overwrite file if exists
param: int $newuserid new userid if required
return: mixed stored_file object or false if error; may throw exception if duplicate found

get_file_content($elname) X-Ref

Get content of uploaded file.

param: string $elname name of file upload element
return: string|bool false in case of failure, string if ok

display() X-Ref

Print html form.

render() X-Ref

Renders the html form (same as display, but returns the result).

Note that you can only output this rendered result once per page, as
it contains IDs which must be unique.

return: string HTML code for the form

after_definition() X-Ref

After definition hook.

This is useful for intermediate classes to inject logic after the definition was
provided without requiring developers to call the parent {{@link self::definition()}}
as it's not obvious by design. The 'intermediate' class is 'MyClass extends
IntermediateClass extends moodleform'.

Classes overriding this method should always call the parent. We may not add
anything specifically in this instance of the method, but intermediate classes
are likely to do so, and so it is a good practice to always call the parent.

return: void

definition_after_data() X-Ref

Dummy stub method - override if you need to setup the form depending on current
values. This method is called after definition(), data submission and set_data().
All form setup that is dependent on form values should go in here.

validation($data, $files) X-Ref

Dummy stub method - override if you needed to perform some extra validation.
If there are errors return array of errors ("fieldname"=>"error message"),
otherwise true if ok.

Server side rules do not work for uploaded files, implement serverside rules here if needed.

param: array $data array of ("fieldname"=>value) of submitted data
param: array $files array of uploaded files "element_name"=>tmp_file_path
return: array of "element_name"=>"error_description" if there are errors,

repeat_elements_fix_clone($i, $elementclone, &$namecloned) X-Ref

Helper used by {@link repeat_elements()}.

param: int $i the index of this element.
param: HTML_QuickForm_element $elementclone
param: array $namecloned array of names

repeat_elements($elementobjs, $repeats, $options, $repeathiddenname,$addfieldsname, $addfieldsno=5, $addstring=null, $addbuttoninside=false) X-Ref

Method to add a repeating group of elements to a form.

param: array $elementobjs Array of elements or groups of elements that are to be repeated
param: int $repeats no of times to repeat elements initially
param: array $options a nested array. The first array key is the element name.
param: string $repeathiddenname name for hidden element storing no of repeats in this form
param: string $addfieldsname name for button to add more fields
param: int $addfieldsno how many fields to add at a time
param: string $addstring name of button, {no} is replaced by no of blanks that will be added.
param: bool $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false.
return: int no of repeats of element in this page

add_checkbox_controller($groupid, $text = null, $attributes = null, $originalValue = 0) X-Ref

Adds a link/button that controls the checked state of a group of checkboxes.

param: int $groupid The id of the group of advcheckboxes this element controls
param: string $text The text of the link. Defaults to selectallornone ("select all/none")
param: array $attributes associative array of HTML attributes
param: int $originalValue The original general state of the checkboxes before the user first clicks this element

add_action_buttons($cancel = true, $submitlabel=null) X-Ref

Use this method to a cancel and submit button to the end of your form. Pass a param of false
if you don't want a cancel button in your form. If you have a cancel button make sure you
check for it being pressed using is_cancelled() and redirecting if it is true before trying to
get data with get_data().

param: bool $cancel whether to show cancel button, default true
param: string $submitlabel label for submit button, defaults to get_string('savechanges')

init_javascript_enhancement($element, $enhancement, array $options=array() X-Ref

Adds an initialisation call for a standard JavaScript enhancement.

This function is designed to add an initialisation call for a JavaScript
enhancement that should exist within javascript-static M.form.init_{enhancementname}.

Current options:
- Selectboxes
- smartselect: Turns a nbsp indented select box into a custom drop down
control that supports multilevel and category selection.
$enhancement = 'smartselect';
$options = array('selectablecategories' => true|false)

param: string|element $element form element for which Javascript needs to be initalized
param: string $enhancement which init function should be called
param: array $options options passed to javascript
param: array $strings strings for javascript

get_js_module() X-Ref

Returns a JS module definition for the mforms JS

return: array

detectMissingSetType() X-Ref

Detects elements with missing setType() declerations.

Finds elements in the form which should a PARAM_ type set and throws a
developer debug warning for any elements without it. This is to reduce the
risk of potential security issues by developers mistakenly forgetting to set
the type.

return: void

mock_submit($simulatedsubmitteddata, $simulatedsubmittedfiles = array() X-Ref

Used by tests to simulate submitted form data submission from the user.

For form fields where no data is submitted the default for that field as set by set_data or setDefault will be passed to
get_data.

This method sets $_POST or $_GET and $_FILES with the data supplied. Our unit test code empties all these
global arrays after each test.

param: array  $simulatedsubmitteddata       An associative array of form values (same format as $_POST).
param: array  $simulatedsubmittedfiles      An associative array of files uploaded (same format as $_FILES). Can be omitted.
param: string $method                       'post' or 'get', defaults to 'post'.
param: null   $formidentifier               the default is to use the class name for this class but you may need to provide

mock_generate_submit_keys($data = []) X-Ref

Used by tests to generate valid submit keys for moodle forms that are
submitted with ajax data.

param: array $data Existing form data you wish to add the keys to.
return: array

set_display_vertical() X-Ref

Set display mode for the form when labels take full width of the form and above the elements even on big screens

Useful for forms displayed inside modals or in narrow containers

set_initial_dirty_state($state = false) X-Ref

Set the initial 'dirty' state of the form.

param: bool $state

setAdvanced($elementName, $advanced = true) X-Ref

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.

param: string $elementName group or element name (not the element name of something inside a group).
param: bool $advanced default true sets the element to advanced. False removes advanced mark.

optional_param($name, $default, $type) X-Ref

Checks if a parameter was passed in the previous form submission

param: string $name the name of the page parameter we want
param: mixed $default the default value to return if nothing is found
param: string $type expected type of parameter
return: mixed

setExpanded($headername, $expanded = true, $ignoreuserstate = false) X-Ref

Use this method to indicate that the fieldset should be shown as expanded.
The method is applicable to header elements only.

param: string $headername header element name
param: boolean $expanded default true sets the element to expanded. False makes the element collapsed.
param: boolean $ignoreuserstate override the state regardless of the state it was on when
return: void

addAdvancedStatusElement($headerid, $showmore=false) X-Ref

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

param: string $headerName header element name.
param: boolean $showmore default false sets the advanced elements to be hidden.

setShowAdvanced($showadvancedNow = null) X-Ref

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

param: bool $showadvancedNow if true will show advanced elements.

getShowAdvanced() X-Ref

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

return: bool (Always false)

setDisableShortforms($disable = true) X-Ref

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

param: boolean $disable default true, controls if the shortforms are disabled.

set_initial_dirty_state($state = false) X-Ref

Set the initial 'dirty' state of the form.

param: bool $state

is_dirty() X-Ref

Is the form currently set to dirty?

return: boolean Initial dirty state.

disable_form_change_checker() X-Ref

Call this method if you don't want the formchangechecker JavaScript to be
automatically initialised for this form.

enable_form_change_checker() X-Ref

If you have called {@link 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.

is_form_change_checker_enabled() X-Ref

return: bool whether this form should automatically initialise

accept(&$renderer) X-Ref

Accepts a renderer

param: HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object

closeHeaderBefore($elementName) X-Ref

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

param: string $elementName name of the element

setForceLtr($elementname, $value = true) X-Ref

Set an element to be forced to flow LTR.

The element must exist and support this functionality. Also note that
when setting the type of a field (@link self::setType} we try to guess the
whether the field should be force to LTR or not. Make sure you're always
calling this method last.

param: string $elementname The element name.
param: bool $value When false, disables force LTR, else enables it.

setType($elementname, $paramtype) X-Ref

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

param: string $elementname
param: int $paramtype defines type of data contained in element. Use the constants PARAM_*.

setTypes($paramtypes) X-Ref

This can be used to set several types at once.

param: array $paramtypes types of parameters.

getCleanType($elementname, $value, $default = PARAM_RAW) X-Ref

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

param: string $elementname name of the element.
param: mixed $value value that should be cleaned.
param: int $default default constant value to be returned (PARAM_...)
return: string|array constant value or array of constant values (PARAM_...)

getCleanedValue($value, $type) X-Ref

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

param: mixed $value value that has to be cleaned.
param: int|array $type constant value to use to clean (PARAM_...), typically returned by {@link self::getCleanType()}.
return: mixed cleaned up value.

updateSubmission($submission, $files) X-Ref

Updates submitted values

param: array $submission submitted values
param: array $files list of files

getReqHTML() X-Ref

Returns HTML for required elements

return: string

getAdvancedHTML() X-Ref

Returns HTML for advanced elements

return: string

setDefault($elementName, $defaultValue) X-Ref

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

param: string $elementName element name
param: mixed $defaultValue values for that element name

addHelpButton($elementname, $identifier, $component = 'moodle', $linktext = '', $suppresscheck = false) X-Ref

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

param: string $elementname name of the element to add the item to
param: string $identifier help string identifier without _help suffix
param: string $component component name to look the help string in
param: string $linktext optional text to display next to the icon
param: bool $suppresscheck set to true if the element may not exist

setConstant($elname, $value) X-Ref

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

param: string $elname name of element
param: mixed $value

exportValues($elementList = null) X-Ref

export submitted values

param: string $elementList list of elements in form
return: array

prepare_fixed_value($name, $value) X-Ref

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

param: string $name the element name.
param: mixed $value the fixed value to set.
return: mixed the appropriate array to add to the $unfiltered array.

addRule($element, $message, $type, $format=null, $validation='server', $reset = false, $force = false) X-Ref

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.

param: string $element Form element name
param: string $message Message to display for invalid data
param: string $type Rule type, use getRegisteredRules() to get types
param: string $format (optional)Required for extra rule data
param: string $validation (optional)Where to perform validation: "server", "client"
param: bool $reset Client-side validation: reset the form element to its original value if there is an error?
param: bool $force Force the rule to be applied, even if the target form element does not exist

addGroupRule($group, $arg1, $type='', $format=null, $howmany=0, $validation = 'server', $reset = false) X-Ref

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.

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

getValidationScript() X-Ref

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: string Javascript to perform validation, empty string if no 'client' rules were added

qf_errorHandler(element, _qfMsg, escapedName) X-Ref

No description

validate_(if (undefined == element) X-Ref

No description

validate_(if (skipClientValidation) X-Ref

No description

_setDefaultRuleMessages() X-Ref

Sets default error message

getLockOptionObject() X-Ref

Get list of attributes which have dependencies

return: array

_getElNamesRecursive($element) X-Ref

Get names of element or elements in a group.

param: HTML_QuickForm_group|element $element element group or element object
return: array

disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1') X-Ref

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

param: string $elementName the name of the element which will be disabled
param: string $dependentOn the name of the element whose state will be checked for condition
param: string $condition the condition to check
param: mixed $value used in conjunction with condition.

hideIf($elementname, $dependenton, $condition = 'notchecked', $value = '1') X-Ref

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

param: string $elementname the name of the element which will be hidden
param: string $dependenton the name of the element whose state will be checked for condition
param: string $condition the condition to check
param: mixed $value used in conjunction with condition.

registerNoSubmitButton($buttonname) X-Ref

Registers button as no submit button

param: string $buttonname name of the button

isNoSubmitButton($buttonname) X-Ref

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

param: string $buttonname name of the button to check
return: bool

_registerCancelButton($addfieldsname) X-Ref

Registers a button as cancel button

param: string $addfieldsname name of the button

hardFreeze($elementList=null) X-Ref

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.

param: string|array $elementList array or string of element(s) to be frozen
return: object|bool if element list is not empty then return error object, else true

hardFreezeAllVisibleExcept($elementList) X-Ref

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.

param: array $elementList array or string of element(s) not to be frozen
return: bool returns true

isSubmitted() X-Ref

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: bool

note_new_repeat($name) X-Ref

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

param: string $name the name of the new element

is_new_repeat($name) X-Ref

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

param: string $name the name of the element being checked
return: bool true if the element is newly added

setAdvancedElements($elements) X-Ref

Set element's as adavance element

param: array $elements form elements which needs to be grouped as advance elements.

setCollapsibleElements($elements) X-Ref

Setting collapsible elements

param: array $elements

startForm(&$form) X-Ref

What to do when starting the form

param: MoodleQuickForm $form reference of the form

startGroup(&$group, $required, $error) X-Ref

Create advance group of elements

param: MoodleQuickForm_group $group Passed by reference
param: bool $required if input is required field
param: string $error error message to display

renderElement(&$element, $required, $error) X-Ref

Renders element

param: HTML_QuickForm_element $element element
param: bool $required if input is required field
param: string $error error message to display

finishForm(&$form) X-Ref

Called when visiting a form, after processing all form elements
Adds required note, form attributes, validation javascript and form content.

param: moodleform $form Passed by reference

renderHeader(&$header) X-Ref

Called when visiting a header element

param: HTML_QuickForm_header $header An HTML_QuickForm_header element being visited

getStopFieldsetElements() X-Ref

Return Array of element names that indicate the end of a fieldset

return: array

Class: MoodleQuickForm - X-Ref

MoodleQuickForm implementation

You never extend this class directly. The class methods of this class are available from
the private $this->_form property on moodleform and its children. You generally only
call methods on this class from within abstract methods that you override on moodleform such
as definition and definition_after_data

__construct($formName, $method, $action, $target = '', $attributes = null, $ajaxformdata = null) X-Ref

Class constructor - same parameters as HTML_QuickForm_DHTMLRulesTableless

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

MoodleQuickForm($formName, $method, $action, $target='', $attributes=null) X-Ref

Old syntax of class constructor. Deprecated in PHP7.

Class: name - X-Ref

get_form_identifier() X-Ref

It should returns unique identifier for the form.
Currently it will return class name, but in case two same forms have to be
rendered on same page then override function to get unique form identifier.
e.g This is used on multiple self enrollments page.

return: string form identifier.

focus($name=NULL) X-Ref

To autofocus on first form element or first element with error.

param: string $name if this is set then the focus is forced to a field with this name
return: string javascript to select form element with first error or

_process_submission($method) X-Ref

Internal method. Alters submitted data to be suitable for quickforms processing.
Must be called when the form is fully set up.

param: string $method name of the method which alters submitted data

_get_post_params() X-Ref

Internal method - should not be used anywhere.

return: array $_POST.

_validate_files(&$files) X-Ref

Internal method. Validates all old-style deprecated uploaded files.
The new way is to upload files via repository api.

param: array $files list of files to be validated
return: bool|array Success or an array of errors

validate_draft_files() X-Ref

Internal method. Validates filepicker and filemanager files if they are
set as required fields. Also, sets the error message if encountered one.

return: bool|array with errors

set_data($default_values) X-Ref

Load in existing data as form defaults. Usually new entry defaults are stored directly in
form definition (new entry form); this function is used to load in data where values
already exist and data is being edited (edit entry form).

note: $slashed param removed

param: stdClass|array $default_values object or array of default values

is_submitted() X-Ref

Check that form was submitted. Does not check validity of submitted data.

return: bool true if form properly submitted

no_submit_button_pressed() X-Ref

Checks if button pressed is not for submitting the form

return: bool

optional_param($name, $default, $type) X-Ref

Checks if a parameter was passed in the previous form submission

param: string $name the name of the page parameter we want
param: mixed $default the default value to return if nothing is found
param: string $type expected type of parameter
return: mixed

is_validated() X-Ref

Check that form data is valid.
You should almost always use this, rather than {@link validate_defined_fields}

return: bool true if form data valid

validate_defined_fields($validateonnosubmit=false) X-Ref

Validate the form.

You almost always want to call {@link is_validated} instead of this
because it calls {@link definition_after_data} first, before validating the form,
which is what you want in 99% of cases.

This is provided as a separate function for those special cases where
you want the form validated before definition_after_data is called
for example, to selectively add new elements depending on a no_submit_button press,
but only when the form is valid when the no_submit_button is pressed,

param: bool $validateonnosubmit optional, defaults to false. The default behaviour
return: bool true if form data valid

is_cancelled() X-Ref

Return true if a cancel button has been pressed resulting in the form being submitted.

return: bool true if a cancel button has been pressed

get_data() X-Ref

Return submitted data if properly submitted or returns NULL if validation fails or
if there is no submitted data.

note: $slashed param removed

return: object submitted data; NULL if not valid or not submitted or cancelled

get_submitted_data() X-Ref

Return submitted data without validation or NULL if there is no submitted data.
note: $slashed param removed

return: object submitted data; NULL if not submitted

save_files($destination) X-Ref

Save verified uploaded files into directory. Upload process can be customised from definition()

param: string $destination path where file should be stored
return: bool Always false

get_new_filename($elname=null) X-Ref

Returns name of uploaded file.

param: string $elname first element if null
return: string|bool false in case of failure, string if ok

save_file($elname, $pathname, $override=false) X-Ref

Save file to standard filesystem

param: string $elname name of element
param: string $pathname full path name of file
param: bool $override override file if exists
return: bool success

save_temp_file($elname) X-Ref

Returns a temporary file, do not forget to delete after not needed any more.

param: string $elname name of the elmenet
return: string|bool either string or false

get_draft_files($elname) X-Ref

Get draft files of a form element
This is a protected method which will be used only inside moodleforms

param: string $elname name of element
return: array|bool|null

save_stored_file($elname, $newcontextid, $newcomponent, $newfilearea, $newitemid, $newfilepath='/',$newfilename=null, $overwrite=false, $newuserid=null) X-Ref

Save file to local filesystem pool

param: string $elname name of element
param: int $newcontextid id of context
param: string $newcomponent name of the component
param: string $newfilearea name of file area
param: int $newitemid item id
param: string $newfilepath path of file where it get stored
param: string $newfilename use specified filename, if not specified name of uploaded file used
param: bool $overwrite overwrite file if exists
param: int $newuserid new userid if required
return: mixed stored_file object or false if error; may throw exception if duplicate found

get_file_content($elname) X-Ref

Get content of uploaded file.

param: string $elname name of file upload element
return: string|bool false in case of failure, string if ok

display() X-Ref

Print html form.

render() X-Ref

Renders the html form (same as display, but returns the result).

Note that you can only output this rendered result once per page, as
it contains IDs which must be unique.

return: string HTML code for the form

after_definition() X-Ref

After definition hook.

This is useful for intermediate classes to inject logic after the definition was
provided without requiring developers to call the parent {{@link self::definition()}}
as it's not obvious by design. The 'intermediate' class is 'MyClass extends
IntermediateClass extends moodleform'.

Classes overriding this method should always call the parent. We may not add
anything specifically in this instance of the method, but intermediate classes
are likely to do so, and so it is a good practice to always call the parent.

return: void

definition_after_data() X-Ref

Dummy stub method - override if you need to setup the form depending on current
values. This method is called after definition(), data submission and set_data().
All form setup that is dependent on form values should go in here.

validation($data, $files) X-Ref

Dummy stub method - override if you needed to perform some extra validation.
If there are errors return array of errors ("fieldname"=>"error message"),
otherwise true if ok.

Server side rules do not work for uploaded files, implement serverside rules here if needed.

param: array $data array of ("fieldname"=>value) of submitted data
param: array $files array of uploaded files "element_name"=>tmp_file_path
return: array of "element_name"=>"error_description" if there are errors,

repeat_elements_fix_clone($i, $elementclone, &$namecloned) X-Ref

Helper used by {@link repeat_elements()}.

param: int $i the index of this element.
param: HTML_QuickForm_element $elementclone
param: array $namecloned array of names

repeat_elements($elementobjs, $repeats, $options, $repeathiddenname,$addfieldsname, $addfieldsno=5, $addstring=null, $addbuttoninside=false) X-Ref

Method to add a repeating group of elements to a form.

param: array $elementobjs Array of elements or groups of elements that are to be repeated
param: int $repeats no of times to repeat elements initially
param: array $options a nested array. The first array key is the element name.
param: string $repeathiddenname name for hidden element storing no of repeats in this form
param: string $addfieldsname name for button to add more fields
param: int $addfieldsno how many fields to add at a time
param: string $addstring name of button, {no} is replaced by no of blanks that will be added.
param: bool $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false.
return: int no of repeats of element in this page

add_checkbox_controller($groupid, $text = null, $attributes = null, $originalValue = 0) X-Ref

Adds a link/button that controls the checked state of a group of checkboxes.

param: int $groupid The id of the group of advcheckboxes this element controls
param: string $text The text of the link. Defaults to selectallornone ("select all/none")
param: array $attributes associative array of HTML attributes
param: int $originalValue The original general state of the checkboxes before the user first clicks this element

add_action_buttons($cancel = true, $submitlabel=null) X-Ref

Use this method to a cancel and submit button to the end of your form. Pass a param of false
if you don't want a cancel button in your form. If you have a cancel button make sure you
check for it being pressed using is_cancelled() and redirecting if it is true before trying to
get data with get_data().

param: bool $cancel whether to show cancel button, default true
param: string $submitlabel label for submit button, defaults to get_string('savechanges')

init_javascript_enhancement($element, $enhancement, array $options=array() X-Ref

Adds an initialisation call for a standard JavaScript enhancement.

This function is designed to add an initialisation call for a JavaScript
enhancement that should exist within javascript-static M.form.init_{enhancementname}.

Current options:
- Selectboxes
- smartselect: Turns a nbsp indented select box into a custom drop down
control that supports multilevel and category selection.
$enhancement = 'smartselect';
$options = array('selectablecategories' => true|false)

param: string|element $element form element for which Javascript needs to be initalized
param: string $enhancement which init function should be called
param: array $options options passed to javascript
param: array $strings strings for javascript

get_js_module() X-Ref

Returns a JS module definition for the mforms JS

return: array

detectMissingSetType() X-Ref

Detects elements with missing setType() declerations.

Finds elements in the form which should a PARAM_ type set and throws a
developer debug warning for any elements without it. This is to reduce the
risk of potential security issues by developers mistakenly forgetting to set
the type.

return: void

mock_submit($simulatedsubmitteddata, $simulatedsubmittedfiles = array() X-Ref

Used by tests to simulate submitted form data submission from the user.

For form fields where no data is submitted the default for that field as set by set_data or setDefault will be passed to
get_data.

This method sets $_POST or $_GET and $_FILES with the data supplied. Our unit test code empties all these
global arrays after each test.

param: array  $simulatedsubmitteddata       An associative array of form values (same format as $_POST).
param: array  $simulatedsubmittedfiles      An associative array of files uploaded (same format as $_FILES). Can be omitted.
param: string $method                       'post' or 'get', defaults to 'post'.
param: null   $formidentifier               the default is to use the class name for this class but you may need to provide

mock_generate_submit_keys($data = []) X-Ref

Used by tests to generate valid submit keys for moodle forms that are
submitted with ajax data.

param: array $data Existing form data you wish to add the keys to.
return: array

set_display_vertical() X-Ref

Set display mode for the form when labels take full width of the form and above the elements even on big screens

Useful for forms displayed inside modals or in narrow containers

set_initial_dirty_state($state = false) X-Ref

Set the initial 'dirty' state of the form.

param: bool $state

setAdvanced($elementName, $advanced = true) X-Ref

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.

param: string $elementName group or element name (not the element name of something inside a group).
param: bool $advanced default true sets the element to advanced. False removes advanced mark.

optional_param($name, $default, $type) X-Ref

Checks if a parameter was passed in the previous form submission

param: string $name the name of the page parameter we want
param: mixed $default the default value to return if nothing is found
param: string $type expected type of parameter
return: mixed

setExpanded($headername, $expanded = true, $ignoreuserstate = false) X-Ref

Use this method to indicate that the fieldset should be shown as expanded.
The method is applicable to header elements only.

param: string $headername header element name
param: boolean $expanded default true sets the element to expanded. False makes the element collapsed.
param: boolean $ignoreuserstate override the state regardless of the state it was on when
return: void

addAdvancedStatusElement($headerid, $showmore=false) X-Ref

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

param: string $headerName header element name.
param: boolean $showmore default false sets the advanced elements to be hidden.

setShowAdvanced($showadvancedNow = null) X-Ref

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

param: bool $showadvancedNow if true will show advanced elements.

getShowAdvanced() X-Ref

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

return: bool (Always false)

setDisableShortforms($disable = true) X-Ref

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

param: boolean $disable default true, controls if the shortforms are disabled.

set_initial_dirty_state($state = false) X-Ref

Set the initial 'dirty' state of the form.

param: bool $state

is_dirty() X-Ref

Is the form currently set to dirty?

return: boolean Initial dirty state.

disable_form_change_checker() X-Ref

Call this method if you don't want the formchangechecker JavaScript to be
automatically initialised for this form.

enable_form_change_checker() X-Ref

If you have called {@link 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.

is_form_change_checker_enabled() X-Ref

return: bool whether this form should automatically initialise

accept(&$renderer) X-Ref

Accepts a renderer

param: HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object

closeHeaderBefore($elementName) X-Ref

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

param: string $elementName name of the element

setForceLtr($elementname, $value = true) X-Ref

Set an element to be forced to flow LTR.

The element must exist and support this functionality. Also note that
when setting the type of a field (@link self::setType} we try to guess the
whether the field should be force to LTR or not. Make sure you're always
calling this method last.

param: string $elementname The element name.
param: bool $value When false, disables force LTR, else enables it.

setType($elementname, $paramtype) X-Ref

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

param: string $elementname
param: int $paramtype defines type of data contained in element. Use the constants PARAM_*.

setTypes($paramtypes) X-Ref

This can be used to set several types at once.

param: array $paramtypes types of parameters.

getCleanType($elementname, $value, $default = PARAM_RAW) X-Ref

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

param: string $elementname name of the element.
param: mixed $value value that should be cleaned.
param: int $default default constant value to be returned (PARAM_...)
return: string|array constant value or array of constant values (PARAM_...)

getCleanedValue($value, $type) X-Ref

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

param: mixed $value value that has to be cleaned.
param: int|array $type constant value to use to clean (PARAM_...), typically returned by {@link self::getCleanType()}.
return: mixed cleaned up value.

updateSubmission($submission, $files) X-Ref

Updates submitted values

param: array $submission submitted values
param: array $files list of files

getReqHTML() X-Ref

Returns HTML for required elements

return: string

getAdvancedHTML() X-Ref

Returns HTML for advanced elements

return: string

setDefault($elementName, $defaultValue) X-Ref

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

param: string $elementName element name
param: mixed $defaultValue values for that element name

addHelpButton($elementname, $identifier, $component = 'moodle', $linktext = '', $suppresscheck = false) X-Ref

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

param: string $elementname name of the element to add the item to
param: string $identifier help string identifier without _help suffix
param: string $component component name to look the help string in
param: string $linktext optional text to display next to the icon
param: bool $suppresscheck set to true if the element may not exist

setConstant($elname, $value) X-Ref

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

param: string $elname name of element
param: mixed $value

exportValues($elementList = null) X-Ref

export submitted values

param: string $elementList list of elements in form
return: array

prepare_fixed_value($name, $value) X-Ref

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

param: string $name the element name.
param: mixed $value the fixed value to set.
return: mixed the appropriate array to add to the $unfiltered array.

addRule($element, $message, $type, $format=null, $validation='server', $reset = false, $force = false) X-Ref

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.

param: string $element Form element name
param: string $message Message to display for invalid data
param: string $type Rule type, use getRegisteredRules() to get types
param: string $format (optional)Required for extra rule data
param: string $validation (optional)Where to perform validation: "server", "client"
param: bool $reset Client-side validation: reset the form element to its original value if there is an error?
param: bool $force Force the rule to be applied, even if the target form element does not exist

addGroupRule($group, $arg1, $type='', $format=null, $howmany=0, $validation = 'server', $reset = false) X-Ref

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.

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

getValidationScript() X-Ref

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: string Javascript to perform validation, empty string if no 'client' rules were added

qf_errorHandler(element, _qfMsg, escapedName) X-Ref

No description

validate_(if (undefined == element) X-Ref

No description

validate_(if (skipClientValidation) X-Ref

No description

_setDefaultRuleMessages() X-Ref

Sets default error message

getLockOptionObject() X-Ref

Get list of attributes which have dependencies

return: array

_getElNamesRecursive($element) X-Ref

Get names of element or elements in a group.

param: HTML_QuickForm_group|element $element element group or element object
return: array

disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1') X-Ref

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

param: string $elementName the name of the element which will be disabled
param: string $dependentOn the name of the element whose state will be checked for condition
param: string $condition the condition to check
param: mixed $value used in conjunction with condition.

hideIf($elementname, $dependenton, $condition = 'notchecked', $value = '1') X-Ref

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

param: string $elementname the name of the element which will be hidden
param: string $dependenton the name of the element whose state will be checked for condition
param: string $condition the condition to check
param: mixed $value used in conjunction with condition.

registerNoSubmitButton($buttonname) X-Ref

Registers button as no submit button

param: string $buttonname name of the button

isNoSubmitButton($buttonname) X-Ref

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

param: string $buttonname name of the button to check
return: bool

_registerCancelButton($addfieldsname) X-Ref

Registers a button as cancel button

param: string $addfieldsname name of the button

hardFreeze($elementList=null) X-Ref

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.

param: string|array $elementList array or string of element(s) to be frozen
return: object|bool if element list is not empty then return error object, else true

hardFreezeAllVisibleExcept($elementList) X-Ref

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.

param: array $elementList array or string of element(s) not to be frozen
return: bool returns true

isSubmitted() X-Ref

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: bool

note_new_repeat($name) X-Ref

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

param: string $name the name of the new element

is_new_repeat($name) X-Ref

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

param: string $name the name of the element being checked
return: bool true if the element is newly added

setAdvancedElements($elements) X-Ref

Set element's as adavance element

param: array $elements form elements which needs to be grouped as advance elements.

setCollapsibleElements($elements) X-Ref

Setting collapsible elements

param: array $elements

startForm(&$form) X-Ref

What to do when starting the form

param: MoodleQuickForm $form reference of the form

startGroup(&$group, $required, $error) X-Ref

Create advance group of elements

param: MoodleQuickForm_group $group Passed by reference
param: bool $required if input is required field
param: string $error error message to display

renderElement(&$element, $required, $error) X-Ref

Renders element

param: HTML_QuickForm_element $element element
param: bool $required if input is required field
param: string $error error message to display

finishForm(&$form) X-Ref

Called when visiting a form, after processing all form elements
Adds required note, form attributes, validation javascript and form content.

param: moodleform $form Passed by reference

renderHeader(&$header) X-Ref

Called when visiting a header element

param: HTML_QuickForm_header $header An HTML_QuickForm_header element being visited

getStopFieldsetElements() X-Ref

Return Array of element names that indicate the end of a fieldset

return: array

Class: MoodleQuickForm_Renderer - X-Ref

MoodleQuickForm renderer

A renderer for MoodleQuickForm that only uses XHTML and CSS and no
table tags, extends PEAR class HTML_QuickForm_Renderer_Tableless

Stylesheet is part of standard theme and should be automatically included.

__construct() X-Ref

Constructor

MoodleQuickForm_Renderer() X-Ref

Old syntax of class constructor. Deprecated in PHP7.

Class: name - X-Ref

get_form_identifier() X-Ref

It should returns unique identifier for the form.
Currently it will return class name, but in case two same forms have to be
rendered on same page then override function to get unique form identifier.
e.g This is used on multiple self enrollments page.

return: string form identifier.

focus($name=NULL) X-Ref

To autofocus on first form element or first element with error.

param: string $name if this is set then the focus is forced to a field with this name
return: string javascript to select form element with first error or

_process_submission($method) X-Ref

Internal method. Alters submitted data to be suitable for quickforms processing.
Must be called when the form is fully set up.

param: string $method name of the method which alters submitted data

_get_post_params() X-Ref

Internal method - should not be used anywhere.

return: array $_POST.

_validate_files(&$files) X-Ref

Internal method. Validates all old-style deprecated uploaded files.
The new way is to upload files via repository api.

param: array $files list of files to be validated
return: bool|array Success or an array of errors

validate_draft_files() X-Ref

Internal method. Validates filepicker and filemanager files if they are
set as required fields. Also, sets the error message if encountered one.

return: bool|array with errors

set_data($default_values) X-Ref

Load in existing data as form defaults. Usually new entry defaults are stored directly in
form definition (new entry form); this function is used to load in data where values
already exist and data is being edited (edit entry form).

note: $slashed param removed

param: stdClass|array $default_values object or array of default values

is_submitted() X-Ref

Check that form was submitted. Does not check validity of submitted data.

return: bool true if form properly submitted

no_submit_button_pressed() X-Ref

Checks if button pressed is not for submitting the form

return: bool

optional_param($name, $default, $type) X-Ref

Checks if a parameter was passed in the previous form submission

param: string $name the name of the page parameter we want
param: mixed $default the default value to return if nothing is found
param: string $type expected type of parameter
return: mixed

is_validated() X-Ref

Check that form data is valid.
You should almost always use this, rather than {@link validate_defined_fields}

return: bool true if form data valid

validate_defined_fields($validateonnosubmit=false) X-Ref

Validate the form.

You almost always want to call {@link is_validated} instead of this
because it calls {@link definition_after_data} first, before validating the form,
which is what you want in 99% of cases.

This is provided as a separate function for those special cases where
you want the form validated before definition_after_data is called
for example, to selectively add new elements depending on a no_submit_button press,
but only when the form is valid when the no_submit_button is pressed,

param: bool $validateonnosubmit optional, defaults to false. The default behaviour
return: bool true if form data valid

is_cancelled() X-Ref

Return true if a cancel button has been pressed resulting in the form being submitted.

return: bool true if a cancel button has been pressed

get_data() X-Ref

Return submitted data if properly submitted or returns NULL if validation fails or
if there is no submitted data.

note: $slashed param removed

return: object submitted data; NULL if not valid or not submitted or cancelled

get_submitted_data() X-Ref

Return submitted data without validation or NULL if there is no submitted data.
note: $slashed param removed

return: object submitted data; NULL if not submitted

save_files($destination) X-Ref

Save verified uploaded files into directory. Upload process can be customised from definition()

param: string $destination path where file should be stored
return: bool Always false

get_new_filename($elname=null) X-Ref

Returns name of uploaded file.

param: string $elname first element if null
return: string|bool false in case of failure, string if ok

save_file($elname, $pathname, $override=false) X-Ref

Save file to standard filesystem

param: string $elname name of element
param: string $pathname full path name of file
param: bool $override override file if exists
return: bool success

save_temp_file($elname) X-Ref

Returns a temporary file, do not forget to delete after not needed any more.

param: string $elname name of the elmenet
return: string|bool either string or false

get_draft_files($elname) X-Ref

Get draft files of a form element
This is a protected method which will be used only inside moodleforms

param: string $elname name of element
return: array|bool|null

save_stored_file($elname, $newcontextid, $newcomponent, $newfilearea, $newitemid, $newfilepath='/',$newfilename=null, $overwrite=false, $newuserid=null) X-Ref

Save file to local filesystem pool

param: string $elname name of element
param: int $newcontextid id of context
param: string $newcomponent name of the component
param: string $newfilearea name of file area
param: int $newitemid item id
param: string $newfilepath path of file where it get stored
param: string $newfilename use specified filename, if not specified name of uploaded file used
param: bool $overwrite overwrite file if exists
param: int $newuserid new userid if required
return: mixed stored_file object or false if error; may throw exception if duplicate found

get_file_content($elname) X-Ref

Get content of uploaded file.

param: string $elname name of file upload element
return: string|bool false in case of failure, string if ok

display() X-Ref

Print html form.

render() X-Ref

Renders the html form (same as display, but returns the result).

Note that you can only output this rendered result once per page, as
it contains IDs which must be unique.

return: string HTML code for the form

after_definition() X-Ref

After definition hook.

This is useful for intermediate classes to inject logic after the definition was
provided without requiring developers to call the parent {{@link self::definition()}}
as it's not obvious by design. The 'intermediate' class is 'MyClass extends
IntermediateClass extends moodleform'.

Classes overriding this method should always call the parent. We may not add
anything specifically in this instance of the method, but intermediate classes
are likely to do so, and so it is a good practice to always call the parent.

return: void

definition_after_data() X-Ref

Dummy stub method - override if you need to setup the form depending on current
values. This method is called after definition(), data submission and set_data().
All form setup that is dependent on form values should go in here.

validation($data, $files) X-Ref

Dummy stub method - override if you needed to perform some extra validation.
If there are errors return array of errors ("fieldname"=>"error message"),
otherwise true if ok.

Server side rules do not work for uploaded files, implement serverside rules here if needed.

param: array $data array of ("fieldname"=>value) of submitted data
param: array $files array of uploaded files "element_name"=>tmp_file_path
return: array of "element_name"=>"error_description" if there are errors,

repeat_elements_fix_clone($i, $elementclone, &$namecloned) X-Ref

Helper used by {@link repeat_elements()}.

param: int $i the index of this element.
param: HTML_QuickForm_element $elementclone
param: array $namecloned array of names

repeat_elements($elementobjs, $repeats, $options, $repeathiddenname,$addfieldsname, $addfieldsno=5, $addstring=null, $addbuttoninside=false) X-Ref

Method to add a repeating group of elements to a form.

param: array $elementobjs Array of elements or groups of elements that are to be repeated
param: int $repeats no of times to repeat elements initially
param: array $options a nested array. The first array key is the element name.
param: string $repeathiddenname name for hidden element storing no of repeats in this form
param: string $addfieldsname name for button to add more fields
param: int $addfieldsno how many fields to add at a time
param: string $addstring name of button, {no} is replaced by no of blanks that will be added.
param: bool $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false.
return: int no of repeats of element in this page

add_checkbox_controller($groupid, $text = null, $attributes = null, $originalValue = 0) X-Ref

Adds a link/button that controls the checked state of a group of checkboxes.

param: int $groupid The id of the group of advcheckboxes this element controls
param: string $text The text of the link. Defaults to selectallornone ("select all/none")
param: array $attributes associative array of HTML attributes
param: int $originalValue The original general state of the checkboxes before the user first clicks this element

add_action_buttons($cancel = true, $submitlabel=null) X-Ref

Use this method to a cancel and submit button to the end of your form. Pass a param of false
if you don't want a cancel button in your form. If you have a cancel button make sure you
check for it being pressed using is_cancelled() and redirecting if it is true before trying to
get data with get_data().

param: bool $cancel whether to show cancel button, default true
param: string $submitlabel label for submit button, defaults to get_string('savechanges')

init_javascript_enhancement($element, $enhancement, array $options=array() X-Ref

Adds an initialisation call for a standard JavaScript enhancement.

This function is designed to add an initialisation call for a JavaScript
enhancement that should exist within javascript-static M.form.init_{enhancementname}.

Current options:
- Selectboxes
- smartselect: Turns a nbsp indented select box into a custom drop down
control that supports multilevel and category selection.
$enhancement = 'smartselect';
$options = array('selectablecategories' => true|false)

param: string|element $element form element for which Javascript needs to be initalized
param: string $enhancement which init function should be called
param: array $options options passed to javascript
param: array $strings strings for javascript

get_js_module() X-Ref

Returns a JS module definition for the mforms JS

return: array

detectMissingSetType() X-Ref

Detects elements with missing setType() declerations.

Finds elements in the form which should a PARAM_ type set and throws a
developer debug warning for any elements without it. This is to reduce the
risk of potential security issues by developers mistakenly forgetting to set
the type.

return: void

mock_submit($simulatedsubmitteddata, $simulatedsubmittedfiles = array() X-Ref

Used by tests to simulate submitted form data submission from the user.

For form fields where no data is submitted the default for that field as set by set_data or setDefault will be passed to
get_data.

This method sets $_POST or $_GET and $_FILES with the data supplied. Our unit test code empties all these
global arrays after each test.

param: array  $simulatedsubmitteddata       An associative array of form values (same format as $_POST).
param: array  $simulatedsubmittedfiles      An associative array of files uploaded (same format as $_FILES). Can be omitted.
param: string $method                       'post' or 'get', defaults to 'post'.
param: null   $formidentifier               the default is to use the class name for this class but you may need to provide

mock_generate_submit_keys($data = []) X-Ref

Used by tests to generate valid submit keys for moodle forms that are
submitted with ajax data.

param: array $data Existing form data you wish to add the keys to.
return: array

set_display_vertical() X-Ref

Set display mode for the form when labels take full width of the form and above the elements even on big screens

Useful for forms displayed inside modals or in narrow containers

set_initial_dirty_state($state = false) X-Ref

Set the initial 'dirty' state of the form.

param: bool $state

setAdvanced($elementName, $advanced = true) X-Ref

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.

param: string $elementName group or element name (not the element name of something inside a group).
param: bool $advanced default true sets the element to advanced. False removes advanced mark.

optional_param($name, $default, $type) X-Ref

Checks if a parameter was passed in the previous form submission

param: string $name the name of the page parameter we want
param: mixed $default the default value to return if nothing is found
param: string $type expected type of parameter
return: mixed

setExpanded($headername, $expanded = true, $ignoreuserstate = false) X-Ref

Use this method to indicate that the fieldset should be shown as expanded.
The method is applicable to header elements only.

param: string $headername header element name
param: boolean $expanded default true sets the element to expanded. False makes the element collapsed.
param: boolean $ignoreuserstate override the state regardless of the state it was on when
return: void

addAdvancedStatusElement($headerid, $showmore=false) X-Ref

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

param: string $headerName header element name.
param: boolean $showmore default false sets the advanced elements to be hidden.

setShowAdvanced($showadvancedNow = null) X-Ref

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

param: bool $showadvancedNow if true will show advanced elements.

getShowAdvanced() X-Ref

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

return: bool (Always false)

setDisableShortforms($disable = true) X-Ref

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

param: boolean $disable default true, controls if the shortforms are disabled.

set_initial_dirty_state($state = false) X-Ref

Set the initial 'dirty' state of the form.

param: bool $state

is_dirty() X-Ref

Is the form currently set to dirty?

return: boolean Initial dirty state.

disable_form_change_checker() X-Ref

Call this method if you don't want the formchangechecker JavaScript to be
automatically initialised for this form.

enable_form_change_checker() X-Ref

If you have called {@link 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.

is_form_change_checker_enabled() X-Ref

return: bool whether this form should automatically initialise

accept(&$renderer) X-Ref

Accepts a renderer

param: HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object

closeHeaderBefore($elementName) X-Ref

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

param: string $elementName name of the element

setForceLtr($elementname, $value = true) X-Ref

Set an element to be forced to flow LTR.

The element must exist and support this functionality. Also note that
when setting the type of a field (@link self::setType} we try to guess the
whether the field should be force to LTR or not. Make sure you're always
calling this method last.

param: string $elementname The element name.
param: bool $value When false, disables force LTR, else enables it.

setType($elementname, $paramtype) X-Ref

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

param: string $elementname
param: int $paramtype defines type of data contained in element. Use the constants PARAM_*.

setTypes($paramtypes) X-Ref

This can be used to set several types at once.

param: array $paramtypes types of parameters.

getCleanType($elementname, $value, $default = PARAM_RAW) X-Ref

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

param: string $elementname name of the element.
param: mixed $value value that should be cleaned.
param: int $default default constant value to be returned (PARAM_...)
return: string|array constant value or array of constant values (PARAM_...)

getCleanedValue($value, $type) X-Ref

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

param: mixed $value value that has to be cleaned.
param: int|array $type constant value to use to clean (PARAM_...), typically returned by {@link self::getCleanType()}.
return: mixed cleaned up value.

updateSubmission($submission, $files) X-Ref

Updates submitted values

param: array $submission submitted values
param: array $files list of files

getReqHTML() X-Ref

Returns HTML for required elements

return: string

getAdvancedHTML() X-Ref

Returns HTML for advanced elements

return: string

setDefault($elementName, $defaultValue) X-Ref

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

param: string $elementName element name
param: mixed $defaultValue values for that element name

addHelpButton($elementname, $identifier, $component = 'moodle', $linktext = '', $suppresscheck = false) X-Ref

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

param: string $elementname name of the element to add the item to
param: string $identifier help string identifier without _help suffix
param: string $component component name to look the help string in
param: string $linktext optional text to display next to the icon
param: bool $suppresscheck set to true if the element may not exist

setConstant($elname, $value) X-Ref

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

param: string $elname name of element
param: mixed $value

exportValues($elementList = null) X-Ref

export submitted values

param: string $elementList list of elements in form
return: array

prepare_fixed_value($name, $value) X-Ref

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

param: string $name the element name.
param: mixed $value the fixed value to set.
return: mixed the appropriate array to add to the $unfiltered array.

addRule($element, $message, $type, $format=null, $validation='server', $reset = false, $force = false) X-Ref

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.

param: string $element Form element name
param: string $message Message to display for invalid data
param: string $type Rule type, use getRegisteredRules() to get types
param: string $format (optional)Required for extra rule data
param: string $validation (optional)Where to perform validation: "server", "client"
param: bool $reset Client-side validation: reset the form element to its original value if there is an error?
param: bool $force Force the rule to be applied, even if the target form element does not exist

addGroupRule($group, $arg1, $type='', $format=null, $howmany=0, $validation = 'server', $reset = false) X-Ref

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.

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

getValidationScript() X-Ref

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: string Javascript to perform validation, empty string if no 'client' rules were added

qf_errorHandler(element, _qfMsg, escapedName) X-Ref

No description

validate_(if (undefined == element) X-Ref

No description

validate_(if (skipClientValidation) X-Ref

No description

_setDefaultRuleMessages() X-Ref

Sets default error message

getLockOptionObject() X-Ref

Get list of attributes which have dependencies

return: array

_getElNamesRecursive($element) X-Ref

Get names of element or elements in a group.

param: HTML_QuickForm_group|element $element element group or element object
return: array

disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1') X-Ref

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

param: string $elementName the name of the element which will be disabled
param: string $dependentOn the name of the element whose state will be checked for condition
param: string $condition the condition to check
param: mixed $value used in conjunction with condition.

hideIf($elementname, $dependenton, $condition = 'notchecked', $value = '1') X-Ref

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

param: string $elementname the name of the element which will be hidden
param: string $dependenton the name of the element whose state will be checked for condition
param: string $condition the condition to check
param: mixed $value used in conjunction with condition.

registerNoSubmitButton($buttonname) X-Ref

Registers button as no submit button

param: string $buttonname name of the button

isNoSubmitButton($buttonname) X-Ref

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

param: string $buttonname name of the button to check
return: bool

_registerCancelButton($addfieldsname) X-Ref

Registers a button as cancel button

param: string $addfieldsname name of the button

hardFreeze($elementList=null) X-Ref

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.

param: string|array $elementList array or string of element(s) to be frozen
return: object|bool if element list is not empty then return error object, else true

hardFreezeAllVisibleExcept($elementList) X-Ref

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.

param: array $elementList array or string of element(s) not to be frozen
return: bool returns true

isSubmitted() X-Ref

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: bool

note_new_repeat($name) X-Ref

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

param: string $name the name of the new element

is_new_repeat($name) X-Ref

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

param: string $name the name of the element being checked
return: bool true if the element is newly added

setAdvancedElements($elements) X-Ref

Set element's as adavance element

param: array $elements form elements which needs to be grouped as advance elements.

setCollapsibleElements($elements) X-Ref

Setting collapsible elements

param: array $elements

startForm(&$form) X-Ref

What to do when starting the form

param: MoodleQuickForm $form reference of the form

startGroup(&$group, $required, $error) X-Ref

Create advance group of elements

param: MoodleQuickForm_group $group Passed by reference
param: bool $required if input is required field
param: string $error error message to display

renderElement(&$element, $required, $error) X-Ref

Renders element

param: HTML_QuickForm_element $element element
param: bool $required if input is required field
param: string $error error message to display

finishForm(&$form) X-Ref

Called when visiting a form, after processing all form elements
Adds required note, form attributes, validation javascript and form content.

param: moodleform $form Passed by reference

renderHeader(&$header) X-Ref

Called when visiting a header element

param: HTML_QuickForm_header $header An HTML_QuickForm_header element being visited

getStopFieldsetElements() X-Ref

Return Array of element names that indicate the end of a fieldset

return: array

Class: MoodleQuickForm_Rule_Required - X-Ref

Required elements validation

This class overrides QuickForm validation since it allowed space or empty tag as a value

validate($value, $options = null) X-Ref

Checks if an element is not empty.
This is a server-side validation, it works for both text fields and editor fields

param: string $value Value to check
param: int|string|array $options Not used yet
return: bool true if value is not empty

getValidationScript($format = null) X-Ref

This function returns Javascript code used to build client-side validation.
It checks if an element is not empty.

param: int $format format of data which needs to be validated.
return: array

Functions that are not part of a class:

pear_handle_error($error) X-Ref

Callback called when PEAR throws an error

param: PEAR_Error $error

form_init_date_js() X-Ref

Initalize javascript for date type form element

Copyright:	2006 Jamie Pratt <me@jamiep.org>
License:	http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size:	3398 lines (143 kb)
Included or required:	0 times
Referenced:	27 times
Includes or requires:	0 files

Defines 7 classes

Defines 2 functions