MoodleDocs - User contributions [en]

Form API

2022-02-04T09:48:16Z

Systemovich: /* Usage */

==Overview==
[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.
==Highlights==
# Tested and optimised for use on major screen-readers like Dragon and JAWS.
# Tableless layout.
# Processes form data securely, with required_param, optional_param and session key.
# Supports client-side validation.
# Facility to add Moodle help buttons to forms.
# Support for file repository using [[File_API]] .
# Support for many custom Moodle specific and non-specific form elements.
# Facility for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].
# Facility for form elements in advanced group
==Usage==
To create a form in Moodle, you have to create a class that extends the moodleform class and overrides the [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] member function for including form elements.
<syntaxhighlight lang="php">
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form.
$mform->setType('email', PARAM_NOTAGS); // Set type of element.
$mform->setDefault('email', 'Please enter email'); // Default value.
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
</syntaxhighlight>
Then instantiate the form (in this case simplehtml_form) on your page.
<syntaxhighlight lang="php">
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
</syntaxhighlight>
If you wish to use the form within a block then you should consider using the render method, as demonstrated below:

Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.
<syntaxhighlight lang="php">
class block_yourblock extends block_base{
public function init(){
$this->title = 'Your Block';
}
public function get_content(){

$this->content = new stdClass();
$this->content->text = '';

$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);

//displays the form
$this->content->text = $mform->render();
}

return $this->content;

}
}
</syntaxhighlight>
==Form elements==
===Basic form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements header]
=== Advanced form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#float float]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]
===Custom form elements===
If you need a custom form element you can dynamical register new elements and then use them like this:

<syntaxhighlight lang="php">
MoodleQuickForm::registerElementType('course_competency_rule',
"$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",
'tool_lp_course_competency_rule_form_element');
// Reuse the same options.
$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);
</syntaxhighlight>
See:

https://github.com/moodle/moodle/blob/master/admin/tool/lp/lib.php#L157-L161

