MoodleDocs - User contributions [en]

Restore 2.0 for developers

2012-05-29T18:28:58Z

GregLyon:

{{Template:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}

== Introduction ==

This page tries to explain, from a development perspective, '''how to implement''' the restore feature for various Moodle 2.x plugins, mainly, modules and blocks.

In order to work with Restore 2.0 you must read [[Backup 2.0 for developers]]. Everything will be crystal clear once you have read it.

In this documentation you will learn about some points that you can not easily deduce from [[Backup 2.0 for developers]] concerning the Choice module.

== Coding ==
the restore is composed by two main php files: restore_choice_stepslib.php and restore_choice_activity_task.class.php
=== restore_choice_stepslib.php ===

<code php>
/**
* Structure step to restore one choice activity
*/
class restore_choice_activity_structure_step extends restore_activity_structure_step {

protected function define_structure() {

$paths = array();
$userinfo = $this->get_setting_value('userinfo');

$paths[] = new restore_path_element('choice', '/activity/choice');
$paths[] = new restore_path_element('choice_option', '/activity/choice/options/option');
if ($userinfo) {
$paths[] = new restore_path_element('choice_answer', '/activity/choice/answers/answer');
}

// Return the paths wrapped into standard activity structure
return $this->prepare_activity_structure($paths);
}

protected function process_choice($data) {
global $DB;

$data = (object)$data;
$oldid = $data->id;
$data->course = $this->get_courseid();

$data->timeopen = $this->apply_date_offset($data->timeopen);
$data->timeclose = $this->apply_date_offset($data->timeclose);
$data->timemodified = $this->apply_date_offset($data->timemodified);

// insert the choice record
$newitemid = $DB->insert_record('choice', $data);
// immediately after inserting "activity" record, call this
$this->apply_activity_instance($newitemid);
}

protected function process_choice_option($data) {
global $DB;

$data = (object)$data;
$oldid = $data->id;

$data->choiceid = $this->get_new_parentid('choice');
$data->timemodified = $this->apply_date_offset($data->timemodified);

$newitemid = $DB->insert_record('choice_options', $data);
$this->set_mapping('choice_option', $oldid, $newitemid);
}

protected function process_choice_answer($data) {
global $DB;

$data = (object)$data;
$oldid = $data->id;

$data->choiceid = $this->get_new_parentid('choice');
$data->optionid = $this->get_mappingid('choice_option', $oldid);
$data->userid = $this->get_mappingid('user', $data->userid);
$data->timemodified = $this->apply_date_offset($data->timemodified);

$newitemid = $DB->insert_record('choice_answers', $data);
// No need to save this mapping as far as nothing depend on it
// (child paths, file areas nor links decoder)
}

protected function after_execute() {
// Add choice related files, no need to match by itemname (just internally handled context)
$this->add_related_files('mod_choice', 'intro', null);
}
}
</code>

=== restore_choice_activity_task.class.php ===
<code php>
/**
* choice restore task that provides all the settings and steps to perform one
* complete restore of the activity
*/

require_once($CFG->dirroot . '/mod/choice/backup/moodle2/restore_choice_stepslib.php'); // Because it exists (must)

class restore_choice_activity_task extends restore_activity_task {

/**
* Define (add) particular settings this activity can have
*/
protected function define_my_settings() {
// No particular settings for this activity
}

/**
* Define (add) particular steps this activity can have
*/
protected function define_my_steps() {
// Choice only has one structure step
$this->add_step(new restore_choice_activity_structure_step('choice_structure', 'choice.xml'));
}

/**
* Define the contents in the activity that must be
* processed by the link decoder
*/
static public function define_decode_contents() {
$contents = array();

$contents[] = new restore_decode_content('choice', array('intro'), 'choice');

return $contents;
}

/**
* Define the decoding rules for links belonging
* to the activity to be executed by the link decoder
*/
static public function define_decode_rules() {
$rules = array();

$rules[] = new restore_decode_rule('CHOICEVIEWBYID', '/mod/choice/view.php?id=$1', 'course_module');
$rules[] = new restore_decode_rule('CHOICEINDEX', '/mod/choice/index.php?id=$1', 'course');

return $rules;

}

/**
* Define the restore log rules that will be applied
* by the {@link restore_logs_processor} when restoring
* choice logs. It must return one array
* of {@link restore_log_rule} objects
*/
static public function define_restore_log_rules() {
$rules = array();

$rules[] = new restore_log_rule('choice', 'add', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'update', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'view', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'choose', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'choose again', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'report', 'report.php?id={course_module}', '{choice}');

return $rules;
}

/**
* Define the restore log rules that will be applied
* by the {@link restore_logs_processor} when restoring
* course logs. It must return one array
* of {@link restore_log_rule} objects
*
* Note this rules are applied when restoring course logs
* by the restore final task, but are defined here at
* activity level. All them are rules not linked to any module instance (cmid = 0)
*/
static public function define_restore_log_rules_for_course() {
$rules = array();

// Fix old wrong uses (missing extension)
$rules[] = new restore_log_rule('choice', 'view all', 'index?id={course}', null,
null, null, 'index.php?id={course}');
$rules[] = new restore_log_rule('choice', 'view all', 'index.php?id={course}', null);

return $rules;
}

}
</code>

'''define_restore_log_rules''': it covers all the "mandatory" log actions, performing {course_module} and {choice} mappings properly. Note that names between curly brackets instruct the log processor to look in the mapping tables for item = name between brackets. Of course, other modules like forum, has a lot of rules, with more complex mappings and so on. Choice is pretty basic.

'''define_restore_log_rules_for_course''': choice module has the 1st rule because, while implementing restore, we discovered one bug causing URLs to be written in the logs table WITHOUT the .php in the URL, hence choice has that extra rule (that uses the 5-8 params, to REWRITE the URL to be inserted on restore). But that was one problem with choices only, afaik, so you probably would not need it in your own module.

== Automatically triggering restore in code ==

As with backup it is possible to automatically trigger a restore for a course (or activity or anything else you can back up). Here is how to restore a course backup into a new course:

# Put the backup files in a specific folder: $CFG->dataroot/temp/backup/$folder, where $folder is a random or unused unique id.
# Decide on the course shortname, fullname, and category id for restore (course must not already exist).
# Run the following code:

<code php>
// Transaction
$transaction = $DB->start_delegated_transaction();

// Create new course
$courseid = restore_dbops::create_new_course($fullname, $shortname, $categoryid);

// Restore backup into course
$controller = new restore_controller($folder, $courseid,
backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id,
backup::TARGET_NEW_COURSE);
$controller->execute_precheck();
$controller->execute_plan();

// Commit
$transaction->allow_commit();
</code>

Note:

* The transaction is used so that if backup fails, the course isn't created.
* The MODE_SAMESITE option is used if restoring a backup which comes from the same site, otherwise MODE_GENERAL might be used.

== Code that runs after restore ==

If you are writing a restore task for an activity module, your code is all executed while the system is restoring that module. For example, the <tt>after_execute</tt> method in your <tt>restore_mymodule_activity_structure_step</tt> class is called immediately after all the other restore functions in that step are finished.

=== The problem ===

Usually this is correct, but in some situations you may need to have an activity module restore that depends in some way on another activity module or on a course section other than the one the module belongs to. Depending on the order within the course, in some cases the other module or section has not yet been restored, so this is a problem.

The code that may not work as a result is code that tries to convert from an 'old' course-module ID or section ID into a 'new' one:

$newcmid = $this->get_mappingid('course_module', $oldcmid);
$newsectionid = $this->get_mappingid('course_section', $oldsectionid);

These functions will return false if the relevant course-module or section has not yet been restored.

=== The solution ===

You can have a method called <tt>after_restore</tt> inside your TASK (not step) class, <tt>restore_mymodule_activity_task</tt>.

public function after_restore() {
// Do something at end of restore
}

In this method you can carry out necessary finishing tasks such as updating course-module and section IDs (using code like the above).

The function will be called once per activity that was restored (for example, if you put this code into forum restore, and there are four forums on the website being restored, then it will be called four times). You can use the <tt>get_activityid</tt> method to return the current activity ID (other functions such as <tt>get_courseid</tt> are also available).

=== Warning ===

You should do as little as possible in this method, and be aware that using it may mean your activity module does not function correctly in some cases.

* It is possible to backup and restore a single module, or a section, rather than a whole course.
* This function (backing up a single module) may also be used to support other upcoming features such as the 'copy activity' feature.

If somebody backs up your activity as a single activity, then obviously any such dependencies will not be included. There is currently no way to indicate that your module has any dependencies. So the backup and restore will go ahead but, once again, the <tt>get_mappingid</tt> function will return false.

At present the best way to handle this is to add a message to the restore log (which will not currently be displayed anywhere, but this might change):

$this->get_logger()->process("Failed to restore dependency in mymodule '$name'. " .
"Backup and restore will not work correctly unless you include the dependent module.",
backup::LOG_ERROR);

Restore 2.0 for developers

2012-05-29T18:28:14Z

GregLyon:

{{Template:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}

== Introduction ==

This page tries to explain, from a development perspective, '''how to implement''' the restore feature for various Moodle 2.x plugins, mainly, modules and blocks.

In order to work with Restore 2.0 you must read [[Backup 2.0 for developers]]. Everything will be crystal clear once you have read it.

In this documentation you will learn about some points that you can not easily deduce from [[Backup 2.0 for developers]] concerning the Choice module.

== Coding ==
the restore is composed by two main php files: restore_choice_stepslib.php and restore_choice_activity_task.class.php
=== restore_choice_stepslib.php ===

<code php>
/**
* Structure step to restore one choice activity
*/
class restore_choice_activity_structure_step extends restore_activity_structure_step {

protected function define_structure() {

$paths = array();
$userinfo = $this->get_setting_value('userinfo');

$paths[] = new restore_path_element('choice', '/activity/choice');
$paths[] = new restore_path_element('choice_option', '/activity/choice/options/option');
if ($userinfo) {
$paths[] = new restore_path_element('choice_answer', '/activity/choice/answers/answer');
}

// Return the paths wrapped into standard activity structure
return $this->prepare_activity_structure($paths);
}

protected function process_choice($data) {
global $DB;

$data = (object)$data;
$oldid = $data->id;
$data->course = $this->get_courseid();

$data->timeopen = $this->apply_date_offset($data->timeopen);
$data->timeclose = $this->apply_date_offset($data->timeclose);
$data->timemodified = $this->apply_date_offset($data->timemodified);

// insert the choice record
$newitemid = $DB->insert_record('choice', $data);
// immediately after inserting "activity" record, call this
$this->apply_activity_instance($newitemid);
}

protected function process_choice_option($data) {
global $DB;

$data = (object)$data;
$oldid = $data->id;

$data->choiceid = $this->get_new_parentid('choice');
$data->timemodified = $this->apply_date_offset($data->timemodified);

$newitemid = $DB->insert_record('choice_options', $data);
$this->set_mapping('choice_option', $oldid, $newitemid);
}

protected function process_choice_answer($data) {
global $DB;

$data = (object)$data;
$oldid = $data->id;

$data->choiceid = $this->get_new_parentid('choice');
$data->optionid = $this->get_mappingid('choice_option', $oldid);
$data->userid = $this->get_mappingid('user', $data->userid);
$data->timemodified = $this->apply_date_offset($data->timemodified);

$newitemid = $DB->insert_record('choice_answers', $data);
// No need to save this mapping as far as nothing depend on it
// (child paths, file areas nor links decoder)
}

protected function after_execute() {
// Add choice related files, no need to match by itemname (just internally handled context)
$this->add_related_files('mod_choice', 'intro', null);
}
}
</code>

=== restore_choice_activity_task.class.php ===
<code php>
/**
* choice restore task that provides all the settings and steps to perform one
* complete restore of the activity
*/

require_once($CFG->dirroot . '/mod/choice/backup/moodle2/restore_kb_stepslib.php'); // Because it exists (must)

class restore_choice_activity_task extends restore_activity_task {

/**
* Define (add) particular settings this activity can have
*/
protected function define_my_settings() {
// No particular settings for this activity
}

/**
* Define (add) particular steps this activity can have
*/
protected function define_my_steps() {
// Choice only has one structure step
$this->add_step(new restore_choice_activity_structure_step('choice_structure', 'choice.xml'));
}

/**
* Define the contents in the activity that must be
* processed by the link decoder
*/
static public function define_decode_contents() {
$contents = array();

$contents[] = new restore_decode_content('choice', array('intro'), 'choice');

return $contents;
}

/**
* Define the decoding rules for links belonging
* to the activity to be executed by the link decoder
*/
static public function define_decode_rules() {
$rules = array();

$rules[] = new restore_decode_rule('CHOICEVIEWBYID', '/mod/choice/view.php?id=$1', 'course_module');
$rules[] = new restore_decode_rule('CHOICEINDEX', '/mod/choice/index.php?id=$1', 'course');

return $rules;

}

/**
* Define the restore log rules that will be applied
* by the {@link restore_logs_processor} when restoring
* choice logs. It must return one array
* of {@link restore_log_rule} objects
*/
static public function define_restore_log_rules() {
$rules = array();

$rules[] = new restore_log_rule('choice', 'add', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'update', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'view', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'choose', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'choose again', 'view.php?id={course_module}', '{choice}');
$rules[] = new restore_log_rule('choice', 'report', 'report.php?id={course_module}', '{choice}');

return $rules;
}

/**
* Define the restore log rules that will be applied
* by the {@link restore_logs_processor} when restoring
* course logs. It must return one array
* of {@link restore_log_rule} objects
*
* Note this rules are applied when restoring course logs
* by the restore final task, but are defined here at
* activity level. All them are rules not linked to any module instance (cmid = 0)
*/
static public function define_restore_log_rules_for_course() {
$rules = array();

// Fix old wrong uses (missing extension)
$rules[] = new restore_log_rule('choice', 'view all', 'index?id={course}', null,
null, null, 'index.php?id={course}');
$rules[] = new restore_log_rule('choice', 'view all', 'index.php?id={course}', null);

return $rules;
}

}
</code>

'''define_restore_log_rules''': it covers all the "mandatory" log actions, performing {course_module} and {choice} mappings properly. Note that names between curly brackets instruct the log processor to look in the mapping tables for item = name between brackets. Of course, other modules like forum, has a lot of rules, with more complex mappings and so on. Choice is pretty basic.

'''define_restore_log_rules_for_course''': choice module has the 1st rule because, while implementing restore, we discovered one bug causing URLs to be written in the logs table WITHOUT the .php in the URL, hence choice has that extra rule (that uses the 5-8 params, to REWRITE the URL to be inserted on restore). But that was one problem with choices only, afaik, so you probably would not need it in your own module.

== Automatically triggering restore in code ==

As with backup it is possible to automatically trigger a restore for a course (or activity or anything else you can back up). Here is how to restore a course backup into a new course:

# Put the backup files in a specific folder: $CFG->dataroot/temp/backup/$folder, where $folder is a random or unused unique id.
# Decide on the course shortname, fullname, and category id for restore (course must not already exist).
# Run the following code:

<code php>
// Transaction
$transaction = $DB->start_delegated_transaction();

// Create new course
$courseid = restore_dbops::create_new_course($fullname, $shortname, $categoryid);

// Restore backup into course
$controller = new restore_controller($folder, $courseid,
backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id,
backup::TARGET_NEW_COURSE);
$controller->execute_precheck();
$controller->execute_plan();

// Commit
$transaction->allow_commit();
</code>

Note:

* The transaction is used so that if backup fails, the course isn't created.
* The MODE_SAMESITE option is used if restoring a backup which comes from the same site, otherwise MODE_GENERAL might be used.

== Code that runs after restore ==

If you are writing a restore task for an activity module, your code is all executed while the system is restoring that module. For example, the <tt>after_execute</tt> method in your <tt>restore_mymodule_activity_structure_step</tt> class is called immediately after all the other restore functions in that step are finished.

=== The problem ===

Usually this is correct, but in some situations you may need to have an activity module restore that depends in some way on another activity module or on a course section other than the one the module belongs to. Depending on the order within the course, in some cases the other module or section has not yet been restored, so this is a problem.

The code that may not work as a result is code that tries to convert from an 'old' course-module ID or section ID into a 'new' one:

$newcmid = $this->get_mappingid('course_module', $oldcmid);
$newsectionid = $this->get_mappingid('course_section', $oldsectionid);

These functions will return false if the relevant course-module or section has not yet been restored.

=== The solution ===

You can have a method called <tt>after_restore</tt> inside your TASK (not step) class, <tt>restore_mymodule_activity_task</tt>.

public function after_restore() {
// Do something at end of restore
}

In this method you can carry out necessary finishing tasks such as updating course-module and section IDs (using code like the above).

The function will be called once per activity that was restored (for example, if you put this code into forum restore, and there are four forums on the website being restored, then it will be called four times). You can use the <tt>get_activityid</tt> method to return the current activity ID (other functions such as <tt>get_courseid</tt> are also available).

=== Warning ===

You should do as little as possible in this method, and be aware that using it may mean your activity module does not function correctly in some cases.

* It is possible to backup and restore a single module, or a section, rather than a whole course.
* This function (backing up a single module) may also be used to support other upcoming features such as the 'copy activity' feature.

If somebody backs up your activity as a single activity, then obviously any such dependencies will not be included. There is currently no way to indicate that your module has any dependencies. So the backup and restore will go ahead but, once again, the <tt>get_mappingid</tt> function will return false.

At present the best way to handle this is to add a message to the restore log (which will not currently be displayed anywhere, but this might change):

$this->get_logger()->process("Failed to restore dependency in mymodule '$name'. " .
"Backup and restore will not work correctly unless you include the dependent module.",
backup::LOG_ERROR);

User:Greg Lyon

2011-05-12T14:03:43Z

GregLyon:

Ever since 2006 I've been enhancing and supporting a variety of moodle systems. Most are still based on 1.8 though I've worked on a couple 1.9 and am just about to start building some custom modules for a moodle 2.0 (This is spring of 2011).

I am a lead developer at Blue Earth Interactive [http://www.blueearth.net/] located in St. Paul, Minnesota, USA.

User:Greg Lyon

2011-05-12T14:02:51Z

GregLyon:

XMLDB defining an XML structure

2007-04-16T17:11:43Z

GregLyon: /* The XMLDB editor */

[[XMLDB Documentation|XMLDB Documentation]] > [[XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the exact RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the edition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Miscellaneous tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Coding#Database_structures| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB Problems#NOT NULL fields using a DEFAULT <nowiki>''</nowiki> clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## This convention is only applicable for relations INSIDE one file. Don't generate FK constraints against other files (courseid, userid), use indexes there.
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://moodle.cvs.sourceforge.net/moodle/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false), '''enum''' (true/false), '''enumvalues''' (the list of values if the field has been declared as enum, for example <tt>'frog','toad','newt'</tt>) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' that conform it. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lib/db/install.xml Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://moodle.cvs.sourceforge.net/moodle/moodle/lib/xmldb/xmldb.dtd?view=markup automatically generated DTD] for the XMLDB files. Also one [http://moodle.cvs.sourceforge.net/moodle/moodle/lib/xmldb/xmldb.xsd?view=markup automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:XMLDB]]

Question type plugin how to

2007-03-29T20:29:17Z

GregLyon: /* Getting started */

{{Quiz developer docs}}
To follow this guide, you need to get hold of the qtype_NEW plugin template. You can get it from CVS in the contrib area or from the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database]. The rest of this guide is just a copy of the README.txt file from in there. (Or is the readme file a copy of this page?)

==New question type template README file==

Welcome to the new question type template.

This blank skeleton is a good place to start if you want to implement your own Moodle question type plugin.

Another good way to start is by looking at an existing question type that has good documentation in the code like TODO (if there is one, otherwise we'll hope that Tims will "light the way" :-) )

The latest version of the template can be found in CVS in http://moodle.cvs.sourceforge.net/moodle/contrib/plugins/question/type/TEMPLATE/ (was in contrib/qtype_NEW module). Because you want your own copy do a cvs export, not a cvs checkout. The package can also been downloaded from [http://moodle.org/mod/data/view.php?d=13&rid=443 the Modules and plugins database].

The latest version of this help can be read (nicely formatted) at https://docs.moodle.org/en/How_to_write_a_question_type_plugin

'''WARNING, THIS TEMPLATE IS NOT COMPLETE YET!'''

==Getting started==

Before you get to the interesting bit, you need to do a bit of file-renaming and search-and-replacing to turn this generic template into your own question type. You need to have chosen two things

;The identifier for your question type
:This is a string of lowercase letters and perhaps underscores that the Moodle code uses to refer to your question type. This needs to be unique, so perhaps start it with your initials. For example, all the quetions types I create while working at the OU will be referred to as ou_something. For the rest of these instructions, I will assume you have chosen 'myqtypeidentifier'.
;The name of your question type
:This is the name that people will see in the Moodle User-interface (in the English translation). For these instructions I will assume you have chosen 'My Question Type Name'.

<strong>NOTE:</strong> depending on where you got the template, some of the files and folders may be called TEMPLATE instead of QTYPEID. The contents of the files will still contain the text QTYPEID in either case.

Then you need to

# Rename the directory question/type/QTYPEID to question/type/myqtypeidentifier.
# Rename the language file lang/en_utf8/qtype_QTYPEID.html to lang/en_utf8/qtype_myqtypeidentifier.html
# Rename the help file lang/en_utf8/help/quiz/QTYPEID.html to lang/en_utf8/help/quiz/myqtypeidentifier.html
# Search and replace 'QTYPEID' with 'myqtypeidentifier' in all the files. You should find:
#* 2 occurrences in the language file
#* 1 occurrence in db/install.xml
#* 5 occurrences in simpletest/testquestiontype.php
#* 3 occurrences in editquestion.html
#* 1 occurrence in editquestion.php
#* 3 occurrences in questiontype.php
# Search and replace 'QTYPENAME' with 'My Question Type Name' in all the files. You should find:
#* 1 occurrence in the help file
#* 3 occurrences in the language file
#* 2 occurrences in questiontype.php
# Search and replace YOURNAME with your name. (This is only in the comments at the top of each file so it is not critical, but surely you want to take credit for your work.) You should find one occurrence in:
#* the language file.
#* simpletest/testquestiontype.php
#* editquestion.html
#* editquestion.php
#* questiontype.php
# Search and replace YOUREMAILADDRESS with your email address. (Again, this is only in the file header comments, but it is helpful if people can contact you if they have any questions about your code.) You should find:
#* There should be one occurrence of YOUREMAILADDRESS in each of the files listed under YOURNAME.
# Search and replace YOURPACKAGENAME with a package name for your code. This is used by PHPdoc when building the documentation for your classes. I suggest you make up one package name for all the question types you write. For example all the question types I write are in the package ou_questiontypes.
#* There should be one occurrence of YOURPACKAGENAME in each of the files listed under YOURNAME.
# Edit icon.gif to make an icon that represents your question type.

Finally, so you can test your code while working on it, you need to copy the lang and question folders on top of the folders in your Moodle test installation. This copy should not ovewrite any existing files. It should just add some new files and folders to that directory tree.

==Now for the interesting bit==

Now you need to write the code to

# Create any database tables you need. This works just like normal in Moodle with the files in the db directory and the version.php file. If you don't need to create any database tables, you can delete the db directory.
# Create the editing form for you question type, and the code to populate it. That means adding code to the files editquestion.html and editquestion.php.
# Create the template that will display the question to the student. This is in display.html. To make good flexible formating you should use CSS classes and use already existing ones when possible. An easy way to find which existing CSS classes exist is TODO
# Implement the rest of the question type class. This is in questiontype.php. You need to
## TODO finish writing this section.
# Make sure that the language file contains all the strings you refer to. Note that some of the strings you want may already be in the qtype_base.php and moodle.php language files in Moodle core. If so, use the existing strings. An easy way to find the existing strings is TODO
# Write the help file for your question type, and any other help files you need.
# Write a set of unit tests for you question type.

All the places in the code where you need to do things are marked TODO, and there are comments right there giving more detailed instructions.

''Note that these comments are not complete or accurate yet. I have only just started implementing my own question type, and I will be filling in those comments and finishing this document as I go along.''--[[User:Tim Hunt|Tim Hunt]] 16:29, 25 August 2006 (CDT)

==When you have finished==

Consider checking your question type into the contrib area of the Moodle CVS server (if you have access) so that other people can share it.

Add your new question type to the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database].

[[Category:Quiz]]

Question type plugin how to

2007-03-29T20:19:51Z

GregLyon: /* New question type template README file */

{{Quiz developer docs}}
To follow this guide, you need to get hold of the qtype_NEW plugin template. You can get it from CVS in the contrib area or from the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database]. The rest of this guide is just a copy of the README.txt file from in there. (Or is the readme file a copy of this page?)

==New question type template README file==

Welcome to the new question type template.

This blank skeleton is a good place to start if you want to implement your own Moodle question type plugin.

Another good way to start is by looking at an existing question type that has good documentation in the code like TODO (if there is one, otherwise we'll hope that Tims will "light the way" :-) )

The latest version of the template can be found in CVS in http://moodle.cvs.sourceforge.net/moodle/contrib/plugins/question/type/TEMPLATE/ (was in contrib/qtype_NEW module). Because you want your own copy do a cvs export, not a cvs checkout. The package can also been downloaded from [http://moodle.org/mod/data/view.php?d=13&rid=443 the Modules and plugins database].

The latest version of this help can be read (nicely formatted) at https://docs.moodle.org/en/How_to_write_a_question_type_plugin

'''WARNING, THIS TEMPLATE IS NOT COMPLETE YET!'''

==Getting started==

Before you get to the interesting bit, you need to do a bit of file-renaming and search-and-replacing to turn this generic template into your own question type. You need to have chosen two things

;The identifier for your question type
:This is a string of lowercase letters and perhaps underscores that the Moodle code uses to refer to your question type. This needs to be unique, so perhaps start it with your initials. For example, all the quetions types I create while working at the OU will be referred to as ou_something. For the rest of these instructions, I will assume you have chosen 'myqtypeidentifier'.
;The name of your question type
:This is the name that people will see in the Moodle User-interface (in the English translation). For these instructions I will assume you have chosen 'My Question Type Name'.

Then you need to

# Rename the directory question/type/QTYPEID to question/type/myqtypeidentifier.
# Rename the language file lang/en_utf8/qtype_QTYPEID.html to lang/en_utf8/qtype_myqtypeidentifier.html
# Rename the help file lang/en_utf8/help/quiz/QTYPEID.html to lang/en_utf8/help/quiz/myqtypeidentifier.html
# Search and replace 'QTYPEID' with 'myqtypeidentifier' in all the files. You should find:
#* 2 occurrences in the language file
#* 1 occurrence in db/install.xml
#* 5 occurrences in simpletest/testquestiontype.php
#* 3 occurrences in editquestion.html
#* 1 occurrence in editquestion.php
#* 3 occurrences in questiontype.php
# Search and replace 'QTYPENAME' with 'My Question Type Name' in all the files. You should find:
#* 1 occurrence in the help file
#* 3 occurrences in the language file
#* 2 occurrences in questiontype.php
# Search and replace YOURNAME with your name. (This is only in the comments at the top of each file so it is not critical, but surely you want to take credit for your work.) You should find one occurrence in:
#* the language file.
#* simpletest/testquestiontype.php
#* editquestion.html
#* editquestion.php
#* questiontype.php
# Search and replace YOUREMAILADDRESS with your email address. (Again, this is only in the file header comments, but it is helpful if people can contact you if they have any questions about your code.) You should find:
#* There should be one occurrence of YOUREMAILADDRESS in each of the files listed under YOURNAME.
# Search and replace YOURPACKAGENAME with a package name for your code. This is used by PHPdoc when building the documentation for your classes. I suggest you make up one package name for all the question types you write. For example all the question types I write are in the package ou_questiontypes.
#* There should be one occurrence of YOURPACKAGENAME in each of the files listed under YOURNAME.
# Edit icon.gif to make an icon that represents your question type.

Finally, so you can test your code while working on it, you need to copy the lang and question folders on top of the folders in your Moodle test installation. This copy should not ovewrite any existing files. It should just add some new files and folders to that directory tree.

==Now for the interesting bit==

Now you need to write the code to

# Create any database tables you need. This works just like normal in Moodle with the files in the db directory and the version.php file. If you don't need to create any database tables, you can delete the db directory.
# Create the editing form for you question type, and the code to populate it. That means adding code to the files editquestion.html and editquestion.php.
# Create the template that will display the question to the student. This is in display.html. To make good flexible formating you should use CSS classes and use already existing ones when possible. An easy way to find which existing CSS classes exist is TODO
# Implement the rest of the question type class. This is in questiontype.php. You need to
## TODO finish writing this section.
# Make sure that the language file contains all the strings you refer to. Note that some of the strings you want may already be in the qtype_base.php and moodle.php language files in Moodle core. If so, use the existing strings. An easy way to find the existing strings is TODO
# Write the help file for your question type, and any other help files you need.
# Write a set of unit tests for you question type.

All the places in the code where you need to do things are marked TODO, and there are comments right there giving more detailed instructions.

''Note that these comments are not complete or accurate yet. I have only just started implementing my own question type, and I will be filling in those comments and finishing this document as I go along.''--[[User:Tim Hunt|Tim Hunt]] 16:29, 25 August 2006 (CDT)

==When you have finished==

Consider checking your question type into the contrib area of the Moodle CVS server (if you have access) so that other people can share it.

Add your new question type to the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database].

[[Category:Quiz]]

lib/formslib.php Usage

2007-03-09T19:59:02Z

GregLyon: /* Basic Usage in A Normal Page */

{{Formslib}}
==Usage of Formslib==

There are many phpdoc style comments in lib/formslib.php

course/edit.php and the included course/edit_form.php provide a good example of usage of this library.

Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.

We created some special wrapper functions for moodle. $mform->get_data() returns null if no data has been submitted or validation fails or returns an object with the contents of the submitted data.

===Basic Usage in A Normal Page===

Generally the structure of a page with a form on it looks like this :

<pre>
require_once('pathtoformdesctiption');
//you'll process some page parameters at the top here and get the info about
//what instance of your module and what course you're in etc. Make sure you
//include hidden variable in your forms which have their defaults set in set_data
//which pass these variables from page to page

$mform = new yourmod_formfunction_form();//name of the form you defined in file above.
//default 'action' for form is strip_querystring(qualified_me())
if ($mform->is_cancelled()){
//you need this section if you have a cancel button on your form
//here you tell php what to do if your user presses cancel
//probably a redirect is called for!
} else if ($fromform=$mform->get_data()){
//this branch is where you process validated data.

} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.
//setup strings for heading
print_header_simple($streditinga, '',
"<a href=\"$CFG->wwwroot/mod/$module->name/index.php?id=$course->id\">$strmodulenameplural</a> ->
$strnav $streditinga", $mform->focus(), "", false);
//notice use of $mform->focus() above which puts the cursor
//in the first form field or the first field with an error.

//call to print_heading_with_help or print_heading? then :

//put data you want to fill out in the form into array $toform here then :

$mform->set_data($toform);
$mform->display();
print_footer($course);

}</pre>

===Defining Your Form Class===

The form class tells us about the structure of the form. It is encouraged for you to put this in file called {function}_form.php probably in the same folder in which the page that uses it is located. The name of your class should be {modname}_{funciton}_form eg. forum_post_form or course_edit_form. These classes will extend class moodleform.

Note the name you give the class is used as the id attrbute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to selectable in CSS by theme designers who may want to tweak the css just for that form.

====definition()====

[[lib/formslib.php_Form_Definition|Help is here for defining your form]] by defining a function definition() in your form class that sets up your form structure.

===Use in Activity Modules Add / Update Forms===

Syntax is the same in activity modules to create your update / add page. We are still supporting mod.html but if you want to use the new formslib then you can in Moodle 1.8 just include in your module directory the file mod_form.php instead of mod.html and it will be automatically detected. Inside this file you define a class with class name '{modname}__mod_form' which extends the class 'moodleform_mod'. See many examples of the core modules which have been converted to use formslib already.

====defaults_preprocessing====

For activity modules you use the same syntax to define your form. You may also want to override method defaults_preprocessing this can be used to take the data from the data base and tell the form how to fill out defaults in the form with this data. For example in the forum module in forum/mod_form.php we needed to tick an enable check box if a date had been selected in the date select. Normally data is loaded from the database and directly loaded into form fields with the same name as the database record you only need to use defaults_preprocessing if there isn't this one to one relationship. Another example is the lesson/mod_form.php which takes the data from the database and unserializes it. choice/mod_form.php shows an exampe of loading data from another db table referred to by a foreign key, to include in the form.

====Post Processing Still Done in lib.php Functions====

Post processing of data is done in lib.php functions modname_add_instance and modname_update_instance after the data has been validated. When migrating a from little change needs to be made in the post processing often. An exception is that date and date_time_selector fields automatically have their submitted data turned into timestamps so you don't need to do this in your add and update functions anymore.

====Automatically Including Standard Activity Module Form Elements====

Standard activity module form elements are automatically included using the moodleform_mod method standard_coursemodule_elements(). The default is to include a visibility and groupsmode select box and to include all necessary hidden fields. You can pass a parameter false to tell the method that your module doesn't support groups and so you don't want the groupsmode select button.

[[Category:Formslib]]

User:Greg Lyon

2006-06-29T19:01:12Z

GregLyon:

Hello! Currently (June '06) evaluating Moodle 1.6.