Backup 2.0 theme data

Template:Development:Backup 2.0Moodle 2.0

Introduction

In Moodle 2, themes can have data tables and files which can be backed up with a course. (To create data tables in a theme, use the standard db folder.)

None of the standard themes have any course-related data so it is not obvious how to code the backup and restore for them. This page gives an example theme as a case study which you can use to implement your own backup code for a theme which contains per-course data.

Note: Theme data backup requires Moodle 2.0.3 or later.

Example: the 'ou' theme

Our theme called the 'ou' theme (i.e. in the folder theme/ou) contains the following per-course data which needs to be backed up:

• Each course using the theme can select a different colour (referred to as 'variant' of the theme). This is so we can have different courses in any of 10 different colours without having to make 10 different themes.

• Each course can also select a custom image which is used in the header on some screens. This is so we can have cute kitten pictures on our test servers.

The variant is stored in a table called theme_ou_courseoptions. This table has 3 fields: id, courseid, and variant. (If we ever need to add more theme data, we can add fields to it.)

The image file is stored using the Moodle file API at the course context, in the theme_ou component and the image file area.

Backup

The backup code is in the file theme/ou/backup/moodle2/backup_theme_ou_plugin.class.php. Leaving out the headers, this file looks like:

class backup_theme_ou_plugin extends backup_theme_plugin {

    /**
     * Returns the theme information to attach to course element
     */
    protected function define_course_plugin_structure() {
        // Define virtual plugin element
        $plugin = $this->get_plugin_element(null, $this->get_theme_condition(), 'ou');

        // Create plugin container element with standard name
        $pluginwrapper = new backup_nested_element($this->get_recommended_name());

        // Add wrapper to plugin
        $plugin->add_child($pluginwrapper);

        // Set up theme's own structure and add to wrapper
        $studyplan = new backup_nested_element('ou', array('id'), array(
            'variant'));
        $pluginwrapper->add_child($studyplan);

        // Use database to get source
        $studyplan->set_source_table('theme_ou_courseoptions',
                array('courseid' => backup::VAR_COURSEID));

        // Include files which have theme_ou and area image and no itemid
        $studyplan->annotate_files('theme_ou', 'image', null);

        return $plugin;
    }
}

As you can see this works in a similar way to backup for modules and other plugins. The first line:

$this->get_plugin_element(null, $this->get_theme_condition(), 'ou');

means that the theme data will only be backed up if the current theme for the course is actually the 'ou' theme. In other words, if you change the course theme to 'standard', this backup data will not be created. (It is possible to change this behaviour if you want to backup theme data even when a different theme is currently selected for the course; leave out the last two parameters.)

You can see how you would change the code to use a different theme name, database table, fields, or file area. It's also possible to add a more complicated data structured in the same way as for other plugins. You could even store user data - however, unless the user data is course-specific, it would probably be more appropriate to store user theme options in user preferences rather than within theme-managed tables.

Testing

To test the backup, carry it out and then look inside the resulting zip file. In the course folder there should be a file called course.xml. If theme data is backed up, it will include a section like the following:

<plugin_theme_ou_course>
 <ou id="2">
  <variant>purple</variant>
 </ou>
</plugin_theme_ou_course>

Additionally, if the file backup worked, you should be able to find any files from within the specified file area inside the 'files' section of the backup (it will help if you know the hash code of the file; otherwise, note the size and make sure the test course doesn't have many other files to look through).

If you switch the course to a different theme, this data will not be backed up.