https://github.com/moodle/moodle/blob/master/admin/tool/lp/classes/course_competency_rule_form_element.php
==Commonly used functions==
====add_action_buttons($cancel = true, $submitlabel=null);====
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''
<syntaxhighlight lang="php">
$this->add_action_buttons();
</syntaxhighlight>
====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]====
To set the default value for an element.
====[[lib/formslib.php_Form_Definition#disabledIf|disabledIf()]]====
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.
====[[lib/formslib.php_Form_Definition#hideIf|hideif()]]====
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
Same syntax as disabledIf. Can do a simple search and replace on disabledIf. Added in Moodle 3.4.
====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====
Add rule for server/client side validation. Like text field is required element and is of type email.
====setHelpButton()====
DEPRECATED - Sets pop-up help button to a form element. Use addHelpButton() instead.
====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====
Adds pop-up help button to a form element
====[[lib/formslib.php_Form_Definition#setType|setType()]]====
PARAM_* types are used to specify how a submitted variable should be cleaned.
====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====
By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.
==FAQ==
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
==See also==
* [[Core_APIs]]
* [[lib/formslib.php_Usage]]
* [[lib/formslib.php_Form_Definition]]
* [[Designing usable forms]]
* [[Fragment]]
* [[MForm_Modal]]
[[Category:API]]

Form API

2022-02-04T09:37:36Z

Systemovich: /* Highlights */

==Overview==
[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.
==Highlights==
# Tested and optimised for use on major screen-readers like Dragon and JAWS.
# Tableless layout.
# Processes form data securely, with required_param, optional_param and session key.
# Supports client-side validation.
# Facility to add Moodle help buttons to forms.
# Support for file repository using [[File_API]] .
# Support for many custom Moodle specific and non-specific form elements.
# Facility for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].
# Facility for form elements in advanced group
==Usage==
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
<syntaxhighlight lang="php">
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
</syntaxhighlight>
Then instantiate form (in this case simplehtml_form) on your page.
<syntaxhighlight lang="php">
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
</syntaxhighlight>
If you wish to use the form within a block then you should consider using the render method, as demonstrated below:

Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.
<syntaxhighlight lang="php">
class block_yourblock extends block_base{
public function init(){
$this->title = 'Your Block';
}
public function get_content(){

$this->content = new stdClass();
$this->content->text = '';

$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);

//displays the form
$this->content->text = $mform->render();
}

return $this->content;

}
}
</syntaxhighlight>
==Form elements==
===Basic form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements header]
=== Advanced form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#float float]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]
===Custom form elements===
If you need a custom form element you can dynamical register new elements and then use them like this:

<syntaxhighlight lang="php">
MoodleQuickForm::registerElementType('course_competency_rule',
"$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",
'tool_lp_course_competency_rule_form_element');
// Reuse the same options.
$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);
</syntaxhighlight>
See:

https://github.com/moodle/moodle/blob/master/admin/tool/lp/lib.php#L157-L161

https://github.com/moodle/moodle/blob/master/admin/tool/lp/classes/course_competency_rule_form_element.php
==Commonly used functions==
====add_action_buttons($cancel = true, $submitlabel=null);====
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''
<syntaxhighlight lang="php">
$this->add_action_buttons();
</syntaxhighlight>
====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]====
To set the default value for an element.
====[[lib/formslib.php_Form_Definition#disabledIf|disabledIf()]]====
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.
====[[lib/formslib.php_Form_Definition#hideIf|hideif()]]====
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
Same syntax as disabledIf. Can do a simple search and replace on disabledIf. Added in Moodle 3.4.
====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====
Add rule for server/client side validation. Like text field is required element and is of type email.
====setHelpButton()====
DEPRECATED - Sets pop-up help button to a form element. Use addHelpButton() instead.
====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====
Adds pop-up help button to a form element
====[[lib/formslib.php_Form_Definition#setType|setType()]]====
PARAM_* types are used to specify how a submitted variable should be cleaned.
====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====
By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.
==FAQ==
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
==See also==
* [[Core_APIs]]
* [[lib/formslib.php_Usage]]
* [[lib/formslib.php_Form_Definition]]
* [[Designing usable forms]]
* [[Fragment]]
* [[MForm_Modal]]
[[Category:API]]

Form API

2022-02-04T09:34:13Z

Systemovich: /* Overview */

==Overview==
[https://en.wikipedia.org/wiki/Form_(HTML) Web forms] in Moodle are created using the Form API. The Form API supports all HTML elements (checkboxes, radio buttons, text boxes, etc), with improved accessibility and security.
==Highlights==
# Tested and optimised for use on major screen-readers Dragon and JAWS.
# Tableless layout.
# Process form data securely, with required_param, optional_param and session key.
# Supports client-side validation
# Facility to add Moodle help buttons to forms.
# Support for file repository using [[File_API]]
# Support for many custom moodle specific and non-specific form elements.
# Addition for [https://docs.moodle.org/dev/lib/formslib.php_repeat_elements repeated elements].
# Addition for form elements in advance group
==Usage==
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
<syntaxhighlight lang="php">
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
</syntaxhighlight>
Then instantiate form (in this case simplehtml_form) on your page.
<syntaxhighlight lang="php">
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
</syntaxhighlight>
If you wish to use the form within a block then you should consider using the render method, as demonstrated below:

Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.
<syntaxhighlight lang="php">
class block_yourblock extends block_base{
public function init(){
$this->title = 'Your Block';
}
public function get_content(){

$this->content = new stdClass();
$this->content->text = '';

$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);

//displays the form
$this->content->text = $mform->render();
}

return $this->content;

}
}
</syntaxhighlight>
==Form elements==
===Basic form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements header]
=== Advanced form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#float float]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]
===Custom form elements===
If you need a custom form element you can dynamical register new elements and then use them like this:

<syntaxhighlight lang="php">
MoodleQuickForm::registerElementType('course_competency_rule',
"$CFG->dirroot/$CFG->admin/tool/lp/classes/course_competency_rule_form_element.php",
'tool_lp_course_competency_rule_form_element');
// Reuse the same options.
$mform->addElement('course_competency_rule', 'competency_rule', get_string('uponcoursemodulecompletion', 'tool_lp'), $options);
</syntaxhighlight>
See:

https://github.com/moodle/moodle/blob/master/admin/tool/lp/lib.php#L157-L161

https://github.com/moodle/moodle/blob/master/admin/tool/lp/classes/course_competency_rule_form_element.php
==Commonly used functions==
====add_action_buttons($cancel = true, $submitlabel=null);====
You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''
<syntaxhighlight lang="php">
$this->add_action_buttons();
</syntaxhighlight>
====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]====
To set the default value for an element.
====[[lib/formslib.php_Form_Definition#disabledIf|disabledIf()]]====
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.
====[[lib/formslib.php_Form_Definition#hideIf|hideif()]]====
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
Same syntax as disabledIf. Can do a simple search and replace on disabledIf. Added in Moodle 3.4.
====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====
Add rule for server/client side validation. Like text field is required element and is of type email.
====setHelpButton()====
DEPRECATED - Sets pop-up help button to a form element. Use addHelpButton() instead.
====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====
Adds pop-up help button to a form element
====[[lib/formslib.php_Form_Definition#setType|setType()]]====
PARAM_* types are used to specify how a submitted variable should be cleaned.
====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====
By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.
==FAQ==
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
==See also==
* [[Core_APIs]]
* [[lib/formslib.php_Usage]]
* [[lib/formslib.php_Form_Definition]]
* [[Designing usable forms]]
* [[Fragment]]
* [[MForm_Modal]]
[[Category:API]]

User profile fields

2021-03-26T09:44:07Z

Systemovich: /* define_validate_specific() */ Added full stop.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
# checkbox
# datetime
# menu
# text
# textarea

==File Structure==
# Create a folder for your plugin in ''/user/profile/field/customprofilefieldplugin''. The folder name should contain only letters and numbers.
# Create the following files and add them to customprofilefieldplugin:
## ''lang/en/profilefield_customprofilefieldplugin.php'' - Language file, containing strings for user profile field.
## ''define.class.php'' - Definition of the user profile field type will be added in this file.
## ''field.class.php'' - Controls user profile field display, while editing or showing as user profile field.
## ''version.php'' - Contains version information for customprofilefieldplugin.

==Naming convention==
# '''profilefield_''' is prefixed to the name of the user profile field plugin, for identifying the name of the plugin.
# ''define.class.php'' should contain a class with a name that has '''profile_define_''' prefixed to the custom user profile field plugin name.
# ''field.class.php'' should contain a class with a name that has '''profile_field_''' prefixed to the custom user profile field plugin name.
# The language file should define a '''pluginname''' string as the name of the plugin.

==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type.
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>

====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type.
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>

====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

User profile fields

2021-03-26T09:43:44Z

Systemovich: /* define_form_specific() */ Added full stop.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
# checkbox
# datetime
# menu
# text
# textarea

==File Structure==
# Create a folder for your plugin in ''/user/profile/field/customprofilefieldplugin''. The folder name should contain only letters and numbers.
# Create the following files and add them to customprofilefieldplugin:
## ''lang/en/profilefield_customprofilefieldplugin.php'' - Language file, containing strings for user profile field.
## ''define.class.php'' - Definition of the user profile field type will be added in this file.
## ''field.class.php'' - Controls user profile field display, while editing or showing as user profile field.
## ''version.php'' - Contains version information for customprofilefieldplugin.

==Naming convention==
# '''profilefield_''' is prefixed to the name of the user profile field plugin, for identifying the name of the plugin.
# ''define.class.php'' should contain a class with a name that has '''profile_define_''' prefixed to the custom user profile field plugin name.
# ''field.class.php'' should contain a class with a name that has '''profile_field_''' prefixed to the custom user profile field plugin name.
# The language file should define a '''pluginname''' string as the name of the plugin.

==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type.
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>

====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>
====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

User profile fields

2021-03-26T09:40:39Z

Systemovich: /* Naming convention */ Emphasised file names. Made the sentences easier to understand.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
# checkbox
# datetime
# menu
# text
# textarea

==File Structure==
# Create a folder for your plugin in ''/user/profile/field/customprofilefieldplugin''. The folder name should contain only letters and numbers.
# Create the following files and add them to customprofilefieldplugin:
## ''lang/en/profilefield_customprofilefieldplugin.php'' - Language file, containing strings for user profile field.
## ''define.class.php'' - Definition of the user profile field type will be added in this file.
## ''field.class.php'' - Controls user profile field display, while editing or showing as user profile field.
## ''version.php'' - Contains version information for customprofilefieldplugin.

==Naming convention==
# '''profilefield_''' is prefixed to the name of the user profile field plugin, for identifying the name of the plugin.
# ''define.class.php'' should contain a class with a name that has '''profile_define_''' prefixed to the custom user profile field plugin name.
# ''field.class.php'' should contain a class with a name that has '''profile_field_''' prefixed to the custom user profile field plugin name.
# The language file should define a '''pluginname''' string as the name of the plugin.

==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>
====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>
====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

User profile fields

2021-03-26T09:35:04Z

Systemovich: /* File Structure */ Fixed grammar. Made capitalization consistent. Emphasized file names.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
# checkbox
# datetime
# menu
# text
# textarea

==File Structure==
# Create a folder for your plugin in ''/user/profile/field/customprofilefieldplugin''. The folder name should contain only letters and numbers.
# Create the following files and add them to customprofilefieldplugin:
## ''lang/en/profilefield_customprofilefieldplugin.php'' - Language file, containing strings for user profile field.
## ''define.class.php'' - Definition of the user profile field type will be added in this file.
## ''field.class.php'' - Controls user profile field display, while editing or showing as user profile field.
## ''version.php'' - Contains version information for customprofilefieldplugin.

==Naming convention==
# '''profilefield_''' is prefixed to name of user profile field plugin, for identifying the name of the plugin.
# define.class.php should have a class with '''profile_define_''' prefix to custom user profile field plugin name.
# field.class.php should have a class with '''profile_field_''' prefix to custom user profile field plugin name.
# Language file should define '''pluginname''' as name of the plugin.
==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>
====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>
====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

User profile fields

2021-03-26T09:30:01Z

Systemovich: /* File Structure */ Added missing full stop. Underscores in the folder name will be stripped out, but then the folder will not be found.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
# checkbox
# datetime
# menu
# text
# textarea

==File Structure==
# Create a folder for your plugin in moodle/user/profile/field/customprofilefieldplugin. The folder name should contain only letters and numbers.
# Create following files and add them to customprofilefieldplugin
## lang/en/profilefield_customprofilefieldplugin.php - Language file, containing strings for user profile field.
## define.class.php - definition of user profile field will be added in this file.
## field.class.php - Controls user profile field display, while editing or showing as user profile field.
## version.php - contains version information for customprofilefieldplugin

==Naming convention==
# '''profilefield_''' is prefixed to name of user profile field plugin, for identifying the name of the plugin.
# define.class.php should have a class with '''profile_define_''' prefix to custom user profile field plugin name.
# field.class.php should have a class with '''profile_field_''' prefix to custom user profile field plugin name.
# Language file should define '''pluginname''' as name of the plugin.
==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>
====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>
====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

User profile fields

2021-03-26T09:27:38Z

Systemovich: /* History */ Fix grammar and make capitalization consistent in list of profile field plug-ins.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exist from Moodle 1.9 and support five default user profile field plugins:
# checkbox
# datetime
# menu
# text
# textarea

==File Structure==
# Create a folder for your plugin in moodle/user/profile/field/customprofilefieldplugin
# Create following files and add them to customprofilefieldplugin
## lang/en/profilefield_customprofilefieldplugin.php - Language file, containing strings for user profile field.
## define.class.php - definition of user profile field will be added in this file.
## field.class.php - Controls user profile field display, while editing or showing as user profile field.
## version.php - contains version information for customprofilefieldplugin
==Naming convention==
# '''profilefield_''' is prefixed to name of user profile field plugin, for identifying the name of the plugin.
# define.class.php should have a class with '''profile_define_''' prefix to custom user profile field plugin name.
# field.class.php should have a class with '''profile_field_''' prefix to custom user profile field plugin name.
# Language file should define '''pluginname''' as name of the plugin.
==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>
====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>
====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

User profile fields

2021-03-26T09:25:14Z

Systemovich: Improve grammar of introduction paragraph.

==Introduction==
This plugin allows you to add custom user profile field types of which instances can be added to the user profile. For example, if you want to display radio buttons on the user profile, then create a radio user profile field plugin, then create an instance of it.
==History==
User profile fields exists from 1.9 and supports five default user profile field plugins:
# Checkbox
# datetime
# menu
# text
# textarea
==File Structure==
# Create a folder for your plugin in moodle/user/profile/field/customprofilefieldplugin
# Create following files and add them to customprofilefieldplugin
## lang/en/profilefield_customprofilefieldplugin.php - Language file, containing strings for user profile field.
## define.class.php - definition of user profile field will be added in this file.
## field.class.php - Controls user profile field display, while editing or showing as user profile field.
## version.php - contains version information for customprofilefieldplugin
==Naming convention==
# '''profilefield_''' is prefixed to name of user profile field plugin, for identifying the name of the plugin.
# define.class.php should have a class with '''profile_define_''' prefix to custom user profile field plugin name.
# field.class.php should have a class with '''profile_field_''' prefix to custom user profile field plugin name.
# Language file should define '''pluginname''' as name of the plugin.
==Interface API==
===define.class.php===
====define_form_specific()====
Prints out the form snippet for the part of creating or editing a profile field specific to the current data type
<pre>
function define_form_specific(&$form) {
// select whether or not this should be checked by default
$form->addElement('selectyesno', 'defaultdata', get_string('label', 'profilefield_myprofilefield'));
$form->setDefault('defaultdata', 0); // defaults to 'no'
$form->setType('defaultdata', PARAM_BOOL);
}
</pre>
====define_validate_specific()====
Validate the data from the add/edit profile field form that is specific to the current data type
<pre>
function define_validate_specific($data) {
$errors = array();
// Make sure defaultdata is not false
if ($data->defaultdata == false) {
$errors['defaultdata'] = get_string('noprovided', 'profilefield_myprofilefield');
}
return $errors;
}
</pre>
====define_after_data====
Alter form based on submitted or existing data
<pre>
function define_after_data(&$form) {
if (empty($data->defaultdata)) {
$mform->addElement('static', 'description', get_string('shouldbeyes', 'profilefield_myprofilefield'));
}
}
</pre>
====define_save_preprocess====
Pre-process data from the profile field form before it is saved.
<pre>
function define_save_preprocess($data) {
if (empty($data->defaultdata)) {
$data->defaultdata = NULL;
}
return $data;
}
</pre>
===field.class.php===
====edit_field_add()====
Adds the profile field to the moodle form
<pre>
function edit_field_add(&$mform) {
// Create form field
$checkbox = &$mform->addElement('advcheckbox', $this->inputname, format_string($this->field->name));
if ($this->data == '1') {
$checkbox->setChecked(true);
}
$mform->setType($this->inputname, PARAM_BOOL);
if ($this->is_required() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->addRule($this->inputname, get_string('required'), 'nonzero', null, 'client');
}
}
</pre>
====display_data()====
Display the data for this field
<pre>
function display_data() {
$options = new stdClass();
$options->para = false;
$checked = intval($this->data) === 1 ? 'checked="checked"' : '';
return '<input disabled="disabled" type="checkbox" name="'.$this->inputname.'" '.$checked.' />';
}
</pre>
====edit_field_set_default()====
Sets the default data for the field in the form object
<pre>
function edit_field_set_default(&$mform) {
if (!empty($default)) {
$mform->setDefault($this->inputname, $this->field->defaultdata);
}
}
</pre>
====edit_validate_field()====
Validate the form field from profile page
<pre>
function edit_validate_field($usernew) {
$errors = array();
if (isset($usernew->{$this->inputname})) {
if ($usernew->{$this->inputname}['text'] === '') {
$errors[$this->inputname] = 'error';
}
}
return $errors;
}
</pre>

====edit_save_data_preprocess()====
Process the data before it gets saved in database
<pre>
function edit_save_data_preprocess($data, &$datarecord) {
if (is_array($data)) {
$datarecord->dataformat = $data['format'];
$data = $data['text'];
}
return $data;
}
</pre>
====edit_field_set_locked()====
HardFreeze the field if locked.
<pre>
function edit_field_set_locked(&$mform) {
if (!$mform->elementExists($this->inputname)) {
return;
}
if ($this->is_locked() and !has_capability('moodle/user:update', get_context_instance(CONTEXT_SYSTEM))) {
$mform->hardFreeze($this->inputname);
$mform->setConstant($this->inputname, $this->data);
}
}
</pre>
===Common functions===
The following will need to be added to any files accessing the profile_ functions:
<pre>
require_once("$CFG->dirroot/user/profile/lib.php");
</pre>
====profile_user_record($userid)====
Returns an object with the custom profile fields set for the given user
====profile_save_data($usernew)====
Saves custom profile field data
====profile_validation($usernew, $files)====
Validates custom user profile field

==Template==
[https://github.com/rajeshtaneja/userprofilefield user profile field template]
==Database tables==
Knowledge of database tables is not required for creating this plugin as, tables get populated when the fields are added to user profile page, by admin. There are two relevant tables for user profile fields:
# user_info_field - Information for custom field added to user profile page.
# user_info_data - Data added by user for the custom profile field
==FAQ==
===How to add custom user profile field===
Admin can add existing or custom profile fields. Refer [[:en : User profile fields]] for adding user profile fields to user profile.
===Which form elements does moodle support===
Refer [[Form_API]] for list of elements supported by moodle

[[Category:Plugins]]

Extending the theme custom menu

2020-07-22T08:32:52Z

Systemovich: /* Before we begin */ Punctuation

{{Template:Themes}}This is a quick tutorial that will run you through extending the custom menu by overriding your theme's renderer.

This tutorial is primarily PHP coding, and ranges from moderate to advanced difficulty.

==Before we begin==
First things first, you need to know a little something about the custom menu. The custom menu is populated from the manually entered input in ''"Theme Settings"''. Once the administrator has entered the custom menu items and saved them, the following steps are what they go through in order to be displayed:
# The theme calls '''''$OUTPUT->custom_menu()''''' which is the core_renderer's method responsible for producing the custom menu.
# core_renderer::custom_menu() does the following:
## Checks to make sure the admin has added custom menu items.
## Creates a new '''''custom_menu''''' object. When the custom menu object is created, it turns whatever the admin entered, into a structured array of information.
## Calls core_renderer::render_custom_menu and gives it the custom_menu object.
# core_renderer::render_custom_menu is where the magic happens. It does the following:
## First, it checks to make sure custom_menu contains items.
## Initializes the JavaScript for the custom menu. This is the YUI3 menunode component.
## Creates the HTML base of the custom menu.
## Then iterates through all of the items and calls the custom menu and passes them to another function that will turn them into HTML correctly.

I'm going to stop there, as there is no need at this point to go into any more detail. Don't worry if you are a little lost, it will get clearer as we start working through code.

In this tutorial will we look at how to extend the theme's renderer in two different way.
# Add a dynamic My Courses branch to the custom menu that will display all of the courses a user is enrolled in.
# Get the custom menu to fetch strings from the language files rather than just static strings you type, allowing for a translatable custom menu.

Before you start into this tutorial you should have read the following tutorial, or at least have a good knowledge of the the Moodle theme engine and Moodle development.
* [[Creating a theme based on boost]]
* [[Overriding a renderer]]

As this is a quick tutorial I am going to assume you have created a theme, tested it and got it all working, and are already well on your way to becoming a theme guru.

==Getting started==
Alright, as you have already have your theme ready to go preparation is pretty simple, we are going to go through and create (if you haven't already) the following files:
* theme/themename/lib.php
* theme/themename/renderers.php
* theme/themename/lang/en/themename.php

Next step open up your themes config.php file and add the following configuration option to it (at the bottom):
<code php>
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

If you've already got a custom renderer you will already have this line.

And thats it! now we move on to extending the custom menu.

==Adding the My Courses branch==
So the point of this extension is to add a '''My Courses''' branch to the end of the custom menu.

The plan is to have the my courses branch and then within that branch have an entry for every course the user is enrolled in, much the same as the my courses branch of the navigation.

In order to achieve this we need to add some items to the custom menu, the my courses branch and all of the courses within it. We can do this overriding the core_renderers '''render_custom_menu''' method, of more accuratly create our own render_custom_menu method that adds our items and then calls the original. Remember we only need to add items, we don't need to change what is being produced.

So within our renderers.php file add the following code:
<code php>
class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

So that is pretty simple right?!

Here we are defining our core_renderer which will contain our overridden method ''render_custom_menu'' which we have also defined there.
Note the definition of the render_custom_menu must be the same as the original, this means it must be '''protected''' and it must take one argument '''custom_menu $menu'''.

Next step is to write the code for our render_custom_menu method. As stated above we want to add a branch and courses to the end of it which we can do with the following bit of code:
<code php>
$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
</code>

So how this all works....
<code php>
$mycourses = $this->page->navigation->get('mycourses');
</code>
This line is a little bit of smarts, what we are doing is getting the mycourses branch from the navigation. We could make all of the database calls and work it all out ourselves but this will be much better for performance and is easier!

The next line of code is an ''if'' statement that checks three things
# The user is logged in, you must be logged in to see your courses.
# That we have a mycourses object, if the user isn't enrolled in anything they won't have a mycourses object.
# The the mycourses object has children, if it exists it should but it is better to be safe than get errors.

Within the if statement we are doing two main things happening, the first is to add the branch to the menu:
<code php>
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);
</code>
When adding a new branch we need to give it three things:
# A label '''$branchlabel'''.
# A URL '''$branchurl'''.
# A title '''$branchtitle''' in this case I have just set it to the same as $branchlabel because I am lazy, you can make it anything you want.
# A sort order '''$branchsort''' this just needs to be high enough that it ends up on last place where we want it. Make it small to put it at the front.

The final line of code from above simply adds it to the menu and collects a reference to it so that we can add courses to it.

The second thing being done in the if statement is iterate through all of the courses in the mycourses object and add them to the branch. That is done with the following bit of code:
<code php>
foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
</code>
So here we go through all of the mycourses objects children (which we know will be courses) and for each one we add an item to the branch.
When adding items here, like above, we need to give it the following:
# A label '''$coursenode->get_content()''' returns us the text in the navigation node.
# A url '''$coursenode->action''' which is the URL for the node.
# A title '''$coursenode->get_title()'''.

In this case we don't need to set a sort order because the navigation has already ordered them correctly!

So now we are through the if statement and there is only one line of code left:
<code php>
return parent::render_custom_menu($menu);
</code>

This line of code simply calls the original '''core_renderer::render_custom_menu''' method to do all of the remaining work. Because we don't need to change the display at all we don't need to redo what it does, we can just use it!.

How easy way that?! it's all done, if you open you site in your browser and log in the custom menu should now contain a my courses branch (providing you are enrolled in courses).

==Loading labels from language files==
If you run a site that is available in more than one language '''and''' you want to make use of the custom menu then you will probably be very interested in this.

The idea behind this extension is to load the labels and titles that get shown in the custom menu from the theme's language files rather than having just the fixed strings you type into the admin setting.

In order to achieve this we need to do somehow override the custom_menu_item class so that it loads the strings from the database if they match a special pattern. We can then update the admin setting to use our patter and wallah! things should load from the language files.

What makes this tricky is that we can't just override the custom_menu_item class, we also need to override the thing that makes create custom_menu_item instances which in this case is the core_renderer::render_custom_menu_item method.

===Overriding the custom_menu_item class===
Within your themes lib.php file add the following lines of code:
<code php>
class theme_themename_transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
// Our code will go here
}
}
</code>
What we have done here is create an overridden custom_menu_item class called '''transmuted_custom_menu_item'''.
Within that class we are overriding the constructor, the constructor will be given the original menu item, and we will need to instantiate this object with the properties of the original. Once we have instantiated it, with the properties of the original, we can alter then as we like.

Next we need to write the contents of the ''__construct'' method:
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
</code>

So there are essentially four things going on here.

First we need to populate this object with the properties of the original item. We do this by calling the original constructor with $menunode properties as shown below.
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
</code>

Next we need to copy the properties that are not included in the original constructor, in this case there is only one '''$this->children'''. This should be an array of all of this item's children (sub items).
<code php>
$this->children = $menunode->get_children();
</code>

Now that we have all the properties set up we can modify them. In our case we want to check if the items label and title match a special pattern and if they do we want to fetch them from the language file instead.
The special pattern is '''<nowiki>[[stringname]]</nowiki>''' where stringname is the name of the string that we want to get from the language file.
<code php>
$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}
</code>
In the code above we do the following:
# Create an array $matches which will hold the stringname if the label matches the pattern.
# We attempt to match the label to the pattern. If it does the $matches array now contains the stringname.
# If it did match we call get string as shown.

The third and final thing is to do the above again but this time for the title.

With that done our transmutable_custom_menu_item class is complete. Next step is to make use of it.

===Overriding render_custom_menu_item===
The next step is make use of the transmutable_custom_menu_item class we created previously.

We can do this by overriding the '''core_renderer::render_custom_menu_item''' method within our renderers.php file as shown below.
<code php>
protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new theme_themename_transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}
</code>
This is pretty simply, essentially we are using our transmuted_custom_menu_item class like a façade to the original custom_menu_item class by creating a new transmuted instance using the original.
Once we have the transmuted object we can call the original render_custom_menu_item method with it.

And that is it! Congratulations if you got it this far.

The only thing left to do is add strings to your themes language file as required!

==Complete source==
<code php>
// theme/themename/renderers.php

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
}

protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new theme_themename_transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}

}
</code>

<code php>
// theme/themename/lib.php

class theme_themename_transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
}
}
</code>

==See also==

* [[Adding courses and categories to the custom menu]]

Extending the theme custom menu

2020-07-22T08:17:05Z

Systemovich: /* Before we begin */ Add appropriate commas.

{{Template:Themes}}This is a quick tutorial that will run you through extending the custom menu by overriding your theme's renderer.

This tutorial is primarily PHP coding, and ranges from moderate to advanced difficulty.

==Before we begin==
First things first, you need to know a little something about the custom menu. The custom menu is populated from the manually entered input in ''"Theme Settings"''. Once the administrator has entered the custom menu items and saved them, the following steps are what they go through in order to be displayed:
# The theme calls '''''$OUTPUT->custom_menu()''''' which is the core_renderers method responsible for producing the custom menu.
# core_renderer::custom_menu() does the following:
## Checks to make sure the admin has added custom menu items.
## Creates a new '''''custom_menu''''' object. When the custom menu object is created it turns what ever the admin entered into a structured array of information.
## Calls core_renderer::render_custom_menu and gives it the custom_menu object.
# core_renderer::render_custom_menu is where the magic happens, it does the following.
## First it checks to make sure custom menu contains items.
## Initialises the JavaScript for the custom menu, this is the YUI3 menunode component.
## Creates the HTML base of the custom menu
## Then iterates through all of the items and calls the custom menu and passes them to another function that will turn them into HTML correctly.

I'm going to stop there, as there is no need at this point to go into any more detail. Don't worry if you are a little lost, it will get clearer as we start working through code.

In this tutorial will we look at how to extend the theme's renderer in two different way.
# Add a dynamic My Courses branch to the custom menu that will display all of the courses a user is enrolled in.
# Get the custom menu to fetch strings from the language files rather than just static strings you type, allowing for a translatable custom menu.

Before you start into this tutorial you should have read the following tutorial, or at least have a good knowledge of the the Moodle theme engine and Moodle development.
* [[Creating a theme based on boost]]
* [[Overriding a renderer]]

As this is a quick tutorial I am going to assume you have created a theme, tested it and got it all working, and are already well on your way to becoming a theme guru.

==Getting started==
Alright, as you have already have your theme ready to go preparation is pretty simple, we are going to go through and create (if you haven't already) the following files:
* theme/themename/lib.php
* theme/themename/renderers.php
* theme/themename/lang/en/themename.php

Next step open up your themes config.php file and add the following configuration option to it (at the bottom):
<code php>
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

If you've already got a custom renderer you will already have this line.

And thats it! now we move on to extending the custom menu.

==Adding the My Courses branch==
So the point of this extension is to add a '''My Courses''' branch to the end of the custom menu.

The plan is to have the my courses branch and then within that branch have an entry for every course the user is enrolled in, much the same as the my courses branch of the navigation.

In order to achieve this we need to add some items to the custom menu, the my courses branch and all of the courses within it. We can do this overriding the core_renderers '''render_custom_menu''' method, of more accuratly create our own render_custom_menu method that adds our items and then calls the original. Remember we only need to add items, we don't need to change what is being produced.

So within our renderers.php file add the following code:
<code php>
class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

So that is pretty simple right?!

Here we are defining our core_renderer which will contain our overridden method ''render_custom_menu'' which we have also defined there.
Note the definition of the render_custom_menu must be the same as the original, this means it must be '''protected''' and it must take one argument '''custom_menu $menu'''.

Next step is to write the code for our render_custom_menu method. As stated above we want to add a branch and courses to the end of it which we can do with the following bit of code:
<code php>
$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
</code>

So how this all works....
<code php>
$mycourses = $this->page->navigation->get('mycourses');
</code>
This line is a little bit of smarts, what we are doing is getting the mycourses branch from the navigation. We could make all of the database calls and work it all out ourselves but this will be much better for performance and is easier!

The next line of code is an ''if'' statement that checks three things
# The user is logged in, you must be logged in to see your courses.
# That we have a mycourses object, if the user isn't enrolled in anything they won't have a mycourses object.
# The the mycourses object has children, if it exists it should but it is better to be safe than get errors.

Within the if statement we are doing two main things happening, the first is to add the branch to the menu:
<code php>
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);
</code>
When adding a new branch we need to give it three things:
# A label '''$branchlabel'''.
# A URL '''$branchurl'''.
# A title '''$branchtitle''' in this case I have just set it to the same as $branchlabel because I am lazy, you can make it anything you want.
# A sort order '''$branchsort''' this just needs to be high enough that it ends up on last place where we want it. Make it small to put it at the front.

The final line of code from above simply adds it to the menu and collects a reference to it so that we can add courses to it.

The second thing being done in the if statement is iterate through all of the courses in the mycourses object and add them to the branch. That is done with the following bit of code:
<code php>
foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
</code>
So here we go through all of the mycourses objects children (which we know will be courses) and for each one we add an item to the branch.
When adding items here, like above, we need to give it the following:
# A label '''$coursenode->get_content()''' returns us the text in the navigation node.
# A url '''$coursenode->action''' which is the URL for the node.
# A title '''$coursenode->get_title()'''.

In this case we don't need to set a sort order because the navigation has already ordered them correctly!

So now we are through the if statement and there is only one line of code left:
<code php>
return parent::render_custom_menu($menu);
</code>

This line of code simply calls the original '''core_renderer::render_custom_menu''' method to do all of the remaining work. Because we don't need to change the display at all we don't need to redo what it does, we can just use it!.

How easy way that?! it's all done, if you open you site in your browser and log in the custom menu should now contain a my courses branch (providing you are enrolled in courses).

==Loading labels from language files==
If you run a site that is available in more than one language '''and''' you want to make use of the custom menu then you will probably be very interested in this.

The idea behind this extension is to load the labels and titles that get shown in the custom menu from the theme's language files rather than having just the fixed strings you type into the admin setting.

In order to achieve this we need to do somehow override the custom_menu_item class so that it loads the strings from the database if they match a special pattern. We can then update the admin setting to use our patter and wallah! things should load from the language files.

What makes this tricky is that we can't just override the custom_menu_item class, we also need to override the thing that makes create custom_menu_item instances which in this case is the core_renderer::render_custom_menu_item method.

===Overriding the custom_menu_item class===
Within your themes lib.php file add the following lines of code:
<code php>
class theme_themename_transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
// Our code will go here
}
}
</code>
What we have done here is create an overridden custom_menu_item class called '''transmuted_custom_menu_item'''.
Within that class we are overriding the constructor, the constructor will be given the original menu item, and we will need to instantiate this object with the properties of the original. Once we have instantiated it, with the properties of the original, we can alter then as we like.

Next we need to write the contents of the ''__construct'' method:
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
</code>

So there are essentially four things going on here.

First we need to populate this object with the properties of the original item. We do this by calling the original constructor with $menunode properties as shown below.
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
</code>

Next we need to copy the properties that are not included in the original constructor, in this case there is only one '''$this->children'''. This should be an array of all of this item's children (sub items).
<code php>
$this->children = $menunode->get_children();
</code>

Now that we have all the properties set up we can modify them. In our case we want to check if the items label and title match a special pattern and if they do we want to fetch them from the language file instead.
The special pattern is '''<nowiki>[[stringname]]</nowiki>''' where stringname is the name of the string that we want to get from the language file.
<code php>
$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}
</code>
In the code above we do the following:
# Create an array $matches which will hold the stringname if the label matches the pattern.
# We attempt to match the label to the pattern. If it does the $matches array now contains the stringname.
# If it did match we call get string as shown.

The third and final thing is to do the above again but this time for the title.

With that done our transmutable_custom_menu_item class is complete. Next step is to make use of it.

===Overriding render_custom_menu_item===
The next step is make use of the transmutable_custom_menu_item class we created previously.

We can do this by overriding the '''core_renderer::render_custom_menu_item''' method within our renderers.php file as shown below.
<code php>
protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new theme_themename_transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}
</code>
This is pretty simply, essentially we are using our transmuted_custom_menu_item class like a façade to the original custom_menu_item class by creating a new transmuted instance using the original.
Once we have the transmuted object we can call the original render_custom_menu_item method with it.

And that is it! Congratulations if you got it this far.

The only thing left to do is add strings to your themes language file as required!

==Complete source==
<code php>
// theme/themename/renderers.php

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
}

protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new theme_themename_transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}

}
</code>

<code php>
// theme/themename/lib.php

class theme_themename_transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
}
}
</code>

==See also==

* [[Adding courses and categories to the custom menu]]

Extending the theme custom menu

2020-07-22T08:05:16Z

Systemovich: Remove superfluous word "quickly". Fixed grammar of sentence.

{{Template:Themes}}This is a quick tutorial that will run you through extending the custom menu by overriding your theme's renderer.

This tutorial is primarily PHP coding, and ranges from moderate to advanced difficulty.

