MoodleDocs - User contributions [en]

Local plugins

2015-01-30T14:11:48Z

Brianking: /* Examples */

{{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_extends_navigation() and local_pluginname_extends_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*_extends_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_extends_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_extends_navigation(global_navigation $navigation) {
if ($home = $navigation->find('home', global_navigation::TYPE_SETTING)) {
$home->remove();
}
}
</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]]

Task API

2014-06-16T15:34:16Z

Brianking:

{{Infobox Project
|name = Task
|state = Integrated
|tracker = MDL-25505
|discussion = https://moodle.org/mod/forum/discuss.php?d=229139
|assignee = Damyon
}}
{{Moodle 2.7}}
== Tasks ==

A task is a unit of work that needs to be done later. Good uses for tasks:

* Run a slow operation in the background
* Run a maintenance task on a regular schedule

In general any operation that takes more than a few seconds should be a candidate for a task.

== Benefits ==

* Better user experience (give them feedback immediately, that their task has been queued)
* Prevent browser timeouts
* Better performance for clusters (tasks can be run on separate, non-webserving cluster node, tasks can run in parallel)
* Failed tasks will be retried
* A better user interface will prevent users queuing multiple tasks, because they thought it had "got stuck".

== Types of task ==

=== Scheduled tasks ===
Scheduled tasks are tasks that will run on a regular schedule. A default schedule can be set, but admins have the ability to change the default schedule if required. Note: Tasks will only run as often as cron is run in Moodle. In 2.7 it is recommended to run cron once per minute to get the benefit from the new task scheduling (don't worry - it will do much less work each time it runs).

=== Adhoc tasks ===
Adhoc tasks are for when you need to queue something to run in the background immediately. Adhoc tasks can contain custom data, specific to this specific instance of the task.

== Usage ==

=== Scheduled task usage ===

Scheduled tasks are created by subclassing \core\task\scheduled_task. They also require an entry in "db/tasks.php" for your plugin.

1. Create a subclass of \core\task\scheduled_task that contains your code to run in a schedule (within "<pluginroot>/classes/task/cut_my_toe_nails.php" for the autoloading mechanism to pick up).

<pre>
namespace mod_hygene\task;

class cut_my_toe_nails extends \core\task\scheduled_task {
public function get_name() {
// Shown in admin screens
return get_string('cutmytoenails', 'mod_hygene');
}

public function execute() {
// apply fungus cream
// apply chainsaw
// apply olive oil
}
}
</pre>
2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task):
<pre>
$tasks = array(
array(
'classname' => 'mod_hygene\task\cut_my_toe_nails',
'blocking' => 0,
'minute' => '*',
'hour' => '*',
'day' => '*',
'dayofweek' => '*',
'month' => '1,6'
)
);
</pre>
The field required in the db/tasks.php file are:
* classname - the fully namespaced classname of your task. This needs to comply with the autoloading rules.
* blocking - if this is set to 1, no other scheduled task will run at the same time as this task. Do not set this to 1 unless you really need it as it will impact the performance of the task queue.
* minute, hour, day, dayofweek, month - This is the default schedule for running the task. The syntax matches the syntax of unix cron.
==== Cron syntax examples ====
* day - Day of month field for task schedule.
** "*" - Every day
** "*/2" - Every 2nd day
** "1" - The first of every month
** "1,15" - The first and fifteenth of every month
* dayofweek - Day of week field for task schedule.
** "*" - Every day
** "0" - Every Sunday
** "6" - Every Saturday
** "1,5" - Every Monday and Friday
* hour - Hour field for task schedule.
** "*" - Every hour
** "*/2" - Every 2 hours
** "2-10" - Every hour from 2am until 10am (inclusive)
** "2,6,9" - 2am, 6am and 9am
* minute - Minute field for task schedule.
** "*" - Every minute
** "*/5" - Every 5 minutes
** "2-10" - Every minute between 2 and 10 minutes past the hour (inclusive)
** "2,6,9" - 2, 6 and 9 minutes past the hour
* month - Month field for task schedule.
** "*" - Every month
** "*/2" - Every second month
** "1" - Every January
** "1,5" - Every January and May

=== Adhoc task usage ===

This is even easier than scheduled tasks.

1. Create a subclass of \core\task\adhoc_task that contains your code to run in the background.
<pre>

class take_over_the_world extends \core\task\adhoc_task {
public function execute() {
// gain 100,000,000 friends on facebook.
// crash the stock market.
// run for president.
}
}

</pre>

2. Create an instance of the task and queue it (adding custom data if required).

<pre>
// create the instance
$domination = new take_over_the_world();
// set blocking if required (it probably isn't)
// $domination->set_blocking(true);
// add custom data
$domination->set_custom_data(array(
'plansfortomorrownight' => 'The same thing we do every night, Pinky!'
));

// queue it
\core\task\manager::queue_adhoc_task($domination);

// profit
</pre>

3. There is no 3.

=== Failures ===
A task, either scheduled or adhoc can sometimes fail. An example would be updating an RSS field when the network is temporarily down. This is handled by the task system automatically - all the failing task needs to do is throw an exception. The task will be retried after 1 minute. If the task keeps failing, the retry algorithm will add more time between each successive attempts up to a max of 24 hours.

=== Caches ===
There is one special case that needs to be considered with this new system. If a particular scheduled or adhoc task runs for a long time and updates many DB records - particularly something related to enrolment - the next task in the queue may suffer because various API's in moodle use static caching to speed up requests, but assume that the data will not change much between the start and end of the request. In this case, you can force the cron to exit after running a task that has done many DB updates. The next cron will be run in the next minute, and will have all static caches cleared because it's a new process. To do this call \core\task\manager::clear_static_caches();

=== Security ===
When scheduling a task to run in the background - or creating a scheduled task, the task will run in the context of the cron user (see "cron_setup_user()"). If you need to perform access checks in your background task, you should pass the userid/context in custom_data and then pass that userid to the access check functions ("require_capability('moodle/course:update', $context, $userid)").

