MoodleDocs - User contributions [en]

How to contribute a web service function to core

2012-12-10T05:03:37Z

Markn86:

==Check the existing ==
Before creating a new issue, check if one of the [https://docs.moodle.org/dev/Web_services_Roadmap#Core_web_service_functions core functions] or [http://tracker.moodle.org/browse/MDL-29934 a function in the roadmap] already matches your need.

==Create a tracker issue ==
Create a new feature issue in the tracker for your new web service function (it is allowed to create one issue for many function only if all functions are deeply related and that all core lib functions exist like for MDL-32662). The issue title should be the [https://docs.moodle.org/dev/Web_services_Roadmap#Naming_convention web service function name], and the issue description should indicate the specs. The following is an example.

<code php>
This web service function will return assignments:

Parameters:
----------

array of course ids - Default: empty array
array of capabilities - Default: empty array

Return value:
-----------

array of [
struct{
course struct [id, fullname, shortname, timemodified]
array of assignment [id,name,timedue,grade,timemodified]
}
]
</code>

Keep the following in mind.
* The web service API is designed to be a clean set of functions with very little overlap. Each web service function should return minimal required information - sometimes ids are enough. We expect the client/external app to manage some local storage between calls. For example, an external app will always retrieve the courses information first. Any function down the app workflow, only needs to return course ids. The external app should already know course fullname, shortname...
* Avoid functions that are too specific - look for the most general possible case. For example, we don't need a set_this_field function when a generic update_object could do it. This is to avoid code duplication and long-term maintenance.
* Moodle contextids are generally internal to Moodle and are not used in the API. (This was [http://tracker.moodle.org/browse/MDL-31681 discussed in this issue]).
* web service function name should be: create, update, get, and delete. Avoid as much as possible add, set, remove...
* description/summary/textfields are always accompanied by a format field. On input: texts should be checked against PARAM_RAW. You must not use format_text(). On output textfields must use external_format_text(). Example:
<code php>
//INPUT in xxx_parameters()
'inputtextaera' => new external_value(PARAM_RAW, 'some html param'),
'inputtextareaformat' => new external_format_value('inputtextarea', VALUE_DEFAULT), // VALUE_DEFAULT has for default format FORMAT_HTML. If not mention VALUE_REQUIRED is used.

//INPUT in xxx()
// no format_text() => just store it in the DB
$params['inputtextareaformat'] = external_validate_format($params['inputtextareaformat']);

//OUTPUT in xxx()
list($text, $textformat) = external_format_text($text, $textformatfromDB, $contextid, $component, $filearea, $itemid);

//OUTPUT in xxx_returns()
'text' => new external_value(PARAM_RAW, 'formatted text'),
'textformat' => new external_format_value('text'),
</code>

=== Add the watchers ===
Add [https://docs.moodle.org/dev/Credits#Component_maintainers the module maintainer] as watcher on your issue. In most of the case, they will be the person to validate the proposal.

=== Link the issue ===
Link your issue to [http://tracker.moodle.org/browse/MDL-29934 the Web service API Roadmap]. Your issue should appear in the "has been marked as being related by:" section.

=== Agreement on the specs ===
Once the component leader agrees on the specs for a web service function, the web service function is placed as a subtask in the roadmap.

== Function implementation ==
Implement the function according to the specs. The implementation must follow all of the below sections.

=== Code logic ===
The code logic should be matching the logic in Moodle. In the best word you will only call a core lib function in Moodle and reproduce some required capabilities/context checkings (search for the core lib function in Moodle, you'll find the required checks).

However often a lib function doesn't exist and you need to reproduce the code logic from different scripts in Moodle. If you end up to create all this logic in your function, it's better to move all this new logic in a new lib function. Then create a tracker issue and indicates to update the scripts using your new generic lib function.

Note that if your web service function does something different from Moodle core, it may be either a feature missing from Moodle (must be implemented at the same time), either something that the function should not be doing (review your web service function specification).

=== File structure ===
The file structure is explained in the [[Web_services_API|Web services API]] and the [[External_functions_API|External function API]]. These are plugin example but they are easy to adapt to core. The easiest way to learn is to look at other functions in the Moodle code.

=== Capabilities and context checks ===
The capability checking should always match the capability checks used in the front-end. You must look for the file(s) where this capibility checks are used.
<code php>
/// capability and context checking of core_group_create_groups
$context = get_context_instance(CONTEXT_COURSE, $group->courseid);
self::validate_context($context);
require_capability('moodle/course:managegroups', $context);
</code>

You also need to comment in the tracker issue about which file in core contains the permission/security checkings. Your web service function code must correspond 100% with Moodle permissions and behaviours - it is the most difficult part of the function implementation as the code logic could be in many different files. You will save reviewers a lot of time by letting them know which file to look at. Usually it's a form script + a page script in the UI, and sometimes in other places like admin pages.

Note: in services.php you'll find out that you can set a 'requiredcapabilities' settings for each web service function declaration. This is just a text help for the administrator. Moodle servers do not do any automaticcally check these capibilities. This is due to the fact that capability checks require a specific context, so you need to implement these checks in your external function.

=== Documentation for the client developer ===
written complete documentation in the xxx_params() and xxx_return() external description functions. [https://docs.moodle.org/22/en/Web_services_FAQ#Where_is_the_Web_Service_API_documented.3F The generated API documentation] will only show to client developers information from these two functions and in the services.php file. Be concise about how to use the function.

=== Web service description functions ===
* set top level parameters as DEFAULT (don't use OPTIONAL)
=== Error handling ===
* handled errors as described [https://docs.moodle.org/dev/Errors_handling_in_web_services in this document]
* DB write functions need to support transactions ($transaction = $DB->start_delegated_transaction(); / $transaction->allow_commit();)

=== Proper format and coding style ===
* ordered the functions: 1) xxx_params() 2) xxx() 3) xxx_returns() (so the integrator is not marked as the last history committer in Git for the functions)
* run the [https://github.com/marinaglancy/moodle-local_moodlecheck moodlecheck]/[https://github.com/moodlehq/moodle-local_codechecker codechecker] on your modified file to check if you code match Moodle standard.
* follow [https://docs.moodle.org/dev/Coding_style Moodle coding style]

=== Unit tests ===
You '''must''' write a [[Web Services Unit Test]]

== Peer-review ==
You can now be peer-reviewed. Push your function in a Github branch named MDL-XXXX. Remember:
* only make one commit if you are the only contributor.
* do not modify lines not related to your issue. For example with Netbeans you can for example "Format" the entire file to make the code prettier. If the file contains some existing code, It is not a good idea because you would be "git blame" for all lines in the files. For reviewer, it's also much more difficult to know what was related to the MDL issue.
* fill up the test instruction of the MDL issue. It should be online, the phpunit command line to run the PHPunit test. A tester will run it after the integration process is finished. Only after this final test, the function will be available in Moodle releases.

Peer-reviews are done by the component maintainer (if you are the component maintainer, then you can pick your peer-reviewer). If there are no component maintainer (or if the component maintainer is not available) the peer-review should be assigned to moodle.com. Peer-reviewer can get help from the [[Peer reviewing checklist]].

== Integration ==
Integration / Moodle HQ development priority follows these rules:

# the web service functions required for the official Mobile app (generally very few);
# the web service functions for which a Git patch has been submitted;
# [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=13101 the most voted issues]; and then
# other web service functions.

[[Category:Web_Services]]

Activity modules

2012-11-15T09:00:30Z

Markn86: /* upgrade.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabilities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the creator of the certificate has chosen to display the code on the certificate and another to store the actual code for each student. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', 'certificate');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 16 * 16. Feel free to use this folder to store other pictures you may use.

'''Update:''' Since 2.4 SVG files were introduced with all core Moodle activities. Please see [[Moodle_icons_2.4]] for more details on this.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The <modname>_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The <modname>_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The <modname>_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders its page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-11-15T08:59:04Z

Markn86: /* Lang Folder */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabilities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', 'certificate');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 16 * 16. Feel free to use this folder to store other pictures you may use.

'''Update:''' Since 2.4 SVG files were introduced with all core Moodle activities. Please see [[Moodle_icons_2.4]] for more details on this.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The <modname>_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The <modname>_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The <modname>_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders its page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-11-15T08:58:45Z

Markn86: /* Pix folder */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabilities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 16 * 16. Feel free to use this folder to store other pictures you may use.

'''Update:''' Since 2.4 SVG files were introduced with all core Moodle activities. Please see [[Moodle_icons_2.4]] for more details on this.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The <modname>_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The <modname>_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The <modname>_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders its page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Blocks

2012-11-15T06:40:37Z

Markn86: /* lang/en/block_simplehtml.php */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned previously, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.

<code php>
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with the capabilities we created and any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

<code php>
$string['pluginname'] = 'Simple HTML block';
$string['simplehtml'] = 'Simple HTML';
$string['simplehtml:addinstance'] = 'Add a new simple HTML block';
$string['simplehtml:myaddinstance'] = 'Add a new simple HTML block to the My Moodle page';
</code>

=== version.php ===

This file will hold version information for the plugin, along with other advanced parameters (not covered here - see [[version.php]] if you want more details).

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also we don't include a closing "?>" tag. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_MULTILANG);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Default title ...';
}

if (empty($this->config->text)) {
$this->config->text = 'Default text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instance', array('blockid'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Blocks

2012-11-15T06:32:08Z

Markn86: /* db/access.php */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned previously, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.

<code php>
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

<code php>
$string['pluginname'] = 'Simple html block';
$string['simplehtml'] = 'Simple html';
</code>

=== version.php ===

This file will hold version information for the plugin, along with other advanced parameters (not covered here - see [[version.php]] if you want more details).

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also we don't include a closing "?>" tag. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_MULTILANG);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Default title ...';
}

if (empty($this->config->text)) {
$this->config->text = 'Default text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instance', array('blockid'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Finding your way into the Moodle code

2012-11-13T10:10:37Z

Markn86: /* Tools that can help */

This article is aimed at people totally new to Moodle development and have some PHP experience, if you don't have that experience please visit [[PHP for novices|PHP for novices]]. It is a few tips to help you get started with the mass of Moodle code.

Please feel free to add more tips here, but I think it is also good if we can keep this article quite short.

==Developer documentation==

If you have not already found it, the main source of developer documentation is [[Developer_documentation]].

==Finding a way in==

For finding where to start, you need to know that when you are looking at, for example, http://moodle.org/mod/forum/discuss.php?d=82799, then the code for that is in /mod/forum/discuss.php, and you just need to follow through what it does.

It calls functions in the main Moodle libraries, and the three most important are:

*lib/moodlelib.php - general stuff.
*lib/weblib.php - things to do with output of HTML
*lib/dmllib.php - things to do with getting data in and out of the database.

==Understanding what you find==

As you look at the code, it is often a good idea, to insert statements like
<code php>
debugging('In function require_login');
</code>
which will print the message above if it gets far enough so you know the code has not stalled before there, or
print_object($course);
which will print out a variable, showing you what it contains.

Variable like $course are often objects with lots of fields. Seeing what they contain will help you understand what is going on. The first of these prints out whatever text you give it, and information about the sequence of function calls that the code took to get there. (It only works if you go to ''Administration > Server > [[:en:Debugging|Debugging]]'', and turn the debug level to ALL or DEVELOPER.)

==Tools that can help==

*'''Eclipse''', for instance helps finding function definitions. You can hold down CTRL and click on the name of a function, it immediately jumps you to where that function is defined. ([[Setting_up_Eclipse]])
*'''Netbeans'''
*'''Sublime 2'''
*'''Emacs'''
*'''Vim'''
*'''TextMate'''

See also [[Developer documentation#Tools]] and [[:Category:Developer tools]].

==See also==
* [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] a course at dev.moodle.org
* [[Development FAQ]]
* [[Developer_documentation]]
* [[Overview]]
* [[ctags]]
* [http://blog.danpoltawski.co.uk/archives/2009-05-Secrets-of-Learning-Moodle-Development!.html "Secrets of Learning Moodle Development!"] by Moodle core developer [[User:Dan Poltawski| Dan Poltawski]]
* [http://www.slideshare.net/tjh1000/a-basic-introduciton-to-the-moodle-architecture-5442122 A basic introduction to the Moodle architecture] by Moodle core developer Tim Hunt
* [http://www.aosabook.org/en/moodle.html The Architecture of Open Source Applications: Moodle] by Tim Hunt

Database collation issue

2012-11-13T10:07:31Z

Markn86: /* Transitional period (minor) */

{{Infobox Project
|name = Database collation issue
|state = Specification in progress
|tracker = MDL-36208
|discussion = https://moodle.org/mod/forum/discuss.php?d=214564
|assignee = ''Hero required''
}}

== Background ==

Database store text data using a particular '''character set'''. Moodle uses UTF-8, which is a good thing, since UTF-8 can represent almost any character ever.

Text data is also stored with an associated '''collation'''. This affects how the values are sorted and compared. For example, different languages have different sort-orders, which depend on which alphabet they use. For example in German the '''ß''' character should come just after '''S''' (and '''s''').

Collations typically come in two forms, case sensitive, and case-insensitive. If you are using a case-insensitive collation, then not only do 'x' and 'X' get sorted the same, but actually, the database thinks that 'x' = 'X'.

Operations like JOINs are typically much faster if both tables (columns) use the same collation.

== The problems ==

=== Collation should depend on current language ===

On multi-lingual sites like [https://moodle.org/ moodle.org], different users will all expect reports to be sorted according to their language's collation rules. If we just specify the collation in database table definition, then all queries for all users have to use the same collation.

Typical bugs:
* MDL-30446 Glossary order issues for some collation settings (Postgres)

=== Machine-readable identifiers ===

Moodle stores two sorts for text data:
* user-visible strings like user.firstname, user.lastname or course.fullname
* machine-readable identifiers like user.username, course.idnumber or file.filepath

For machine-readable identifiers, the 'x' == 'X', or worse 'e' == 'é' behaviour is really bad, particularly if you want to put a unique index on the column in question. It has lead to bugs like:
* MDL-29332 Calculated Questions Require Case Sensitive Data Tables (MySQL)
* MDL-33655 MySQL case insensitivity breaks get_directory_files (MySQL)
* MDL-34271 improve mysql collation handling

=== MySQL only has localised collations that are case-insensitive ===

If you look at the list of [https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-sets.html MySQL collations], you will see that the only collations that give correctly locale-aware ordering are case-insensitive (the ci bit in utf8_czech_ci), and so suffer from the 'x' == 'X' and 'e' == 'é' problem. The only collation that does not have this problem is utf8_bin, which is not the order people want to see.

== Outline solution ==

The proposed solution is simple in outline:
# Store all data in database tables that use a case-sentistive collation (e.g. utf8_bin).
# Change all ORDER BY clauses in all SQL that sort text, to specify the correct sort collation, based on the current language.

To support that second part, we will need some helper code, for example, each language pack must specify the right collation to use, for each supported database, for example using new strings in langconfig.php. We will also need an $DB->sql_order_by_text($column) helper function to return the right SQL fragment like "columnname COLLATE utf8_czech_ci".

== Difficulties with the proposed solution ==

=== Transitional period (minor) ===

In the transitional period, when the table definitions have been updated to use a collation like utf8_bin, but before we have found and fixed all SQL queries in Moodle core (and in all third-party plugins) to use sql_order_by_text, then the worst that can happen is that the results of some reports appear in a slightly odd order for some users. The reports will still basically work.

Whenever a problem like this is detected, it will be easy to add the necessary sql_order_by_text call to the code to fix it.

=== Time to do the upgrade (moderate) ===

The amount of time required to upgrade all tables to a new collation is going to be comparable to the time required for the change that changed all unsigned int columns to signed. This was an issue for some large sites.

Like dropping unsigned columns, this is probably a necessary evil that we can live with.

=== Backwards compatibility of identifiers (severe) ===

This is the most serious problem. It affects areas like:
* What are valid user names? Are user names case-sensitive.
* For people using integrations like the database authentication and enrolment plugins, or CVS import, it may be that at the moment, the identifiers currently match using case-insensitive collation, but if we changed the database collation to utf8_bin, then things would not longer match. This could cause a real mess.

So, we may have to add an admin option for these areas, where admins can choose if they want case-sensitive or case-insenstivive collations. Then, if they choose case-insensitive collation for backwards compatibility, we will have to add explicit LOWER(...) or COLLATE calls to the code, to maintain the current behaviour.

Here the risk is not just wrong sorting of reports, but it could badly break sites data integration. Hence, the risks if we get this wrong is very severe.

We do not yet have a good solution to this problem.

[[Category:Project]]

Blocks

2012-11-08T08:42:59Z

Markn86:

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned previously, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for each core block. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.

<code php>
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

<code php>
$string['pluginname'] = 'Simple html block';
$string['simplehtml'] = 'Simple html';
</code>

=== version.php ===

This file will hold version information for the plugin, along with other advanced parameters (not covered here - see [[version.php]] if you want more details).

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also we don't include a closing "?>" tag. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_MULTILANG);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Default title ...';
}

if (empty($this->config->text)) {
$this->config->text = 'Default text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instance', array('blockid'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Blocks

2012-11-08T08:40:46Z

Markn86:

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned previously, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for each core block. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.

<code php>
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title). Now we will create this language package. Create the file ''/blocks/simplehtml/lang/en/'''''block_simplehtml.php''' and paste the following code:

<code php>
$string['pluginname'] = 'Simple html block';
$string['simplehtml'] = 'Simple html';
</code>

=== version.php ===

This file will hold version information for the plugin, along with other advanced parameters (not covered here - see [[version.php]] if you want more details).

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also that we didnt include the closing "?>" tag for PHP. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_MULTILANG);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Default title ...';
}

if (empty($this->config->text)) {
$this->config->text = 'Default text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instance', array('blockid'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Blocks

2012-11-08T08:21:15Z

Markn86: /* Ready, Set, Go! */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just three PHP files. Here were are going to create a block called 'simplehtml', change any reference here to the name of the block you are creating. The three files are:

; /blocks/simplehtml/block_simplehtml.php : This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

; /blocks/simplehtml/db/access.php : This file will hold the new capabilities created by the block.

; /blocks/simplehtml/lang/en/block_simplehtml.php : This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code. All language files for blocks go under the /lang subfolder of the block's installation folder.

; /blocks/simplehtml/version.php : This file will hold version information for the plugin, along with other advanced parameters (not covered here - see [[version.php]] if you want more details).

We start by creating the directory ''/blocks/simplehtml/'' and creating the main object file, ''/blocks/simplehtml/'''''block_simplehtml.php'''. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned previously, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

Moodle 2.4 onwards introduced the capability check addinstance and myaddinstance for each core block. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability is not required.

<code php>
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title). Now we will create this language package. Create the file ''/blocks/simplehtml/lang/en/'''''block_simplehtml.php''' and paste the following code:

<code php>
<?php
$string['pluginname'] = 'Simple html block';
$string['simplehtml'] = 'Simple html';
</code>

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
<?php
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also that we didnt include the closing "?>" tag for PHP. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing bracket for the class definition

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_MULTILANG);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Default title ...';
}

if (empty($this->config->text)) {
$this->config->text = 'Default text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Responding to Cron ==

It is possible to have our block respond to the global Moodle cron process; we can have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly we need to define a new function within our block class:

<code php>
public function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then we will need to set the (minimum) execution interval for our cron function. Prior to Moodle 2.0, this was achieved by setting the value of a block's $this->cron field, via the init() method. This is now achieved by adding an additional line to our ''/blocks/simplehtml/'''version.php''''' file. Open it up and add the following:

<code php>
$plugin->cron = 300;
</code>

Cron intervals are set in seconds, so the above line will set our minimum execution interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. So if our block is set to wait at least 5 minutes between runs, as in this example, but Moodle's cron system is only set to run every 24 hours, then our block is going to be waiting a lot longer between runs than we expected!

Remember that if we change any values in the version file or block file we '''must''' bump the version number and visit the Notifications page to upgrade the block, otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function ''$this'' is defined, but it has almost nothing in it (only title and content fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
public function cron() {

global $DB; // Global database object

// Get the instances of the block
$instances = $DB->get_records( 'block_instance', array('blockid'=>'simplehtml') );

// Iterate over the instances
foreach ($instances as $instance) {

// Recreate block object
$block = block_instance('simplehtml', $instance);

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Common unit test problems

2012-11-08T04:19:09Z

Markn86: /* Solution */

=== Unit tests are taking more than 5 mins to run ===
This problem is under investigation. We are hoping to find the soluton. On a typical system all tests complete in under 3 mins.--[[User:Dan Poltawski|Dan Poltawski]] 12:43, 15 May 2012 (WST)

You maybe find much better performance on psql as a workaround for now if not doing DB dependent tests.

=== dml_testcase::test_unique_index_collation_trouble===
"Unique index is accent insensitive, this may cause problems for non-ascii languages. This is usually caused by accent insensitive default collation."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_unicode_ci collation.

=== dml_testcase::test_sql_binary_equal ===
"SQL operator "=" is expected to be case sensitive Failed asserting that 1 matches expected 2."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_unicode_ci collation.

=== moodlesimplepie_testcase::test_getfeed ===
"Failed to load the sample RSS file. Please check your proxy settings in Moodle. %s"
==== Solution ====
Your moodle needs network connectivity, please check proxy settings.

=== moodlesimplepie_testcase::test_redirect ===
Failed asserting that 'cURL Error: Operation timed out after 2000 milliseconds with 0 bytes received' is null.
==== Solution ====
Your moodle needs network connectivity, please check proxy settings

=== collatorlib_testcase::test_asort_objects_by_method ===
Collation aware sorting not supported, PHP extension "intl" is not available.
==== Solution ====
Install php intl extension.

Note that, on Windows, this extension does not seem to be included in the installer, but you can get it by downloading the zip, and copying the right DLLs across. If you Google, there are more detailed instructions on Stack Exchange.

=== grading_manager_testcase::test_tokenize===
A test using UTF-8 characters has failed. Consider updating PHP and PHP's PCRE or INTL extensions (MDL-30494) Failed asserting that false is true.
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== moodlelib_testcase::test_fix_utf8 ===
Failed asserting that false is identical to 'aaabbb'.
==== Solution ====
This problem indicates buggy iconv. See [http://tracker.moodle.org/browse/MDL-33007] for discussion. So this is a real problem, to be fixed in a future integration cycle

=== Segfaults on Oracle ===
When I was running tests on oracle I was getting phpunit sefaulting.. --[[User:Dan Poltawski|Dan Poltawski]] 00:29, 16 May 2012 (WST)
==== Solution ====
Set statement_cache_size in php.ini:
oci8.statement_cache_size = 0

=== filestoragelib_testcase::test_get_file_preview ===
Failed asserting that false is an instance of class "stored_file".
==== Solution ====
Related to installing GD after you initialised PHP Unit.

Go to your Moodle directory and type 'php admin/tool/phpunit/cli/util.php --drop', then reinitialise PHPunit and run the test again.

Common unit test problems

2012-11-08T04:04:13Z

Markn86: /* Solution = */

Common unit test problems

2012-11-08T04:03:51Z

Markn86:

=== Unit tests are taking more than 5 mins to run ===
This problem is under investigation. We are hoping to find the soluton. On a typical system all tests complete in under 3 mins.--[[User:Dan Poltawski|Dan Poltawski]] 12:43, 15 May 2012 (WST)

You maybe find much better performance on psql as a workaround for now if not doing DB dependent tests.

=== dml_testcase::test_unique_index_collation_trouble===
"Unique index is accent insensitive, this may cause problems for non-ascii languages. This is usually caused by accent insensitive default collation."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_unicode_ci collation.

=== dml_testcase::test_sql_binary_equal ===
"SQL operator "=" is expected to be case sensitive Failed asserting that 1 matches expected 2."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_unicode_ci collation.

=== moodlesimplepie_testcase::test_getfeed ===
"Failed to load the sample RSS file. Please check your proxy settings in Moodle. %s"
==== Solution ====
Your moodle needs network connectivity, please check proxy settings.

=== moodlesimplepie_testcase::test_redirect ===
Failed asserting that 'cURL Error: Operation timed out after 2000 milliseconds with 0 bytes received' is null.
==== Solution ====
Your moodle needs network connectivity, please check proxy settings

=== collatorlib_testcase::test_asort_objects_by_method ===
Collation aware sorting not supported, PHP extension "intl" is not available.
==== Solution ====
Install php intl extension.

Note that, on Windows, this extension does not seem to be included in the installer, but you can get it by downloading the zip, and copying the right DLLs across. If you Google, there are more detailed instructions on Stack Exchange.

=== grading_manager_testcase::test_tokenize===
A test using UTF-8 characters has failed. Consider updating PHP and PHP's PCRE or INTL extensions (MDL-30494) Failed asserting that false is true.
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== moodlelib_testcase::test_fix_utf8 ===
Failed asserting that false is identical to 'aaabbb'.
==== Solution ====
This problem indicates buggy iconv. See [http://tracker.moodle.org/browse/MDL-33007] for discussion. So this is a real problem, to be fixed in a future integration cycle

=== Segfaults on Oracle ===
When I was running tests on oracle I was getting phpunit sefaulting.. --[[User:Dan Poltawski|Dan Poltawski]] 00:29, 16 May 2012 (WST)
==== Solution ====
Set statement_cache_size in php.ini:
oci8.statement_cache_size = 0

=== filestoragelib_testcase::test_get_file_preview ===
Failed asserting that false is an instance of class "stored_file".
=== Solution ====
Go to Dan P's computer and disturb him.

Activity modules

2012-11-06T07:16:33Z

Markn86: /* access.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabilities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The <modname>_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The <modname>_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The <modname>_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:11:10Z

Markn86: /* lib.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The <modname>_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The <modname>_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The <modname>_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:09:48Z

Markn86: /* upgrade.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:08:40Z

Markn86: /* install.xml */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:08:06Z

Markn86: /* install.xml */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:07:08Z

Markn86: /* access.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:06:39Z

Markn86: /* access.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create, if there are no new capabilities needed then this file is not needed. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T04:02:57Z

Markn86: /* Standard Files and their Functions */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-19T02:38:27Z

Markn86:

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders it's page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:32:44Z

Markn86: /* lib.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.<br /><br />
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance.<br /><br />
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:31:15Z

Markn86: /* lib.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:30:26Z

Markn86: /* Standard Files and their Functions */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:30:01Z

Markn86: /* Introduction */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:29:39Z

Markn86: /* Introduction */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:28:40Z

Markn86: /* lib.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

Replace certificate with the name of your module.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:26:18Z

Markn86: /* upgrade.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function <modname>_add_instance($certificate);
function <modname>_update_instance($certificate);
function <modname>_delete_instance($id);
</code>

In this case <modname> is replaced with certificate.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:26:03Z

Markn86: /* upgrade.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function <modname>_add_instance($certificate);
function <modname>_update_instance($certificate);
function <modname>_delete_instance($id);
</code>

In this case <modname> is replaced with certificate.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:24:25Z

Markn86: /* upgrade.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function <modname>_add_instance($certificate);
function <modname>_update_instance($certificate);
function <modname>_delete_instance($id);
</code>

In this case <modname> is replaced with certificate.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:23:16Z

Markn86: /* upgrade.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.<br />
2. Add the instructions for the upgrade.php files.<br />
3. Update the version number in your version.php file.<br />

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function <modname>_add_instance($certificate);
function <modname>_update_instance($certificate);
function <modname>_delete_instance($id);
</code>

In this case <modname> is replaced with certificate.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:21:06Z

Markn86: /* Introduction */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.
2. Add the instructions for the upgrade.php files.
3. Update the version number in your version.php file.

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function <modname>_add_instance($certificate);
function <modname>_update_instance($certificate);
function <modname>_delete_instance($id);
</code>

In this case <modname> is replaced with certificate.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:20:34Z

Markn86: /* Introduction */

== Introduction ==

Activity modules reside in the '''/mod''' directory. They are the oldest type of plugins in Moodle - that's why they have this overly-generic name and also why they have a few idiosyncrasies and operate slightly differently from all the plugins that came later.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.
2. Add the instructions for the upgrade.php files.
3. Update the version number in your version.php file.

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function <modname>_add_instance($certificate);
function <modname>_update_instance($certificate);
function <modname>_delete_instance($id);
</code>

In this case <modname> is replaced with certificate.

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

File:Activities file structure example.jpg

2012-10-18T09:20:13Z

Markn86:

Activity modules

2012-10-18T09:18:13Z

Markn86: /* lib.php */

Activity modules

2012-10-18T09:17:35Z

Markn86: /* mod_form.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory. They are the oldest type of plugins in Moodle - that's why they have this overly-generic name and also why they have a few idiosyncrasies and operate slightly differently from all the plugins that came later.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.
2. Add the instructions for the upgrade.php files.
3. Update the version number in your version.php file.

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:13:49Z

Markn86: /* lib.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory. They are the oldest type of plugins in Moodle - that's why they have this overly-generic name and also why they have a few idiosyncrasies and operate slightly differently from all the plugins that came later.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.
2. Add the instructions for the upgrade.php files.
3. Update the version number in your version.php file.

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.

The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.

The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$mform->addElement('select', 'savecert', get_string('savecert', 'certificate'), $ynoptions);
$mform->setDefault('savecert', 0);
$mform->addHelpButton('savecert', 'savecert', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to store the PDF generated by the certificate on the filesystem or not with a default value of 0 and a help button explaining what it's function is. The function standard_coursemodule_elements adds the elements common to the modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either certificate_add_instance or certificate_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:13:04Z

Markn86: /* install.xml */

== Introduction ==

Activity modules reside in the '''/mod''' directory. They are the oldest type of plugins in Moodle - that's why they have this overly-generic name and also why they have a few idiosyncrasies and operate slightly differently from all the plugins that came later.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.
2. Add the instructions for the upgrade.php files.
3. Update the version number in your version.php file.

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$mform->addElement('select', 'savecert', get_string('savecert', 'certificate'), $ynoptions);
$mform->setDefault('savecert', 0);
$mform->addHelpButton('savecert', 'savecert', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to store the PDF generated by the certificate on the filesystem or not with a default value of 0 and a help button explaining what it's function is. The function standard_coursemodule_elements adds the elements common to the modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either certificate_add_instance or certificate_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Activity modules

2012-10-18T09:12:31Z

Markn86:

== Introduction ==

Activity modules reside in the '''/mod''' directory. They are the oldest type of plugins in Moodle - that's why they have this overly-generic name and also why they have a few idiosyncrasies and operate slightly differently from all the plugins that came later.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that Moodle looks for when using your module, they each have a particular function and are all not necessary. Below are the list of most commonly used files, to view them all please

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabalities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate" NEXT="certificate_images">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the XMLDB editor. Your module should always have a table called after the module itself with the fields id, name and course.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure.
2. Add the instructions for the upgrade.php files.
3. Update the version number in your version.php file.

In this example we are only adding two new columns to the database, so we can use the XMLDB editor to change the install.xml file AND create the upgrade path. Please view [[XMLDB_editor]].

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091801) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new version.php numer) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The certificate_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is added, so this is where you should place the logic to add the activity.
The certificate_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit.
The certificate_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the ID of the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

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

$mform->addElement('select', 'savecert', get_string('savecert', 'certificate'), $ynoptions);
$mform->setDefault('savecert', 0);
$mform->addHelpButton('savecert', 'savecert', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to store the PDF generated by the certificate on the filesystem or not with a default value of 0 and a help button explaining what it's function is. The function standard_coursemodule_elements adds the elements common to the modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either certificate_add_instance or certificate_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Conditional user fields

2012-05-18T10:46:13Z

Markn86:

This page explains how to restrict an activity, resource or course section via user fields and/or custom profile fields.

==Instructions==

1. Conditional access must be enabled. (see [[Conditional_activities]] for instructions on how to enable this for your site).<br />
2. When adding or editing an activity, resource or course section scroll to the user fields in the 'Restrict Access' section.<br />
3. Choose which fields you want to restrict by (adding more if needed), select the restriction you want to put in place and then enter a value.<br />
4. Save the settings.

==Example==

This is an example of the interface in Moodle when adding an activity to a course with the conditional functionality enabled

[[File:conditional_user_setup.jpg]]

This is how it will appear to users who fail to meet the restrictions set in place.

[[File:conditional_user_courseview.jpg]]

==User Fields==

You can restrict by using one of the user fields that are located in the Moodle user table. Not all the user fields are included, as not all of them would make sense in this context. The ones included are listed below.

===AIM ID===

This is the value in the 'aim' column.

===Address===

This is the value in the 'address' column.

===City/town===

This is the value in the 'city' column.

===Country===

This is the value in the 'country' column.

===Department===

This is the value in the 'department' column.

===Email Address===

This is the value in the 'email' column.

===First name===

This is the value in the 'firstname' column.

===ICQ number===

This is the value in the 'icq' column.

===ID number===

This is the value in the 'idnumber' column.

===Institution===

This is the value in the 'institution' column.

===Interests===

This is the value in the 'interests' column.

===MSN ID===

This is the value in the 'msn' column.

===Mobile phone===

This is the value in the 'phone2' column.

===Phone===

This is the value in the 'phone1' column.

===Skype ID===

This is the value in the 'skype' column.

===Surname===

This is the value in the 'lastname' column.

===Web page===

This is the value in the 'url' column.

===Yahoo ID===

This is the value in the 'yahoo' column.

==Custom Profile Fields==

These are all the custom profile fields that have been created on the Moodle site. See [[User_profile_fields]]

==Operators==

The operators define the relationship between the field chosen and the value entered. For example, when the user's email must contain @school.com, the field chosen is 'Email address', the operater is 'contains' and the value is '@school.com'.

===Contains===

This operator restricts access to those whos chosen field contains the value provided.

===Does not contain===

This operator restricts access to those whos chosen field does not contain the value provided.

===Is Equal To===

This operator restricts access to those whos chosen field equals the value provided.

===Starts With===

This operator restricts access to the activity to those whos chosen field starts with the value provided.

===Ends With===

This operator restricts access to the activity to those whos chosen field ends with the value provided.

===Is Empty===

This operator restricts access to the activity to those whos chosen field is empty. Note, if any value is provided in this case, it is ignored.

Conditional user fields

2012-05-18T10:45:19Z

Markn86:

{{Help}}
This page explains how to set up an activity, resource or course section and restrict it by user fields and/or custom profile fields.

==Instructions==

1. Conditional access must be enabled. (see [[Conditional_activities]] for instructions on how to enable this for your site).<br />
2. When adding or editing an activity, resource or course section scroll to the user fields in the 'Restrict Access' section.<br />
3. Choose which fields you want to restrict by (adding more if needed), select the restriction you want to put in place and then enter a value.<br />
4. Save the settings.

==Example==

This is an example of the interface in Moodle when adding an activity to a course with the conditional functionality enabled

[[File:conditional_user_setup.jpg]]

This is how it will appear to users who fail to meet the restrictions set in place.

[[File:conditional_user_courseview.jpg]]

==User Fields==

You can restrict by using one of the user fields that are located in the Moodle user table. Not all the user fields are included, as not all of them would make sense in this context. The ones included are listed below.

===AIM ID===

This is the value in the 'aim' column.

===Address===

This is the value in the 'address' column.

===City/town===

This is the value in the 'city' column.

===Country===

This is the value in the 'country' column.

===Department===

This is the value in the 'department' column.

===Email Address===

This is the value in the 'email' column.

===First name===

This is the value in the 'firstname' column.

===ICQ number===

This is the value in the 'icq' column.

===ID number===

This is the value in the 'idnumber' column.

===Institution===

This is the value in the 'institution' column.

===Interests===

This is the value in the 'interests' column.

===MSN ID===

This is the value in the 'msn' column.

===Mobile phone===

This is the value in the 'phone2' column.

===Phone===

This is the value in the 'phone1' column.

===Skype ID===

This is the value in the 'skype' column.

===Surname===

This is the value in the 'lastname' column.

===Web page===

This is the value in the 'url' column.

===Yahoo ID===

This is the value in the 'yahoo' column.

==Custom Profile Fields==

These are all the custom profile fields that have been created on the Moodle site. See [[User_profile_fields]]

==Operators==

The operators define the relationship between the field chosen and the value entered. For example, when the user's email must contain @school.com, the field chosen is 'Email address', the operater is 'contains' and the value is '@school.com'.

===Contains===

This operator restricts access to those whos chosen field contains the value provided.

===Does not contain===

This operator restricts access to those whos chosen field does not contain the value provided.

===Is Equal To===

This operator restricts access to those whos chosen field equals the value provided.

===Starts With===

This operator restricts access to the activity to those whos chosen field starts with the value provided.

===Ends With===

This operator restricts access to the activity to those whos chosen field ends with the value provided.

===Is Empty===

This operator restricts access to the activity to those whos chosen field is empty. Note, if any value is provided in this case, it is ignored.

File:conditional user courseview.jpg

2012-05-18T10:44:05Z

Markn86:

File:conditional user setup.jpg

2012-05-18T10:43:44Z

Markn86:

User talk:Jerome mouneyrac

2010-02-10T04:00:07Z

Markn86:

==Soccer==

==6 Jan 7:35==

* Andrew
* Sam-agol
* St Jerome
* The Shananator
* Mark
* ...

Not playing: Martin, Rolf Harris, Dongsheng

Result: Orange 0 - 4 Black<br/>
Players: Sam, Jerome, Jordan, Shane, Damon, Andrew, Mark<br/>
Goals: sam hurted the post but Mark hurted it even more

==13 Jan Bye==

==20 Jan 7:35==

* Sam-apost
* St Jerome
* The Shananator
* ...

Not playing: Martin, Andrew

==27 Jan 6:00==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==3 Feb 6:00==

* Andrew
* Martin
* Jerome
* The Shananator

Not playing: Sam, Damon

==10 Feb 10:15==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator
* Damon
* Markus Arrelius

Not playing:

==17 Feb 6:30==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator
* Damon

Not playing:

User talk:Jerome mouneyrac

2010-01-18T04:43:02Z

Markn86: /* 13 Jan Bye */

==Soccer==

==6 Jan 7:35==

* Andrew
* Sam-agol
* St Jerome
* The Shananator
* Mark
* ...

Not playing: Martin, Rolf Harris, Dongsheng

Result: Orange 0 - 4 Black<br/>
Players: Sam, Jerome, Jordan, Shane, Damon, Andrew, Mark<br/>
Goals: sam hurted the post but Mark hurted it even more

==13 Jan Bye==

==20 Jan 7:35==

* Andrew
* Sam-apost
* St Jerome
* The Shananator
* ...

Not playing: Martin

==27 Jan 6:00==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==3 Feb 6:00==

* Andrew
* Martin
* Jerome
* The Shananator

Not playing: Sam

==10 Feb 10:15==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==17 Feb 6:30==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

User talk:Jerome mouneyrac

2010-01-18T04:42:39Z

Markn86: /* 13 Jan Bye */

==Soccer==

==6 Jan 7:35==

* Andrew
* Sam-agol
* St Jerome
* The Shananator
* Mark
* ...

Not playing: Martin, Rolf Harris, Dongsheng

Result: Orange 0 - 4 Black<br/>
Players: Sam, Jerome, Jordan, Shane, Damon, Andrew, Mark<br/>
Goals: sam hurted the post but Mark hurted it even more

==13 Jan Bye==

:(

==20 Jan 7:35==

* Andrew
* Sam-apost
* St Jerome
* The Shananator
* ...

Not playing: Martin

==27 Jan 6:00==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==3 Feb 6:00==

* Andrew
* Martin
* Jerome
* The Shananator

Not playing: Sam

==10 Feb 10:15==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==17 Feb 6:30==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

User talk:Jerome mouneyrac

2010-01-18T04:42:01Z

Markn86:

==Soccer==

==6 Jan 7:35==

* Andrew
* Sam-agol
* St Jerome
* The Shananator
* Mark
* ...

Not playing: Martin, Rolf Harris, Dongsheng

Result: Orange 0 - 4 Black<br/>
Players: Sam, Jerome, Jordan, Shane, Damon, Andrew, Mark<br/>
Goals: sam hurted the post but Mark hurted it even more

==13 Jan Bye==

==20 Jan 7:35==

* Andrew
* Sam-apost
* St Jerome
* The Shananator
* ...

Not playing: Martin

==27 Jan 6:00==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==3 Feb 6:00==

* Andrew
* Martin
* Jerome
* The Shananator

Not playing: Sam

==10 Feb 10:15==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing:

==17 Feb 6:30==

* Andrew
* Martin
* Sam
* Jerome
* The Shananator

Not playing: