MoodleDocs - Contribucions de l'usuari [ca]

Administration via command line

2011-05-09T07:54:30Z

Agwells: /* Upgrading via command line */

{{Moodle 2.0}}

If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. All command line tools are located in <code>admin/cli/*</code> directory. To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php --non-interactive

Upgrading via command line is a very comfortable way of Moodle upgrade if you use [[CVS]] or [[Git|git]] checkout of the Moodle source code. See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ git fetch
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git merge origin/cvshead
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

===Issues with Upgrading via Command Line===

if your config.php contains information about several moodle instances (distinct moodle websites and databases sharing the same codebase), then this script will silently fail

The solution is to temporarily eliminate from config.php all but the one instance you want to upgrade

If this is a problem for the other instances (production sites), then modify the cli script to point to a copy of config.php (which will be the one edited to contain only one moodle instance at a time)

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

[[Category:Administrator]]

[[fr:Administration en ligne de commande]]

lib/formslib.php Form Definition

2011-01-06T22:01:01Z

Agwells: /* tags */

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform =& $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. 
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with a couple of important improvements:

# The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.

=== choosecoursefile ===
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Development:Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

<code php>
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</code>

You can supply a fourth param to htmleditor of an array of options :

<code php>

array(
'canUseHtmlEditor'=>'detect',
'rows' => 10,
'cols' => 65,
'width' => 0,
'height'=> 0,
'course'=> 0,
);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</code>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===

<code php>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

====multi-select====
<pre>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

==setHelpButton==
{{Moodle 1.9}}

<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==addHelpButton==
{{Moodle 2.0}}

<pre>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</pre>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in

Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

1. get_string($identifier, $component): The title of the help page
2. get_string("{$identifier}_help", $component): The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

The possible choices here are in the function lockoptionsall in lib/javascript-static.js.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]

If you have problems creating php forms you may get them with form builder http://phpforms.net/tutorial/html-basics/form-builder.html

lib/formslib.php Form Definition

2011-01-06T22:00:09Z

Agwells:

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform =& $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. 
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with a couple of important improvements:

# The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.

=== choosecoursefile ===
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'applydst' => true,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Development:Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

<code php>
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</code>

You can supply a fourth param to htmleditor of an array of options :

<code php>

array(
'canUseHtmlEditor'=>'detect',
'rows' => 10,
'cols' => 65,
'width' => 0,
'height'=> 0,
'course'=> 0,
);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</code>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===

<code php>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

====multi-select====
<pre>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.1}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

==setHelpButton==
{{Moodle 1.9}}

<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==addHelpButton==
{{Moodle 2.0}}

<pre>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</pre>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in

Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

1. get_string($identifier, $component): The title of the help page
2. get_string("{$identifier}_help", $component): The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

The possible choices here are in the function lockoptionsall in lib/javascript-static.js.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]

If you have problems creating php forms you may get them with form builder http://phpforms.net/tutorial/html-basics/form-builder.html

Repository plugins

2011-01-06T04:31:48Z

Agwells: All the lang directories use "en" rather than "en_utf8" now

A guide for developers on how to create a repository plugin.

== Introduction ==
===Prerequisites===
Before starting coding, it is necessary to know how to use repository administration pages and how to use the file picker.

There is a template attached to MDL-16543 which might be useful to help get you started.

===First steps===
# Create a folder for your plugin in ''moodle/repository/'' e.g. ''moodle/repository/myplugin''
# Create the following files and add them to the plugin folder:
#* ''lib.php''
#* ''pix/icon.png'' (the icon displayed in the file picker)
#* "version.php"
# Create the language file ''repository_myplugin.php'' and add it to the plugin folder, keeping the following folder structure:
#*''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php''
# Create access.php and upgrade scripts

===Overview===

The 3 different parts to write
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

==Administration APIs==

As an example, let's create a Flickr plugin for accessing a public flickr account. The plugin will be called "Flickr Public".

Firstly the skeleton:

<code php>
<?php
/**
* repository_flickr_public class
* Moodle user can access public flickr account
*
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License
*/
class repository_flickr_public extends repository {
}
?>
</code>

Then consider the question "What does my plugin do?"

In the Moodle file picker, we want to display some flickr public repositories directly linked to a flickr public account. For example ''My Public Flickr Pictures'', and also ''My Friend's Flickr Pictures''. When the user clicks on one of these repositories, the public pictures are displayed in the file picker.

In order to access to a flickr public account, the plugin needs to know the email address of the Flickr public account owner. So the administrator will need to set an email address for every repository. Let's add an "email address" setting to every repository.

<code php>
//We tell the API that the repositories have specific settings: "email address"
public static function get_instance_option_names() {
return array('email_address');
}

//We add an "email address" text box to the create/edit repository instance Moodle form
public function instance_config_form(&$mform) {
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', get_string('required'), 'required', null, 'client');
}
</code>