==Before we begin==
First things first you need to know a little something about the custom menu. The custom menu is populated from the manually entered input in ''"Theme Settings"''. Once the administrator has entered the custom menu items and saved them the following steps are what they go through in order to be displayed:
# The theme calls '''''$OUTPUT->custom_menu()''''' which is the core_renderers method responsible for producing the custom menu.
# core_renderer::custom_menu() does the following:
## Checks to make sure the admin has added custom menu items.
## Creates a new '''''custom_menu''''' object. When the custom menu object is created it turns what ever the admin entered into a structured array of information.
## Calls core_renderer::render_custom_menu and gives it the custom_menu object.
# core_renderer::render_custom_menu is where the magic happens, it does the following.
## First it checks to make sure custom menu contains items.
## Initialises the JavaScript for the custom menu, this is the YUI3 menunode component.
## Creates the HTML base of the custom menu
## Then iterates through all of the items and calls the custom menu and passes them to another function that will turn them into HTML correctly.

I'm going to stop there, as there is no need at this point to go into any more detail. Don't worry if you are a little lost, it will get clearer as we start working through code.

In this tutorial will we look at how to extend the theme's renderer in two different way.
# Add a dynamic My Courses branch to the custom menu that will display all of the courses a user is enrolled in.
# Get the custom menu to fetch strings from the language files rather than just static strings you type, allowing for a translatable custom menu.

