MoodleDocs - User contributions [en]

Local plugins

2016-07-05T11:23:15Z

Mattjohnsonuk: Added an example of how to use site wide settings for local plugins

{{Infobox Project
|name = Local customisations
|state = Implemented
|tracker = MDL-17376, MDL-16438
|discussion = http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]], some parts were originally proposed and implemented in 1.9 by Penny Leach
}}
{{Moodle 2.0}}

The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

== Custom /local/ plugins ==

Local plugins are used in cases when no standard plugin fits, examples are:
* event consumers communicating with external systems
* custom definitions of web services and external functions
* applications that extend moodle at the system level (hub server, amos server, etc.)
* new database tables used in core hacks (discouraged)
* new capability definitions used in core hacks
* custom admin settings
* extending the navigation block with custom menus [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095]

=== Standard plugin features: ===
* /local/xxx/[[version.php]] - version of script (must be incremented after changes)
* /local/xxx/db/install.xml - executed during install (new version.php found)
* /local/xxx/db/install.php - executed right after install.xml
* /local/xxx/db/uninstall.php - executed during uninstallation
* /local/xxx/db/upgrade.php - executed after version.php change
* /local/xxx/db/access.php - definition of capabilities
* /local/xxx/db/events.php - event handlers and subscripts
* /local/xxx/db/messages.php - messaging registration
* /local/xxx/db/external.php - web services and external functions descriptions
* /local/xxx/cron.php - cron job, run at the interval defined in version.php. Alternatively, you can define <tt>local_xxx_cron()</tt> in lib.php. (The lib.php method is now preferred.)
* /local/xxx/lang/en/local_pluginname.php - language file
* /local/xxx/lib.php - function library, automatically included with by config.php. Hook functions local_pluginname_extend_navigation() and local_pluginname_extend_settings_navigation() can be used to add items to the navigation and settings blocks
* /local/xxx/settings.php - configuration options. These get added to the admin menu.

The ''xxx'' is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

=== List of differences from normal plugins: ===
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
* are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
* can add admin settings to any settings page - loaded last when constructing admin tree
* do not need to have any UI - other plugins are usually visible somewhere
* some extra hooks (not implemented yet)

== /local/xxx/db/messages.php ==
Example File Structure:
<code php>
<?php

/**
* Defines message providers (types of messages being sent)
*
* @package mod-forum
* @copyright 1999 onwards Martin Dougiamas http://moodle.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

$messageproviders = array (

/// Ordinary single forum posts
'posts' => array (
)

);
</code>

== Other /local/ customisation files==

===Customised site defaults===

Different default site settings can be stored in file /local/defaults.php.
These new defaults are used during installation, upgrade and later are
displayed as default values in admin settings. This means that the content
of the defaults files is usually updated BEFORE installation or upgrade.

These customised defaults are useful especially when using CLI tools
for installation and upgrade.

Sample /local/defaults.php file content:
<code php>
<?php
$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
$defaults['moodlecourse']['numsections'] = 11;
$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
</code>
First bracket contains string from column plugin of config_plugins table.
Second bracket is the name of setting. In the admin settings UI the plugin and
name of setting is separated by "|".

The values usually correspond to the raw string in config table, with the exception
of comma separated lists that are usually entered as real arrays.

Please note that not all settings are converted to admin_tree,
they are mostly intended to be set directly in config.php.

=== 2.0 pre-upgrade script===

You can use /local/upgrade_pre20.php script for any code that needs to
be executed before the main upgrade to 2.0. Most probably this will
be used for undoing of old hacks that would otherwise break normal
2.0 upgrade.

This file is just included directly, there does not need to be any
function inside. If the execution stops the script is executed again
during the next upgrade. The first execution of lib/db/upgrade.php
increments the version number and the pre upgrade script is not
executed any more.

== Customisations outside of /local/ directory==

=== Forced settings===

Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.

In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.

Sample code in config.php
<code php>
$CFG->allowobjectembed = 0;
$CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>array('requiremodintro'=>1));
</code>

=== Local language customisations===

Moodle supports other type of local customisation of standard language
packs. If you want to create your own language pack based on another
language create new dataroot directory with "_local" suffix, for example
following file with content changes string "Login" to "Sign in":
moodledata/lang/en_local
<code php>
<?php
$string['login'] = 'Sign in';
</code>
See also https://docs.moodle.org/en/Language_editing

=== Custom script injection===

Very old customisation option that allows you to modify scripts by injecting
code right after the require 'config.php' call.

This setting is enabled by manually setting $CFG->customscripts variable
in config.php script. The value is expected to be full path to directory
with the same structure as dirroot. Please note this hack only affects
files that actually include the config.php!

; Examples:
* disable one specific moodle page without code modification
* alter page parameters on the fly

=== Direct code modifications===
This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

=== Direct database modifications===
Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

== Examples ==

=== Adding an element to the settings menu ===

In local/*pluginname*/lib.php, define a function named local_*pluginname*_extend_settings_navigation, this will get called when Moodle builds the settings block.
This example adds a link to the bottom of the course administration section of the settings block.
<code php>
function local_myplugin_extend_settings_navigation($settingsnav, $context) {
global $CFG, $PAGE;

// Only add this settings item on non-site course pages.
if (!$PAGE->course or $PAGE->course->id == 1) {
return;
}

// Only let users with the appropriate capability see this settings item.
if (!has_capability('moodle/backup:backupcourse', context_course::instance($PAGE->course->id))) {
return;
}

if ($settingnode = $settingsnav->find('courseadmin', navigation_node::TYPE_COURSE)) {
$strfoo = get_string('foo', 'local_myplugin');
$url = new moodle_url('/local/myplugin/foo.php', array('id' => $PAGE->course->id));
$foonode = navigation_node::create(
$strfoo,
$url,
navigation_node::NODETYPE_LEAF,
'myplugin',
'myplugin',
new pix_icon('t/addcontact', $strfoo)
);
if ($PAGE->url->compare($url, URL_MATCH_BASE)) {
$foonode->make_active();
}
$settingnode->add_node($foonode);
}
}
</code>