So at this moment all our Flickr Public Repositories will have a specific email address. However this is not enough. In order to communicate with Flickr, Moodle needs to know a Flickr API key (http://www.flickr.com/services/api/). This API key is the same for any repository. We could add it with the email address setting but the administrator would have to enter the same API key for every repository. Hopefully the administrator can add settings to the plugin level, impacting all repositories. The code is similar the repository instance settings:
<code php>
//We tell the API that the repositories have general settings: "api_key"
public static function get_type_option_names() {
return array('api_key');
}

//We add an "api key" text box to the create/edit repository plugin Moodle form (also called a Repository type Moodle form)
public function type_config_form(&$mform) {
//the following line is needed in order to retrieve the API key value from the database when Moodle displays the edit form
$api_key = get_config('flickr_public', 'api_key');
$mform->addElement('text', 'api_key', get_string('apikey', 'repository_flickr_public'),
array('value'=>$api_key,'size' => '40'));
$mform->addRule('api_key', get_string('required'), 'required', null, 'client');
}
</code>

Have we finished yet?

Yes! We have created everything necessary for the administration pages. But let's go further. It would be good if the user can enter any "Flickr public account email address" in the file picker. In fact we want to display in the file picker a Flickr Public repository that the Moodle administrator can never delete. Let's add:

<code php>
//this function is only called one time, when the Moodle administrator add the Flickr Public Plugin into the Moodle site.
public static function plugin_init() {
//here we create a default repository instance. The last parameter is 1 in order to set the instance as readonly.
repository_static_function('flickr_public','create', 'flickr_public', 0, get_system_context(),
array('name' => 'default instance','email_address' => null),1);
}
</code>

That's all - the administration part of our Flickr Public plugin is done. For your information, Box.net, Flickr, and Flickr Public all have similar administration APIs.

===Functions===
All of the following functions are optional. If they're not implemented, your plugin will not have manual settings and will have only one instance displayed in the File Picker (The repository API creates this unique instance when the administrator add the plugin).

==== get_instance_option_names====
''This function must be declared static'' 
Return an array of strings. These strings are setting names. These settings are specific to an instance.
If the function returns an empty array, the API will consider that the plugin displays only one repository in the file picker.
Parent function returns an empty array.

====instance_config_form(&$mform)====
This is for modifying the Moodle form displaying the settings specific to an instance.

For example, to add a required text box called email_address:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

''Note: ''mform'' has by default a name text box (cannot be removed).''

Parent function does nothing.

====get_type_option_names====
''This function must be declared static'' 
Return an array of string. These strings are setting names. These settings are shared by all instances.
Parent function return an empty array.

====type_config_form(&$mform)====
This is for modifying the Moodle form displaying the plugin settings.
Similar to ''instance_config_form(&$mform)''

====plugin_init()====
''This function must be declared static'' 
This function is called when the administrator adds the plugin. So unless the administrator deletes the plugin and re-adds it, it should be called only once.
Parent function does nothing.

==File picker APIs==
=== Quick Start ===
'''To be completed''' 
First of all, the File Picker using intensively Ajax you will need a easy way to debug. Install FirePHP (MDL-16371) and make it works. It will save you a lot of time. (You might give the [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] a try, it's still work in progress, though.)

Your first question when you write your plugin specification is 'Does the user need to log-in'? 
.....

For most of plugins, you need to establish a connection with the remote repository. This connection can be done into the get_listing(), constructor() function... 
.....

You wanna display a list of files once the user is logged 
.... get_listing() .....

You wanna retrieve the file that the user selected 
....

Optional question that you should ask yourself is 'Does the user can execute a search' 
.... search() ....

===Functions you *MUST* override===
====__construct====
You may initialize your plugin here, such as:
# Get options from database
# Get user name and password from HTTP POST

====get_listing($path="", $page="")====
This function will return a list of files, the list must be a array like this:
<code php>
$list = array(
//this will be used to build navigation bar
'path'=>array(array('name'=>'root','path'=>'/'), array('name'=>'subfolder', 'path'=>'/subfolder')),
'manage'=>'http://webmgr.moodle.com',
'list'=> array(
array('title'=>'filename1', 'date'=>'01/01/2009', 'size'=>'10MB', 'source'=>'http://www.moodle.com/dl.rar'),
array('title'=>'folder', 'date'=>'01/01/2009', 'size'=>'0', 'children'=>array())
)
);
</code>
'''The full specification of list element:'''
<code php>
array(
// Used to build navegation bar, so you need to include all parents folders
// array(array('name'=>'root','path'=>'/'), array('name'=>'subfolder', 'path'=>'/subfolder'))
'path' => (array) this will be used to build navigation bar
// dynload tells file picker to fetch list dynamically, when user click
// the folder, it will send a ajax request to server side.
// if you are using pagination, 'page' and 'pages' parameters should be used
// and note, you'd better don't use pagination and page at the same time
'page' => (int) which page is this list
'pages' => (pages) how many pages
'dynload' => (bool) use dynamic loading,
// will display a link in file picker
'manage' => (string) url of the file manager,
// set to true, the login link will be removed from file picker
'nologin' => (bool) requires login,
// set to true, the search link will be removed from file picker
'nosearch' => (bool) no search link,
// set this option will display a upload form in file picker
// only used in upload plugin currently
'upload' => array( // upload manager
'label' => (string) label of the form element,
'id' => (string) id of the form element
),
// file picker will build a file tree according this
// list
'list' => array(
array( // file
'title' => (string) file name,
'shorttitle' => (string) optional, if you prefer to display a short title
'date' => (string) file last modification time, usually userdate(...),
'size' => (int) file size,
'thumbnail' => (string) url to thumbnail for the file,
'thumbnail_width' => (int) the width of the thumbnail image,
'source' => plugin-dependent unique path to the file (id, url, path, etc.),
'url'=> the accessible url of file
),
array( // folder - same as file, but no 'source'.
'title' => (string) folder name,
'shorttitle' => (string) optional, if you prefer to display a short title
'path' => (string) path to this folder
'date' => (string) folder last modification time, usually userdate(...),
'size' => 0,
'thumbnail' => (string) url to thumbnail for the folder,
'children' => array( // an empty folder needs to have 'children' defined, but empty.
// content (files and folders)
)
),
)
)
</code>
Dynamically loading
Some repositories contain many files which cannot load in one time, in this case, we need dynamically loading to fetch them step by step, files in subfolder won't be listed until user click the folder in file picker treeview.

As a plug-in developer, if you set dynload flag as '''true''', you should return files and folders (set children as a null array) in current path instead of building the whole file tree.

Example of dynamically loading
See [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

===Functions you can override===
====print_login====
This function will help to print a login form, for the Ajax file picker, this function will return a
PHP array to define this form.
<code php>
public function print_login(){
if ($this->options['ajax']) {
$user_field->label = get_string('username', 'repository_boxnet').': ';
$user_field->id = 'box_username';
$user_field->type = 'text';
$user_field->name = 'boxusername';
$user_field->value = $ret->username;

$passwd_field->label = get_string('password', 'repository_boxnet').': ';
$passwd_field->id = 'box_password';
$passwd_field->type = 'password';
$passwd_field->name = 'boxpassword';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
// if you are going to rename submit button label, use this option
//$ret['login_btn_label'] = get_string('submit_btn_label');
// if you are going to display a search form instead of login form
// set this option to true
//$ret['login_search_form'] = true;
return $ret;
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

If your plugin don't require logging in, you don't need to override it, it will call get_listing to list files automatically by default.
====check_login====
This function will return a boolean value to tell Moodle whether the user has logged in.
By default, this function will return true.
====logout====
When a user clicks the logout button in file picker, this function will be called. You may clean up the session or disconnect the connection with remote server here.
====print_search====
When a user clicks the search button on file picker, this function will be called to return a search form. By default, it will create a form with single search bar - you can override it to create a advanced search form.
====search====
This function will do the searching job. You can obtain the POST parameters from the from the form you created in print_search function
This function will return a file list exactly like the one from get_listing.
====get_file====
When a user clicks the "Get" button to transfer the file, this function will be called. Basically, it will download a file to Moodle - you can override it to modify the file then move it to a better location.
====get_name====
This function will return the name of the repository instance.

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en_utf8/repository_myplugin.php'' or ''moodle/lang/en_utf8/repository_myplugin.php'':

<code php>
$string['configplugin'] = 'Flickr Public configuration';
$string['repositorydesc'] = 'A Flickr public repository';
$string['repositoryname'] = 'Flickr Public';
</code>

== Standard repository plugins ==
This is the functional specification list of the officially supported repository plugins.
For each plugins, the two mains part we are interested in are:
* How do I administrate the plugin? See [[Development:Repository_Administration_Specification| Repository Administration Specification - UC001-3]]
* How do I set up an account for this repository? See [[Development:Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]

=== Functional specifications ===
*[[Development:Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Development:Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Development:Moodle Repository Plugin|Remote Moodle Repository Plugin]]

==See also==

*[[Development:Repository API| Repository API]]
*[[Development:Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers
[[Category:Repositories]]

Broken/How Moodle outputs HTML

2011-01-06T02:17:54Z

Agwells:

'''THIS PAGE IS OUTDATED, DO NOT USE!'''

(What should you use instead?)

If you think about the HTML that is output by Moodle, then you can split it into two parts:
# the parts like the header and the user-interface, that are generated automatically by the Moodle code and the themes; and
# the bits like the contents of forum posts and labels that are input by the users.
This page is about the bits of output that are generated automatically. It explains how that happens.

==History==

Most of what is described here is new in Moodle 2.0. The work that lead to this new system is described in [[Development:Theme engines for Moodle?]] and [[Development:Navigation 2.0 implementation plan]]. Those documents were both written before the new system was developed and shows how the thinking evolved and the rationale behind it.

If you are familiar with Moodle 1.9 or before, and just wish to update your existing code, you may wish to read [[Development:Migrating your code to the 2.0 rendering API]].

==Overview==

I said above that this page is about the parts of the output that are automatically generated by Moodle code. We can break those bits of output down further:
# The overall layout of the page including the header and the footer. This is generated from the layout template provided by the theme (for example theme/standard/layout.php).
# The blocks that can appear in various places on the page. Where the blocks can appear on the page is determined by the theme layout. Which blocks appear where on which pages is configured by the user. The code that manages this is in blocklib.php. Finally, the contents of the blocks is a mixture of user-entered content (for example, the HTML block) and automatically generated content (for example, the Administration block).
# The main content in the middle of the page. This is generated by the particular script, for example mod/forum/view.php using the output libraries. (Moodle mostly uses a transaction script architecture.) This area frequently contains user-entered content too.

==Basic HTML output and $OUTPUT==

==Themes==

Themes (along with some of the other the configuration choices made by the administrator) control the overall look of a Moodle site.

A Moodle theme is a folder of code like theme/mytheme. It contains a number of files:
; config.php
: tells Moodle the settings that this theme wants.
; layout.php, layout-head.php, ...
: defines the overall layout of the page. Different types of page can have different templates. This is controlled by config.php.
; styles.css, styles_colours.css, ...
: the stylesheets that determine the layout. It is up to the theme whether to have one or many.
; rtl.css
: A special stylesheet that is only included if the current language is right-to-left.
; readme.html, screenshot.jpg
: Information about the theme. Used in the theme chooser user interface.
; favicon.ico, pix/*
: Images that the theme wants to use. These can replace the default Moodle icons.
; meta.php
: A way to add information to the page header. Somewhat an implementation detail.
; styles.php
: Implementation detail. Responsible for serving the CSS.

===Theme config.php===

===Layout templates===

===Ways themes can change other parts of the HTML===

====Basic themes====

====Minor changes to the HTML====

====Templated themes====
(Experimental)

$THEME gets initialised the frist time you use $OUTPUT, or the first time you refer to $PAGE->theme

==Blocks==

==Plugin-specific output==

$OUTPUT lets themes customise the HTML used for standard things like boxes, but what about places where code echoes HTML directly? Well, in addition to moodle_core_renderer, every plugin should also define its own renderer, like moodle_mod_workshop_renderer, and all module-specific HTML output should done in methods of that class. That class should be defined in a files called renderers.php inside your plugin.

When you actually want to do some output, you need to get an instance of your class (or whatever subclass the theme wants to substitute). You do that like this:
<code php>
global $PAGE; // If necessary.
$wsoutput = $PAGE->theme->get_renderer('mod_workshop', $PAGE);
echo $wsoutput->manual_allocation_interface($workshop, $allocationdata);
</code>
The moodle_mod_workshop_renderer object will have access to a moodle_core_renderer available as $this->output. You should use this instead of global $OUTPUT, and you should use it. That is, boxes in the workshop should look like boxes elsewhere, so boxes in the workshop should be output with $this->output->box().

==How to learn more==

Software normally needs documentation on three levels:
# An general overview of how all the parts fit together. You've just read that!
# Detailed documentation of the API and how to use it. What functions exist. What arguments they take and what they mean. What is returned. You can find that at http://phpdocs.moodle.org/. All the output code is in the moodlecore package.
# All the details of how the code actually works. In the open source world, the best way to learn that (after you have read the overview) is to read the code itself. It is the only sort of documentation that never goes out of date!

You should also remember Moodle's [[Pedagogy|social constructionist pedagogy]]. We learn best by doing, and then showing what we have done to others; we learn by looking at what other people have done; and we learn by asking each other questions. Don't be afraid to use the [http://moodle.org/course/view.php?id=5 forums] to share what you have done, and to ask for further explanation. This document has already benefited greatly from the questions that Sam Hemelryk and David Mudrak asked when they started working with this code.

==See also==

* [[Development:Migrating your code to the 2.0 rendering API]]
* [[Development:Theme_engines_for_Moodle%3F]]
* [[Development:Navigation_2.0_implementation_plan]]
* [[Development:Navigation_2.0]]

{{CategoryDeveloper}}

Setting up Netbeans

2011-01-05T01:59:28Z

Agwells: /* Installation */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest stable version from [http://netbeans.org http://netbeans.org]. Get the bundle that contains only PHP support.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will need to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within NetBeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to ''Tools->plugins->available plugins'' and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2011-01-05T01:59:07Z

Agwells: /* Installation */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest stable version from [http://netbeans.org]. Get the bundle that contains only PHP support.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will need to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within NetBeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to ''Tools->plugins->available plugins'' and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Podcasting

2010-12-14T04:17:18Z

Agwells:

'''Podcasting''' is an easy way to deliver a series of audio files in such a way that people can subscribe and have all current and future 'episodes' downloaded automatically to their computer or media player.

== Podcasting in Moodle ==

There are two possibilities for podcasting using Moodle:

* Starting from Moodle 1.6, simply use the discussion forums tool! If you create a discussion forum and activate RSS feeds for the forum, you can simply post messages with media files as attachments. These will be delivered as podcasts in the [[RSS in forums|RSS feed]]. (''Note:'' This works in some situations and not in others, possibly based on whether or not guest users are able to view the forum. Otherwise the media files may not be accessible by the podcast-receiving software.)
* Use the optional [[Ipodcast module]] which creates a specific podcasting activity type in Moodle. The advantage of this method is that it includes extra ''metadata'' designed to work well with Apple's ''iTunes'' software (such as keywords and category labels).
* Or the "Podcaster" module: http://moodle.org/mod/data/view.php?d=13&rid=2160

== Podcasting about Moodle ==

You may also like to know that a podcast ''about'' Moodle is in preparation, tentatively called "[[Portal:mCast|mCast]]".

== Software for receiving podcasts ==

* Apple's [http://www.apple.com/itunes/ iTunes] is currently one of the more popular pieces of software for subscribing to podcasts
* [http://juicereceiver.sourceforge.net/ Juice] (previously known as ''iPodder'') which is open-source and available on Windows and Macintosh.
* [http://getsongbird.com/ Songbird], a truly cross-platform, Open Source media player.
* [http://www.gnome.org/projects/rhythmbox/ Rhythmbox] for the Gnome Desktop
* [http://amarok.kde.org/ Amarok] for KDE

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=7230 Podcasting module forum]
* [http://en.wikipedia.org/wiki/Podcasting Wikipedia article on podcasting]
* [http://www.apple.com/podcasting Apple webpage on podcasting]
*[[Audio in Moodle]]
*[[iTunes university block]] contributed code that links to iTunes U

[[Category:RSS]]
[[Category:Contributed code]]
[[Category:Audio]]

[[pl:Podcasting]]

Moodle myths

2010-10-18T04:02:40Z

Agwells: /* The Total Cost of Ownership is actually higher for Moodle than it would be with a wholly commercial platform */

{{About Moodle}}
Our top 10 has expanded. Sometimes we hear these myths:

==Once Moodle is stable, it will be put under licence. If it were any good, they’d already be charging for it==
Martin Dougiamas is [http://moodle.org/mod/forum/discuss.php?d=41253 on record] that Moodle will always be free and under the GPL. Even if it weren't, the community could take the latest GPL code and continue development from there. One of the reasons why Moodle's so good is that it's open source code, and so the world wide educational community can contribute to making it better still.

In other cases where such things have happened, the community quickly "forked" the tool and continued it, with ongoing improvements, as an open-source project. What is out there up to this point will stay out there - legally - even if something in the future did not. Nobody can "buy" Moodle, and any coopting without the consent of the global community wouldn't get very far.

==Moodle needs a full time, php developer on your staff- or at least a lot of technical support to run it in house==
There are ''plenty'' of institutions running Moodle as is, without any php developers in sight. You don't need to know any programming if you just want to run an out of the box, as a full featured, rich Moodle site.

That said, PHP is actually a fairly easy language to pick up, and the Moodle code is well documented, so if you did want to help with [[Developer|development]], it's a fairly gentle learning curve. We have [[Development:Developer documentation|documentation]] and a process to help you.

It is also fair to say you need a certain amount of technical know-how to run any program on the web securely. But this has more to do with getting a web-server, SQL database and scripting language up and integrated than running a Moodle instance itself. If you can run your own webserver, you should be OK to run Moodle on it.

You don't actually have to run Moodle in house. There are well respected [[Moodle Partners]] who'll run Moodle for you. Some of the more enlightened educational consortia (Regional Broadband Consortia in the UK), or some local non-profit authorities may provide Moodle hosting. Moodle will work on plenty of commercially [[Web Hosts|hosted]] webspaces too.

==Moodle won’t be compatible with our other systems/software==
Moodle will run on FreeBSD, Linux, Mac OS X, Solaris, Windows and many others. It's compatible with a huge range of databases through ADODB integration. There's a whole host of authentication and enrollment mechanisms, including LDAP and arbitrary external databases. Moodle will allow teachers to integrate content in a wide range of different formats, including SCORM, Flash, MP3s and RSS feeds. On the [[Roadmap]] for future releases is a Web API which will allow easy integration with other web-based applications.

Finally, remember that this is open source software, with a well documented data and file structure. If Moodle's not compatible with a particular application at the moment, then you can pay a developer to code up that integration, or develop it in-house.

==Moodle just doesn’t have the commercial experience we’re looking for==
Check out the [http://moodle.com partners]. Moodle is in use throughout the world by corporate clients for in-house training, including flight schools, pilot and mechanic certification, health professionals and all other varieties of professional development. Remember, Moodle is a tool (an application). The PEOPLE that make up the Moodle world-wide community have experience across the board in every industry and every sort of education setting. In fact, you'll be hard-pressed to find a more committed group of educators and [[Trainer|trainers]] in one place on the web than on moodle.org. Further evidence of the commercial applications of Moodle are supported by the fact that Microsoft Corporation funded the modification of Moodle to work on their SQL Server platform (if you choose to use that instead of mySQL) and that the support for features ranging from clustering to built-in payment mechanisms is growing with each version.

==You can’t just use Moodle out of the box – the basic Moodle install just isn’t that sophisticated==
Have a look at the [[Features|feature list]], all of which comes as standard with every Moodle download. Additional themes, blocks and activities are easy to integrate and the vast majority are free, open source code too. In fact, one of your problems will be to determine which combination of sophisticated features are best going to meet your needs right out of the box.

You can do a full install on a Windows or Mac OS based personal computer in the time it takes to download a 50MB file, run an install program (less than 10 minutes), and type [[Localhost]]. This install includes a webserver, the database, and the Moodle installation. While this basic install is not appropriate for an enterprise installation, the simplicity of the install along with all its features is a testament to the robustness of the platform.

==There’s no documentation, training or technical support available – you’re on your own==
There's excellent documentation [https://docs.moodle.org/en/Main_Page online], provided by the user and developer community. Being online and digital, this resource is updated daily and keeps abreast of Moodle developments as they happen - with far more details than any book could provide, and certainly more than any commercial vendor offers for their product.

There are lots of [[Moodle manuals|books on Moodle]]. A few examples: Jason Cole and Helen Foster have written an excellent introduction to Moodle for teachers, available as a [http://www.amazon.com/gp/product/0596008635/ proper book] from O'Reilly. Additionally, [http://www.packtpub.com/ Packt Publishing] has several other books on Moodle teaching and administration available.

Most users find the Moodle interface intuitive which helps reduce the training requirements. Many organizations offer Moodle training to their members on line and in face to face settings. Some Moodle Partners [http://moodle.com/training/ moodle.com] also specialize in training.

High quality, timely technical support is available from the user and developer community in the Using Moodle course on [http://moodle.org moodle.org]. Some LAs and RBCs (Local Authorities and Regional Broadband Consortia in the UK) support Moodle in their areas. Commercial support contracts are available from authorized Moodle Partners [http://moodle.com/support/ moodle.com].

==The Total Cost of Ownership is actually higher for Moodle than it would be with a wholly commercial platform==
Stop and think for a moment about [[Wikipedia:Total cost of ownership|TCO]]. With both Moodle and commercial platforms, you'll still need to pay for hosting, support, training and content, one way or another: with Moodle, more of these costs ''can'' be brought in-house, because the code's open source and Moodle's great at providing the tools teachers need to write online activities themselves, but that doesn't mean you have to.

The difference is that with Moodle, there are '''no''' licence fees to pay. None, nada, zero. If you must spend money, please help us by making the software better, to improve Moodle for the common good. None of your money needs to go to meet shareholder dividends or pay back the venture capitalists. Furthermore, you're not exposed to the risks of commercial suppliers unilaterally increasing their licence fees, or going out of business. You are also not '''restricted''' by license agreements - you can use it however you like. There isn't an "Enterprise" version that costs many times more than the basic (but has the features you actually) need - Moodle comes with '''everything''' you need.

It's that Moodle offers significant savings over other applications. For example when the UK government agency [http://www.becta.org.uk Becta] examined the [http://publications.becta.org.uk/display.cfm?resID=25907 Total Cost of Ownership of open-source software] on desktops in UK schools, they found significant savings compared to commercial alternatives. The savings on support costs were particularly impressive. It's likely that these savings would have been greater still had they examined web-based applications like Moodle.

==Moodle is just no good for an institution as large as mine==
Does that mean you have more than 30,000 on line students? [http://aprender.unb.br Universidade de Brasília] has 34,000 users, [http://www.sfsu.edu San Francisco State University (SFSU)] has 34,000 active users, The Austrian Federal Ministry of Education has over 110,000 on [http://www.edumoodle.at/moodle/ their site] and the UK's Open University has well over 180,000 users. There are plenty of other less than 30,000 user [[Large_installations|institution systems]] officially using Moodle.

Moodle works for large institutions who also have a large numbers of users.

==Moodle is just not designed to cope with my specific group of learners or customers==
Moodle's being used successfully from elementary education, including early years provision, up to higher education, in all subject areas including art, languages, the humanities and mathematics. It's also established itself in the world of life-long learning, teachers' CPD, corporate and government training environments.

==We have all our stuff on *******, it’s just not worth the hassle of switching to Moodle==
The switch may not be that much of a hassle, as Moodle will happily import content in a wide range of standard formats, including SCORM, Blackboard and WebCT questions. There are an increasing number of Further and Higher Education institutions that are making the move.

Pedagogically, there's much to be gained from moving to a VLE which puts social, collaborative learning at the centre, and acknowledges the vital role that learners have to play, as well as providing teachers with the tools that they need to build effective on-line learning communities, rather than just presenting resources and activities.

From a financial perspective, the costs involved in switching to Moodle should be quickly recouped through savings in licence fees.

==Moodle is free and therefore can't really be as good as something produced by a large company which earns millions in Licence fees every year==
The fact that Moodle is both free and Free (as in Free Speech) means you are certainly not buying something on blind faith that it will fit your needs, as with most commercial products.

For example, the efforts of the Moodle core team are entirely public. Anyone can watch progress in our issue [[Tracker]], download recently written code and take part in their conversations in the forums. This means that anyone who wants to (and there are literally hundreds that do) can assist in developing either the core code, custom plugins and modules, integrations and themes, or by reporting bugs that appear. A licence fee to a commercial product will not give you access to over 150 contributed code extensions that are in Moodle's [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database]. Nor will the fee have such a public and transparent issue reporting system as [http://tracker.moodle.org/secure/Dashboard.jspa MoodleTracker]. A License fee will not buy you these outstanding features.

On top of that, many institutions that use Moodle decide to devote some of their own in-house expertise to maintaining parts of the Moodle code, or developing new features. Because Moodle is free, this makes sense. With a commercial product, customization is only made by the company and their price includes all their overheads and profit. Moodle's community (or customer) direct input gets more bang for the resources spent. And there is no yearly licence fee.

All this open activity and discussion with the entire software application community is a big advantage for the Moodle user. The secretiveness inherent in a proprietary application also stifles customer based innovation and change. In a proprietary for profit company everything is controlled and developed in house. with the goal to maximize profit. As with most Open Source software, Moodle develops much faster for a given amount of cash input than commercial software.

Additionally, a commercial company has to devote significant resources to selling a virtual learning environment product to potential customers (and others). This translates into less money and focus in meaningful product development. Moodle has no such overhead, leaving more resources for customer drive development.

Put together, the stable open source core and dozens of custom plugins means that Moodle can be tailored to fit your institutional needs much better than a secretive, one-size-fits-all offering. These are some of the reasons Moodle has such a large install base of satisfied users.

==See also==
A top 10 list in Moodle Docs started life in [http://moodle.org/mod/forum/discuss.php?d=33044 a post by Josie Fraser], as part of the 2005-6 [http://helpusgettobett.com HUGToB campaign]. Thanks to Josie and others for their contributions.

[[es:Los 10 mitos de Moodle]]
[[fr:Mythes sur Moodle]]
[[zh:Moodle十大流言]]
[[ja:Moodle伝説トップ10]]
[[de:Moodle-Mythen]]

DB layer 2.0 migration docs

2010-10-04T04:55:20Z

Agwells: Noting the upgrade_mod_savepoint() change to upgrade.php

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[Development:XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before start migrating your code to Moodle 2.0, it's recommended to install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). I'll show you the list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any idea to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|update)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|(add|strip)slashes(?!_js)

Will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (xml files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===
* STATEMENTS section was replaced by db/install.php code and db/log.php
* Few other changes are required in install.xml files (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them since now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both $enum and $enumvalues are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both $enum and $enumvalues (the 7th and 8th parameters) are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both $enum and $enumvalues (the 6th and 7th parameters) are out from function declaration!)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* The DDL functions that change things (create/drop/rename/add)_(table/field/index) no longer return boolean. Instead, they throw an exception if they fail. So your upgrade.php no longer needs to use a '''$result''' variable, and instead should use the '''upgrade_mod_savepoint()''' function:
<code php>/** old way **/
if ($result && $oldversion < 2008061000) {
$table = new xmldb_table('facetoface_submissions');
$field = new xmldb_field('notificationtype');
$field->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'timemodified');

$result = $result && $dbman->add_field($table, $field);
}

/** new way **/
if ($oldversion < 2008061000) {
$table = new xmldb_table('facetoface_submissions');
$field = new xmldb_field('notificationtype');
$field->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'timemodified');

$dbman->add_field($table, $field);
upgrade_mod_savepoint(true, 2008061000, 'facetoface');
}</code>

* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). One good time to clean-up a bit your upgrade code ;-). Don't forget to take a look to the [[XMLDB editor|XMLDB Editor]] and to core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files look like in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array. Note that named params '''must be unique''', no matter if the value passed is the same.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

To obtain a value for the LIKE operator, include any % signs into the parameter string. For example, code that was previously <tt>"LIKE '$value%'"</tt> becomes <tt>"LIKE ?"</tt> with the parameter <tt>$value.'%'</tt>.

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$param['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.
* [[Development:DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[Development:DML exceptions|DML exceptions]] - DML exceptions information.

DB layer 2.0 migration docs

2010-10-04T03:39:49Z

Agwells:

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[Development:XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before start migrating your code to Moodle 2.0, it's recommended to install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). I'll show you the list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any idea to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|update)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|(add|strip)slashes(?!_js)

Will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (xml files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===
* STATEMENTS section was replaced by db/install.php code and db/log.php
* Few other changes are required in install.xml files (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them since now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both $enum and $enumvalues are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both $enum and $enumvalues (the 7th and 8th parameters) are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both $enum and $enumvalues (the 6th and 7th parameters) are out from function declaration!)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). One good time to clean-up a bit your upgrade code ;-). Don't forget to take a look to the [[XMLDB editor|XMLDB Editor]] and to core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files look like in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array. Note that named params '''must be unique''', no matter if the value passed is the same.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

To obtain a value for the LIKE operator, include any % signs into the parameter string. For example, code that was previously <tt>"LIKE '$value%'"</tt> becomes <tt>"LIKE ?"</tt> with the parameter <tt>$value.'%'</tt>.

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$param['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.
* [[Development:DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[Development:DML exceptions|DML exceptions]] - DML exceptions information.

DB layer 2.0 migration docs

2010-10-04T03:13:59Z

Agwells: /* The changes */

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[Development:XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before start migrating your code to Moodle 2.0, it's recommended to install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). I'll show you the list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any idea to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|update)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|(add|strip)slashes(?!_js)

Will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (xml files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===
* STATEMENTS section was replaced by db/install.php code and db/log.php
* Few other changes are required in install.xml files (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them since now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both $enum and $enumvalues (the 7th and 8th parameters) are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both $enum and $enumvalues (the 6th and 7th parameters) are out from function declaration!)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). One good time to clean-up a bit your upgrade code ;-). Don't forget to take a look to the [[XMLDB editor|XMLDB Editor]] and to core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files look like in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array. Note that named params '''must be unique''', no matter if the value passed is the same.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

To obtain a value for the LIKE operator, include any % signs into the parameter string. For example, code that was previously <tt>"LIKE '$value%'"</tt> becomes <tt>"LIKE ?"</tt> with the parameter <tt>$value.'%'</tt>.

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$param['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.
* [[Development:DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[Development:DML exceptions|DML exceptions]] - DML exceptions information.

DB layer 2.0 migration docs

2010-10-04T03:07:16Z

Agwells: /* The changes */

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[Development:XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before start migrating your code to Moodle 2.0, it's recommended to install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). I'll show you the list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any idea to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|update)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|(add|strip)slashes(?!_js)

Will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (xml files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===
* STATEMENTS section was replaced by db/install.php code and db/log.php
* Few other changes are required in install.xml files (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them since now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both enum and enumvalues (the 7th and 8th parameters) are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). One good time to clean-up a bit your upgrade code ;-). Don't forget to take a look to the [[XMLDB editor|XMLDB Editor]] and to core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files look like in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array. Note that named params '''must be unique''', no matter if the value passed is the same.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

To obtain a value for the LIKE operator, include any % signs into the parameter string. For example, code that was previously <tt>"LIKE '$value%'"</tt> becomes <tt>"LIKE ?"</tt> with the parameter <tt>$value.'%'</tt>.

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$param['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.
* [[Development:DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[Development:DML exceptions|DML exceptions]] - DML exceptions information.

Broken/Blocks

2010-09-22T23:56:10Z

Agwells: Undo revision 76072 by Agwells (Talk)

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

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

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

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 '''reference''' text should refer to [[Development: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 standardized 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 one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// 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 standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] 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 a language file we are presumably distributing together 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 [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== 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>
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 curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

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 [[Development: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.

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". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

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

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behaviour is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

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

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

{{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/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</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 [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development: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 [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development: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>
function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Some title ...';
}
if (empty($this->config->text)) {
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development: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 [[Development: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 [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== 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 [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development: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 [[Development: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.

== 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>
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!

There are a couple more of interesting points to note here. First of all, 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.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

{{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.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

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

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

===String me up ===

Now that we have a working config_global with saved values we want to be able to read the values from it. The simplest way to do this is to assign the config setting to a string and then use the string as we would any other. IE;

$string = $CFG->configsetting;

You can check all the configuration settings available to a module by displaying them all with;

print_object($CFG);

{{Top}}

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
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>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$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>

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 [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== 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>
function hide_header() {
return true;
}
</code>

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

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also 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 would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) 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 assign to our block's container the class HTML attribute with the value "sideblock 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, ".sideblock.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, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

===and some other useful examples too:===
<code php>
function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
</code>

This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.

If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

<code php>
function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
</code>

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers 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 /course/view.php (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>
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>
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>
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.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Responding to Cron ==

It is possible to have your block respond to the cron process. That is have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly you need to define a new function within your block class:

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

// do something

return true;
}
</code>

Then within your init function you will need to set the (minimum) execution interval for your cron function.

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

Will set the minimum interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. Remember that if you change any values in the init function you '''must''' bump the version number and visit the Notifications page 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 although $this is defined it has almost nothing in it (only title, content type, version and cron 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>
function cron() {

// get the block type from the name
$blocktype = get_record( 'block', 'name', 'my_block_name' );

// get the instances of the block
$instances = get_records( 'block_instance','blockid',$blocktype->id );

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

// recreate block object
$block = block_instance( 'my_block_name', $instance );

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

'my_block_name' will coincide with the name of the directory the block is stored in.

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.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices 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 [[Development: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 [[Development: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.

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 [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
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[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

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

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

{{Top}}

== Database support ==
In case you need to have a database table that holds some specific information that is used with your block. you will need to create a sub folder '''db''' and have an '''install.xml''' file with the table schema setup.

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

== See also ==
* [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: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[ru:Development:Blocks]]

Broken/Blocks

2010-09-22T23:54:38Z

Agwells: Should use isset() before checking for a variable that may not be defined, in order to avoid a PHP warning

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

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

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

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 '''reference''' text should refer to [[Development: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 standardized 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 one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// 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 standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] 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 a language file we are presumably distributing together 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 [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:''' 
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== 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>
function get_content() {
if (isset($this->content) && $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 curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

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 [[Development: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.

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". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

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

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: /blocks/simplehtml/'''config_instance.html''' (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behaviour is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

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

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

{{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/config_instance.html. Here goes:

<code php>
<tr valign="top">
<td align="right">
<?php print_string('configtitle', 'block_simplehtml'); ?>:
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</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 [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development: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 [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development: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>
function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Some title ...';
}
if (empty($this->config->text)) {
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development: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 [[Development: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 [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== 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 [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development: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 [[Development: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.

== 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>
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!

There are a couple more of interesting points to note here. First of all, 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.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

{{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.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

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

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file /blocks/simplehtml/config_global.html which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>

<input type="submit" value="<?php print_string('savechanges'); ?>" />

</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

===String me up ===

Now that we have a working config_global with saved values we want to be able to read the values from it. The simplest way to do this is to assign the config setting to a string and then use the string as we would any other. IE;

$string = $CFG->configsetting;

You can check all the configuration settings available to a module by displaying them all with;

print_object($CFG);

{{Top}}

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
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>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$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>

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 [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== 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>
function hide_header() {
return true;
}
</code>

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

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also 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 would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) 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 assign to our block's container the class HTML attribute with the value "sideblock 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, ".sideblock.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, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

===and some other useful examples too:===
<code php>
function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
</code>

This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.

If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

<code php>
function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
</code>

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers 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 /course/view.php (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>
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>
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>
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.

'''UPDATING:''' 
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Responding to Cron ==

It is possible to have your block respond to the cron process. That is have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly you need to define a new function within your block class:

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

// do something

return true;
}
</code>

Then within your init function you will need to set the (minimum) execution interval for your cron function.

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

Will set the minimum interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. Remember that if you change any values in the init function you '''must''' bump the version number and visit the Notifications page 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 although $this is defined it has almost nothing in it (only title, content type, version and cron 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>
function cron() {

// get the block type from the name
$blocktype = get_record( 'block', 'name', 'my_block_name' );

// get the instances of the block
$instances = get_records( 'block_instance','blockid',$blocktype->id );

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

// recreate block object
$block = block_instance( 'my_block_name', $instance );

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

'my_block_name' will coincide with the name of the directory the block is stored in.

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.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices 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 [[Development: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 [[Development: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.

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 [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
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[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

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

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

{{Top}}

== Database support ==
In case you need to have a database table that holds some specific information that is used with your block. you will need to create a sub folder '''db''' and have an '''install.xml''' file with the table schema setup.

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

== See also ==
* [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: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[ru:Development:Blocks]]

Usuari:Aaron Wells

2010-09-22T23:21:39Z

Agwells: New page: http://moodle.org/user/view.php?id=1070092&course=1

http://moodle.org/user/view.php?id=1070092&course=1

Broken/Enrolment plugins

2010-09-22T06:10:04Z

Agwells:

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''.

<code php>
class enrolment_plugin_PLUGINNAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Optional functions ===

==== Automated enrolment ====

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.enrol column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

==== Interactive enrolment ====

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

==== Cron ====

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Language Strings ===

Create a lang directory and file under your plugin's directory, like this '''<code>enrol/PLUGINNAME/lang/en_utf8/enrol_PLUGINNAME.php</code>'''. Plugins are expected to provide at least these two strings:

<code php><?php

// The name of your plugin. Displayed on admin menus.
$string['enrolname'] = 'My plugin';

// Description of your plugin. Shown on the plugin's configuration screen.
$string['description'] = 'This is what my plugin does.';

?></code>

Those two strings will be accessed automatically by Moodle in various situations. You can (and should) of course include other [[Development:Places to search for lang strings|language strings]] in your plugin's lang file(s). These can be accessed like normal language strings, using "enrol_PLUGINNAME" as the module name, e.g. <code>get_string('anotherstring', 'enrol_PLUGINNAME')</code>.

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30); 
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]

Broken/Enrolment plugins

2010-09-16T04:42:03Z

Agwells: /* Database */

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''.

<code php>
class enrolment_plugin_PLUGINNAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Automated enrolment ===

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.enrol column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

=== Interactive enrolment ===

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

=== Cron ===

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30); 
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]

Broken/Enrolment plugins

2010-09-16T04:41:05Z

Agwells: /* Automated enrolment */

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''.

<code php>
class enrolment_plugin_PLUGINNAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Automated enrolment ===

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.enrol column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

=== Interactive enrolment ===

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

=== Cron ===

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB Editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30); 
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]

Broken/Enrolment plugins

2010-09-16T04:40:09Z

Agwells: /* How to write an Enrolment plugin in Moodle 1.9 */

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''.

<code php>
class enrolment_plugin_PLUGINNAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Automated enrolment ===

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.auth column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

=== Interactive enrolment ===

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

=== Cron ===

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB Editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30); 
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]

Broken/Enrolment plugins

2010-09-16T04:39:41Z

Agwells: Adding some documentation about how to write an enrolment plugin

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''.

<code php>
class enrolment_plugin_NAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Automated enrolment ===

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.auth column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

=== Interactive enrolment ===

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

=== Cron ===

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB Editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30); 
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]

Installing and upgrading plugin database tables

2010-09-15T06:22:12Z

Agwells: Explaining the version number format

==Introduction==

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visit the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:
;version.php : This records the version of the plugin code ('''Please note:''' In Moodle installations below v2.0, this is not required for blocks, which use the version number returned by the block's init() method - see [[Development:Blocks#Ready.2C_Set.2C_Go.21|the blocks development page]])
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.9 and before, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.0 an beyond, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100; // Today's date in YYYYMMDD format, plus two additional digits
$plugin->requires = '''XXXXXXXXXX; // Moodle version - copy from $version in the top-level version.php file.'''
:Version numbers normally consist of the day's date in YYYYMMDD format, followed by two additional digits to allow for multiple versions in the same day, e.g. Sept 15, 2010 could have versions 2010091500, 2010091501, 2010091502, etc.

;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
$result = true;

/// Add a new column newcol to the mdl_question_myqtype
if ($result && $oldversion < 2008080200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from
upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
which says what is currently installed
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}

else if ($CFG->qtype_myqtype_version does not exist) {
Create the tables from the definitions in install.xml
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no ''plugintype''_''pluginname''_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the ''plugintype''_''pluginname''_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Development:XMLDB_Documentation|XMLDB_Documentation]]
* [[Development:Coding|Coding guidelines]]
* [[Development:DDL functions|DDL functions]]
* [[Development:XMLDB defining an XML structure|install.xml file documentation]]

[[Category:Developer]]
[[Category:XMLDB]]
[[Category:Installation]]

Installing and upgrading plugin database tables

2010-09-15T06:17:40Z

Agwells: /* The files you need for the first release */

==Introduction==

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visit the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:
;version.php : This records the version of the plugin code ('''Please note:''' In Moodle installations below v2.0, this is not required for blocks, which use the version number returned by the block's init() method - see [[Development:Blocks#Ready.2C_Set.2C_Go.21|the blocks development page]])
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.9 and before, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.0 an beyond, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
:Version numbers normally consist of the day's date in YYYYMMDD format, followed by two additional numbers to allow for multiple versions in the same day, e.g. Sept 15, 2010 could have versions 2010091500, 2010091501, 2010091502, etc.

;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
$result = true;

/// Add a new column newcol to the mdl_question_myqtype
if ($result && $oldversion < 2008080200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from
upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
which says what is currently installed
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}

else if ($CFG->qtype_myqtype_version does not exist) {
Create the tables from the definitions in install.xml
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no ''plugintype''_''pluginname''_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the ''plugintype''_''pluginname''_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Development:XMLDB_Documentation|XMLDB_Documentation]]
* [[Development:Coding|Coding guidelines]]
* [[Development:DDL functions|DDL functions]]
* [[Development:XMLDB defining an XML structure|install.xml file documentation]]

[[Category:Developer]]
[[Category:XMLDB]]
[[Category:Installation]]

Events API

2010-08-19T22:15:50Z

Agwells: /* Users */

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

Then we post the object as an event and forget about it:

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''message_send''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

All event names should follow a consistent naming pattern, such as modulename_noun_verb

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table

===Roles===
* role_assigned (full new record from 'role_assignments' table)
* role_unassigned (record from 'role_assignments', course context only)

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed
* module_removed

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Development:Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]