Getting started with the NEWMODULE template

Let's start by downloading a copy of the NEWMODULE template. You can do this either by using the source code included with the book, or by accessing the contributed downloads at http://moodle.org/. Note that the code for NEWMODULE is included in the chapter's source code folder, in order to provide a comparison of the version used to develop this example. New development should be done by using the newest version of the module provided at the specified link. Next, we will rename the folder to the name of our new module. We are going to name our folder foo. Then, we need to use our development environment to perform a global search and replace on the folder's contents. Note that it is a common feature of development environments to be able to replace a particular string throughout an entire directory structure. What we want to do is find any text 'newmodule' and replace it with the text 'foo'. Alternately, if our development environment doesn't support global search and replace, then we could perform a search and replace on each document as we go through each file, or we can make the changes manually as we review the text of the sample code. Next, we need to rename the language file to the module name. Look in the lang/en_utf8 folder for a file named newmodule.php. We need to rename it to foo.php. Now, we are ready to move the entire folder into the /mod folder of our development site. In the next section, we start by making the form for creating new activity instances. Let's start coding!

Completing mod_form.php

The file mod_form.php provides the form when a new module instance is created. This form captures the user input for any settings that we want to save on creation of a new activity. We will be creating our form by extending the moodleform_mod class. This is the standard method for providing a new activity form.

The following two lines of code include the necessary library file that defines the moodleform_mod class, and then creates our extended class mod_foo_mod_form. The general form of this definition is mod_<MODULE NAME>_mod_form:

require_once ($CFG->dirroot.'/course/moodleform_mod.php');
class mod_foo_mod_form extends moodleform_mod {

Following is an example of a form generated with the moodleform_mod class. This is from the settings page for the assignment module from the Moodle core:

Our form will define some general elements: instructions, title or name, grade, outcomes, group mode, visible indicator, and grade category. Note that all of this is accomplished by defining a single function definition:

function definition() {
global $COURSE, $CFG;

Next, we define an instance of our new class and define elements of the instance, which will control how our form displays and what input elements it contains:

// Create form instance
$mform =& $this->_form;

This section of code creates the form header and will be present in any form that we create by using the Moodle forms library. Note that the forms library is discussed in greater detail inChapter 13, Building Forms with formslib, when we discuss formslib.

$mform->addElement('header', 'general', get_string('general', 'form'));

Next we will cover how to define our input values.

Defining input values

In this section of code, we set the name of the activity. Note that the input element is controlled by the value of the setType element, and any UI rules are defined by setting addRule. Also, note that the value set for the second parameter, name in this case, should be set to the corresponding field name in our database. The form library will take care of making sure that the values entered go into the correct place in the database as long as the field name is set correctly:

$mform->addElement('text', 'name', get_string('fooname', 'foo'), array('size'=>'64'));
$mform->setType('name', PARAM_TEXT);
$mform->addRule('name', null, 'required', null, 'client');

Next we see an example of using the htmleditor element to gather the instructions for our activity:

$mform->addElement('htmleditor', 'instructions', get_string('instructions', 'foo'));
$mform->setType('instructions', PARAM_RAW);
$mform->addRule('instructions', get_string('required'), 'required', null, 'client');

Here we set up a help button for the instructions form element:

$mform->setHelpButton('instructions', array('questions', 'richtext'), false, 'editorhelpbutton');

In this section, we gather date data to control when the activity is available to learners:

// Dates available settings
$mform->addElement('date_time_selector', 'timeavailable', get_string('timeavailable', 'foo'), array('optional'=>true));
$mform->setDefault('timeavailable', 0);
$mform->addElement('date_time_selector', 'timedue', get_string('timedue', 'foo'), array('optional'=>true));
$mform->setDefault('timedue', 0);
$mform->addElement('date_time_selector', 'timeavailable', get_string('timeavailable', 'foo'), array('optional'=>true));
$mform->setDefault('timeavailable', 0);
$mform->addElement('date_time_selector', 'timedue', get_string('timedue', 'foo'), array('optional'=>true));
$mform->setDefault('timedue', 0);

In the next few lines, we make use of the modgrade element to create a menu that lets the user select the point value for the activity. This value will be used to set the points earned in the gradebook:

$mform->addElement('modgrade', 'scale', get_string('grade'), false);
$mform->disabledIf('scale', 'assessed', 'eq', 0);

Using common form elements

Finally, we wrap up the form by setting some common module elements. The values set in the features array are passed into standard_coursemodule_elements, which controls the display of multiple form elements. This method is a real time saver versus manually making the form elements:

$features = array('groups'=>true, 'groupings'=>true, 'groupmembersonly'=>true,'outcomes'=>false, 'gradecat'=>false, 'idnumber'=>false);
$this->standard_coursemodule_elements($features);
$this->add_action_buttons();

We have completed our new instance form and can now move on to the version.php file. The following screenshot shows an example of how Moodle renders this form: