08MOD: Moodle Module Development - Generate Upgrade snippet with XMLDB Editor

TO START THE TUTORIAL FROM THE BEGINNING, CLICK HERE

During our initial setup of the Module we modified the install.xml file.  We are now faced with a dillema - while modifying the module's form we introduced a new database column.  This value is needed by the module's logic and needs to be saved to our inyourface table (mdl_inyourface if your installation uses the default table prefix).

To handle this new challenge, we have to set up our first module upgrade.  We accomplish the upgrade by following a number of simple steps:

• We generate XMLDB code that we use in our module's .\mod\inyourface\db\upgrade.php script
• We paste the new code into the upgrade.php script
• We update our .\mod\inyourface\version.php file
• We run notifications from the Moodle admin menu

When we finish these steps, we can verify that our changes took effect by changing the Post Limit value in our module's form, and making sure that the change took place.


THE MOODLE XMLDB EDITOR

The XMLDB Editor is a nifty little tool that generates code we can use to update our module's database structure.  The editor can read existing XMLDB files (like our install.xml file) and generate code in SQL, XML or PHP.

For our immediate need, we need to generate PHP code for use in our module upgrade.

We start by accessing the XMLDB Editor

• Navigate to Moodle's Site Administration Menu and select Miscellaneous
• Select XMLDB Editor

Click Image to Zoom

The editor opens to a Main View, listing all of the available XML files. We need to scroll down to the listing for our module, mod\inyourface/db and click on the entry's "Load" link. The page refreshes and enables the  "Load" link,  Yes - we click on it as soon as it becomes available!

Click Image to Zoom

After the Edit XML File page loads, we scroll down to the Tables section and find our table's "Edit" link  This will open the module's XML file.

Click Image to Zoom

The Edit Table screen displays, where we can select to add a New Field:

Click Image to Zoom

From this screen we can enter the details of our new field, which will be of type integer:

Clicking on the "change" button saves our changes and returns us to the Edit Table screen, where we can select to view PHP Code.  We need this snippet so we can set up our update.php script and initiate the version update.

Basically, we are using the XMLDB Editor to generate
the snippet of HTML code needed for the update.php file. 

Once we have the snippet, we have all we need for this module upgrade.

So let's generate and fetch our snippet:

Click to Zoom Image

The PHP Code form defaults to the first field in the table, so we need to use the Select Field dropdown to pick our new field (postlimit).  We then click on the "View" button:

Click Image to Zoom

We now have the piece of the puzzle we need to complete our first module upgrade!!!

Click Image to Zoom

The snippet generated by the editor is:


if ($result && $oldversion < XXXXXXXXXX) {
    /// Define field postlimit to be added to inyourface
    $table = new XMLDBTable('inyourface');
    $field = new XMLDBField('postlimit');
    $field->setAttributes(XMLDB_TYPE_INTEGER, '2', XMLDB_UNSIGNED, null, null, null, null, '1', 'timemodified');
    /// Launch add field postlimit
    $result = $result && add_field($table, $field);
}

Copy the code to your clipboard and open the .\mod\inyourface\db\upgrade.php file.

ABOUT MODULE MODULES VERSION NUMBERS:
Version numbers are based on the date of the change, followed
by a sequence number. The first update on a
given day is given sequence number 00.

For example, our upgrade is being completed
on May 14,2010 and it is the first and only update.
Our new version number is 2010051400.

Notice that we did not run a search and replace on the upgrade.php file. We will erase all of its contents and replace it with the following code:


<?php
function xmldb_inyourface_upgrade($oldversion=0) {
    global $CFG, $THEME, $db;
    $result = true;
    if ($result && $oldversion < 2007040200)
    {
        /// Define field postlimit to be added to inyourface
        $table = new XMLDBTable('inyourface');
        $field = new XMLDBField('postlimit');
        $field->setAttributes(XMLDB_TYPE_INTEGER, '2', XMLDB_UNSIGNED, null, null, null, null, '1', 'timemodified');
        /// Launch add field postlimit
        $result = $result && add_field($table, $field);
     }
     return $result;
}
?>

The upgrade.php script should have a snippet for every upgrade that we make. It is an additive process, so we need to make sure that we safeguard our upgrade snippets.

OK.. so now we have an upgrade script that updates our mdl_inyourface table by adding a new column called postlimit.

Looks like a lot of work to generate a
simple SQL statement

BUT - the cost of managing upgrades
in the future will be well worth it!!!

Before we can complete the upgrade . . .

We need to update our .\mod\inyouface\version.php file to force Moodle to recognize that an upgrade is required.  When we are done, the version.php file should look like this:

.


<?php // $Id: version.php,v 1.5.2.2 2009/03/19 12:23:11 mudrd8mz Exp $

/**
* Code fragment to define the version of newmodule
* This fragment is called by moodle_needs_upgrading() and /admin/index.php
*
* @author Your Name <your@email.address>
* @version $Id: version.php,v 1.5.2.2 2009/03/19 12:23:11 mudrd8mz Exp $
* @package mod/newmodule
*/

/// $module->version = 2007040200; // The current module version (Date: YYYYMMDDXX)
$module->version = 2010051400; // The current module version (Date: YYYYMMDDXX)
$module->cron = 0; // Period for cron to check this module (secs)
?>

So far we have . . .

Used the XMLDB Editor to generate the code snippet to add a new column to our module table
Modified the upgrade.php script
Modified the version.php script

With these changes in place, we can navigate to the Moodle Site Administration Menu, and select the Notifications option.  And VOILA! Our upgrade executes!!!