Before you start into this tutorial you should have read the following tutorial, or at least have a good knowledge of the the Moodle theme engine and Moodle development.
* [[Creating a theme based on boost]]
* [[Overriding a renderer]]

As this is a quick tutorial I am going to assume you have created a theme, tested it and got it all working, and are already well on your way to becoming a theme guru.

==Getting started==
Alright, as you have already have your theme ready to go preparation is pretty simple, we are going to go through and create (if you haven't already) the following files:
* theme/themename/lib.php
* theme/themename/renderers.php
* theme/themename/lang/en/themename.php

Next step open up your themes config.php file and add the following configuration option to it (at the bottom):
<code php>
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

If you've already got a custom renderer you will already have this line.

And thats it! now we move on to extending the custom menu.

==Adding the My Courses branch==
So the point of this extension is to add a '''My Courses''' branch to the end of the custom menu.

The plan is to have the my courses branch and then within that branch have an entry for every course the user is enrolled in, much the same as the my courses branch of the navigation.

In order to achieve this we need to add some items to the custom menu, the my courses branch and all of the courses within it. We can do this overriding the core_renderers '''render_custom_menu''' method, of more accuratly create our own render_custom_menu method that adds our items and then calls the original. Remember we only need to add items, we don't need to change what is being produced.

So within our renderers.php file add the following code:
<code php>
class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

So that is pretty simple right?!

Here we are defining our core_renderer which will contain our overridden method ''render_custom_menu'' which we have also defined there.
Note the definition of the render_custom_menu must be the same as the original, this means it must be '''protected''' and it must take one argument '''custom_menu $menu'''.

Next step is to write the code for our render_custom_menu method. As stated above we want to add a branch and courses to the end of it which we can do with the following bit of code:
<code php>
$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
</code>

So how this all works....
<code php>
$mycourses = $this->page->navigation->get('mycourses');
</code>
This line is a little bit of smarts, what we are doing is getting the mycourses branch from the navigation. We could make all of the database calls and work it all out ourselves but this will be much better for performance and is easier!

The next line of code is an ''if'' statement that checks three things
# The user is logged in, you must be logged in to see your courses.
# That we have a mycourses object, if the user isn't enrolled in anything they won't have a mycourses object.
# The the mycourses object has children, if it exists it should but it is better to be safe than get errors.

Within the if statement we are doing two main things happening, the first is to add the branch to the menu:
<code php>
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);
</code>
When adding a new branch we need to give it three things:
# A label '''$branchlabel'''.
# A URL '''$branchurl'''.
# A title '''$branchtitle''' in this case I have just set it to the same as $branchlabel because I am lazy, you can make it anything you want.
# A sort order '''$branchsort''' this just needs to be high enough that it ends up on last place where we want it. Make it small to put it at the front.