=== Removing the "Site Home" link from the navigation menu ===
<code php>
function local_xxx_extend_navigation(global_navigation $navigation) {
if ($home = $navigation->find('home', global_navigation::TYPE_SETTING)) {
$home->remove();
}
}
</code>

=== Adding Site Wide Settings For Your Local Plugin ===

If you need to add site wide settings for your local plugin, perhaps connection details for an API, you will need to do something similar to the below in your settings file (local/yourplugin/settings.php)

<code php>
// Ensure the configurations for this site are set
if ( $hassiteconfig ){

// Create the new settings page
// - in a local plugin this is not defined as standard, so normal $settings->methods will throw an error as
// $settings will be NULL
$settings = new admin_settingpage( 'local_yourplugin', 'Your Settings Page Title' );

// Create
$ADMIN->add( 'localplugins', $settings );

// Add a setting field to the settings for this page
$settings->add( new admin_setting_configtext(

// This is the reference you will use to your configuration
'yourplugin_apikey',

// This is the friendly title for the config, which will be displayed
'External API: Key',

// This is helper text for this config field
'This is the key used to access the External API',

// This is the default value
'No Key Defined',

// This is the type of Parameter this config is
PARAM_TEXT

) );

}
</code>

== Local customisations in previous versions ==
Previous versions include only partial support for customisations in /local/ directory.

=== List of local customisations in 1.9.x: ===
* /local/cron.php - custom cron jobs
* /local/settings.php - custom admin settings
* /local/db/upgrade.php - general modifications
* /local/lang/* - custom strings
* /local/lib.php - local_delete_course()

=== Migration from old 1.9.x /local/: ===
* <code>local/*</code> needs to be copied to new directory
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
* events are used instead of hooks
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

==See also==

* [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Extending navigation block]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* http://cvs.moodle.org/moodle/local/readme.txt?view=markup
* [[Local customisation (Moodle 1.9)]]

[[Category:Plugins]]

Form API

2016-07-05T11:14:36Z

Mattjohnsonuk: Added in the usage for within blocks

==Overview==
Web Forms in moodle are created using forms API. Form API supports all html elements (checkbox, radio, textbox etc), with improved accessibility and security.
==Highlights==
# Tested and optimised for use on major screen-readers Dragon and JAWS.
# Tableless layout.
# Process form data securely, with required_param, optional_param and session key.
# Supports client-side validation
# Facility to add Moodle help buttons to forms.
# Support for file repository using [[File_API]]
# Support for many custom moodle specific and non-specific form elements.
# Addition for repeated elements.
# Addition for form elements in advance group

==Usage==
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
<code php>
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

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

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
</code>
Then instantiate form (in this case simplehtml_form) on your page.
<code php>
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
</code>

If you wish to use the form within a block then you should consider using the render method, as demonstrated below:

Note that the render method does the same as the display method, except returning the HTML rather than outputting it to the browser, as with above make sure you've included the file which contains the class for your Moodle form.

<code php>
class block_yourblock extends block_base{
public function init(){
$this->title = 'Your Block';
}
public function get_content(){

$this->content = new stdClass();
$this->content->text = '';

$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);

//displays the form
$this->content->text = $mform->render();
}

return $this->content;

}
}
</code>

==Form elements==
===Basic form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]

===Custom form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete Autocomplete] - A select box that allows you to start typing to narrow the list of options, or search for results.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]

==Commonly used functions==

====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'). Note the '''$this''' not '''$mform'''

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

====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]====
To set the default value for an element.

====[[lib/formslib.php_Form_Definition#disabledIf|disableif()]]====
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====
Add rule for server/client side validation. Like text field is required element and is of type email.

====[[lib/formslib.php_Form_Definition#setHelpButton|setHelpButton()]]====
Sets pop-up help button to a form element.

====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====
Adds pop-up help button to a form element

====[[lib/formslib.php_Form_Definition#setType|setType()]]====
PARAM_* types are used to specify how a submitted variable should be cleaned.

====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====
By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.

==FAQ==
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
==See also==

* [[Core_APIs]]
* [[lib/formslib.php_Usage]]
* [[lib/formslib.php_Form_Definition]]
* [[Designing usable forms]]
* [[Fragment]]

[[Category:API]]