View source for Development: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 my 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 and it with //<yourusername> <date> <the old code>.  This allows for retention of eisting 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 the 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, change it in the file /lib/form/modgrade.php

Find: 

 for ($i=100; $i>=1; $i--) {

Change to:

 for ($i=100; $i>=1; $i--) { // GVA 20080616 for ($i=100; $i>=1; $i--) {