The final line of code from above simply adds it to the menu and collects a reference to it so that we can add courses to it.

The second thing being done in the if statement is iterate through all of the courses in the mycourses object and add them to the branch. That is done with the following bit of code:
<code php>
foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
</code>
So here we go through all of the mycourses objects children (which we know will be courses) and for each one we add an item to the branch.
When adding items here, like above, we need to give it the following:
# A label '''$coursenode->get_content()''' returns us the text in the navigation node.
# A url '''$coursenode->action''' which is the URL for the node.
# A title '''$coursenode->get_title()'''.

In this case we don't need to set a sort order because the navigation has already ordered them correctly!

So now we are through the if statement and there is only one line of code left:
<code php>
return parent::render_custom_menu($menu);
</code>

This line of code simply calls the original '''core_renderer::render_custom_menu''' method to do all of the remaining work. Because we don't need to change the display at all we don't need to redo what it does, we can just use it!.

How easy way that?! it's all done, if you open you site in your browser and log in the custom menu should now contain a my courses branch (providing you are enrolled in courses).

==Loading labels from language files==
If you run a site that is available in more than one language '''and''' you want to make use of the custom menu then you will probably be very interested in this.

The idea behind this extension is to load the labels and titles that get shown in the custom menu from the theme's language files rather than having just the fixed strings you type into the admin setting.