=== Legacy cron ===
The older syntax of cron.php or modname_cron() is still supported - but is not as good as this new API. This is because:
* the legacy cron functions run serially - a long running cron in one plugin will hold up the other plugins crons
* the legacy cron functions are fragile - a failure in one cron in one plugin will prevent the cron in other functions from running at all
* the scheduling cannot be changed by admins

== For Admins ==
Admins have a new screen where they can adjust the schedules for any scheduled task. They can also reset any scheduled task to it's default schedule.
[[File:task_admin_screenshot.png|Screenshot of admin page]]

== Specification ==
The specification for this feature is here: https://docs.moodle.org/dev/Scheduled_Tasks_Proposal

Old Events API

2014-04-03T12:56:50Z

Brianking: /* Events wishlist */

==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 enrolment in Moodle 2.0. In the enrolment system, lib/enrollib.php will generate a 'user_enrolled' event upon completion of an enrolment of a user.

===Triggering an event===

When a user is enrolled, a 'user_enrolled' event is built and sent out by the enrol API. In this example let's pretend someone was just enrolled.

The enrol lib (could even be a module thats creating this event) 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.
<code php>
$ue = new stdClass();
$ue->enrolid = $instance->id;
$ue->status = is_null($status) ? ENROL_USER_ACTIVE : $status;
$ue->userid = $userid;
$ue->timestart = $timestart;
$ue->timeend = $timeend;
$ue->modifierid = $USER->id;
...
$ue->courseid = $courseid;
$ue->enrol = $name;

events_trigger('user_enrolled', $ue);
</code>
Then we post the object as an event and forget about it:
<code php>
events_trigger('user_enrolled', $eventdata);
</code>
We have now broadcast an event that we think other parts of the system might need to know about.

===Handling an event===

Modules or core code can define an events.php in under its */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 mod/forum/db/events.php.

<code php>
$handlers = array (
'user_enrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_enrolled',
'schedule' => 'instant',
'internal' => 1,
),

'user_unenrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_unenrolled',
'schedule' => 'instant',
'internal' => 1,
),
);
</code>

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''user_enrolled''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):
<code php>
include_once($CFG->dirroot.$handlers['user_enrolled']['handlerfile']);
call_user_func($handlers['user_enrolled']['handlerfunction'], $eventdata);
</code>
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.
<code php>
function forum_user_unenrolled($eventdata) {
// handle event
// ...
return true;
}
</code>
note: a lib/db/events.php exists as legacy and no events should be added here. Core API is not supposed to define events for consumption. Only modules and core components (non-api) should define events for consumption/handling.

==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 componentname_noun_verb (See [[Frankenstyle]] about the component name)

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
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===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
* course_content_removed
** full course record
* course_restored (2.5)

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

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

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

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_started
* quiz_attempt_submitted - ''Note: these two quiz events changed in Moodle 2.1''.

==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 discriminating 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 ''(= mod_created in v2?)''
* module_removed ''(= mod_deleted in v2?)''
* grade_update ''(= quiz_attempt_processed in v2?)''
* assignment_submitted
* course - editing turned on or off
* course completed
* course module completion state changed (completed / not completed)
* course was reset
* Some will_be ... events that would allow another plugin to react before these things happen:
** course_will_be_restored (with info about course being restored and the target category)
** course_category_will_be_moved (with info about category being moved and target category)
** course_will_be_moved (with course info and target category info)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [[Core APIs]]
* [http://moodle.org/mod/forum/discuss.php?d=69103 Original General Developer Forum thread discussing this proposal].
* [[Messaging_2.0]]
* [[Event_2]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]
[[Category:API]]

Old Events API

2013-07-09T07:59:02Z

Brianking: /* Events wishlist */

==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 enrollment in Moodle 2.0. In the enrollment system, lib/enrollib.php will generate a 'user_enrolled' event upon completion of a enrollment of a user.

===Triggering an event===

When a user is enrolled, a 'user_enrolled' event is built and sent out by the enrol API. In this example let's pretend someone was just enrolled.

The enrol lib (could even be a module thats creating this event) 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.
<code php>
$ue = new stdClass();
$ue->enrolid = $instance->id;
$ue->status = is_null($status) ? ENROL_USER_ACTIVE : $status;
$ue->userid = $userid;
$ue->timestart = $timestart;
$ue->timeend = $timeend;
$ue->modifierid = $USER->id;
...
$ue->courseid = $courseid;
$ue->enrol = $name;

events_trigger('user_enrolled', $ue);
</code>
Then we post the object as an event and forget about it.:
<code php>
events_trigger('user_enrolled', $eventdata);
</code>
We have now broadcast an event that we think other parts of the system might need to know about.

===Handling an event===

Modules or core code can define an events.php in under its */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 mod/forum/db/events.php.

<code php>
$handlers = array (
'user_enrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_enrolled',
'schedule' => 'instant',
'internal' => 1,
),

'user_unenrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_unenrolled',
'schedule' => 'instant',
'internal' => 1,
),
);
</code>

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''user_enrolled''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):
<code php>
include_once($CFG->dirroot.$handlers['user_enrolled']['handlerfile']);
call_user_func($handlers['user_enrolled']['handlerfunction'], $eventdata);
</code>
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.
<code php>
function forum_user_unenrolled($eventdata) {
// handle event
// ...
return true;
}
</code>
note: a lib/db/events.php exists as legacy and no events should be added here. Core API is not supposed to define events for consumption. Only modules and core components (non-api) should define events for consumption/handling.

==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 componentname_noun_verb (See [[Frankenstyle]] about the component name)

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
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===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
* course_content_removed
** full course record
* course_restored (2.5)

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

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

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

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_started
* quiz_attempt_submitted - ''Note: these two quiz events changed in Moodle 2.1''.

==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 discriminating 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 ''(= mod_created in v2?)''
* module_removed ''(= mod_deleted in v2?)''
* grade_update ''(= quiz_attempt_processed in v2?)''
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)
* Some will_be ... events that would allow another plugin to react before these things happen:
** course_will_be_restored (with info about course being restored and the target category)
** course_category_will_be_moved (with info about category being moved and target category)
** course_will_be_moved (with course info and target category info)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [[Core APIs]]
* [http://moodle.org/mod/forum/discuss.php?d=69103 Original General Developer Forum thread discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]
[[Category:API]]

Local plugins

2013-06-24T14:14:27Z

Brianking: /* Adding an element to the settings menu */

{{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_extends_navigation() and local_pluginname_extends_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*_extends_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_extends_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>

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

Local plugins

2013-06-24T14:10:25Z

Brianking:

{{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_extends_navigation() and local_pluginname_extends_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*_extends_settings_navigation, this will get called when Moodle builds the settings block.
<code php>
function local_myplugin_extends_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>

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

Local plugins

2013-06-24T14:08:52Z

Brianking:

{{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_extends_navigation() and local_pluginname_extends_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*_extends_settings_navigation, this will get called when Moodle builds the settings block.
<code php>
function local_myplugin_extends_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>

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

Local plugins

2013-06-24T13:47:28Z

Brianking: /* Standard plugin features: */

{{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_extends_navigation() and local_pluginname_extends_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.

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

Old Events API

2010-05-04T11:42:04Z

Brianking: /* Handling an event */

==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_updated
** full new record from 'user' table

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

* user_role_assign
* user_role_unassign
* 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].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Old Events API

2010-05-04T11:40:11Z

Brianking: /* Handling an event */

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

{code}
function message_send_handler($eventdata) {
// handle event
return true;
}
{code}

==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_updated
** full new record from 'user' table

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

* user_role_assign
* user_role_unassign
* 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].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Talk:File API internals

2009-01-20T15:37:56Z

Brianking: /* meta information */

===Main tasks===
* File Storage API:
** abstract (M1)
** local pool implementation (M1)
** DB schema (M1)
** deletion, acls, metadata (M1)
** problem: empty directories, file overwriting
* File Manager API:
** unique class, able to handle one "file area" (M2)
** security (M2)
** hack old file manager to be able to work with new fileareas (M3)
** js and non js implementations of FileManager (M4)
** integration with editor (M4)
** integration with formslib (M4)
** integration with repos (M4)
** problem: zip support
* File Serving:
** from pool:
*** file.php
*** pluginfile.php
*** draftfile.php
*** userfile.php
** from other moddata places:
*** rssfile.php
*** user/pix.php
*** user/pixgroup.php
* Migration:
** course files (as much as possible, allow fallback) (M2)
** moddata
**
* Backup & restore:

===Milestones===
M1: File storage API completed (this week)
M2: migration of course files + new filephp + FileManager + hacked old file manager (next monday)
M3: ...

===rssfile.php===
It's said that rss/file.php is kept only for backwards compatibility. But what exactly is meant by "backwards compatibility"?
Just display feeds with nice error messages and info how to re-subscribe?

== meta information ==

It seems like it would be nice to include some meta information about certain file types, e.g.:

* images: width, height, alt
* flash files: width, height

Talk:File API internals

2009-01-20T15:37:17Z

Brianking: New section: meta information

===Main tasks===
* File Storage API:
** abstract (M1)
** local pool implementation (M1)
** DB schema (M1)
** deletion, acls, metadata (M1)
** problem: empty directories, file overwriting
* File Manager API:
** unique class, able to handle one "file area" (M2)
** security (M2)
** hack old file manager to be able to work with new fileareas (M3)
** js and non js implementations of FileManager (M4)
** integration with editor (M4)
** integration with formslib (M4)
** integration with repos (M4)
** problem: zip support
* File Serving:
** from pool:
*** file.php
*** pluginfile.php
*** draftfile.php
*** userfile.php
** from other moddata places:
*** rssfile.php
*** user/pix.php
*** user/pixgroup.php
* Migration:
** course files (as much as possible, allow fallback) (M2)
** moddata
**
* Backup & restore:

===Milestones===
M1: File storage API completed (this week)
M2: migration of course files + new filephp + FileManager + hacked old file manager (next monday)
M3: ...

===rssfile.php===
It's said that rss/file.php is kept only for backwards compatibility. But what exactly is meant by "backwards compatibility"?
Just display feeds with nice error messages and info how to re-subscribe?

== meta information ==

It seems like it would be nice to include some meta information about certain file types, e.g.:
images: width, height, alt
flash files: width, height

Old Events API

2009-01-19T14:49:54Z

Brianking: /* Courses */

{{obsolete_design}}
{{Moodle 1.9}}
The Events API is a new core system in Moodle to allow better communication between modules. It's based on modules triggering new events with attached data, and the other modules handling those events with custom functions.

==Overview==

We'll be using the example of a grade being posted from a module into the [[Grades|new gradebook in Moodle 1.9]], but there are obviously all kinds of events possible.

===Triggering an event===

Whenever a grade is created or changed by a module, it should “tell” the system about it (in addition to any local working storage it uses). So, using the quiz as an example, we first define an object as follows:

$eventdata = new object();
$eventdata->itemid = $grade_item->id;
$eventdata->userid = $USER->id;
$eventdata->gradevalue = $currentvalue;

Then we post the object as an event and forget about it:

events_trigger('grade_updated', $eventdata);

===Handling an event===

Modules can define an events.php in their db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For example, an export plugin could register something like:

$handlers = array (
'grade_updated' => array (
'handlerfile' => '/grade/export/banner/lib.php',
'handlerfunction' => 'banner_handle_grade_test', // argument to call_user_func(), could be an array
'schedule' => 'cron'
)
);
These are parsed during install / upgrade and stored in a simple database table.

Then, when a grade_updated event happens, all the registered functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['grade_updated']['handlerfile']);
call_user_func($handlers['grade_updated']['handlerfunction'], $eventdata);

All plugins in Moodle have access to this and can this easily “hook in” to 'grade_updated' events (and of course any other events).

==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 handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called any time an 'grade_added' event is triggered by a module.

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. 'grade_updated'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /grade/export/lib.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

==Events which exist==

===Users===
* user_updated
* password_changed

===Courses===
* course_created
* course_updated
* course_deleted
* category_updated
* category_deleted

===Groups===
* group_deleted
* grouping_deleted
* group_user_added
* group_user_removed

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

* user_created (for example to handle custom emails. this is commonly desired: e.g. send a custom email to a related person (teacher, boss, etc.) based on some institution-specific logic)
* user_enrolled_in_course
* user_unenrolled_from_course

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[:Development:Grades]]

[[Category:Events]]
[[Category:Grades]]

Old Events API

2009-01-19T14:49:36Z

Brianking: /* Events wishlist */

{{obsolete_design}}
{{Moodle 1.9}}
The Events API is a new core system in Moodle to allow better communication between modules. It's based on modules triggering new events with attached data, and the other modules handling those events with custom functions.

==Overview==

We'll be using the example of a grade being posted from a module into the [[Grades|new gradebook in Moodle 1.9]], but there are obviously all kinds of events possible.

===Triggering an event===

Whenever a grade is created or changed by a module, it should “tell” the system about it (in addition to any local working storage it uses). So, using the quiz as an example, we first define an object as follows:

$eventdata = new object();
$eventdata->itemid = $grade_item->id;
$eventdata->userid = $USER->id;
$eventdata->gradevalue = $currentvalue;

Then we post the object as an event and forget about it:

events_trigger('grade_updated', $eventdata);

===Handling an event===

Modules can define an events.php in their db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For example, an export plugin could register something like:

$handlers = array (
'grade_updated' => array (
'handlerfile' => '/grade/export/banner/lib.php',
'handlerfunction' => 'banner_handle_grade_test', // argument to call_user_func(), could be an array
'schedule' => 'cron'
)
);
These are parsed during install / upgrade and stored in a simple database table.

Then, when a grade_updated event happens, all the registered functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['grade_updated']['handlerfile']);
call_user_func($handlers['grade_updated']['handlerfunction'], $eventdata);

All plugins in Moodle have access to this and can this easily “hook in” to 'grade_updated' events (and of course any other events).

==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 handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called any time an 'grade_added' event is triggered by a module.

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. 'grade_updated'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /grade/export/lib.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

==Events which exist==

===Users===
* user_updated
* password_changed

===Courses===
* course_updated
* course_deleted
* category_updated
* category_deleted

===Groups===
* group_deleted
* grouping_deleted
* group_user_added
* group_user_removed

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

* user_created (for example to handle custom emails. this is commonly desired: e.g. send a custom email to a related person (teacher, boss, etc.) based on some institution-specific logic)
* user_enrolled_in_course
* user_unenrolled_from_course

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[:Development:Grades]]

[[Category:Events]]
[[Category:Grades]]

lib/formslib.php Form Definition

2008-05-02T15:37:33Z

Brianking: /* multi-select */

{{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();'

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 defintion 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.

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a legend.

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

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) :

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

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

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

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

===checkbox===
<pre>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</pre>
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param 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.

====advcheckbox====
<pre>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), array(0, 1), array('group' => 1));
</pre>
Similar to the checkbox above, but with a couple of important improvements:

#The 4th 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.
#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 [[lib/formslib.php_add_checkbox_controller|checkbox controller]]

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

</pre>

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

<pre>
array('courseid'=>null,\\if it is null (default then use globabl $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'

</pre>

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

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 :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true);
</pre>

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===
<pre>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</pre>
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:

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

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.

===file===

File upload input box with browse button. In the form definition type
<pre>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</pre>

after form submission and validation use
<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</pre>

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

$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');

</pre>

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

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',..).

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

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

===htmleditor & format===
<pre>

$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'));
</pre>
You can supply a fourth param to htmleditor of an array of options :

<pre>
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.
</pre>

===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===
<pre>
$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);
</pre>

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.

====setDefault====

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

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

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.

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

==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 an example of 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>

==setHelpButton==
<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();

==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 first 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, selected, eq or if it is anything else then 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 selected then we check to see if a particular option is selected from a dropdown list.

''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''

==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://midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com]

[[Category:Formslib]]

lib/formslib.php Form Definition

2008-04-16T21:30:54Z

Brianking: /* select */

{{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();'

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 defintion 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.

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a legend.

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

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) :

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

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

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

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

===checkbox===
<pre>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</pre>
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param 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.

====advcheckbox====
<pre>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), array(0, 1), array('group' => 1));
</pre>
Similar to the checkbox above, but with a couple of important improvements:

#The 4th 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.
#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 [[lib/formslib.php_add_checkbox_controller|checkbox controller]]

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

</pre>

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

<pre>
array('courseid'=>null,\\if it is null (default then use globabl $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'

</pre>

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

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 :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true);
</pre>

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===
<pre>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</pre>
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:

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

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.

===file===

File upload input box with browse button. In the form definition type
<pre>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</pre>

after form submission and validation use
<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</pre>

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

$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');

</pre>

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

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',..).

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

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

===htmleditor & format===
<pre>

$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'));
</pre>
You can supply a fourth param to htmleditor of an array of options :

<pre>
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.
</pre>

===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===
<pre>
$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);
</pre>

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.

====setDefault====

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

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

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.

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

==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 an example of 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>

==setHelpButton==
<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();

==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 first 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, selected, eq or if it is anything else then 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 selected then we check to see if a particular option is selected from a dropdown list.

''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''

==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://midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com]

[[Category:Formslib]]

Old Events API

2008-04-14T09:18:08Z

Brianking: /* Events wishlist */

The Events API is a new core system in Moodle to allow better communication between modules. It's based on modules triggering new events with attached data, and the other modules handling those events with custom functions.

==Overview==

We'll be using the example of a grade being posted from a module into the [[Grades|new gradebook in Moodle 1.9]], but there are obviously all kinds of events possible.

===Triggering an event===

Whenever a grade is created or changed by a module, it should “tell” the system about it (in addition to any local working storage it uses). So, using the quiz as an example, we first define an object as follows:

$eventdata = new object();
$eventdata->itemid = $grade_item->id;
$eventdata->userid = $USER->id;
$eventdata->gradevalue = $currentvalue;

Then we post the object as an event and forget about it:

events_trigger('grade_updated', $eventdata);

===Handling an event===

Modules can define an events.php in their db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For example, an export plugin could register something like:

$handlers = array (
'grade_updated' => array (
'handlerfile' => '/grade/export/banner/lib.php',
'handlerfunction' => 'banner_handle_grade_test', // argument to call_user_func(), could be an array
'schedule' => 'cron'
)
);
These are parsed during install / upgrade and stored in a simple database table.

Then, when a grade_added event happens, all the registered functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['grade_updated']['file']);
call_user_func($handlers['grade_updated']['function'], $eventdata);

All plugins in Moodle have access to this and can this easily “hook in” to 'grade_updated' events (and of course any other events).

==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 handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called any time an 'grade_added' event is triggered by a module.

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. 'grade_updated'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /grade/export/lib.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

==Events which exist==

===Users===
* user_updated
* password_changed

===Courses===
* course_updated
* course_deleted
* category_updated
* category_deleted

===Groups===
* group_deleted
* grouping_deleted
* group_user_added
* group_user_removed

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

* user_created (for example to handle custom emails. this is commonly desired: e.g. send a custom email to a related person (teacher, boss, etc.) based on some institution-specific logic)
* user_enrolled_in_course
* user_unenrolled_from_course

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[:Development:Grades]]

[[Category:Events]]
[[Category:Grades]]

Old Events API

2008-04-04T07:20:07Z

Brianking: /* Events wishlist */

The Events API is a new core system in Moodle to allow better communication between modules. It's based on modules triggering new events with attached data, and the other modules handling those events with custom functions.

==Overview==

We'll be using the example of a grade being posted from a module into the [[Grades|new gradebook in Moodle 1.9]], but there are obviously all kinds of events possible.

===Triggering an event===

Whenever a grade is created or changed by a module, it should “tell” the system about it (in addition to any local working storage it uses). So, using the quiz as an example, we first define an object as follows:

$eventdata = new object();
$eventdata->itemid = $grade_item->id;
$eventdata->userid = $USER->id;
$eventdata->gradevalue = $currentvalue;

Then we post the object as an event and forget about it:

events_trigger('grade_updated', $eventdata);

===Handling an event===

Modules can define an events.php in their db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For example, an export plugin could register something like:

$handlers = array (
'grade_updated' => array (
'handlerfile' => '/grade/export/banner/lib.php',
'handlerfunction' => 'banner_handle_grade_test', // argument to call_user_func(), could be an array
'schedule' => 'cron'
)
);
These are parsed during install / upgrade and stored in a simple database table.

Then, when a grade_added event happens, all the registered functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['grade_updated']['file']);
call_user_func($handlers['grade_updated']['function'], $eventdata);

All plugins in Moodle have access to this and can this easily “hook in” to 'grade_updated' events (and of course any other events).

==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 handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called any time an 'grade_added' event is triggered by a module.

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. 'grade_updated'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /grade/export/lib.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

==Events which exist==

===Users===
* user_updated
* password_changed

===Courses===
* course_updated
* course_deleted
* category_updated
* category_deleted

===Groups===
* group_deleted
* grouping_deleted
* group_user_added
* group_user_removed

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

* user_created (for example to handle custom emails. this is commonly desired: e.g. send a custom email to a related person (teacher, boss, etc.) based on some institution-specific logic)
* user_enrolled_in_course

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[:Development:Grades]]

[[Category:Events]]
[[Category:Grades]]

Old Events API

2008-04-03T12:48:01Z

Brianking: /* Standards for naming events */

The Events API is a new core system in Moodle to allow better communication between modules. It's based on modules triggering new events with attached data, and the other modules handling those events with custom functions.

==Overview==

We'll be using the example of a grade being posted from a module into the [[Grades|new gradebook in Moodle 1.9]], but there are obviously all kinds of events possible.

===Triggering an event===

Whenever a grade is created or changed by a module, it should “tell” the system about it (in addition to any local working storage it uses). So, using the quiz as an example, we first define an object as follows:

$eventdata = new object();
$eventdata->itemid = $grade_item->id;
$eventdata->userid = $USER->id;
$eventdata->gradevalue = $currentvalue;

Then we post the object as an event and forget about it:

events_trigger('grade_updated', $eventdata);

===Handling an event===

Modules can define an events.php in their db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For example, an export plugin could register something like:

$handlers = array (
'grade_updated' => array (
'handlerfile' => '/grade/export/banner/lib.php',
'handlerfunction' => 'banner_handle_grade_test', // argument to call_user_func(), could be an array
'schedule' => 'cron'
)
);
These are parsed during install / upgrade and stored in a simple database table.

Then, when a grade_added event happens, all the registered functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['grade_updated']['file']);
call_user_func($handlers['grade_updated']['function'], $eventdata);

All plugins in Moodle have access to this and can this easily “hook in” to 'grade_updated' events (and of course any other events).

==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 handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called any time an 'grade_added' event is triggered by a module.

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. 'grade_updated'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /grade/export/lib.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

==Events which exist==

===Users===
* user_updated
* password_changed

===Courses===
* course_updated
* course_deleted
* category_updated
* category_deleted

===Groups===
* group_deleted
* grouping_deleted
* group_user_added
* group_user_removed

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

