Patching forms tutorial
by Gary Anderson
One of the easiest local modifications that an institution can make to customize their Moodle site is to make simple changes to the form elements that appear on pages. This permits one to set different default values when creating new items, allows one to hide unused input elements to simplify the interface, and lets one identify certain more complicated elements as "advanced" so that features are still availale while simplifying the interface for most uses.
This tutorial will demonstrate how to do such modifications.
Warning Making custom changes to the PHP scripting code in Moodle should be done carefully. You should always test your code before using it on your production site and should backup the original scripts. You should always comment your code so you know what has been changed. Care should also be taken during upgrades in the code to make sure things are not broken (like conflicts during a CVS update).
Having said that, these patches are among the simplest and the recovery from an error is easy: simply replace the file with original from the core distribution.
Moodle Forms Overview
Rather than placing HTML form elements directly on the page, most well-written Moodle code will use the Forms Library. This allows a standard way to create user input elements and also centralizes code making it easier to override certain behaviors creating a greater consistency.
An entire form is an "object" with methods and attributes. In many places in the Moodle code, the instance of the object is identified by the variable $mform, but you can use any variable.
Common methods of the form object look like:
- $mform->addelement(<elementtype>,<elementidentifier>,<displayname>,<options>);
This creates a new input element on a page.
While forms can be produced in any scripting page which outputs code, you will often find code for printing out forms in a file like mod_form.php or in index.php of the affected component. The examine the URL of the page being viewed as a starting point for finding the file to be changed.
Always comment your code so you can change or remove it later.. For single line modifications, considering putting in your new code, and then end it with //<yourusername> <date> <the old code>. This allows for retention of existing line numbers.
Changing defaults
The setDefault method is used to establish the initial value used in the form and allows you to to define the most common setting for use in your institution.
Example: Change the default number of points for a default assignment from 100 points to 10 points.
Solution:
In the file /mod/assignment/mod_form.php, find
$mform->setDefault('grade', 100);
Change the default to 10, and comment out the previous code with your initial and dates:
$mform->setDefault('grade', 10); //GVA 20080608 $mform->setDefault('grade', 100);
Hiding fields
Form elements are created for a page using the addElement method. Various types of element are text, select, date_time_selector, htmleditor, etc.
There is also the type "hidden" that defines the element on a page and allows you to set a default value, stores previous values from a submission etc. To simplify your forms for you users, simply change the type of the field during when addElement is called to hidden.
Example: Your site does not want to use meta courses and you want to remove it from the course creation/edit page. In the file /course/edit_form.php
Change:
$mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);
to
$mform->addElement('hidden', 'metacourse', get_string('managemeta'), $meta); //GVA 20080610 $mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);
Setting fields to "Advanced"
For elements that are infrequently used in your institution, you can still simplify the interface while making options still available to your 'Power Users' by marking elements as "advanced".
These elements only appear to the user when they click the "Set Advanced" button.
To identify the element as advanced, call the setAdvanced method after the element has been created.
Example:
Your typical user is local and hence it will be rare that they will use a different time zone. To clean up the interface, set the option to change the user time zone so that it is shown only when the user clicks "Set Advanced".
Solution:
In the file /user/editlib.php, find:
$mform->addElement('select', 'timezone', get_string('timezone'), $choices);
Set the field to advanced using the setAdvanced method
$mform->addElement('select', 'timezone', get_string('timezone'), $choices);
$mform->setAdvanced('timezone');
Other Examples
Here are some other example of making simple changes to forms
Change the maximum allowed grade
The maximum grade for a module is set in the standard form to 100. To change this to a different value (such as 200) in version 1.9, make this change in the file /lib/form/modgrade.php
Find:
for ($i=100; $i>=1; $i--) {
Change to:
for ($i=200; $i>=1; $i--) { // GVA 20080616 for ($i=100; $i>=1; $i--) {
Set a standard start date and number of weeks for courses
By default, Moodle starts courses on the day following course creation and gives them a duration of 10 weeks. As many institutions have standard terms, setting the default start date and duration will allow for more uniformity, fewer mistakes, and will ease course creation.
In version 1.9, edit the file /course/edit_form.php. Insert the following lines after the affected fields are defined (perhaps on lines just before $this->add_action_buttons();)
//GVA 20080618 Number of weeks for default course. Should go through final exam
$mform->setDefault('numsections', 13);
//GVA 20080618 Set default course start date. Always start on a Monday to have weeks work right
$mform->setDefault('startdate', strtotime("1 Sep 2008"));