In order to achieve this we need to do somehow override the custom_menu_item class so that it loads the strings from the database if they match a special pattern. We can then update the admin setting to use our patter and wallah! things should load from the language files.

What makes this tricky is that we can't just override the custom_menu_item class, we also need to override the thing that makes create custom_menu_item instances which in this case is the core_renderer::render_custom_menu_item method.

===Overriding the custom_menu_item class===
Within your themes lib.php file add the following lines of code:
<code php>
class theme_themename_transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
// Our code will go here
}
}
</code>
What we have done here is create an overridden custom_menu_item class called '''transmuted_custom_menu_item'''.
Within that class we are overriding the constructor, the constructor will be given the original menu item, and we will need to instantiate this object with the properties of the original. Once we have instantiated it, with the properties of the original, we can alter then as we like.

Next we need to write the contents of the ''__construct'' method:
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
</code>

So there are essentially four things going on here.

First we need to populate this object with the properties of the original item. We do this by calling the original constructor with $menunode properties as shown below.
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
</code>

Next we need to copy the properties that are not included in the original constructor, in this case there is only one '''$this->children'''. This should be an array of all of this item's children (sub items).
<code php>
$this->children = $menunode->get_children();
</code>

Now that we have all the properties set up we can modify them. In our case we want to check if the items label and title match a special pattern and if they do we want to fetch them from the language file instead.
The special pattern is '''<nowiki>[[stringname]]</nowiki>''' where stringname is the name of the string that we want to get from the language file.
<code php>
$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}
</code>
In the code above we do the following:
# Create an array $matches which will hold the stringname if the label matches the pattern.
# We attempt to match the label to the pattern. If it does the $matches array now contains the stringname.
# If it did match we call get string as shown.

The third and final thing is to do the above again but this time for the title.

With that done our transmutable_custom_menu_item class is complete. Next step is to make use of it.

===Overriding render_custom_menu_item===
The next step is make use of the transmutable_custom_menu_item class we created previously.

We can do this by overriding the '''core_renderer::render_custom_menu_item''' method within our renderers.php file as shown below.
<code php>
protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new theme_themename_transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}
</code>
This is pretty simply, essentially we are using our transmuted_custom_menu_item class like a façade to the original custom_menu_item class by creating a new transmuted instance using the original.
Once we have the transmuted object we can call the original render_custom_menu_item method with it.

And that is it! Congratulations if you got it this far.

The only thing left to do is add strings to your themes language file as required!

==Complete source==
<code php>
// theme/themename/renderers.php

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
}

protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new theme_themename_transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}

}
</code>

<code php>
// theme/themename/lib.php

class theme_themename_transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
}
}
</code>

==See also==

* [[Adding courses and categories to the custom menu]]

Upgrade API

2020-02-06T09:13:45Z

Systemovich: Replace "module" in first sentence with more general term "plugin". "Module" might be confused with activity plugins only. Grammar errors, like repeated words.

The Upgrade API is how your plugin installs and upgrades itself, by keeping track of its own version.

==Introduction==
By implementing this API in your plugin, Moodle will automatically create your database tables for you when you visit the Admin notifications page (.../admin/index.php).