* user_created (for example to handle custom emails. this is commonly desired: e.g. send a custom email to a related person (teacher, boss, etc.) based on some institution-specific logic)

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[:Development:Grades]]

[[Category:Events]]
[[Category:Grades]]

MNet

2007-02-06T14:24:50Z

Brianking: /* Key config variables and functions */

{{Moodle 1.8}}

Random notes for Moodle Network. Should get these organised...

* Documentation for administrators is here [[Moodle Network]]
* Some old documentation about the initial planning and dev
** [[Community_hub]]
** [[Community_hub_technotes]]
** [[Community_hub_progress]]

=Key config variables and functions=

// what mnethostid should "local" users have?
// this is guaranteed to be set, except during the 1.7->1.8 upgrade
$id = $CFG->mnet_localhost_id;

// a quick way to check if our user is local
is_mnet_remote_user($user);
// internally wis_mnet_remote_user() does
// if ($user->mnethostid == $CFG->mnet_localhost_id)

// Are we listening to mnet requests? Nothing else works if we aren't.
if ($CFG->mnet_dispatcher_mode === 'strict') {
// Moodle is listening to mnet requests. Nothing else works if we aren't.
}

// Are we allowing remote users in via auth/mnet?
if (is_enabled_auth('mnet')) {
// yes indeed
}

// Will auth/mnet autocreate new user accts?
if (get_config('auth/mnet', 'auto_add_remote_users')) {
// yes it will!
}

=Protocols=

==MNET handshake==

==Authentication/SSO==

==Enrolment==

=To Do=

Some immediate items that would add polish without major surgery

* Exchange more enrolment info at log-entry exchange time on cron
* Special default role
** Add a new "remote student" role
** Add a config var to enrol/mnet: "defaultremoterole" to use "remote student"
** Add a config var to the courses table to optionally override defaultremoterole
* Nicer CSS in the "my courses" listing in moodle homepage for remote hosts and remote courses. See course/lib.php print_remote_course() and print_remote_host().

=Roadmap=

A bit more work, and a whole lot more features. From easy to hard...

* Better per-host stats and log views for administrators. This is relatively easy using data we already have.
* In mod/forum craft a special URL for remote users so that the post URL is in the wantsurl parameter, so they can bounce-off their IDP in one go.
** According to Jonathan Harker, this requires that we modify jump to accept the remote wwwroot as a parameter. Also: will this be safe enough?
* Display aggregated calendar on the IDP
* Exchange grades. Needs a bit of design.
* Build a SCORM/IMSCP/MoodleZip repository scheme.
** MartinL has some ideas on how to get this done in easy and super-scalable.

Mnet Web services API

2007-02-02T11:45:14Z

Brianking: /* Code */

== Overview ==
Please also see the discussion about a simple to use xml-rpc based api at [[Simple web services|simple web services]].

Provide Moodle with a web service interface to allow exchange of data and information with other systems.

Specifically,
# Manage user data - send and retrieve the information,
# Manage course enrolments - add/remove teachers and students,
# Course management - create new courses based on templates,
# Gradebook info - extract grades information from Moodle.

The API will be built in two tiers:
# Generic Moodle web services - This will define the API available to be used by specific protocols.
# Protocol-specific web services - Using the generic services as the parent, define specific interfaces for SOAP, XML-RPC and others.

'''Class Structure:''' 
Base class <code>server.class.php</code>: 
:This class provides most of the necessary functions to authenticate and communicate with Moodle. It also defines the methods that must be implemented by the protocol class. Any web service protocol class must:
:* call the base class constructor (<code>parent::init()</code>),
:* implement the main method (<code>main([$httpdata])</code>),
:* implement the request method (<code>request($input)</code>),
:* implement the reply method (<code>response($request)</code>).

Derived class (e.g. <code>soapserver.class.php</code>).

The driver for the whole operation is through <code>service.php</code>. It takes one argument, <code>type</code>, which contains a string identifying the protocol to use (e.g. 'soap').

So, to call a SOAP based web service: 
<code>http://your.server.org/moodle/ws/server.php?type=soap</code>
The data for the entire operation comes through the POST mechanism.

== Manage User Data ==
These functions will allow the exchange of user data, and account management functions. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Course Enrolments ==
These functions will allow for student, teacher and group management functions within a course. Initial work will use the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lang/en_utf8/help/enrol/imsenterprise/formatoverview.html IMS Enterprise XML] standard for data definition.

== Manage Courses ==
These functions will allow for definition and management of courses. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Grades ==
These functions will allow for information about grades to be exchanged. Initial work will use the IMS Enterprise XML standard for data definition.

== Code ==
The code is available in the contrib/patches/ws directory of cvs.
cvs -z3 -d:pserver:anonymous@moodle.cvs.sourceforge.net:/cvsroot/moodle co contrib/patches/ws

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44079 Web Services in forthcoming Moodle] and [http://moodle.org/mod/forum/discuss.php?d=51752 Proposal: Web Services / API / Refactoring Opportunity] forum discussions

[[Category:Administrator]]

Mnet Web services API

2007-02-02T11:44:46Z

Brianking: /* Code */

== Overview ==
Please also see the discussion about a simple to use xml-rpc based api at [[Simple web services|simple web services]].

Provide Moodle with a web service interface to allow exchange of data and information with other systems.

Specifically,
# Manage user data - send and retrieve the information,
# Manage course enrolments - add/remove teachers and students,
# Course management - create new courses based on templates,
# Gradebook info - extract grades information from Moodle.

The API will be built in two tiers:
# Generic Moodle web services - This will define the API available to be used by specific protocols.
# Protocol-specific web services - Using the generic services as the parent, define specific interfaces for SOAP, XML-RPC and others.

'''Class Structure:''' 
Base class <code>server.class.php</code>: 
:This class provides most of the necessary functions to authenticate and communicate with Moodle. It also defines the methods that must be implemented by the protocol class. Any web service protocol class must:
:* call the base class constructor (<code>parent::init()</code>),
:* implement the main method (<code>main([$httpdata])</code>),
:* implement the request method (<code>request($input)</code>),
:* implement the reply method (<code>response($request)</code>).

Derived class (e.g. <code>soapserver.class.php</code>).

The driver for the whole operation is through <code>service.php</code>. It takes one argument, <code>type</code>, which contains a string identifying the protocol to use (e.g. 'soap').

So, to call a SOAP based web service: 
<code>http://your.server.org/moodle/ws/server.php?type=soap</code>
The data for the entire operation comes through the POST mechanism.

== Manage User Data ==
These functions will allow the exchange of user data, and account management functions. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Course Enrolments ==
These functions will allow for student, teacher and group management functions within a course. Initial work will use the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lang/en_utf8/help/enrol/imsenterprise/formatoverview.html IMS Enterprise XML] standard for data definition.

== Manage Courses ==
These functions will allow for definition and management of courses. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Grades ==
These functions will allow for information about grades to be exchanged. Initial work will use the IMS Enterprise XML standard for data definition.

== Code ==
The code is available in the contrib/patches/ws directory of cvs.
cvs -z3 -d:pserver:anonymous@moodle.cvs.sourceforge.net:/cvsroot/moodle/contrib/patches/ws co contrib/patches/ws

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44079 Web Services in forthcoming Moodle] and [http://moodle.org/mod/forum/discuss.php?d=51752 Proposal: Web Services / API / Refactoring Opportunity] forum discussions

[[Category:Administrator]]

Mnet Web services API

2007-02-02T11:27:06Z

Brianking: /* Code */

== Overview ==
Please also see the discussion about a simple to use xml-rpc based api at [[Simple web services|simple web services]].

Provide Moodle with a web service interface to allow exchange of data and information with other systems.

Specifically,
# Manage user data - send and retrieve the information,
# Manage course enrolments - add/remove teachers and students,
# Course management - create new courses based on templates,
# Gradebook info - extract grades information from Moodle.

The API will be built in two tiers:
# Generic Moodle web services - This will define the API available to be used by specific protocols.
# Protocol-specific web services - Using the generic services as the parent, define specific interfaces for SOAP, XML-RPC and others.

'''Class Structure:''' 
Base class <code>server.class.php</code>: 
:This class provides most of the necessary functions to authenticate and communicate with Moodle. It also defines the methods that must be implemented by the protocol class. Any web service protocol class must:
:* call the base class constructor (<code>parent::init()</code>),
:* implement the main method (<code>main([$httpdata])</code>),
:* implement the request method (<code>request($input)</code>),
:* implement the reply method (<code>response($request)</code>).

Derived class (e.g. <code>soapserver.class.php</code>).

The driver for the whole operation is through <code>service.php</code>. It takes one argument, <code>type</code>, which contains a string identifying the protocol to use (e.g. 'soap').

So, to call a SOAP based web service: 
<code>http://your.server.org/moodle/ws/server.php?type=soap</code>
The data for the entire operation comes through the POST mechanism.

== Manage User Data ==
These functions will allow the exchange of user data, and account management functions. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Course Enrolments ==
These functions will allow for student, teacher and group management functions within a course. Initial work will use the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lang/en_utf8/help/enrol/imsenterprise/formatoverview.html IMS Enterprise XML] standard for data definition.

== Manage Courses ==
These functions will allow for definition and management of courses. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Grades ==
These functions will allow for information about grades to be exchanged. Initial work will use the IMS Enterprise XML standard for data definition.

== Code ==
The code is available in the contrib/patches/ws directory of cvs.

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44079 Web Services in forthcoming Moodle] and [http://moodle.org/mod/forum/discuss.php?d=51752 Proposal: Web Services / API / Refactoring Opportunity] forum discussions

[[Category:Administrator]]

Mnet Web services API

2006-11-15T15:16:55Z

Brianking:

== Overview ==
Please also see the discussion about a simple to use xml-rpc based api at [[Simple web services|simple web services]].

Provide Moodle with a web service interface to allow exchange of data and information with other systems.

Specifically,
# Manage user data - send and retrieve the information,
# Manage course enrolments - add/remove teachers and students,
# Course management - create new courses based on templates,
# Gradebook info - extract grades information from Moodle.

The API will be built in two tiers:
# Generic Moodle web services - This will define the API available to be used by specific protocols.
# Protocol-specific web services - Using the generic services as the parent, define specific interfaces for SOAP, XML-RPC and others.

'''Class Structure:''' 
Base class <code>server.class.php</code>: 
:This class provides most of the necessary functions to authenticate and communicate with Moodle. It also defines the methods that must be implemented by the protocol class. Any web service protocol class must:
:* call the base class constructor (<code>parent::init()</code>),
:* implement the main method (<code>main([$httpdata])</code>),
:* implement the request method (<code>request($input)</code>),
:* implement the reply method (<code>response($request)</code>).

Derived class (e.g. <code>soapserver.class.php</code>).

The driver for the whole operation is through <code>service.php</code>. It takes one argument, <code>type</code>, which contains a string identifying the protocol to use (e.g. 'soap').

So, to call a SOAP based web service: 
<code>http://your.server.org/moodle/ws/server.php?type=soap</code>
The data for the entire operation comes through the POST mechanism.

== Manage User Data ==
These functions will allow the exchange of user data, and account management functions. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Course Enrolments ==
These functions will allow for student, teacher and group management functions within a course. Initial work will use the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lang/en_utf8/help/enrol/imsenterprise/formatoverview.html IMS Enterprise XML] standard for data definition.

== Manage Courses ==
These functions will allow for definition and management of courses. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Grades ==
These functions will allow for information about grades to be exchanged. Initial work will use the IMS Enterprise XML standard for data definition.