This process is controlled by three files within your plugin (there are other optional files you can use for various things. These are covered at the end of this document):
;[[version.php]] : This records the version of the plugin code ('''Please note:''' In Moodle installations below v2.0, this is not required for blocks, which use the version number returned by the block's init() method - see [[Blocks#Ready.2C_Set.2C_Go.21|the blocks development page]]). You must increase version in version.php after any change in /db/ folder, any change in javascript code, any new auto-loaded class, any new setting and also after any change in language pack, because a new version triggers the upgrade procedure and resets all caches.
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.x, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.x, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the ('qtype_myqtype', 'version') row of the mdl_config_plugins table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_myqtype_options, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_myqtype_options table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100; // Today's date in YYYYMMDD format, plus two additional digits
$plugin->requires = '''XXXXXXXXXX; // Moodle version - copy from $version in the top-level version.php file.'''
:Version numbers normally consist of the day's date in YYYYMMDD format, followed by two additional digits to allow for multiple versions in the same day, e.g. Sept 15, 2010 could have versions 2010091500, 2010091501, 2010091502, etc.

;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_myqtype_options table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_myqtype_options table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_myqtype_options table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion) {
global $DB;
$dbman = $DB->get_manager();

/// Add a new column newcol to the mdl_myqtype_options
if ($oldversion < 2015031200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return true;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/upgradelib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

if (get_config('qtype_myqtype', 'version') exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from upgrade.php,
passing the old version number that says what is currently installed
set_config('version', ''latest number from version.php'', 'qtype_myqtype')
to record what is currently installed

} else if (get_config('qtype_myqtype', 'version') does not exist) {
Create the tables from the definitions in install.xml
set_config('version', ''latest number from version.php'', 'qtype_myqtype')
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_myqtype_options does not exist, and there will not be a ('qtype_myqtype', 'version') row in the mdl_config_plugins table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_myqtype_options table will exist with the two columns col1 and col2; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_myqtype_options table will exist with the two columns col1 and col2; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables ('qtype_myqtype', 'version') is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_myqtype_options table will now have three columns col1, col2 and newcol; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_myqtype_options does not exist, and there will not be a ('qtype_myqtype', 'version') row in the mdl_config_plugins table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_myqtype_options table will exist with three columns col1, col2 and newcol; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080200.

== Upgrade code restrictions ==

Within an upgrade, there are restrictions on the functions your code should call, because the system has not been fully updated.

* All upgrade code can use the basic database API ($DB->... functions).
* In a '''plugin''', upgrade code should not call '''any plugin functions'''. (For example, if your plugin has a function that changes frog settings to 'green', and you need to do this during upgrade, then you should not call this function; instead, manually update the database rows so that the frog settings become green.) However, '''you should call core functions''' rather than making core changes in database.
* In '''core''', upgrade code should not even call '''any core functions''' (For example, if you need to add a calendar event, this should be done by inserting into a database table rather than calling a function to add the event.) Certain functions marked with a comment such as set_config and get_config are excepted.

The reason for this is the state of the system during upgrade.

During core upgrade the state is as follows:

* Core data: '''Old'''.
* Plugin data: '''Old'''.

Core functions expect core data to be in the Current state, so it is not safe to call them, unless the following is present in the function's docblock: "NOTE: this function is called from lib/db/upgrade.php".

During plugin upgrade the state is as follows:

* Core data: '''Current'''. (Because core upgrade runs before plugin upgrade.)
* Plugin data: '''Old'''.

Core functions are now safe to call because the core data is in Current state. But plugin functions, which expect data to be in the Current state, are not safe.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no (''plugintype''_''pluginname'', version) value in the mdl_config_plugins table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the (''plugintype''_''pluginname'', version) value in the mdl_config_plugins table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Other things that can be in the db folder==

Of these, only install.php relates to creating the necessary database structure. The other files are mainly about providing the other meta-data that is required when the plugin is installed. I have tried to link to other documentation that goes into detail where possible.

===install.php===

(Moodle 2.0 and later)

If you define a function like xmldb_qtype_myqtype_install(), this PHP code will be executed when your plugin is installed. This is an opportunity to do things that you cannot do with install.xml. It's executed immediately after the DB schema associated with the component (install.xml) is created.

(Moodle 1.9)

An install function can be defined in lib.php in the root directory of your module. The install function must have the name qtype_install() and takes no arguments (n.b. this is called from lib/adminlib.php after install.xml is parsed)

===uninstall.php===

(Moodle 2.0 and later)

Balancing the previous feature, it's also possible to define one function like xmldb_qtype_myqtype_uninstall(), that will be executed when your plugin is uninstalled, before dropping its DB schema.

===access.php===

(Moodle 1.7 and later)

Use to define the [[Roles#Capabilities|capabilities]] that this plugin handles with the [[Access API]]. You must increase version in version.php after adding new capabilities.

===events.php===

(Moodle 1.9(?) and later)

Used to define the events this plugin sends to the [[Events_API|Events API]]. You must increase version in version.php after modifying or adding new events.

===log.php===

(Moodle 2.0 and later)

Used to describe the type of log entries that this plugin creates. See the [[Logging API#Mod/*/db/log.php Files| log.php section]] of the [[Logging API]] for more information. You must increase version in version.php after any change.

===messages.php===

(Moodle 2.0 and later)

Used to define the messages this plugin sends through the [[Message API|Messaging API]]. You must increase version in version.php after any change.

===services.php===

(Moodle 2.0 and later)

Used to define the functions and services this plugin publishes through the [[Web services API]]. Usually all those functions are part of the [[External functions API]]. You must increase version in version.php after any change.

===upgradelib.php===

Optional file where upgrade code can be grouped under some '''helper functions''' to be used in the upgrade.php file. If needed, this file must be '''manually required''' once from upgrade.php. Its main goal is to keep the upgrade.php scripts reduced and clear (this cannot contain any function themselves apart from the xmldb_xxx_upgrade() one).

It's '''important''' to note that the upgradelib.php files should always be performing any task using raw - low level - database access exclusively, '''avoiding any use of the Moodle APIs'''.

===mod/.../db/subplugins.php===

(Moodle 2.0 and later)

This only applies to activity modules, not other types of plugin. It is a way to allow an activity module to have its own sorts of plugins. For example workshop allocation schemes, or quiz reports.

==Language packs==

Do not forget to increase version number after modifying lang/en/type_yourplugin.php language file. See [[Languages/AMOS]] section AMOS script for more information.

==Upgrade API Cheatsheet==

The Upgrade API is '''related with a lot''' of different files and APIs (access, event, log, webservice...) as far as it's the API used to install/upgrade all those artifacts. The previous sections have tried to list all those dependencies when possible.

Also, the Upgrade API '''does a very intensive use''' of other APIs ([[Data definition API|ddl]], [[Data manipulation API|dml]]) and tools (the XMLDB editor...) in order to proceed with the modifications of the Moodle system.

Once stated the above, we could summarise the API as the '''collection of a few files and functions''', here they are:

'''The files''': For each component we can have, under its "db" directory.
* '''version.php''': Where the $version is specified and, if bumped, the upgrade machinery will be launched and all caches reset. Bump up version after changing /db/, /lang/, theme or JavaScript.
* '''install.xml''': XMLDB definition of the DB schema. generated with the XMLDB Editor.
* '''install.php''': Post-install file executed once the schema has been created.
* '''uninstall.php''': Pre-uninstall file executed before the schema is dropped.
* '''upgrade.php''': Ordered list of upgrade steps, each one performing a well-defined task.
* '''upgradelib.php''': Library files composed of helper functions to be used by upgrade.php.

'''The functions''': With different names for different components, but available to all them:
* '''xmldb_[main|[[Frankenstyle|frankenstyle]]]_install()''': to be used in install.php files.
* '''xmldb_[main|frankenstyle]_uninstall()''': to be used in uninstall.php files.
* '''xmldb_[main|frankenstyle]_upgrade()''': to be used in upgrade.php files.
* '''upgrade_set_timeout()''': to be used within the upgrade steps in upgrade.php files, in order to grant more time to the step.
* '''upgrade_[main|mod|block|plugin]_savepoint()''': to consider one upgrade step completed and reset timeouts. Avoids double executions.

Of course, for practical examples of the use of this API it's '''highly recommended to examine and understand current code'''. Everything is out there.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Core APIs]]
* [[XMLDB_Documentation|XMLDB_Documentation]]
* [[Coding|Coding guidelines]]
* [[DDL functions|DDL functions]]
* [[XMLDB defining an XML structure|install.xml file documentation]]

[[Category:XMLDB]]
[[Category:Plugins]]
[[Category:API]]

[[es: API de Actualización]]