== Code ==
The code is available in the contrib/ws directory of cvs.

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44079 Web Services in forthcoming Moodle] and [http://moodle.org/mod/forum/discuss.php?d=51752 Proposal: Web Services / API / Refactoring Opportunity] forum discussions

[[Category:Administrator]]

Mnet Web services API

2006-11-15T15:15:59Z

Brianking: /* Overview */

== Overview ==
Please also see the discussion about a simple to use xml-rpc based api at [[Simple web services|simple web services]].

Provide Moodle with a web service interface to allow exchange of data and information with other systems.

Specifically,
# Manage user data - send and retrieve the information,
# Manage course enrolments - add/remove teachers and students,
# Course management - create new courses based on templates,
# Gradebook info - extract grades information from Moodle.

The API will be built in two tiers:
# Generic Moodle web services - This will define the API available to be used by specific protocols.
# Protocol-specific web services - Using the generic services as the parent, define specific interfaces for SOAP, XML-RPC and others.

'''Class Structure:''' 
Base class <code>server.class.php</code>: 
:This class provides most of the necessary functions to authenticate and communicate with Moodle. It also defines the methods that must be implemented by the protocol class. Any web service protocol class must:
:* call the base class constructor (<code>parent::init()</code>),
:* implement the main method (<code>main([$httpdata])</code>),
:* implement the request method (<code>request($input)</code>),
:* implement the reply method (<code>response($request)</code>).

Derived class (e.g. <code>soapserver.class.php</code>).

The driver for the whole operation is through <code>service.php</code>. It takes one argument, <code>type</code>, which contains a string identifying the protocol to use (e.g. 'soap').

So, to call a SOAP based web service: 
<code>http://your.server.org/moodle/ws/server.php?type=soap</code>
The data for the entire operation comes through the POST mechanism.

== Manage User Data ==
These functions will allow the exchange of user data, and account management functions. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Course Enrolments ==
These functions will allow for student, teacher and group management functions within a course. Initial work will use the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lang/en_utf8/help/enrol/imsenterprise/formatoverview.html IMS Enterprise XML] standard for data definition.

== Manage Courses ==
These functions will allow for definition and management of courses. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Grades ==
These functions will allow for information about grades to be exchanged. Initial work will use the IMS Enterprise XML standard for data definition.

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44079 Web Services in forthcoming Moodle] and [http://moodle.org/mod/forum/discuss.php?d=51752 Proposal: Web Services / API / Refactoring Opportunity] forum discussions

[[Category:Administrator]]

Mnet Web services API

2006-11-15T15:14:17Z

Brianking: /* Overview */

== Overview ==
Provide Moodle with a web service interface to allow exchange of data and information with other systems.

The code is available in the contrib/ws directory of cvs.
Please also see the discussion about a simple to use xml-rpc based api at [[Simple web services|simple web services]].

Specifically,
# Manage user data - send and retrieve the information,
# Manage course enrolments - add/remove teachers and students,
# Course management - create new courses based on templates,
# Gradebook info - extract grades information from Moodle.

The API will be built in two tiers:
# Generic Moodle web services - This will define the API available to be used by specific protocols.
# Protocol-specific web services - Using the generic services as the parent, define specific interfaces for SOAP, XML-RPC and others.

'''Class Structure:''' 
Base class <code>server.class.php</code>: 
:This class provides most of the necessary functions to authenticate and communicate with Moodle. It also defines the methods that must be implemented by the protocol class. Any web service protocol class must:
:* call the base class constructor (<code>parent::init()</code>),
:* implement the main method (<code>main([$httpdata])</code>),
:* implement the request method (<code>request($input)</code>),
:* implement the reply method (<code>response($request)</code>).

Derived class (e.g. <code>soapserver.class.php</code>).

The driver for the whole operation is through <code>service.php</code>. It takes one argument, <code>type</code>, which contains a string identifying the protocol to use (e.g. 'soap').

So, to call a SOAP based web service: 
<code>http://your.server.org/moodle/ws/server.php?type=soap</code>
The data for the entire operation comes through the POST mechanism.

== Manage User Data ==
These functions will allow the exchange of user data, and account management functions. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Course Enrolments ==
These functions will allow for student, teacher and group management functions within a course. Initial work will use the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lang/en_utf8/help/enrol/imsenterprise/formatoverview.html IMS Enterprise XML] standard for data definition.

== Manage Courses ==
These functions will allow for definition and management of courses. Initial work will use the IMS Enterprise XML standard for data definition.

== Manage Grades ==
These functions will allow for information about grades to be exchanged. Initial work will use the IMS Enterprise XML standard for data definition.

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44079 Web Services in forthcoming Moodle] and [http://moodle.org/mod/forum/discuss.php?d=51752 Proposal: Web Services / API / Refactoring Opportunity] forum discussions

[[Category:Administrator]]

Enrolment plugins

2006-09-12T16:55:47Z

Brianking: /* Testing paypal using the paypal developer sandbox (for moodle 1.6) */

{{stub}}
==Testing paypal using the paypal developer sandbox==
(for moodle 1.4 - 1.6)
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)

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]

Enrolment plugins

2006-09-12T15:21:21Z

Brianking: /* Testing paypal using the paypal developer sandbox (for moodle 1.6) */

{{stub}}
==Testing paypal using the paypal developer sandbox (for moodle 1.6)==

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)

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]

Enrolment plugins

2006-09-12T14:46:37Z

Brianking: /* Testing paypal using the paypal developer sandbox (for moodle 1.6) */

{{stub}}
==Testing paypal using the paypal developer sandbox (for moodle 1.6)==
* 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)

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]

Enrolment plugins

2006-09-12T14:46:18Z

Brianking: /* Testing paypal using the paypal developer sandbox (for moodle 1.6) */

{{stub}}
==Testing paypal using the paypal developer sandbox (for moodle 1.6)==
* 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)

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]

Enrolment plugins

2006-09-12T14:45:53Z

Brianking: /* See also */

{{stub}}
==Testing paypal using the paypal developer sandbox (for moodle 1.6)==
* 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)

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]