https://docs.moodle.org/dev/api.php?action=feedcontributions&feedformat=atom&user=NakohdoMoodleDocs - User contributions [en]2026-08-06T17:05:56ZUser contributionsMediaWiki 1.43.5https://docs.moodle.org/dev/index.php?title=Filters&diff=42634Filters2013-10-16T10:03:28Z<p>Nakohdo: /* Trying out your filter */ corrected typo</p>
<hr />
<div><p class="note">'''Please note:''' This page contains information for developers. You may prefer to read the [[:en:Filters| information about filters for teachers and administrators]].</p><br />
<br />
{{Moodle 2.0}}<br />
<br />
<br />
'''Filters''' are a way to automatically transform content before it is output. For example<br />
* render embedded equations to images (the TeX filter)<br />
* Links to media files can be automatically converted to an embedded applet for playing the media.<br />
* Mentions of glossary terms can be automatically converted to links.<br />
The possibilities are endless. There are a number of standard filters included with Moodle, or you can create your own. Filters are one of the easiest types of plugin to create. This page explains how.<br />
<br />
==Before you start==<br />
<br />
Go to Site administration ▶ Plugins ▶ Filters ▶ Common filter settings and set Text cache lifetime to 0 ("No") while you do development. Otherwise, you will not be able to see the effects of your changes when you edit your filter's code. (You should also be using the other common developer settings, like developer debug, theme designer mode and so on.)<br />
<br />
==Creating a basic filter==<br />
<br />
During this tutorial, we will build a simple example filter. We will make one that adds the word 'hello' before every occurrence of the word 'world'.<br />
<br />
1. Since our filter is not part of a module, we should put it inside the 'filter' folder. Therefore, we create a directory called 'filter/helloworld'.<br />
<br />
2. Inside that folder, we create a file called 'filter.php'.<br />
<br />
3. Inside that PHP file, we define a class called filter_helloworld, that extends the moodle_text_filter class.<br />
<code php><br />
<?php<br />
class filter_helloworld extends moodle_text_filter {<br />
// ...<br />
}<br />
?><br />
</code><br />
<br />
4. Inside that class, we have to define one method, called 'filter'. This takes the HTML to be filtered as an argument. The method should then transform that, and return the processed text. Replace the '// ...' above with<br />
<code php><br />
class filter_helloworld extends moodle_text_filter {<br />
public function filter($text, array $options = array()) {<br />
return str_replace('world', 'hello world!', $text);<br />
}<br />
}<br />
</code><br />
<br />
That is basically all there is to it!<br />
<br />
==Giving your filter a name==<br />
<br />
To try the new filter, you first have to log in as Administrator and enable it by going to the page Administration ► Plugins ► Filters ► Manage filters.<br />
<br />
When you do, you will find that your plugin does not have a name. We missed a step:<br />
<br />
5. Inside the 'filter/helloworld' folder, create a folder called 'lang', and in there, create a folder called 'en'.<br />
<br />
6. Inside there, create a file called 'filter_helloworld.php'. That is, you have just created the file 'filter/helloworld/lang/en/filter_helloworld.php'.<br />
<br />
7. In that file, put<br />
<code php><br />
<?php // $Id$<br />
// Language string for filter/helloworld.<br />
<br />
$string['filtername'] = 'Hello world!';<br />
</code><br />
<br />
That may seem a little involved, just to give your filter a name, but it is just [[Places_to_search_for_lang_strings|the standard way Moodle stores language strings for plugins]].<br />
<br />
==Trying out your filter==<br />
<br />
We had just got to the [[Filters|filters administration screen]]. If you reload that page now, it should now show your filter with its proper name. Turn your filter on now.<br />
<br />
Filters are applied to all text that is printed with the [[Output functions|output functions]] format_text(), and, if you have turned on that option, format_string(). So, to see your filter in action, add some content containing the word 'world' somewhere, for example, create a test course, and use the word in the course description. When you look at that course in the course listing, you should see that your filter has transformed it.<br />
<br />
==Adding a global settings screen==<br />
<br />
Some filters can benefit from some settings to let the administrator control how they work. Suppose we want to greet something other than 'world'. To add global settings to the filter you need to:<br />
<br />
8. Create a file called 'filtersettings.php' inside the 'filter/helloworld' folder. Use standard 'settings.php' file in Moodle 2.6 and later.<br />
<br />
9. In the 'filtersettings.php' file, put something like:<br />
<code php><br />
$settings->add(new admin_setting_configtext('filter_helloworld_word',<br />
get_string('word', 'filter_helloworld'),<br />
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));<br />
</code><br />
<br />
10. In the language file 'filter/helloworld/lang/en/filter_helloworld.php' add the necessary strings:<br />
<code php><br />
$string['word'] = 'The thing to greet';<br />
$string['word_desc'] = 'The hello world filter will add the word \'hello\' in front of every occurrence of this word in any content.';<br />
</code><br />
<br />
11. Change the filter to use the new setting:<br />
<code php><br />
class filter_helloworld extends moodle_text_filter {<br />
public function filter($text, array $options = array()) {<br />
global $CFG;<br />
return str_replace($CFG->filter_helloworld_word,<br />
"hello $CFG->filter_helloworld_word!", $text);<br />
}<br />
}<br />
</code><br />
<br />
In standard Moodle, the censor, mediaplugin and tex filters all provide good examples of of how filters use global configuration like this.<br />
<br />
==A note about performance==<br />
<br />
One important thing to remember when creating a filter is that the filter will be called to transform every bit of text output using format_text(), and possibly also format_string(). That means that you have to be careful, or you could cause big performance problems. If you have to get data out of the database, try to cache it so that you only do a fixed number of database queries per page load. The Glossary filter is an example of this. (I am not sure how good an example ;-))<br />
<br />
==Local configuration==<br />
<br />
In addition, in Moodle 2.0, filters can also have different configuration in each context. For example, the glossary could be changes so that in Forum A, you can choose to only link words from a particular glossary, sat Glossary A, while in Forum B you choose to link words from Glossary B.<br />
<br />
To do that sort of thing, you need to add a file called filterlocalsettings.php. In it, you must define a [[lib/formslib.php|Moodle form]] that is a subclass of filter_local_settings_form. In addition to the standard formslib methods, you also need to define a save_changes method. There is not a good example of this in the standard Moodle install yet. To continue our example:<br />
<br />
12. Create a file called 'filterlocalsettings.php' inside the 'filter/helloworld' folder.<br />
<br />
13. In the 'filterlocalsettings.php' file, put:<br />
<code php><br />
class helloworld_filter_local_settings_form extends filter_local_settings_form {<br />
protected function definition_inner($mform) {<br />
$mform->addElement('text', 'word', get_string('word', 'filter_helloworld'), array('size' => 20));<br />
$mform->setType('word', PARAM_NOTAGS);<br />
}<br />
}<br />
?><br />
</code><br />
<br />
14. Extend the filter to use the new setting, if it is present. The filter must be able to work if the setting is not set, for example by falling back to the global or default setting in this case<br />
<code php><br />
<?php<br />
class filter_helloworld extends moodle_text_filter {<br />
public function filter($text, array $options = array()) {<br />
global $CFG;<br />
if (isset($this->localconfig['word'])) {<br />
$word = $this->localconfig['word'];<br />
} else {<br />
$word = $CFG->filter_helloworld_word;<br />
}<br />
return str_replace($word, "hello $word!", $text);<br />
}<br />
}<br />
?><br />
</code><br />
<br />
==Two types of filter==<br />
<br />
In the past, Moodle supported two different types of filter:<br />
* Stand-alone filters like the one we created above. These live in a folder inside the 'filter' folder. For example, in 'filter/myfilter'. 'filter/tex' is an example of a core filter of this type.<br />
* Filters that were part of an activity module. In this case, the filter code lives inside the 'mod/mymod' folder. 'mod/glossary' used to be an example of a core module with a filter.<br />
The second option no longer exists. All filters live in the filter folder. Of course, a filter may depend on an associated other plugin, like mod_glossary. If so, you should declare that in the [[version.php]] file.<br />
<br />
==See also==<br />
<br />
* [[Filters]] how to write filters for Moodle 1.9 and before. Note that a Moodle 1.9 filter will still work in Moodle 2.0, but you should still update your code when you get the chance.<br />
* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system<br />
* [[Filters 2.0]] - user documentation about filters.<br />
* [https://moodle.org/plugins/browse.php?list=category&id=7 - List of filters in the Plugins database].<br />
<br />
[[Category:Filters]]<br />
[[Category:Filter]]<br />
<br />
[[Category:Plugins]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Filters&diff=42633Filters2013-10-16T10:01:32Z<p>Nakohdo: /* Before you start */</p>
<hr />
<div><p class="note">'''Please note:''' This page contains information for developers. You may prefer to read the [[:en:Filters| information about filters for teachers and administrators]].</p><br />
<br />
{{Moodle 2.0}}<br />
<br />
<br />
'''Filters''' are a way to automatically transform content before it is output. For example<br />
* render embedded equations to images (the TeX filter)<br />
* Links to media files can be automatically converted to an embedded applet for playing the media.<br />
* Mentions of glossary terms can be automatically converted to links.<br />
The possibilities are endless. There are a number of standard filters included with Moodle, or you can create your own. Filters are one of the easiest types of plugin to create. This page explains how.<br />
<br />
==Before you start==<br />
<br />
Go to Site administration ▶ Plugins ▶ Filters ▶ Common filter settings and set Text cache lifetime to 0 ("No") while you do development. Otherwise, you will not be able to see the effects of your changes when you edit your filter's code. (You should also be using the other common developer settings, like developer debug, theme designer mode and so on.)<br />
<br />
==Creating a basic filter==<br />
<br />
During this tutorial, we will build a simple example filter. We will make one that adds the word 'hello' before every occurrence of the word 'world'.<br />
<br />
1. Since our filter is not part of a module, we should put it inside the 'filter' folder. Therefore, we create a directory called 'filter/helloworld'.<br />
<br />
2. Inside that folder, we create a file called 'filter.php'.<br />
<br />
3. Inside that PHP file, we define a class called filter_helloworld, that extends the moodle_text_filter class.<br />
<code php><br />
<?php<br />
class filter_helloworld extends moodle_text_filter {<br />
// ...<br />
}<br />
?><br />
</code><br />
<br />
4. Inside that class, we have to define one method, called 'filter'. This takes the HTML to be filtered as an argument. The method should then transform that, and return the processed text. Replace the '// ...' above with<br />
<code php><br />
class filter_helloworld extends moodle_text_filter {<br />
public function filter($text, array $options = array()) {<br />
return str_replace('world', 'hello world!', $text);<br />
}<br />
}<br />
</code><br />
<br />
That is basically all there is to it!<br />
<br />
==Giving your filter a name==<br />
<br />
To try the new filter, you first have to log in as Administrator and enable it by going to the page Administration ► Plugins ► Filters ► Manage filters.<br />
<br />
When you do, you will find that your plugin does not have a name. We missed a step:<br />
<br />
5. Inside the 'filter/helloworld' folder, create a folder called 'lang', and in there, create a folder called 'en'.<br />
<br />
6. Inside there, create a file called 'filter_helloworld.php'. That is, you have just created the file 'filter/helloworld/lang/en/filter_helloworld.php'.<br />
<br />
7. In that file, put<br />
<code php><br />
<?php // $Id$<br />
// Language string for filter/helloworld.<br />
<br />
$string['filtername'] = 'Hello world!';<br />
</code><br />
<br />
That may seem a little involved, just to give your filter a name, but it is just [[Places_to_search_for_lang_strings|the standard way Moodle stores language strings for plugins]].<br />
<br />
==Trying out your filter==<br />
<br />
We had just got to the [[Filters|filters administration screen]]. If you reload that page now, it should now show your filter with its proper name. Turn your filter on now.<br />
<br />
Filters are applied to all text that is printed with the [[Output functions|output functions]] format_text(), and, if you have turned on that option, format_string(). So, to see your filter in action, add some content containing the work 'world' somewhere, for example, create a test course, and use the work in the course description. When you look at that course in the course listing, you should see that your filter has transformed it.<br />
<br />
==Adding a global settings screen==<br />
<br />
Some filters can benefit from some settings to let the administrator control how they work. Suppose we want to greet something other than 'world'. To add global settings to the filter you need to:<br />
<br />
8. Create a file called 'filtersettings.php' inside the 'filter/helloworld' folder. Use standard 'settings.php' file in Moodle 2.6 and later.<br />
<br />
9. In the 'filtersettings.php' file, put something like:<br />
<code php><br />
$settings->add(new admin_setting_configtext('filter_helloworld_word',<br />
get_string('word', 'filter_helloworld'),<br />
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));<br />
</code><br />
<br />
10. In the language file 'filter/helloworld/lang/en/filter_helloworld.php' add the necessary strings:<br />
<code php><br />
$string['word'] = 'The thing to greet';<br />
$string['word_desc'] = 'The hello world filter will add the word \'hello\' in front of every occurrence of this word in any content.';<br />
</code><br />
<br />
11. Change the filter to use the new setting:<br />
<code php><br />
class filter_helloworld extends moodle_text_filter {<br />
public function filter($text, array $options = array()) {<br />
global $CFG;<br />
return str_replace($CFG->filter_helloworld_word,<br />
"hello $CFG->filter_helloworld_word!", $text);<br />
}<br />
}<br />
</code><br />
<br />
In standard Moodle, the censor, mediaplugin and tex filters all provide good examples of of how filters use global configuration like this.<br />
<br />
==A note about performance==<br />
<br />
One important thing to remember when creating a filter is that the filter will be called to transform every bit of text output using format_text(), and possibly also format_string(). That means that you have to be careful, or you could cause big performance problems. If you have to get data out of the database, try to cache it so that you only do a fixed number of database queries per page load. The Glossary filter is an example of this. (I am not sure how good an example ;-))<br />
<br />
==Local configuration==<br />
<br />
In addition, in Moodle 2.0, filters can also have different configuration in each context. For example, the glossary could be changes so that in Forum A, you can choose to only link words from a particular glossary, sat Glossary A, while in Forum B you choose to link words from Glossary B.<br />
<br />
To do that sort of thing, you need to add a file called filterlocalsettings.php. In it, you must define a [[lib/formslib.php|Moodle form]] that is a subclass of filter_local_settings_form. In addition to the standard formslib methods, you also need to define a save_changes method. There is not a good example of this in the standard Moodle install yet. To continue our example:<br />
<br />
12. Create a file called 'filterlocalsettings.php' inside the 'filter/helloworld' folder.<br />
<br />
13. In the 'filterlocalsettings.php' file, put:<br />
<code php><br />
class helloworld_filter_local_settings_form extends filter_local_settings_form {<br />
protected function definition_inner($mform) {<br />
$mform->addElement('text', 'word', get_string('word', 'filter_helloworld'), array('size' => 20));<br />
$mform->setType('word', PARAM_NOTAGS);<br />
}<br />
}<br />
?><br />
</code><br />
<br />
14. Extend the filter to use the new setting, if it is present. The filter must be able to work if the setting is not set, for example by falling back to the global or default setting in this case<br />
<code php><br />
<?php<br />
class filter_helloworld extends moodle_text_filter {<br />
public function filter($text, array $options = array()) {<br />
global $CFG;<br />
if (isset($this->localconfig['word'])) {<br />
$word = $this->localconfig['word'];<br />
} else {<br />
$word = $CFG->filter_helloworld_word;<br />
}<br />
return str_replace($word, "hello $word!", $text);<br />
}<br />
}<br />
?><br />
</code><br />
<br />
==Two types of filter==<br />
<br />
In the past, Moodle supported two different types of filter:<br />
* Stand-alone filters like the one we created above. These live in a folder inside the 'filter' folder. For example, in 'filter/myfilter'. 'filter/tex' is an example of a core filter of this type.<br />
* Filters that were part of an activity module. In this case, the filter code lives inside the 'mod/mymod' folder. 'mod/glossary' used to be an example of a core module with a filter.<br />
The second option no longer exists. All filters live in the filter folder. Of course, a filter may depend on an associated other plugin, like mod_glossary. If so, you should declare that in the [[version.php]] file.<br />
<br />
==See also==<br />
<br />
* [[Filters]] how to write filters for Moodle 1.9 and before. Note that a Moodle 1.9 filter will still work in Moodle 2.0, but you should still update your code when you get the chance.<br />
* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system<br />
* [[Filters 2.0]] - user documentation about filters.<br />
* [https://moodle.org/plugins/browse.php?list=category&id=7 - List of filters in the Plugins database].<br />
<br />
[[Category:Filters]]<br />
[[Category:Filter]]<br />
<br />
[[Category:Plugins]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42563FirePHP2013-10-14T16:03:10Z<p>Nakohdo: /* Moodle resources */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
== What is FirePHP? ==<br />
[http://www.firephp.org/ FirePHP] enables you to log to your Firebug Console using a simple PHP method call. <br />
<br />
== FirePHP block for Moodle ==<br />
* There's a [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] in the works. <br />
* The block will soon be available in the Moodle Plugin Directory: https://moodle.org/plugins/view.php?plugin=block_firephp<br />
<br />
== Moodle resources == <br />
* [https://moodle.org/mod/forum/discuss.php?d=119961 Moodle General developer forum: FirePHP plugin] - where everything started.<br />
* The plugin in the [https://moodle.org/mod/data/view.php?d=13&rid=4793 old plugin database]<br />
* Related tracker issue: MDL-16371<br />
* Current code on [https://moodle.org/mod/data/view.php?d=13&rid=4793 GitHub]<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]<br />
<br />
<br />
[[Category:Developer tools|Firebug]]<br />
[[Category:Firefox extensions|Firebug]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Repository_plugins&diff=42561Repository plugins2013-10-14T15:56:14Z<p>Nakohdo: /* Quick Start */</p>
<hr />
<div>{{Repository plugins}}<br />
== Introduction ==<br />
<br />
Repository plugin allow Moodle to bring contents into Moodle from external repositories.<br />
<br />
===Prerequisites===<br />
Before starting coding, it is necessary to know how to use repository administration pages and how to use the file picker.<br />
<br />
===Overview===<br />
<br />
The 3 different parts to write<br />
# Administration - You can customise the way administrators and users can configure their repositories. <br />
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.<br />
# I18n - Internationalization should be done at the same time as you're writing the other parts.<br />
<br />
== History ==<br />
<br />
Repository plugins exists from 2.0<br />
<br />
== Example ==<br />
*[[Box.net Repository Plugin|Box.net Repository Plugin]]<br />
*[[Flickr Repository Plugin|Flickr Repository Plugin]]<br />
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]<br />
<br />
==Creating new repository plugin==<br />
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''<br />
# Create the following files in your plugin folder:<br />
#* ''/repository/myplugin/lib.php''<br />
#* ''/repository/myplugin/pix/icon.png'' - the icon displayed in the file picker (16x16)<br />
#* ''/repository/myplugin/[[version.php]]''<br />
#* ''/repository/myplugin/lang/en/repository_myplugin.php'' - language file<br />
#* ''/repository/myplugin/db/access.php''<br />
# Declare class '''repository_myplugin extends repository''' in your lib.php<br />
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''<br />
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file<br />
# Add capability 'repository/myplugin:view' to your access.php file<br />
# Create install and upgrade scripts (optional or you can do it later)<br />
# Login as admin on your website and run upgrade<br />
# Open Site Administration->Plugins->Repositories->Manage Repositories and make your repository 'Enabled and visible'<br />
<br />
For a more detailed explanation of each of each of the files that have been created here, along with code examples, see [[Repository plugin files]].<br />
<br />
==Administration APIs==<br />
<br />
===Fixed settings===<br />
<br />
These are settings that are hard-coded into your repository plugin and can only be updated by changing the plugin code.<br />
<br />
====supported_returntypes()====<br />
Return any combination of the following values:<br />
* FILE_INTERNAL - the file is uploaded/downloaded and stored directly within the Moodle file system<br />
* FILE_EXTERNAL - the file stays in the external repository and is accessed from there directly<br />
* FILE_REFERENCE - the file may be cached locally, but is automatically synchronised, as required, with any changes to the external original<br />
The type used by Moodle depends on the choices made by the end user (e.g. inserting a link, will result in 'FILE_EXTERNAL'-related functions being used, using a 'shortcut/alias' will result in the 'FILE_REFERENCE'-related functions being used).<br />
<code php><br />
function supported_returntypes() {<br />
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;<br />
}<br />
</code><br />
<br />
====supported_filetypes()====<br />
Optional. Returns '*' for all file types (default implementation), or an array of types or groups (e.g. array('text/plain', 'image/gif', 'web_image') )<br />
<code php><br />
function supported_filetypes() {<br />
//return '*';<br />
//return array('image/gif', 'image/jpeg', 'image/png');<br />
return array('web_image');<br />
}<br />
</code><br />
For a full list of possible types and groups, look in lib/filelib.php, function get_mimetypes_array().<br />
<br />
===Global settings===<br />
<br />
These are settings that are configured for the whole Moodle site and not per instance of your plugin. All of these are optional, without them there will be no configuration options in the Site administration > Plugins > Repositories > Myplugin page.<br />
<br />
====get_type_option_names()====<br />
''This function must be declared static''<br><br />
Optional. Return an array of string. These strings are setting names. These settings are shared by all instances.<br />
Parent function returns an empty array.<br />
<br />
For example:<br />
<code php><br />
public static function get_type_option_names() {<br />
return array_merge(parent::get_type_option_names(), array('rootpath'));<br />
}<br />
</code><br />
<br />
====type_config_form($mform, $classname='repository')====<br />
Optional. This is for modifying the Moodle form displaying the plugin settings. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.<br />
<br />
For example, to display the standard repository plugin settings along with the custom ones use:<br />
<code php><br />
public function type_config_form($mform) {<br />
parent::type_config_form($mform);<br />
<br />
$rootpath = get_config('repository_someplugin', 'rootpath');<br />
$mform->addElement('text', 'rootpath', get_string('rootpath', 'repository_someplugin'), array('size' => '40'));<br />
$mform->setDefault('rootpath', $rootpath);<br />
}<br />
</code><br />
<br />
====type_form_validation($mform, $data, $errors)====<br />
Optional. Use this function if you need to validate some variables submitted by plugin settings form. To use it, check through the associative array of data provided ('settingname' => value) for any errors. Then push the items to $error array in the format ("fieldname" => "human readable error message") to have them highlighted in the form.<br />
<br />
With the example above, this function may look like:<br />
<code php><br />
public static function type_form_validation($mform, $data, $errors) {<br />
if (!is_dir($data['rootpath'])) {<br />
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');<br />
}<br />
return $errors;<br />
}<br />
</code><br />
<br />
===Instance settings===<br />
These functions relate to a specific instance of your plugin (e.g. the URL and login details to access a specific webdav repository). All of these are optional, without them, the instance settings form will only contain a single 'name' field.<br />
<br />
==== get_instance_option_names()====<br />
''This function must be declared static''<br><br />
Optional. Return an array of strings. These strings are setting names. These settings are specific to an instance.<br />
If the function returns an empty array, the API will consider that the plugin displays only one repository in the file picker.<br />
Parent function returns an empty array. This is equivalent to ''get_type_option_names()'', but for a specific instance.<br />
<code php><br />
public static function get_instance_option_names() {<br />
return array('fs_path'); // From repository_filesystem<br />
}<br />
</code><br />
<br />
====instance_config_form($mform)====<br />
Optional. This is for modifying the Moodle form displaying the settings specific to an instance. This is equivalent to ''type_config_form($mform, $classname)'' but for instances. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.<br />
<br />
For example, to add a required text box called email_address:<br />
<code php><br />
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));<br />
$mform->addRule('email_address', $strrequired, 'required', null, 'client');<br />
</code><br />
<br />
''Note: ''mform'' has by default a name text box (cannot be removed).''<br />
<br />
Parent function does nothing.<br />
<br />
====instance_form_validation($mform, $data, $errors)====<br />
Optional. This allows us to validate what has been submitted in the instance configuration form. This is equivalent to ''type_form_validation($mform, $data, $errors), but for instances. For example:<br />
<code php><br />
public static function instance_form_validation($mform, $data, $errors) {<br />
if (empty($data['email_address'])) {<br />
$errors['email_address'] = get_string('invalidemailsettingname', 'repository_flickr_public');<br />
}<br />
return $errors;<br />
}<br />
</code><br />
<br />
====Getting / updating settings====<br />
<br />
Both global and instance settings can be retrieved, from within the plugin, via $this->get_option('settingname') and updated via $this->set_option(array('settingname' => 'value')).<br />
<br />
====plugin_init()====<br />
''This function must be declared static''<br><br />
Optional. This function is called when the administrator adds the plugin. So unless the administrator deletes the plugin and re-adds it, it should be called only once.<br />
Parent function does nothing.<br />
<br />
===Example of using the settings===<br />
<br />
As an example, let's create a Flickr plugin for accessing a public flickr account. The plugin will be called "Flickr Public".<br />
<br />
Firstly the skeleton:<br />
<br />
<code php><br />
<?php<br />
/**<br />
* repository_flickr_public class<br />
* Moodle user can access public flickr account<br />
*<br />
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License<br />
*/<br />
class repository_flickr_public extends repository {<br />
}<br />
</code><br />
<br />
Then consider the question "What does my plugin do?"<br />
<br />
In the Moodle file picker, we want to display some flickr public repositories directly linked to a flickr public account. For example ''My Public Flickr Pictures'', and also ''My Friend's Flickr Pictures''. When the user clicks on one of these repositories, the public pictures are displayed in the file picker.<br />
<br />
In order to access to a flickr public account, the plugin needs to know the email address of the Flickr public account owner. So the administrator will need to set an email address for every repository. Let's add an "email address" setting to every repository.<br />
<br />
<code php><br />
//We tell the API that the repositories have specific settings: "email address"<br />
public static function get_instance_option_names() {<br />
return array('email_address');<br />
}<br />
<br />
//We add an "email address" text box to the create/edit repository instance Moodle form<br />
public function instance_config_form($mform) {<br />
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));<br />
$mform->addRule('email_address', get_string('required'), 'required', null, 'client');<br />
}<br />
</code><br />
<br />
So at this moment all our Flickr Public Repositories will have a specific email address. However this is not enough. In order to communicate with Flickr, Moodle needs to know a Flickr API key (http://www.flickr.com/services/api/). This API key is the same for any repository. We could add it with the email address setting but the administrator would have to enter the same API key for every repository. Hopefully the administrator can add settings to the plugin level, impacting all repositories. The code is similar the repository instance settings:<br />
<code php><br />
//We tell the API that the repositories have general settings: "api_key"<br />
public static function get_type_option_names() {<br />
return array('api_key');<br />
}<br />
<br />
//We add an "api key" text box to the create/edit repository plugin Moodle form (also called a Repository type Moodle form)<br />
public function type_config_form($mform) {<br />
//the following line is needed in order to retrieve the API key value from the database when Moodle displays the edit form<br />
$api_key = get_config('flickr_public', 'api_key');<br />
$mform->addElement('text', 'api_key', get_string('apikey', 'repository_flickr_public'), <br />
array('value'=>$api_key,'size' => '40'));<br />
$mform->addRule('api_key', get_string('required'), 'required', null, 'client');<br />
}<br />
</code><br />
<br />
Have we finished yet?<br />
<br />
Yes! We have created everything necessary for the administration pages. But let's go further. It would be good if the user can enter any "Flickr public account email address" in the file picker. In fact we want to display in the file picker a Flickr Public repository that the Moodle administrator can never delete. Let's add:<br />
<br />
<code php><br />
//this function is only called one time, when the Moodle administrator add the Flickr Public Plugin into the Moodle site.<br />
public static function plugin_init() {<br />
//here we create a default repository instance. The last parameter is 1 in order to set the instance as readonly.<br />
repository::static_function('flickr_public','create', 'flickr_public', 0, get_system_context(), <br />
array('name' => 'default instance','email_address' => null),1);<br />
}<br />
</code><br />
<br />
That's all - the administration part of our Flickr Public plugin is done. For your information, Box.net, Flickr, and Flickr Public all have similar administration APIs.<br />
<br />
==Repository APIs==<br />
=== Quick Start ===<br />
First of all, the File Picker using intensively Ajax you will need a easy way to debug. Install [[FirePHP]] (MDL-16371) and make it works. It will save you a lot of time. (You might give the [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] a try, it's still work in progress, though.)<br />
<br />
* Your first question when you write your plugin specification is 'Does the user need to log-in'? If they do, in your plugin you have to detect user session in constructor() function, and use print_login() if required, see more details below.<br />
* For most of plugins, you need to establish a connection with the remote repository. This connection can be done into the get_listing(), constructor() function, see more details below.<br />
* You wanna retrieve the file that the user selected, rewrite get_file() if required, see more details below.<br />
* Optional question that you should ask yourself is 'Does the user can execute a search', if they do, you will have to rewrite search() method, see more details below.<br />
<br />
===Functions you *MUST* override===<br />
<br />
These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.<br />
<br />
====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====<br />
Should be overridden to do any initialisation required by the repository, including:<br />
* logging in via optional_param, if required - see 'print_login', below<br />
* getting any options from the database<br />
<br />
The possible items in the $options array are:<br />
* 'ajax' - bool, true if the user is using the AJAX filepicker<br />
* 'mimetypes' - array of accepted mime types, or '*' for all types<br />
<br />
Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:<br />
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)<br />
* $this->context - the context in which the repository instance can be found<br />
* $this->instance - the repository instance record (from mdl_repository_instances)<br />
* $this->readonly - whether or not the settings can be changed<br />
* $this->options - the above options, combined with the settings saved in the database<br />
* $this->name - as specified by $this->get_name()<br />
* $this->returntypes - as specified by $this->supported_returntypes()<br />
<br />
====get_listing($path="", $page="")====<br />
This function will return a list of files to be displayed to the user, the list must be a array like this:<br />
<code php><br />
$list = array(<br />
//this will be used to build navigation bar<br />
'path'=>array(array('name'=>'root','path'=>'/'), array('name'=>'subfolder', 'path'=>'/subfolder')),<br />
'manage'=>'http://webmgr.moodle.com',<br />
'list'=> array(<br />
array('title'=>'filename1', 'date'=>'1340002147', 'size'=>'10451213', 'source'=>'http://www.moodle.com/dl.rar'),<br />
array('title'=>'folder', 'date'=>'1340002147', 'size'=>'0', 'children'=>array())<br />
)<br />
);<br />
</code><br />
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.<br />
<br />
'''The full specification of list element:'''<br />
<code php><br />
array(<br />
// 'path' is used to build navegation bar to show the current folder, so you need to include all parents folders<br />
// array(array('name'=>'root','path'=>'/'), array('name'=>'subfolder', 'path'=>'/subfolder'))<br />
// This will result in: /root/subfolder as current directory<br />
'path' => (array) this will be used to build navigation bar<br />
// 'dynload' tells file picker to fetch list dynamically.<br />
// When user clicks the folder, it will send a ajax request to server side.<br />
// Default value is false but note that non-Javascript file picker always acts as if dynload was set to true<br />
'dynload' => (bool) use dynamic loading,<br />
// if you are using pagination, 'page' and 'pages' parameters should be set.<br />
// It is not recommended to use pagination and subfolders at the same time, the tree view mode can not handle it correctly<br />
'page' => (int) which page is this list<br />
'pages' => (int) how many pages. If number of pages is unknown but we know that the next page exists repository may return -1<br />
'manage' => (string) url to file manager for the external repository, if specified will display link in file picker<br />
'help' => (string) url to the help window, if specified will display link in file picker<br />
'nologin' => (bool) requires login, default false, if set to true the login link will be removed from file picker<br />
'norefresh' => (bool) no refresh button, default false<br />
'logouttext' => (string) in case of nologin=false can substitute the text 'Logout' for logout link in file picker<br />
'nosearch' => (bool) no search link, default false, if set to true the search link will be removed from file picker<br />
'issearchresult' => (bool) tells that this listing is the result of search<br />
// for repositories that actually upload a file: set 'upload' option to display an upload form in file picker<br />
'upload' => array( // upload manager<br />
'label' => (string) label of the form element,<br />
'id' => (string) id of the form element<br />
),<br />
// 'list' is used by file picker to build a file/folder tree<br />
'list' => array(<br />
array( // file<br />
'title' => (string) file name,<br />
'shorttitle' => (string) optional, if you prefer to display a short title<br />
'date' => (int) UNIX timestamp, default value for datemodified and datecreated,<br />
'datemodified' => (int) UNIX timestamp when the file was last modified [2.3+],<br />
'datecreated' => (int) UNIX timestamp when the file was last created [2.3+],<br />
'size' => (int) file size in bytes,<br />
'thumbnail' => (string) url to thumbnail for the file,<br />
'thumbnail_width' => (int) the width of the thumbnail image,<br />
'thumbnail_height' => (int) the height of the thumbnail image,<br />
'source' => plugin-dependent unique path to the file (id, url, path, etc.),<br />
'url' => the accessible url of file,<br />
'icon' => (string) url to icon of the image (24x24px), if omitted the moodle filetype icon will be used [2.3+],<br />
'realthumbnail' => (string) url to image preview to be lazy-loaded when scrolled to it (if it requires to be generated and can not be returned as 'thumbnail') [2.3+],<br />
'realicon' => (string) url to image preview in icon size (24x24) [2.3+],<br />
'author' => (string) default value for file author,<br />
'license' => (string) default value for license (short name, see class license_manager),<br />
'image_height' => (int) if the file is an image, image height in pixels, null otherwise [2.3+],<br />
'image_width' => (int) if the file is an image, image width in pixels, null otherwise [2.3+]<br />
),<br />
array( // folder - similar to file, has also 'path' and 'children' but no 'source' or 'url'<br />
'title' => (string) folder name,<br />
'shorttitle' => (string) optional, if you prefer to display a short title<br />
'path' => (string) path to this folder. In case of dynload=true (and for non-JS filepicker) the value will be passed to repository_xxx::get_listing() in order to retrieve children<br />
'date', 'datemodified', 'datecreated', 'thumbnail', 'icon' => see above,<br />
'children' => array( <br />
// presence of this attribute actually tells file picker that this is a folder. In case of dynload=true, it should be empty array<br />
// otherwise it is a nested list of contained files and folders<br />
)<br />
),<br />
)<br />
// The 'object' tag can be used to embed an external web page or application within the filepicker<br />
'object' => array(<br />
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'<br />
'src' => (string) the website address to embed in the object<br />
)<br />
)<br />
</code><br />
Dynamically loading<br />
Some repositories contain many files which cannot load in one time, in this case, we need dynamically loading to fetch them step by step, files in subfolder won't be listed until user click the folder in file picker treeview.<br />
<br />
As a plug-in developer, if you set dynload flag as '''true''', you should return files and folders (set children as a null array) in current path only instead of building the whole file tree.<br />
<br />
Example of dynamically loading<br />
See [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in<br />
<br />
The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.<br />
<br />
===User login (optional)===<br />
If the plugin requires login from the user at the time when they use it, then these functions can be used.<br />
<br />
====print_login====<br />
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.<br />
<code php><br />
public function print_login() { // From repository_alfresco<br />
if ($this->options['ajax']) {<br />
$user_field = new stdClass();<br />
$user_field->label = get_string('username', 'repository_alfresco').': ';<br />
$user_field->id = 'alfresco_username';<br />
$user_field->type = 'text';<br />
$user_field->name = 'al_username';<br />
<br />
$passwd_field = new stdClass();<br />
$passwd_field->label = get_string('password', 'repository_alfresco').': ';<br />
$passwd_field->id = 'alfresco_password';<br />
$passwd_field->type = 'password';<br />
$passwd_field->name = 'al_password';<br />
<br />
$ret = array();<br />
$ret['login'] = array($user_field, $passwd_field);<br />
return $ret;<br />
} else { // Non-AJAX login form - directly output the form elements<br />
echo '<table>';<br />
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';<br />
echo '<td><input type="text" name="al_username" /></td></tr>';<br />
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';<br />
echo '<td><input type="password" name="al_password" /></td></tr>';<br />
echo '</table>';<br />
echo '<input type="submit" value="Enter" />';<br />
}<br />
}<br />
</code><br />
This will help to generate a form by file picker which contains user name and password input elements.<br />
<br />
If your login form is static and never changes, you can add ''$ret['allowcaching'] = true;'' and filepicker will not send the request to the server every time user opens the login/search form.<br />
<br />
For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).<br />
<code php><br />
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {<br />
// Taken from repository_alfresco<br />
<br />
/* Skipping code that is not relevant to user login */<br />
<br />
$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']); <br />
$this->username = optional_param('al_username', '', PARAM_RAW);<br />
$this->password = optional_param('al_password', '', PARAM_RAW);<br />
try{<br />
// deal with user logging in<br />
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {<br />
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);<br />
$SESSION->{$this->sessname} = $this->ticket;<br />
} else {<br />
if (!empty($SESSION->{$this->sessname})) {<br />
$this->ticket = $SESSION->{$this->sessname};<br />
}<br />
}<br />
$this->user_session = $this->alfresco->createSession($this->ticket);<br />
$this->store = new SpacesStore($this->user_session);<br />
} catch (Exception $e) {<br />
$this->logout();<br />
}<br />
$this->current_node = null;<br />
<br />
/* Skipping code that is not relevant to user login */<br />
<br />
}<br />
</code><br />
<br />
Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.<br />
<code php><br />
public function print_login(){ // Code taken from repository_boxnet<br />
$t = $this->boxclient->getTicket();<br />
if ($this->options['ajax']) {<br />
$popup_btn = new stdClass();<br />
$popup_btn->type = 'popup';<br />
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];<br />
<br />
$ret = array();<br />
$ret['login'] = array($popup_btn);<br />
return $ret;<br />
} else {<br />
echo '<table>';<br />
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';<br />
echo '<td><input type="text" name="boxusername" /></td></tr>';<br />
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';<br />
echo '<td><input type="password" name="boxpassword" /></td></tr>';<br />
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';<br />
echo '</table>';<br />
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';<br />
}<br />
}<br />
</code><br />
<br />
====check_login====<br />
This function will return a boolean value to tell Moodle whether the user has logged in.<br />
By default, this function will return true.<br />
<code php><br />
public function check_login() { // Taken from repository_alfresco<br />
global $SESSION;<br />
return !empty($SESSION->{$this->sessname});<br />
}<br />
</code><br />
====logout====<br />
When a user clicks the logout button in file picker, this function will be called. You may clean up the session or disconnect the connection with remote server here. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):<br />
<code php><br />
public function logout() { // Taken from repository_alfresco<br />
global $SESSION;<br />
unset($SESSION->{$this->sessname});<br />
return $this->print_login();<br />
}<br />
</code><br />
<br />
===Transferring files to Moodle (optional)===<br />
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.<br />
<br />
====get_file_reference($source)====<br />
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).<br />
<br />
====get_file($url, $filename = "")====<br />
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:<br />
* path - the local path where the file was saved<br />
* url - the $url param passed into the function<br />
<br />
<code php><br />
public function get_file($url, $filename = '') {<br />
// Default implementation from the base 'repository' class<br />
$path = $this->prepare_file($filename); // Generate a unique temporary filename<br />
$c = new curl;<br />
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));<br />
if ($result !== true) {<br />
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);<br />
}<br />
return array('path'=>$path, 'url'=>$url);<br />
}<br />
</code><br />
<code php><br />
public function get_file($reference, $filename = '') {<br />
// Slightly extended version taken from repository_equella<br />
global $USER;<br />
// Extract the details saved in the 'source' param by <br />
// repository/equella/callback.php (now in the $reference paramater)<br />
$ref = @unserialize(base64_decode($reference));<br />
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {<br />
// Occurs when the user isn't known..<br />
return null;<br />
}<br />
$path = $this->prepare_file($filename);<br />
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');<br />
$c = new curl(array('cookie'=>$cookiepathname));<br />
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));<br />
// Delete cookie jar.<br />
if (file_exists($cookiepathname)) {<br />
unlink($cookiepathname);<br />
}<br />
if ($result !== true) {<br />
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);<br />
}<br />
return array('path'=>$path, 'url'=>$url);<br />
}<br />
</code><br />
<br />
====get_link($url)====<br />
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.<br />
<br />
{{Moodle 2.3}}====get_file_source_info($source)====<br />
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and returns the value to be stored in files.source field in DB (regardless whether file is picked as a copy or by reference). It indicates where the file came from. It is advised to include either full URL here or indication of the repository.<br />
Examples: 'Dropbox: /filename.jpg', 'http://fullurl.com/path/file', etc.<br />
This value will be used to display warning message if reference can not be restored from backup. Also it can (although not has to) be used in get_reference_details() to produce the human-readable reference source in the fileinfo dialogue in the file manager.<br />
<br />
===Search functions (optional)===<br />
<br />
These functions allow you to implement search functionality within your repository.<br />
<br />
====print_search====<br />
When a user clicks the search button on file picker, this function will be called to return a search form. By default, it will create a form with single search bar - you can override it to create a advanced search form.<br />
<br />
A custom search form must include the following:<br />
* A text field element named '''s''', this is where users will type in their search criteria<br />
<br />
The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):<br />
* A hidden element named '''repo_id''' and the value must be the id of the repository instance<br />
* A hidden element named '''ctx_id''' and the value must be the context id of the repository instance<br />
* A hidden element named '''sesskey''' and the value must be the session key<br />
<br />
<code php><br />
public function print_search() {<br />
// The default implementation in class 'repository'<br />
global $PAGE;<br />
$renderer = $PAGE->get_renderer('core', 'files');<br />
return $renderer->repository_default_searchform();<br />
}<br />
<br />
// From core_files_renderer (repository/renderer.php)<br />
public function repository_default_searchform() {<br />
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';<br />
return $str;<br />
}<br />
</code><br />
<br />
<code php><br />
public function print_search() {<br />
<br />
// label search name<br />
$param = array('for' => 'label_search_name');<br />
$title = get_string('search_name', 'myrepo_search_name');<br />
$html .= html_writer::tag('label', $title, $param);<br />
$html .= html_writer::empty_tag('br');<br />
<br />
// text field search name<br />
$attributes['type'] = 'text';<br />
$attributes['name'] = 's';<br />
$attributes['value'] = '';<br />
$attributes['title'] = $title;<br />
$html .= html_writer::empty_tag('input', $attributes);<br />
$html .= html_writer::empty_tag('br');<br />
<br />
return $html;<br />
}<br />
</code><br />
<br />
====search($search_text, $page = 0)====<br />
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:<br />
* list - with the same layout as the 'list' element in 'get_listing'<br />
<code php><br />
public function search($search_text, $page = 0) { <br />
// Example from repoistory_googledocs<br />
$gdocs = new google_docs($this->googleoauth);<br />
<br />
$ret = array();<br />
$ret['dynload'] = true;<br />
$ret['list'] = $gdocs->get_file_list($search_text);<br />
return $ret;<br />
}<br />
</code><br />
<br />
====global_search()====<br />
Return true if should be included in a search throughout all repositories (currently not available via the UI)<br />
<br />
{{Moodle 2.3}}===Repository support for returning file as alias/shortcut=== <br />
<br />
<br />
From Moodle 2.3 it became possible to link to the file from external (or internal) repository by reference. In UI it is called “create alias/shortcut”. This creates a row in {files} table but the contents of the file is not stored. Although it may be cached by repository if developer wants to.<br />
<br />
Make sure that function supported_returntypes() returns FILE_REFERENCE among other types.<br />
<br />
Note that external file is synchronised by moodle when UI wants to show the file size.<br />
<br />
====get_reference_file_lifetime()====<br />
Return minimum number of seconds before checking for changes to the file (default implementation = 1 day)<br />
<code php><br />
public function get_reference_file_lifetime($ref) {<br />
return 60 * 60 * 24; // One day<br />
}<br />
</code><br />
<br />
====sync_individual_file(stored_file $storedfile)====<br />
Called after the file has reached the 'lifetime' specified above to see if it should now be synchronised (default implementation is to return true)<br />
<code php><br />
public function sync_individual_file(stored_file $storedfile) {<br />
return true;<br />
}<br />
</code><br />
<br />
====get_reference_details($reference, $filestatus = 0)====<br />
Returns human-readable information about where the original file is stored (to be displayed in the filepicker properties box). It is usually prefixed with repository name and semicolon (e.g. 'Myrepository: http://url.to.file'). $reference is the 'source' output by 'get_listing'. $filestatus can be either 0 (OK - default) or 666 (source file missing).<br />
<code php><br />
public function get_reference_details($reference, $filestatus = 0) {<br />
// Example taken from repository_equella<br />
if (!$filestatus) {<br />
$ref = unserialize(base64_decode($reference));<br />
return $this->get_name(). ': '. $ref->filename;<br />
} else {<br />
return get_string('lostsource', 'repository', '');<br />
}<br />
}<br />
</code><br />
<br />
====get_file_by_reference($reference)====<br />
Returns up-to-date information about the original file, only called when the 'lifetime' is reached and 'sync_individual_file' returns true.<br />
* for image files - download the file and return either $ret->filepath (full path on the server), $ret->handle (open handle to the file) or $ret->content (raw data from the file) to allow the file to be saved into the Moodle filesystem and the thumbnail to be updated<br />
* for non-image files - avoid downloading the file (if possible) and just return $ret->filesize to update that information<br />
* for missing / inaccessible files - return null<br />
Remember this function may be called quite a lot, as the filemanager often wants to know the filesize.<br />
<code php><br />
public function get_file_by_reference($reference) {<br />
// Example taken from repository_equella<br />
global $USER;<br />
// Extract the remote file identifier<br />
$ref = @unserialize(base64_decode($reference->reference));<br />
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {<br />
// Occurs when the user isn't known..<br />
return null;<br />
}<br />
<br />
// Download the file details<br />
$return = null;<br />
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');<br />
$c = new curl(array('cookie' => $cookiepathname));<br />
if (file_extension_in_typegroup($ref->filename, 'web_image')) {<br />
// The file is an image - download and return the file path<br />
$path = $this->prepare_file('');<br />
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::SYNCIMAGE_TIMEOUT));<br />
if ($result === true) {<br />
$return = (object)array('filepath' => $path);<br />
}<br />
} else {<br />
// The file is not an image - just get the file details<br />
$result = $c->head($url, array('followlocation' => true, 'timeout' => self::SYNCFILE_TIMEOUT));<br />
}<br />
// Delete cookie jar.<br />
if (file_exists($cookiepathname)) {<br />
unlink($cookiepathname);<br />
}<br />
<br />
$this->connection_result($c->get_errno());<br />
$curlinfo = $c->get_info();<br />
if ($return === null && isset($curlinfo['http_code']) && $curlinfo['http_code'] == 200<br />
&& array_key_exists('download_content_length', $curlinfo)<br />
&& $curlinfo['download_content_length'] >= 0) {<br />
// we received a correct header and at least can tell the file size<br />
$return = (object)array('filesize' => $curlinfo['download_content_length']);<br />
}<br />
return $return;<br />
}<br />
</code><br />
<br />
====send_file($storedfile, $lifetime=86400, $filter=0, $forcedownload=false, array $options = null)====<br />
Send the requested file back to the user's browser. The 'reference' for the file can be found via $storedfile->get_reference(). If the file is not found / no longer exists, the function 'send_file_not_found()' should be used. Otherwise the file should be output directly, via the most appropriate method - e.g. use a 'Location: ' header to redirect to the external URL; or download the file and cache within the Moodle filesystem (possibly using '$this->import_external_file_contents()'), then call 'send_stored_file'. Note, it is up to the repository developer to decide whether to actually download the file or to return a locally cached copy instead.<br />
<code php><br />
public function send_file($stored_file, $lifetime=86400 , $filter=0, $forcedownload=false, array $options = null) {<br />
// Example taken from repository_equella<br />
$reference = unserialize(base64_decode($stored_file->get_reference()));<br />
$url = $this->appendtoken($reference->url);<br />
if ($url) {<br />
header('Location: ' . $url);<br />
} else {<br />
send_file_not_found();<br />
}<br />
}<br />
</code><br />
An example of caching files within the Moodle filesystem can be found in repository_dropbox.<br />
<br />
===Misc functions===<br />
<br />
A couple of other useful functions to be aware of.<br />
<br />
====get_name()====<br />
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).<br />
<br />
====cron()====<br />
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).<br />
<br />
== I18n - Internationalization ==<br />
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':<br />
<br />
<code php><br />
$string['pluginname'] = 'Flickr Public';<br />
$string['configplugin'] = 'Flickr Public configuration';<br />
$string['pluginname_help'] = 'A Flickr public repository';<br />
</code><br />
<br />
==See also==<br />
<br />
*[[Plugins]]<br />
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]<br />
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]<br />
* MDL-16543 - A list of officially supported repository plugins<br />
* MDL-16543 - Template plugin for developers<br />
<br />
[[Category:Repositories]]<br />
[[Category:Plugins]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42560FirePHP2013-10-14T15:46:57Z<p>Nakohdo: </p>
<hr />
<div>{{Work in progress}}<br />
<br />
== What is FirePHP? ==<br />
[http://www.firephp.org/ FirePHP] enables you to log to your Firebug Console using a simple PHP method call. <br />
<br />
== FirePHP block for Moodle ==<br />
* There's a [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] in the works. <br />
* The block will soon be available in the Moodle Plugin Directory: https://moodle.org/plugins/view.php?plugin=block_firephp<br />
<br />
== Moodle resources == <br />
* [https://moodle.org/mod/forum/discuss.php?d=119961 Moodle General developer forum: FirePHP plugin] - where everything started.<br />
* The plugin in the [https://moodle.org/mod/data/view.php?d=13&rid=4793 old plugin database]<br />
* Related [https://tracker.moodle.org/browse/MDL-16371 tracker issue]<br />
* Current code on [https://moodle.org/mod/data/view.php?d=13&rid=4793 GitHub]<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]<br />
<br />
<br />
[[Category:Developer tools|Firebug]]<br />
[[Category:Firefox extensions|Firebug]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42559FirePHP2013-10-14T15:46:17Z<p>Nakohdo: /* See also */</p>
<hr />
<div>{{Work in progress}}<br />
{{stub}}<br />
<br />
== What is FirePHP? ==<br />
[http://www.firephp.org/ FirePHP] enables you to log to your Firebug Console using a simple PHP method call. <br />
<br />
== FirePHP block for Moodle ==<br />
* There's a [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] in the works. <br />
* The block will soon be available in the Moodle Plugin Directory: https://moodle.org/plugins/view.php?plugin=block_firephp<br />
<br />
== Moodle resources == <br />
* [https://moodle.org/mod/forum/discuss.php?d=119961 Moodle General developer forum: FirePHP plugin] - where everything started.<br />
* The plugin in the [https://moodle.org/mod/data/view.php?d=13&rid=4793 old plugin database]<br />
* Related [https://tracker.moodle.org/browse/MDL-16371 tracker issue]<br />
* Current code on [https://moodle.org/mod/data/view.php?d=13&rid=4793 GitHub]<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]<br />
<br />
<br />
[[Category:Developer tools|Firebug]]<br />
[[Category:Firefox extensions|Firebug]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42558FirePHP2013-10-14T15:41:18Z<p>Nakohdo: /* Moodle resources */</p>
<hr />
<div>{{Work in progress}}<br />
{{stub}}<br />
<br />
== What is FirePHP? ==<br />
[http://www.firephp.org/ FirePHP] enables you to log to your Firebug Console using a simple PHP method call. <br />
<br />
== FirePHP block for Moodle ==<br />
* There's a [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] in the works. <br />
* The block will soon be available in the Moodle Plugin Directory: https://moodle.org/plugins/view.php?plugin=block_firephp<br />
<br />
== Moodle resources == <br />
* [https://moodle.org/mod/forum/discuss.php?d=119961 Moodle General developer forum: FirePHP plugin] - where everything started.<br />
* The plugin in the [https://moodle.org/mod/data/view.php?d=13&rid=4793 old plugin database]<br />
* Related [https://tracker.moodle.org/browse/MDL-16371 tracker issue]<br />
* Current code on [https://moodle.org/mod/data/view.php?d=13&rid=4793 GitHub]<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42557FirePHP2013-10-14T15:40:42Z<p>Nakohdo: </p>
<hr />
<div>{{Work in progress}}<br />
{{stub}}<br />
<br />
== What is FirePHP? ==<br />
[http://www.firephp.org/ FirePHP] enables you to log to your Firebug Console using a simple PHP method call. <br />
<br />
== FirePHP block for Moodle ==<br />
* There's a [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] in the works. <br />
* The block will soon be available in the Moodle Plugin Directory: https://moodle.org/plugins/view.php?plugin=block_firephp<br />
<br />
== Moodle resources == <br />
* [https://moodle.org/mod/forum/discuss.php?d=119961 Moodle General developer forum: FirePHP plugin] - where everything started.<br />
* The plugin in the [https://moodle.org/mod/data/view.php?d=13&rid=4793 old plugin database]<br />
* Relatede [https://tracker.moodle.org/browse/MDL-16371 tracker issue]<br />
* Current code on [https://moodle.org/mod/data/view.php?d=13&rid=4793 GitHub]<br />
<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42556FirePHP2013-10-14T15:34:35Z<p>Nakohdo: </p>
<hr />
<div>{{Work in progress}}<br />
<br />
{{stub}}<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42555FirePHP2013-10-14T15:33:56Z<p>Nakohdo: </p>
<hr />
<div>{{stub}}<br />
{{Work in progress}}<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=FirePHP&diff=42554FirePHP2013-10-14T15:31:07Z<p>Nakohdo: Created page with "{{Stub}} == See also == * Firebug * Moodle Development kit"</p>
<hr />
<div>{{Stub}}<br />
<br />
== See also ==<br />
* [[Firebug]]<br />
* [[Moodle Development kit]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Acceptance_testing&diff=42540Acceptance testing2013-10-13T18:17:01Z<p>Nakohdo: /* Writing features */ Changed the syntax highlighting language for scenarios to YAML.</p>
<hr />
<div>== Introduction ==<br />
This page describes how we describe Moodle's functionalities and how we automatically test all of them.<br />
<br />
Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate users interactions.<br />
<br />
For technical info: [[Behat integration]]<br />
<br />
=== How it works ===<br />
Behat parses and executes features files which describes Moodle's features (for example ''Post in a forum''), each feature file is composed by many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed by steps (for example ''I press "Post to Forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into an PHP method and is executed.<br />
<br />
This features are executed nightly in the HQ servers with all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and test new functionalities.<br />
<br />
=== Examples ===<br />
<br />
* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:<br />
@auth<br />
'''Feature''': Login<br />
In order to login<br />
As a moodle user<br />
I need to be able to validate the username and password against moodle<br />
<br />
'''Scenario''': Login as an existing user<br />
Given I am on "login/index.php"<br />
When I fill in "username" with "admin"<br />
And I fill in "password" with "moodle"<br />
And I press "loginbtn"<br />
Then I should see "Moodle 101: Course Name"<br />
<br />
'''Scenario''': Login as an unexisting user<br />
Given I am on "login/index.php"<br />
When I fill in "username" with "admin"<br />
And I fill in "password" with "moodle"<br />
And I press "loginbtn"<br />
Then I should see "Moodle 101: Course Name"<br />
<br />
Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.<br />
<br />
These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:<br />
<br />
@mod @mod_forum<br />
'''Feature''': Add forum activities and discussions<br />
In order to discuss topics with other users<br />
As a moodle teacher<br />
I need to add forum activities to moodle courses<br />
<br />
'''Scenario''': Add a forum and a discussion<br />
'''Given''' the following "users" exists:<br />
| username | firstname | lastname | email |<br />
| teacher1 | Teacher | 1 | teacher1@asd.com |<br />
'''And''' the following "courses" exists:<br />
| fullname | shortname | category |<br />
| Course 1 | C1 | 0 |<br />
'''And''' the following "course enrolments" exists:<br />
| user | course | role |<br />
| teacher1 | C1 | editingteacher |<br />
'''And''' I log in as "teacher1"<br />
'''And''' I follow "Course 1"<br />
'''And''' I turn editing mode on<br />
'''And''' I add a "Forum" to section "1" and I fill the form with:<br />
| Forum name | Test forum name |<br />
| Forum type | Standard forum for general use |<br />
| Description | Test forum description |<br />
'''When''' I add a new discussion to "Test forum name" forum with:<br />
| Subject | Forum post subject |<br />
| Message | This is the body |<br />
'''Then''' I should see "Test forum name"<br />
<br />
Note that:<br />
<br />
* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution<br />
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.<br />
<br />
== Quick start ==<br />
<br />
This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.<br />
<br />
To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.<br />
<br />
# Open a command line interface<br />
# '''cd /to/your/moodle/dirroot'''<br />
# Edit config.php adding the following lines before the lib/setup.php include<br />
#: <code language="text">$CFG->behat_prefix = 'b_';<br />
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';<br />
$CFG->behat_switchcompletely = true;<br />
</code><br />
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)<br />
# '''php admin/tool/behat/cli/init.php'''<br />
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"<br />
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''<br />
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''<br />
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example<br />
# Browse to your $CFG->wwwroot, this is an empty test site and it is reset before each test (called scenario)<br />
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)<br />
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)<br />
# To 'add a blog entry' we need to:<br />
## Log in the system as a valid user<br />
## Expand 'My profile' node of the navigation block<br />
## Expand the 'Blogs' node of the navigation block<br />
## Follow he 'Add a new entry' link<br />
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'<br />
## Press the 'Save changes' button<br />
## Verify you see the values you entered in the form and verify you are not in the form page<br />
# This translated to steps is:<br />
#: <code language="text">Given I log in as "admin"<br />
And I expand "My profile" node<br />
And I expand "Blogs" node<br />
And I follow "Add a new entry"<br />
And I fill the moodle form with:<br />
| Entry title | I'm the name |<br />
| Blog entry body | I'm the description |<br />
When I press "Save changes"<br />
Then I should see "Blog entries"<br />
And I should see "I'm the description"<br />
And I should not see "Required"<br />
</code><br />
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)<br />
#: <code language="text"><br />
@core @core_blog<br />
Feature: Add a blog entry<br />
In order to let the world know about me<br />
As a user<br />
I need to write blog entries<br />
<br />
@javascript<br />
Scenario: Add a blog entry with valid data<br />
Given I log in as "admin"<br />
And I expand "My profile" node<br />
And I expand "Blogs" node<br />
And I follow "Add a new entry"<br />
And I fill the moodle form with:<br />
| Entry title | I'm the name |<br />
| Blog entry body | I'm the description |<br />
When I press "Save changes"<br />
Then I should see "View all of my entries"<br />
And I should see "I'm a description"<br />
And I should not see "Required"<br />
</code><br />
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''<br />
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)<br />
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''<br />
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed<br />
<br />
You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.<br />
<br />
For detailed steps and/or troubleshooting:<br />
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests<br />
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features<br />
<br />
== Requirements ==<br />
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)<br />
* Other dependencies are managed by the composer installer<br />
<br />
== Installation ==<br />
* Edit config.php<br />
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions<br />
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''<br />
* Download composer<br />
** '''cd /your/moodle/dirroot'''<br />
** '''curl http://getcomposer.org/installer | php'''<br />
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':<br />
**** Download '''http://getcomposer.org/installer'''<br />
**** Store it in /your/moodle/dirroot/composerinstaller.php for example<br />
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')<br />
* Install behat dependencies and enable the test environment<br />
** '''cd /your/moodle/dirroot'''<br />
** '''php admin/tool/behat/cli/init.php'''<br />
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium<br />
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"<br />
<br />
== Running tests ==<br />
# Start the PHP built-in web server<br />
#* Open a command line interface and '''cd /to/your/moodle/dirroot'''<br />
#* '''php -S localhost:8000''' (This is the default address, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage)<br />
#** ''There is something crazy going on here. Thit advice seems to assume that you have $CFG->wwwroot set to 'http://localhost:8000', but it does not acutally tell you to set that anywhere, and if you do that, it will break your normal install. Please could someone sort out these instructions.''<br />
# (Optional) Start the Selenium server (in case you want to run tests that involves Javascript)<br />
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''<br />
# Run Behat<br />
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)<br />
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''<br />
#* If you followed all the steps and you receive an unknown weird error probably your system's Firefox version is not compatible with the Selenium version you are running, try downloading the latest Selenium release from it's website as explained above<br />
# (Optional) If you are adding new tests or steps definitions update the tests list:<br />
#* '''php admin/tool/behat/cli/util.php --enable'''<br />
# (Optional) Disable test environment (in case you want to use the PHP built-in web server for regular moodle environment)<br />
#* '''php admin/tool/behat/cli/util.php --disable'''<br />
<br />
<br />
'''Note that if you have the HTTP_PROXY environemnt variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''<br />
<br />
=== Tests filters ===<br />
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are few tags that you might be interested in:<br />
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.<br />
* '''@_only_local''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.<br />
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.<br />
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.<br />
<br />
=== Output formats ===<br />
<br />
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format.<br />
<br />
== Advanced usage ==<br />
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.<br />
<br />
* '''Different test server URL''', by default the test web server only can be accessed in localhost. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''<br />
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers... <br />
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.<br />
<br />
<code language="php"><br />
$CFG->behat_config = array(<br />
'default' => array(<br />
'extensions' => array(<br />
'Behat\MinkExtension\Extension' => array(<br />
'selenium2' => array(<br />
'browser' => 'chrome'<br />
)<br />
)<br />
)<br />
)<br />
);<br />
</code><br />
<br />
:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.<br />
* '''Switch completely to test environment''', DON'T USE THIS SETTING IN PRODUCTION SITES! all the site users would be using the test environment instead of the regular one with your courses and all your data and they wouldn't be able to login in your site; this setting should only be used in development/testing installations. It's purpose is to ease the integration with cloud-based continuous integration systems, another possible use is to allow acceptance testing in a development environment without PHP 5.4.<br />
** Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.<br />
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.<br />
<br />
== Writing features ==<br />
<br />
All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.<br />
<br />
Once you decided which functionality you want to specify as a feature you should:<br />
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file<br />
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem<br />
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:<br />
#: <code lang="yaml">@plugintype @plugintype_pluginname<br />
Feature: FEATURENAME<br />
In order to ... // Why this feature is useful<br />
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'<br />
I need to ... // The feature we want</code><br />
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected<br />
# For each scenario you thought:<br />
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected<br />
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)<br />
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work. Remember to use ''Given'', ''When'' and ''Then'' in a way that reflects what the scenario is testing<br />
## Copy the list of steps to the .feature file with the Scenario header:<br />
##: <code lang="yaml">Scenario: Short description of the scenario<br />
Given step 1<br />
And step 2<br />
And step 3<br />
When step 4<br />
And step 5<br />
Then step 6</code><br />
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline<br />
##: <code lang="yaml">@javascript<br />
Scenario: Short description of the scenario<br />
...<br />
...</code><br />
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.<br />
# Add extra tags to the scenario or the feature if required<br />
#* If there are scenarios that includes files uploads they should be tagged as @_only_local<br />
#* If there are scenarios that are likely to fail in some browser-OS combinations they can be tagged as @_cross_browser, they will be tested in different OS / browser combinations by Moodle HQ continuous integration servers<br />
<br />
=== Available steps ===<br />
<br />
Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:<br />
* Processes to set up the environment<br />
* Actions that provokes an event<br />
* Checkings to ensure the outcomes are the expected ones<br />
<br />
[[File:Acceptance_testing_UI_2.5.png]]<br />
<br />
=== Tips ===<br />
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)<br />
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)<br />
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.<br />
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''<br />
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary<br />
<br />
=== Providing values to steps ===<br />
Most of the steps requires values, there are four methods to provide values to steps, the method depends on the step specification, you can know when a steps requires a value because you will see a drop down menu with a closed list of options that the step accepts as argument or an upper case string between double quotes, something like '''I press "BUTTON_STRING"''' or it ends with a ''':''' . The three methods are:<br />
* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''<br />
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''<br />
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.<br />
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, in the 'Acceptance testing' interface you can see a dropdown menu to select one of these options:<br />
** field - for searching a field by its id, name, value or label<br />
** fieldset - for searching a fieldset by it's id or legend<br />
** link - for searching a link by its href, id, title, img alt or value<br />
** button - for searching a button by its name, id, value, img alt or title<br />
** link_or_button - for searching for both, links and buttons<br />
** select - for searching a select field by its id, name or label<br />
** checkbox - for searching a checkbox by its id, name, or label<br />
** radio - for searching a radio button by its id, name, or label<br />
** file - for searching a file input by its id, name, or label<br />
** optgroup - for searching optgroup by its label<br />
** option - for searching an option by its content<br />
** table - for searching a table by its id or caption<br />
** css_element - for searching an element by its CSS selector<br />
** xpath_element - for searching an element by its XPath<br />
<br />
==== Uploading files ====<br />
Note than some tests requires files to be uploaded, in this case<br />
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page<br />
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*<br />
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example) <br />
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.<br />
* The scenarios that includes files uploading should be tagged using the '''@_only_local''' tag<br />
<br />
=== Fixtures ===<br />
<br />
As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.<br />
<br />
==== Available elements ====<br />
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings. <br />
<br />
The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.<br />
<br />
* Course categories<br />
** The required field is idnumber<br />
** References between parent/children by their idnumber, using the "category" field<br />
Given the following "categories" exists:<br />
| name | category | idnumber |<br />
| Category 1 | 0 | CAT1 |<br />
| Category 2 | CAT1 | CAT2 |<br />
<br />
* Courses<br />
** The required field is shortname<br />
** Uses the category idnumber as category reference<br />
Given the following "courses" exists:<br />
| fullname | shortname | category | format | <br />
| Course 1 | COURSE1 | CAT1 | topics |<br />
| Course 2 | COURSE2 | CAT2 | |<br />
<br />
* Groups<br />
** The required fields are course and idnumber<br />
** Uses the course shortname as course reference<br />
Given the following "groups" exists:<br />
| name | description | course | idnumber |<br />
| Group 1 | Anything | COURSE1 | GROUP1 |<br />
<br />
* Groupings<br />
** The required fields are course and idnumber<br />
** Uses the course shortname as course reference<br />
Given the following "groupings" exists:<br />
| name | course | idnumber |<br />
| Grouping 1 | COURSE1 | GROUPING1 |<br />
| Grouping 2 | COURSE1 | GROUPING2 |<br />
<br />
* Users<br />
** The required field is username (if password is not set username value will be used as password too)<br />
Given the following "users" exists:<br />
| username | email | firstname | lastname |<br />
| testuser | asd@asd.com | Test | User |<br />
<br />
* Course enrolments<br />
** The required fields are user, course and role<br />
** Uses the course shortname as course reference<br />
** Uses the user username as user reference<br />
** Uses the role shortname as role reference<br />
** Uses the enrolment name as enrol reference<br />
Given the following "course enrolments" exists:<br />
| user | course | role | enrol |<br />
| testuser | COURSE1 | editingteacher | manual |<br />
<br />
* System role assigns<br />
** The required fields are user and role<br />
** Uses the user username as user reference<br />
** Uses the role shortname as role reference<br />
Given the following "system role assigns" exists:<br />
| user | role |<br />
| testuser | manager |<br />
<br />
* Group members<br />
** The required fields are user and group<br />
** Uses the group idnumber as group reference<br />
** Uses the user username as user reference<br />
Given the following "group members" exists:<br />
| user | group |<br />
| testuser | GROUP1 |<br />
<br />
* Grouping groups<br />
** The required fields are grouping and group<br />
** Uses the group idnumber as group reference<br />
** Uses the grouping idnumber as grouping reference<br />
Given the following "grouping groups" exists:<br />
| grouping | group |<br />
| GROUPING1 | GROUP1 |<br />
<br />
* Cohorts<br />
** The required field is idnumber<br />
Given the following "cohorts" exists:<br />
| name | idnumber |<br />
| Cohort 1 | COHORT1 |<br />
<br />
=== Features check list ===<br />
* It's a new feature or a new scenario of an existing feature<br />
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)<br />
* Are using the appropriate Moodle component tag and includes @_only_local or @_cross_browser when required<br />
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features<br />
* Covers both JS and non-JS environments<br />
<br />
== Adding steps definitions ==<br />
<br />
Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.<br />
<br />
As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.<br />
<br />
=== Example ===<br />
<br />
You can use this example below or any of the existing steps definitions as a template.<br />
<br />
* auth/tests/behat/behat_auth.php<br />
class behat_auth extends behat_base {<br />
/**<br />
* Logs in the user. There should exist a user with the same value as username and password<br />
*<br />
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/<br />
*/<br />
public function i_log_in_as($username) {<br />
return array(new Given('I am on homepage'),<br />
new Given('I follow "Login"'),<br />
new Given('I fill in "Username" with "'.$username.'"'),<br />
new Given('I fill in "Password" with "'.$username.'"'),<br />
new Given('I press "Login"'),<br />
new Given('I should see "You are logged in as"'));<br />
}<br />
}<br />
<br />
=== Tips ===<br />
<br />
If you are creating a completely new step definition there are also a few things to consider:<br />
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both<br />
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem<br />
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''<br />
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure<br />
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.<br />
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)<br />
<br />
<br />
If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''<br />
<br />
=== Check list ===<br />
<br />
New steps should be/have:<br />
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension<br />
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)<br />
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)<br />
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component<br />
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem<br />
* Describe the regular expression with the most appropriate tag inside the method doc comment:<br />
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')<br />
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')<br />
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')<br />
* Depending on the inputs your definition expects you must use a different regular expression:<br />
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')<br />
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')<br />
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table<br />
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)<br />
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')<br />
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)<br />
<br />
== Links == <br />
* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]<br />
* Technical info: [[Behat integration]]<br />
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html<br />
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors<br />
* See Also [https://tracker.moodle.org/browse/MDL-37046 MDL37046] for clear instruction<br />
[[Category:Behat]][[Category:Quality Assurance]]<br />
<br />
[[es:Prueba de aceptación]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Acceptance_testing&diff=42539Acceptance testing2013-10-13T18:14:07Z<p>Nakohdo: /* Advanced usage */ Changed syntax highlighting language to PHP.</p>
<hr />
<div>== Introduction ==<br />
This page describes how we describe Moodle's functionalities and how we automatically test all of them.<br />
<br />
Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate users interactions.<br />
<br />
For technical info: [[Behat integration]]<br />
<br />
=== How it works ===<br />
Behat parses and executes features files which describes Moodle's features (for example ''Post in a forum''), each feature file is composed by many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed by steps (for example ''I press "Post to Forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into an PHP method and is executed.<br />
<br />
This features are executed nightly in the HQ servers with all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and test new functionalities.<br />
<br />
=== Examples ===<br />
<br />
* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:<br />
@auth<br />
'''Feature''': Login<br />
In order to login<br />
As a moodle user<br />
I need to be able to validate the username and password against moodle<br />
<br />
'''Scenario''': Login as an existing user<br />
Given I am on "login/index.php"<br />
When I fill in "username" with "admin"<br />
And I fill in "password" with "moodle"<br />
And I press "loginbtn"<br />
Then I should see "Moodle 101: Course Name"<br />
<br />
'''Scenario''': Login as an unexisting user<br />
Given I am on "login/index.php"<br />
When I fill in "username" with "admin"<br />
And I fill in "password" with "moodle"<br />
And I press "loginbtn"<br />
Then I should see "Moodle 101: Course Name"<br />
<br />
Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.<br />
<br />
These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:<br />
<br />
@mod @mod_forum<br />
'''Feature''': Add forum activities and discussions<br />
In order to discuss topics with other users<br />
As a moodle teacher<br />
I need to add forum activities to moodle courses<br />
<br />
'''Scenario''': Add a forum and a discussion<br />
'''Given''' the following "users" exists:<br />
| username | firstname | lastname | email |<br />
| teacher1 | Teacher | 1 | teacher1@asd.com |<br />
'''And''' the following "courses" exists:<br />
| fullname | shortname | category |<br />
| Course 1 | C1 | 0 |<br />
'''And''' the following "course enrolments" exists:<br />
| user | course | role |<br />
| teacher1 | C1 | editingteacher |<br />
'''And''' I log in as "teacher1"<br />
'''And''' I follow "Course 1"<br />
'''And''' I turn editing mode on<br />
'''And''' I add a "Forum" to section "1" and I fill the form with:<br />
| Forum name | Test forum name |<br />
| Forum type | Standard forum for general use |<br />
| Description | Test forum description |<br />
'''When''' I add a new discussion to "Test forum name" forum with:<br />
| Subject | Forum post subject |<br />
| Message | This is the body |<br />
'''Then''' I should see "Test forum name"<br />
<br />
Note that:<br />
<br />
* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution<br />
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.<br />
<br />
== Quick start ==<br />
<br />
This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.<br />
<br />
To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.<br />
<br />
# Open a command line interface<br />
# '''cd /to/your/moodle/dirroot'''<br />
# Edit config.php adding the following lines before the lib/setup.php include<br />
#: <code language="text">$CFG->behat_prefix = 'b_';<br />
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';<br />
$CFG->behat_switchcompletely = true;<br />
</code><br />
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)<br />
# '''php admin/tool/behat/cli/init.php'''<br />
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"<br />
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''<br />
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''<br />
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example<br />
# Browse to your $CFG->wwwroot, this is an empty test site and it is reset before each test (called scenario)<br />
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)<br />
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)<br />
# To 'add a blog entry' we need to:<br />
## Log in the system as a valid user<br />
## Expand 'My profile' node of the navigation block<br />
## Expand the 'Blogs' node of the navigation block<br />
## Follow he 'Add a new entry' link<br />
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'<br />
## Press the 'Save changes' button<br />
## Verify you see the values you entered in the form and verify you are not in the form page<br />
# This translated to steps is:<br />
#: <code language="text">Given I log in as "admin"<br />
And I expand "My profile" node<br />
And I expand "Blogs" node<br />
And I follow "Add a new entry"<br />
And I fill the moodle form with:<br />
| Entry title | I'm the name |<br />
| Blog entry body | I'm the description |<br />
When I press "Save changes"<br />
Then I should see "Blog entries"<br />
And I should see "I'm the description"<br />
And I should not see "Required"<br />
</code><br />
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)<br />
#: <code language="text"><br />
@core @core_blog<br />
Feature: Add a blog entry<br />
In order to let the world know about me<br />
As a user<br />
I need to write blog entries<br />
<br />
@javascript<br />
Scenario: Add a blog entry with valid data<br />
Given I log in as "admin"<br />
And I expand "My profile" node<br />
And I expand "Blogs" node<br />
And I follow "Add a new entry"<br />
And I fill the moodle form with:<br />
| Entry title | I'm the name |<br />
| Blog entry body | I'm the description |<br />
When I press "Save changes"<br />
Then I should see "View all of my entries"<br />
And I should see "I'm a description"<br />
And I should not see "Required"<br />
</code><br />
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''<br />
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)<br />
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''<br />
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed<br />
<br />
You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.<br />
<br />
For detailed steps and/or troubleshooting:<br />
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests<br />
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features<br />
<br />
== Requirements ==<br />
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)<br />
* Other dependencies are managed by the composer installer<br />
<br />
== Installation ==<br />
* Edit config.php<br />
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions<br />
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''<br />
* Download composer<br />
** '''cd /your/moodle/dirroot'''<br />
** '''curl http://getcomposer.org/installer | php'''<br />
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':<br />
**** Download '''http://getcomposer.org/installer'''<br />
**** Store it in /your/moodle/dirroot/composerinstaller.php for example<br />
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')<br />
* Install behat dependencies and enable the test environment<br />
** '''cd /your/moodle/dirroot'''<br />
** '''php admin/tool/behat/cli/init.php'''<br />
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium<br />
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"<br />
<br />
== Running tests ==<br />
# Start the PHP built-in web server<br />
#* Open a command line interface and '''cd /to/your/moodle/dirroot'''<br />
#* '''php -S localhost:8000''' (This is the default address, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage)<br />
#** ''There is something crazy going on here. Thit advice seems to assume that you have $CFG->wwwroot set to 'http://localhost:8000', but it does not acutally tell you to set that anywhere, and if you do that, it will break your normal install. Please could someone sort out these instructions.''<br />
# (Optional) Start the Selenium server (in case you want to run tests that involves Javascript)<br />
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''<br />
# Run Behat<br />
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)<br />
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''<br />
#* If you followed all the steps and you receive an unknown weird error probably your system's Firefox version is not compatible with the Selenium version you are running, try downloading the latest Selenium release from it's website as explained above<br />
# (Optional) If you are adding new tests or steps definitions update the tests list:<br />
#* '''php admin/tool/behat/cli/util.php --enable'''<br />
# (Optional) Disable test environment (in case you want to use the PHP built-in web server for regular moodle environment)<br />
#* '''php admin/tool/behat/cli/util.php --disable'''<br />
<br />
<br />
'''Note that if you have the HTTP_PROXY environemnt variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''<br />
<br />
=== Tests filters ===<br />
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are few tags that you might be interested in:<br />
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.<br />
* '''@_only_local''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.<br />
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.<br />
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.<br />
<br />
=== Output formats ===<br />
<br />
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format.<br />
<br />
== Advanced usage ==<br />
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.<br />
<br />
* '''Different test server URL''', by default the test web server only can be accessed in localhost. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''<br />
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers... <br />
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.<br />
<br />
<code language="php"><br />
$CFG->behat_config = array(<br />
'default' => array(<br />
'extensions' => array(<br />
'Behat\MinkExtension\Extension' => array(<br />
'selenium2' => array(<br />
'browser' => 'chrome'<br />
)<br />
)<br />
)<br />
)<br />
);<br />
</code><br />
<br />
:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.<br />
* '''Switch completely to test environment''', DON'T USE THIS SETTING IN PRODUCTION SITES! all the site users would be using the test environment instead of the regular one with your courses and all your data and they wouldn't be able to login in your site; this setting should only be used in development/testing installations. It's purpose is to ease the integration with cloud-based continuous integration systems, another possible use is to allow acceptance testing in a development environment without PHP 5.4.<br />
** Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.<br />
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.<br />
<br />
== Writing features ==<br />
<br />
All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.<br />
<br />
Once you decided which functionality you want to specify as a feature you should:<br />
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file<br />
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem<br />
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:<br />
#: <code lang="text">@plugintype @plugintype_pluginname<br />
Feature: FEATURENAME<br />
In order to ... // Why this feature is useful<br />
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'<br />
I need to ... // The feature we want</code><br />
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected<br />
# For each scenario you thought:<br />
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected<br />
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)<br />
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work. Remember to use ''Given'', ''When'' and ''Then'' in a way that reflects what the scenario is testing<br />
## Copy the list of steps to the .feature file with the Scenario header:<br />
##: <code lang="text">Scenario: Short description of the scenario<br />
Given step 1<br />
And step 2<br />
And step 3<br />
When step 4<br />
And step 5<br />
Then step 6</code><br />
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline<br />
##: <code lang="text">@javascript<br />
Scenario: Short description of the scenario<br />
...<br />
...</code><br />
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.<br />
# Add extra tags to the scenario or the feature if required<br />
#* If there are scenarios that includes files uploads they should be tagged as @_only_local<br />
#* If there are scenarios that are likely to fail in some browser-OS combinations they can be tagged as @_cross_browser, they will be tested in different OS / browser combinations by Moodle HQ continuous integration servers<br />
<br />
=== Available steps ===<br />
<br />
Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:<br />
* Processes to set up the environment<br />
* Actions that provokes an event<br />
* Checkings to ensure the outcomes are the expected ones<br />
<br />
[[File:Acceptance_testing_UI_2.5.png]]<br />
<br />
=== Tips ===<br />
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)<br />
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)<br />
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.<br />
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''<br />
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary<br />
<br />
=== Providing values to steps ===<br />
Most of the steps requires values, there are four methods to provide values to steps, the method depends on the step specification, you can know when a steps requires a value because you will see a drop down menu with a closed list of options that the step accepts as argument or an upper case string between double quotes, something like '''I press "BUTTON_STRING"''' or it ends with a ''':''' . The three methods are:<br />
* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''<br />
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''<br />
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.<br />
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, in the 'Acceptance testing' interface you can see a dropdown menu to select one of these options:<br />
** field - for searching a field by its id, name, value or label<br />
** fieldset - for searching a fieldset by it's id or legend<br />
** link - for searching a link by its href, id, title, img alt or value<br />
** button - for searching a button by its name, id, value, img alt or title<br />
** link_or_button - for searching for both, links and buttons<br />
** select - for searching a select field by its id, name or label<br />
** checkbox - for searching a checkbox by its id, name, or label<br />
** radio - for searching a radio button by its id, name, or label<br />
** file - for searching a file input by its id, name, or label<br />
** optgroup - for searching optgroup by its label<br />
** option - for searching an option by its content<br />
** table - for searching a table by its id or caption<br />
** css_element - for searching an element by its CSS selector<br />
** xpath_element - for searching an element by its XPath<br />
<br />
==== Uploading files ====<br />
Note than some tests requires files to be uploaded, in this case<br />
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page<br />
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*<br />
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example) <br />
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.<br />
* The scenarios that includes files uploading should be tagged using the '''@_only_local''' tag<br />
<br />
=== Fixtures ===<br />
<br />
As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.<br />
<br />
==== Available elements ====<br />
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings. <br />
<br />
The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.<br />
<br />
* Course categories<br />
** The required field is idnumber<br />
** References between parent/children by their idnumber, using the "category" field<br />
Given the following "categories" exists:<br />
| name | category | idnumber |<br />
| Category 1 | 0 | CAT1 |<br />
| Category 2 | CAT1 | CAT2 |<br />
<br />
* Courses<br />
** The required field is shortname<br />
** Uses the category idnumber as category reference<br />
Given the following "courses" exists:<br />
| fullname | shortname | category | format | <br />
| Course 1 | COURSE1 | CAT1 | topics |<br />
| Course 2 | COURSE2 | CAT2 | |<br />
<br />
* Groups<br />
** The required fields are course and idnumber<br />
** Uses the course shortname as course reference<br />
Given the following "groups" exists:<br />
| name | description | course | idnumber |<br />
| Group 1 | Anything | COURSE1 | GROUP1 |<br />
<br />
* Groupings<br />
** The required fields are course and idnumber<br />
** Uses the course shortname as course reference<br />
Given the following "groupings" exists:<br />
| name | course | idnumber |<br />
| Grouping 1 | COURSE1 | GROUPING1 |<br />
| Grouping 2 | COURSE1 | GROUPING2 |<br />
<br />
* Users<br />
** The required field is username (if password is not set username value will be used as password too)<br />
Given the following "users" exists:<br />
| username | email | firstname | lastname |<br />
| testuser | asd@asd.com | Test | User |<br />
<br />
* Course enrolments<br />
** The required fields are user, course and role<br />
** Uses the course shortname as course reference<br />
** Uses the user username as user reference<br />
** Uses the role shortname as role reference<br />
** Uses the enrolment name as enrol reference<br />
Given the following "course enrolments" exists:<br />
| user | course | role | enrol |<br />
| testuser | COURSE1 | editingteacher | manual |<br />
<br />
* System role assigns<br />
** The required fields are user and role<br />
** Uses the user username as user reference<br />
** Uses the role shortname as role reference<br />
Given the following "system role assigns" exists:<br />
| user | role |<br />
| testuser | manager |<br />
<br />
* Group members<br />
** The required fields are user and group<br />
** Uses the group idnumber as group reference<br />
** Uses the user username as user reference<br />
Given the following "group members" exists:<br />
| user | group |<br />
| testuser | GROUP1 |<br />
<br />
* Grouping groups<br />
** The required fields are grouping and group<br />
** Uses the group idnumber as group reference<br />
** Uses the grouping idnumber as grouping reference<br />
Given the following "grouping groups" exists:<br />
| grouping | group |<br />
| GROUPING1 | GROUP1 |<br />
<br />
* Cohorts<br />
** The required field is idnumber<br />
Given the following "cohorts" exists:<br />
| name | idnumber |<br />
| Cohort 1 | COHORT1 |<br />
<br />
=== Features check list ===<br />
* It's a new feature or a new scenario of an existing feature<br />
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)<br />
* Are using the appropriate Moodle component tag and includes @_only_local or @_cross_browser when required<br />
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features<br />
* Covers both JS and non-JS environments<br />
<br />
== Adding steps definitions ==<br />
<br />
Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.<br />
<br />
As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.<br />
<br />
=== Example ===<br />
<br />
You can use this example below or any of the existing steps definitions as a template.<br />
<br />
* auth/tests/behat/behat_auth.php<br />
class behat_auth extends behat_base {<br />
/**<br />
* Logs in the user. There should exist a user with the same value as username and password<br />
*<br />
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/<br />
*/<br />
public function i_log_in_as($username) {<br />
return array(new Given('I am on homepage'),<br />
new Given('I follow "Login"'),<br />
new Given('I fill in "Username" with "'.$username.'"'),<br />
new Given('I fill in "Password" with "'.$username.'"'),<br />
new Given('I press "Login"'),<br />
new Given('I should see "You are logged in as"'));<br />
}<br />
}<br />
<br />
=== Tips ===<br />
<br />
If you are creating a completely new step definition there are also a few things to consider:<br />
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both<br />
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem<br />
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''<br />
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure<br />
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.<br />
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)<br />
<br />
<br />
If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''<br />
<br />
=== Check list ===<br />
<br />
New steps should be/have:<br />
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension<br />
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)<br />
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)<br />
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component<br />
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem<br />
* Describe the regular expression with the most appropriate tag inside the method doc comment:<br />
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')<br />
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')<br />
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')<br />
* Depending on the inputs your definition expects you must use a different regular expression:<br />
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')<br />
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')<br />
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table<br />
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)<br />
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')<br />
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)<br />
<br />
== Links == <br />
* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]<br />
* Technical info: [[Behat integration]]<br />
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html<br />
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors<br />
* See Also [https://tracker.moodle.org/browse/MDL-37046 MDL37046] for clear instruction<br />
[[Category:Behat]][[Category:Quality Assurance]]<br />
<br />
[[es:Prueba de aceptación]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=32585NanoGong/Converting to Moodle 2.02012-02-27T15:07:19Z<p>Nakohdo: </p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
'''Note''': Just copied over from http://moodle.org/mod/forum/post.php?reply=807695 --[[User:Frank Ralf|Frank Ralf]] 17:49, 13 September 2011 (WST)<br />
<br />
In response to Frank's request to join forces I thought I'd give it a shot and happy to let ya all know that I've managed to make it work as a dataform field:<br />
<br />
It is still just a stub and at any rate the implementation assumes all kinds of things the dataform does, so the code itself may not be very useful. But the approach and some relevant bits of code may help so here's a summary and if you have any questions just let me know.<br />
<br />
I basically create a draft area and pass the draft item id to the uploading php script which resides in a designated file. In that script I create an instance of repository_upload and call its upload method:<br />
<br />
<code php><br />
$repo = new repository_upload($repo_id, null, array('ajax'=>true, 'name'=>'', 'type'=>'upload')); <br />
try {<br />
$ret = $repo->upload($saveas_filename, $maxbytes);<br />
} catch (moodle_exception $e) {<br />
print $e->errorcode;<br />
die;<br />
}<br />
print $saveas_filename. ' uploaded';<br />
</code><br />
<br />
The repository_upload looks for the uploaded file in a specific place and this place should be indicated in the javascript call in the upload button (btw, just a standard button, not a submit):<br />
<br />
<code php><br />
var ret = recorder.sendGongRequest('PostToForm',<br />
inputpage,<br />
'repo_upload_file',<br />
'',<br />
filename);<br />
</code><br />
<br />
Then all that remains is to fetch the file from the draft area and store it in a proper area.<br />
<br />
I use the repository_upload because I like to reuse existing code as much as possible. This may or may not be the best way. I'll look into that more thoroughly when I return to finalize the field.<br />
<br />
=== Further references ===<br />
* [[Repository API]]<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=32584NanoGong/Converting to Moodle 2.02012-02-27T15:07:03Z<p>Nakohdo: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
<br />
{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
'''Note''': Just copied over from http://moodle.org/mod/forum/post.php?reply=807695 --[[User:Frank Ralf|Frank Ralf]] 17:49, 13 September 2011 (WST)<br />
<br />
In response to Frank's request to join forces I thought I'd give it a shot and happy to let ya all know that I've managed to make it work as a dataform field:<br />
<br />
It is still just a stub and at any rate the implementation assumes all kinds of things the dataform does, so the code itself may not be very useful. But the approach and some relevant bits of code may help so here's a summary and if you have any questions just let me know.<br />
<br />
I basically create a draft area and pass the draft item id to the uploading php script which resides in a designated file. In that script I create an instance of repository_upload and call its upload method:<br />
<br />
<code php><br />
$repo = new repository_upload($repo_id, null, array('ajax'=>true, 'name'=>'', 'type'=>'upload')); <br />
try {<br />
$ret = $repo->upload($saveas_filename, $maxbytes);<br />
} catch (moodle_exception $e) {<br />
print $e->errorcode;<br />
die;<br />
}<br />
print $saveas_filename. ' uploaded';<br />
</code><br />
<br />
The repository_upload looks for the uploaded file in a specific place and this place should be indicated in the javascript call in the upload button (btw, just a standard button, not a submit):<br />
<br />
<code php><br />
var ret = recorder.sendGongRequest('PostToForm',<br />
inputpage,<br />
'repo_upload_file',<br />
'',<br />
filename);<br />
</code><br />
<br />
Then all that remains is to fetch the file from the draft area and store it in a proper area.<br />
<br />
I use the repository_upload because I like to reuse existing code as much as possible. This may or may not be the best way. I'll look into that more thoroughly when I return to finalize the field.<br />
<br />
=== Further references ===<br />
* [[Repository API]]<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Git_for_Administrators&diff=30404Git for Administrators2011-11-06T15:27:51Z<p>Nakohdo: </p>
<hr />
<div>See [https://docs.moodle.org/20/en/Installing_Moodle_from_Git_repository Installing Moodle from Git repository]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Git_for_Administrators&diff=30403Git for Administrators2011-11-06T15:27:05Z<p>Nakohdo: manual redirect as automatic #REDIRECT doesn't work across wikis</p>
<hr />
<div>See [https://docs.moodle.org/20/en/Installing_Moodle_from_Git_repository]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Git_for_Administrators&diff=30402Git for Administrators2011-11-06T15:24:49Z<p>Nakohdo: Redirected page to Installing Moodle from Git repository</p>
<hr />
<div>#REDIRECT [[Installing_Moodle_from_Git_repository]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Git_for_Administrators&diff=30401Git for Administrators2011-11-06T15:24:19Z<p>Nakohdo: redirect to already exisiting page</p>
<hr />
<div>#REDIRECT [https://docs.moodle.org/20/en/Installing_Moodle_from_Git_repository]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=29401NanoGong/Converting to Moodle 2.02011-09-13T09:49:53Z<p>Nakohdo: /* Itamar' first shot */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
'''Note''': Just copied over from http://moodle.org/mod/forum/post.php?reply=807695 --[[User:Frank Ralf|Frank Ralf]] 17:49, 13 September 2011 (WST)<br />
<br />
In response to Frank's request to join forces I thought I'd give it a shot and happy to let ya all know that I've managed to make it work as a dataform field:<br />
<br />
It is still just a stub and at any rate the implementation assumes all kinds of things the dataform does, so the code itself may not be very useful. But the approach and some relevant bits of code may help so here's a summary and if you have any questions just let me know.<br />
<br />
I basically create a draft area and pass the draft item id to the uploading php script which resides in a designated file. In that script I create an instance of repository_upload and call its upload method:<br />
<br />
<code php><br />
$repo = new repository_upload($repo_id, null, array('ajax'=>true, 'name'=>'', 'type'=>'upload')); <br />
try {<br />
$ret = $repo->upload($saveas_filename, $maxbytes);<br />
} catch (moodle_exception $e) {<br />
print $e->errorcode;<br />
die;<br />
}<br />
print $saveas_filename. ' uploaded';<br />
</code><br />
<br />
The repository_upload looks for the uploaded file in a specific place and this place should be indicated in the javascript call in the upload button (btw, just a standard button, not a submit):<br />
<br />
<code php><br />
var ret = recorder.sendGongRequest('PostToForm',<br />
inputpage,<br />
'repo_upload_file',<br />
'',<br />
filename);<br />
</code><br />
<br />
Then all that remains is to fetch the file from the draft area and store it in a proper area.<br />
<br />
I use the repository_upload because I like to reuse existing code as much as possible. This may or may not be the best way. I'll look into that more thoroughly when I return to finalize the field.<br />
<br />
=== Further references ===<br />
* [[Repository API]]<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=29400NanoGong/Converting to Moodle 2.02011-09-13T09:49:01Z<p>Nakohdo: /* Itamar' first shot */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
'''Note''': Just copied over from http://moodle.org/mod/forum/post.php?reply=807695 --[[User:Frank Ralf|Frank Ralf]] 17:49, 13 September 2011 (WST)<br />
<br />
In response to Frank's request to join forces I thought I'd give it a shot and happy to let ya all know that I've managed to make it work as a dataform field:<br />
<br />
It is still just a stub and at any rate the implementation assumes all kinds of things the dataform does, so the code itself may not be very useful. But the approach and some relevant bits of code may help so here's a summary and if you have any questions just let me know.<br />
<br />
I basically create a draft area and pass the draft item id to the uploading php script which resides in a designated file. In that script I create an instance of repository_upload and call its upload method:<br />
<br />
<code php><br />
$repo = new repository_upload($repo_id, null, array('ajax'=>true, 'name'=>'', 'type'=>'upload')); <br />
try {<br />
$ret = $repo->upload($saveas_filename, $maxbytes);<br />
} catch (moodle_exception $e) {<br />
print $e->errorcode;<br />
die;<br />
}<br />
print $saveas_filename. ' uploaded';<br />
</code><br />
<br />
The repository_upload looks for the uploaded file in a specific place and this place should be indicated in the javascript call in the upload button (btw, just a standard button, not a submit):<br />
<br />
<<code php><br />
var ret = recorder.sendGongRequest('PostToForm',<br />
inputpage,<br />
'repo_upload_file',<br />
'',<br />
filename);<br />
</code><br />
<br />
Then all that remains is to fetch the file from the draft area and store it in a proper area.<br />
<br />
I use the repository_upload because I like to reuse existing code as much as possible. This may or may not be the best way. I'll look into that more thoroughly when I return to finalize the field.<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=29399NanoGong/Converting to Moodle 2.02011-09-13T09:47:41Z<p>Nakohdo: /* Itamar' first shot */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
{{Note|<br />
Just copied over from http://moodle.org/mod/forum/post.php?reply=807695<br />
}}<br />
<br />
In response to Frank's request to join forces I thought I'd give it a shot and happy to let ya all know that I've managed to make it work as a dataform field:<br />
<br />
It is still just a stub and at any rate the implementation assumes all kinds of things the dataform does, so the code itself may not be very useful. But the approach and some relevant bits of code may help so here's a summary and if you have any questions just let me know.<br />
<br />
I basically create a draft area and pass the draft item id to the uploading php script which resides in a designated file. In that script I create an instance of repository_upload and call its upload method:<br />
<br />
<code php><br />
$repo = new repository_upload($repo_id, null, array('ajax'=>true, 'name'=>'', 'type'=>'upload')); <br />
try {<br />
$ret = $repo->upload($saveas_filename, $maxbytes);<br />
} catch (moodle_exception $e) {<br />
print $e->errorcode;<br />
die;<br />
}<br />
print $saveas_filename. ' uploaded';<br />
</code><br />
<br />
The repository_upload looks for the uploaded file in a specific place and this place should be indicated in the javascript call in the upload button (btw, just a standard button, not a submit):<br />
<br />
<<code php><br />
var ret = recorder.sendGongRequest('PostToForm',<br />
inputpage,<br />
'repo_upload_file',<br />
'',<br />
filename);<br />
</code><br />
<br />
Then all that remains is to fetch the file from the draft area and store it in a proper area.<br />
<br />
I use the repository_upload because I like to reuse existing code as much as possible. This may or may not be the best way. I'll look into that more thoroughly when I return to finalize the field.<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=29398NanoGong/Converting to Moodle 2.02011-09-13T09:45:39Z<p>Nakohdo: /* Itamar' first shot */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
In response to Frank's request to join forces I thought I'd give it a shot and happy to let ya all know that I've managed to make it work as a dataform field:<br />
<br />
It is still just a stub and at any rate the implementation assumes all kinds of things the dataform does, so the code itself may not be very useful. But the approach and some relevant bits of code may help so here's a summary and if you have any questions just let me know.<br />
<br />
I basically create a draft area and pass the draft item id to the uploading php script which resides in a designated file. In that script I create an instance of repository_upload and call its upload method:<br />
<br />
<code php><br />
$repo = new repository_upload($repo_id, null, array('ajax'=>true, 'name'=>'', 'type'=>'upload')); <br />
try {<br />
$ret = $repo->upload($saveas_filename, $maxbytes);<br />
} catch (moodle_exception $e) {<br />
print $e->errorcode;<br />
die;<br />
}<br />
print $saveas_filename. ' uploaded';<br />
</code><br />
<br />
The repository_upload looks for the uploaded file in a specific place and this place should be indicated in the javascript call in the upload button (btw, just a standard button, not a submit):<br />
<br />
<<code php><br />
var ret = recorder.sendGongRequest('PostToForm',<br />
inputpage,<br />
'repo_upload_file',<br />
'',<br />
filename);<br />
</code><br />
<br />
Then all that remains is to fetch the file from the draft area and store it in a proper area.<br />
<br />
I use the repository_upload because I like to reuse existing code as much as possible. This may or may not be the best way. I'll look into that more thoroughly when I return to finalize the field.<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=29397NanoGong/Converting to Moodle 2.02011-09-13T09:44:57Z<p>Nakohdo: /* See also */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== Itamar' first shot ==<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Repository_API&diff=29393Repository API2011-09-12T18:10:43Z<p>Nakohdo: </p>
<hr />
<div>{{Moodle_2.0}}<br />
<br />
<p class="note"><br />
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 endeavor to merge all such suggestions into the further development and fix all kinds of problems.<br />
</p><br />
<br />
Note that parts of this document have been now split off into a separate [[File_API]]<br />
<br />
==Objectives==<br />
<br />
# Allow all Moodle users to easily bring content into Moodle from external repositories<br />
# Provide a consistent interface to any external repository, for any Moodle module<br />
<br />
==Use cases==<br />
<br />
===Teacher adding an external file as a new resource===<br />
<br />
# Teacher wants to add a new resource to a course <br />
# Teacher clicks the "Choose a resource" button<br />
# Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)<br />
# Teacher chooses a file in an external repository<br />
# File is COPIED into Moodle and stored by the resource module<br />
# File is marked as owned by that user<br />
# Whenever someone wants to view that file, the resource module controls access (see [[File API]] )<br />
<br />
===Teacher linking to an external file as a new resource (think video repository) ===<br />
<br />
# Teacher wants to display a file in the repository <br />
# Teacher clicks the "Choose a resource" button<br />
# Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)<br />
# Teacher chooses a file in an external repository<br />
# Link to the file is COPIED into Moodle and stored by the resource module<br />
# Link is marked as owned by that user<br />
# Whenever someone wants to follow that link, the resource module controls access (see [[File API]] )<br />
<br />
===Student submitting an assignment===<br />
# Student needs to submit an assignment and presses the "Choose files" button<br />
# 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])<br />
# Student chooses MySpace from the list<br />
# 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)<br />
# Student sees their files in MySpace and chooses one or more<br />
# Files are copied from MySpace to Moodle <br />
# Assignment module controls the permissions so that only the Student and assignment graders can see the file (other students would not have permission).<br />
<br />
===Student attaching an image to a forum===<br />
# Student needs to attach an image and presses the "Choose files" button in the posting screen<br />
# Student sees a "file picker" where they can see files listed on any of several configured repositories<br />
# Student chooses Mahara from the list<br />
# Student is prompted to enter Mahara username/password<br />
# Student sees their files in Mahara and chooses one image<br />
# Image is copied to Moodle <br />
# Image file is attached to forum post by Forum module (by reference)<br />
# Forum module controls permissions so that anyone who can read that forum can see that file<br />
<br />
===Student attaching the same image in another forum===<br />
<br />
# Student needs to submit an assignment and presses the "Choose files" button<br />
# Student sees a "file picker" where they can see files listed on any of several configured repositories<br />
# Student chooses "Local files" from the list and sees all the files they've permission to use<br />
# A COPY of the image file is attached to forum post by Forum module<br />
# Forum module controls access to this file.<br />
<br />
<br />
<br />
Please add more use cases in this same format<br />
<br />
==Mock screenshots==<br />
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):<br />
<br />
[[Image:Filepicker_login.jpg]]<br />
<br />
Browsing files could look something like this:<br />
<br />
[[Image:Filepicker_browser.jpg]]<br />
<br />
And you can also search:<br />
<br />
[[Image:Filepicker_search.jpg]]<br />
<br />
==General architecture==<br />
<br />
Each repository plugin (a standard Moodle plugin stored under /repository/xxx) will subclass the standard API and override methods specific to that repository.<br />
<br />
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.<br />
<br />
Once a repository has been used the file will usually be copied into Moodle there and then. However there will also be options to:<br />
* only return the URL to the file if it's desired to keep it external (but this does present security and integrity risks), or<br />
* refresh the local file copy regularly and automatically<br />
* refresh the file manually if desired<br />
<br />
Once in Moodle, it is subject to the [[File API]] for access control like any other file.<br />
<br />
==Repository requirements==<br />
<br />
From the Moodle point of view, each repository is just a hierarchy of nodes.<br />
<br />
The repository MUST provide:<br />
# A URI to download each node (eg file).<br />
# 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).<br />
<br />
The repository can OPTIONALLY:<br />
# Require some authentication credentials <br />
# Provide more metadata about each node (mime type, size, dates, related files, dublin core stuff, etc)<br />
# Describe a search facility (so that Moodle can construct a search form)<br />
# Provide copyright and usage rules (or just information about the rules)<br />
<br />
==Repository plugins==<br />
<br />
Some plugins I'd like to see developed for the first version are:<br />
* box - an interface to [http://box.net box.net]<br />
* mahara - an interface to a Mahara installation<br />
* Server Files - very similar to the current course-based file manager, except user-based<br />
* Remote Moodle - an interface to another Moodle site, accessed over a secure mnet connection<br />
* googledocs - an interface to [http://docs.google.com Google Docs]<br />
* s3 - an interface to [http://www.amazon.com/gp/browse.html?node=16427261 Amazon S3]<br />
* flickr - an interface to [http://flickr.com flickr]<br />
* WebDAV - to access arbitrary external WebDAV servers<br />
* merlot - an interface to the learning materials in [http://www.merlot.org/merlot/materials.htm Merlot.org]<br />
* File System - a plugin to list files on local file system, of course, you can mount remote files to this local directory<br />
* youtube - an interface to [http://youtube.com YouTube]<br />
* jsr170 - an interface that can talk to anything that supports jsr170 (eg [http://www.alfresco.com/ Alfresco])<br />
* oki - an OKI emulator allowing us to access things with OKI interfaces,like [http://www.fedora.info/ Fedora]<br />
* briefcase - an interface to [http://briefcase.yahoo.com/ Yahoo Briefcase]<br />
* myspace - an interface to MySpace files (perhaps via [http://www.programmableweb.com/api/myspace this MySpace API])<br />
* skydrive - an interface to Microsoft's [http://skydrive.live.com/ SkyDrive] files<br />
* Dropbox - an interface to Dropbox files [http://www.dropbox.com]<br />
* facebook - an interface to Facebook files<br />
* [http://www.dspace.org/ Dspace] - a repository from MIT<br />
* DOOR - another popular open source repository<br />
* 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.<br />
<br />
==Tables==<br />
<br />
=== repository ===<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|'''Field''' <br />
|'''Type''' <br />
|'''Default''' <br />
|'''Info''' <br />
<br />
|-<br />
|'''id'''<br />
|int(10)<br />
|<br />
|autoincrementing <br />
<br />
|-<br />
|'''type'''<br />
|varchar(255)<br />
|<br />
|The type of the repository <br />
<br />
|-<br />
|'''visible'''<br />
|tinyint(1)<br />
|<br />
|<br />
<br />
|-<br />
|sortorder<br />
|int(10)<br />
|<br />
|<br />
|}<br />
<br />
=== repository_instances ===<br />
<br />
This table contains one entry for every configured external repository instance.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|'''Field''' <br />
|'''Type''' <br />
|'''Default''' <br />
|'''Info''' <br />
<br />
|-<br />
|'''id'''<br />
|int(10)<br />
|<br />
|autoincrementing <br />
<br />
|-<br />
|name<br />
|varchar 255<br />
|<br />
|A custom name for this repository (non-unique)<br />
<br />
|-<br />
|'''typeid''' <br />
|int(10)<br />
| <br />
|The id of repository type<br />
<br />
|-<br />
|'''userid''' <br />
|int(10)<br />
| <br />
|The person who created this repository instance<br />
<br />
|-<br />
|'''contextid''' <br />
|int(10)<br />
| <br />
|The context that this repository is available to ( = system context for site-wide ones)<br />
<br />
|-<br />
|username<br />
|varchar(255)<br />
| <br />
|username to log in with, if required (almost never!)<br />
<br />
|-<br />
|password<br />
|varchar(255)<br />
| <br />
|password to log in with, if required (almost never!)<br />
<br />
|-<br />
|timecreated<br />
|int(10)<br />
|<br />
|The time this repository was created<br />
<br />
|-<br />
|timemodified<br />
|int(10)<br />
|<br />
|The last time the repository was modified<br />
|}<br />
<br />
=== repository_instance_config ===<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|'''Field''' <br />
|'''Type''' <br />
|'''Default''' <br />
|'''Info''' <br />
<br />
|-<br />
|'''id'''<br />
|int(10)<br />
|<br />
|autoincrementing <br />
<br />
|-<br />
|'''instanceid'''<br />
|int(int)<br />
|<br />
|<br />
<br />
|-<br />
|'''name'''<br />
|varchar(255)<br />
|<br />
|<br />
<br />
|-<br />
|value<br />
|Text<br />
|<br />
|<br />
|}<br />
<br />
===File types===<br />
<br />
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). <br />
<br />
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).<br />
<br />
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<br />
<br />
==Technical walkthrough==<br />
<br />
(See also the functional spec for the [[Repository_File_Picker]] )<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Case 1: As part of a Moodleform with Javascript===<br />
<br />
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:<br />
<br />
eg $mform->addElement('filepicker', 'uniqueelementid', $fullname, $data)<br />
<br />
2. When rendering the form, Moodle will display a read-only filename field with an '''"Add 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).<br />
<br />
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)<br />
<br />
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.<br />
<br />
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. <br />
<br />
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. <br />
<br />
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.<br />
<br />
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:<br />
<br />
eg $mform->store_local_file('uniqueelementid', $context, $filearename, $itemid, $filepath);<br />
<br />
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).<br />
<br />
===Case 2: As part of a Moodleform without Javascript===<br />
<br />
Steps 1-2 are the same as for the case with Javascript.<br />
<br />
3. The add file button is a submit button for the form with a different value. When the add file button is pressed,<br />
* the whole form will be ''submitted'' to the original location (but with a different submit button value)<br />
* 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<br />
* moodleforms get_data() then redirects the user to a new page showing the main picker interface<br />
<br />
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.<br />
<br />
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.<br />
<br />
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).<br />
<br />
Steps 8-9 are the same as for the case with Javascript.<br />
<br />
===Case 3: As part of a HTML editor===<br />
<br />
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.<br />
<br />
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'''<br />
<br />
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.)<br />
<br />
3. The path parameter also needs to be added to the editor configuration in the current page.<br />
<br />
4. Editor plugins can be modified to look for these variables in the editor configuration.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Repository plugins==<br />
<br />
===Required elements===<br />
<br />
Each repository plugin is required to contain the following elements:<br />
<br />
====class repository()====<br />
<br />
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<br />
<br />
===Optional elements===<br />
<br />
Repositories can redefine any of these methods as required (and in some instances, MUST redefine them):<br />
<br />
====__construct($repositoryid, $contextid, $options=array(), $readonly)====<br />
<br />
'''MUST''' redefine<br />
<br />
Accept necessary parameters, and do initialization of repository.<br />
<br />
====get_file($url, $file = '')====<br />
<br />
Given a URL, download a file from there, save the file in a temporary directory.<br />
<br />
====get_link($info)====<br />
Get the url of external resource<br />
<br />
====get_listing($path='/', $page='''''''')====<br />
<br />
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.<br />
<br />
====search($keyword)====<br />
Search repository by given keyword, it will return an array of the same format of get_listing<br />
<br />
====print_login()====<br />
<br />
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.<br />
<br />
====print_search==== <br />
<br />
Print the search form, it will return a json string<br />
<br />
====get_meta()====<br />
Return information for creating ajax request, it is private function, you don't need to rewrite it.<br />
<br />
====create()====<br />
Create an instance<br />
<br />
====delete()====<br />
Delete this instance from `repository` table<br />
<br />
====hide()====<br />
Hide a repository instance from file picker list<br />
<br />
====set_option()====<br />
set options in data1-data5 fields, can be overrided<br />
<br />
====get_option()====<br />
get option list or a specific option from database<br />
<br />
====get_type_option_names()====<br />
If this plugin needs admin settings, please refine this function to return option names.<br />
<br />
====type_config_form()====<br />
If get_type_option_names return non empty array, this function '''MUST''' redefine, it will help to build the setting form.<br />
<br />
====type_form_validation()====<br />
This function can be used for validating the data submitted by plugin setting form.<br />
<br />
====get_instance_option_names()====<br />
If plugin instance needs settings, this function will return instance option names.<br />
<br />
====instance_config_form()====<br />
If get_instance_option_names return non empty array, this function '''MUST''' redefine, it will help to build the instance setting form.<br />
<br />
====instance_form_validation()====<br />
This function can be used for validating the data submitted by instance setting form.<br />
<br />
====supported_filetypes()====<br />
What file types are supported by this repository plugin, it will return an array, the file type name is defined in a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file in lib/file/file_types.mm<br />
<br />
====supported_returntypes()====<br />
The repository plugin could support external link or copying files to moodle. If the plugin support file link only, developer should override this function to return FILE_EXTERNAL, if plugin support copying file only, it should return FILE_INTERNAL, by default, plugin supports both.<br />
<br />
====filter()====<br />
Filter file listing to exclude specific file types<br />
<br />
===icon.png===<br />
<br />
A logo that represents the repository. Ideally square but we should handle all sizes.<br />
<br />
==See also==<br />
<br />
* [[Repository Administration Specification]]<br />
* [[Repository Interface for Moodle/Course/User]]<br />
* [[Repository plugins]]<br />
* [[Repository File Picker]]<br />
* [[File API]]<br />
* [[Portfolio API]]<br />
* MDL-13766 and MDL-16543 Repository API Meta issues<br />
<br />
[[Category:Repositories]]<br />
<br />
[[ja:開発:リポジトリAPI]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Repository_API&diff=29392Repository API2011-09-12T18:07:06Z<p>Nakohdo: note template added</p>
<hr />
<div>{{Moodle_2.0}}<br />
<br />
{{Note|<br />
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 further development and fix all kinds of problems.<br />
}}<br />
<br />
Note that parts of this document have been now split off into a separate [[File_API]]<br />
<br />
==Objectives==<br />
<br />
# Allow all Moodle users to easily bring content into Moodle from external repositories<br />
# Provide a consistent interface to any external repository, for any Moodle module<br />
<br />
==Use cases==<br />
<br />
===Teacher adding an external file as a new resource===<br />
<br />
# Teacher wants to add a new resource to a course <br />
# Teacher clicks the "Choose a resource" button<br />
# Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)<br />
# Teacher chooses a file in an external repository<br />
# File is COPIED into Moodle and stored by the resource module<br />
# File is marked as owned by that user<br />
# Whenever someone wants to view that file, the resource module controls access (see [[File API]] )<br />
<br />
===Teacher linking to an external file as a new resource (think video repository) ===<br />
<br />
# Teacher wants to display a file in the repository <br />
# Teacher clicks the "Choose a resource" button<br />
# Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)<br />
# Teacher chooses a file in an external repository<br />
# Link to the file is COPIED into Moodle and stored by the resource module<br />
# Link is marked as owned by that user<br />
# Whenever someone wants to follow that link, the resource module controls access (see [[File API]] )<br />
<br />
===Student submitting an assignment===<br />
# Student needs to submit an assignment and presses the "Choose files" button<br />
# 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])<br />
# Student chooses MySpace from the list<br />
# 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)<br />
# Student sees their files in MySpace and chooses one or more<br />
# Files are copied from MySpace to Moodle <br />
# Assignment module controls the permissions so that only the Student and assignment graders can see the file (other students would not have permission).<br />
<br />
===Student attaching an image to a forum===<br />
# Student needs to attach an image and presses the "Choose files" button in the posting screen<br />
# Student sees a "file picker" where they can see files listed on any of several configured repositories<br />
# Student chooses Mahara from the list<br />
# Student is prompted to enter Mahara username/password<br />
# Student sees their files in Mahara and chooses one image<br />
# Image is copied to Moodle <br />
# Image file is attached to forum post by Forum module (by reference)<br />
# Forum module controls permissions so that anyone who can read that forum can see that file<br />
<br />
===Student attaching the same image in another forum===<br />
<br />
# Student needs to submit an assignment and presses the "Choose files" button<br />
# Student sees a "file picker" where they can see files listed on any of several configured repositories<br />
# Student chooses "Local files" from the list and sees all the files they've permission to use<br />
# A COPY of the image file is attached to forum post by Forum module<br />
# Forum module controls access to this file.<br />
<br />
<br />
<br />
Please add more use cases in this same format<br />
<br />
==Mock screenshots==<br />
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):<br />
<br />
[[Image:Filepicker_login.jpg]]<br />
<br />
Browsing files could look something like this:<br />
<br />
[[Image:Filepicker_browser.jpg]]<br />
<br />
And you can also search:<br />
<br />
[[Image:Filepicker_search.jpg]]<br />
<br />
==General architecture==<br />
<br />
Each repository plugin (a standard Moodle plugin stored under /repository/xxx) will subclass the standard API and override methods specific to that repository.<br />
<br />
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.<br />
<br />
Once a repository has been used the file will usually be copied into Moodle there and then. However there will also be options to:<br />
* only return the URL to the file if it's desired to keep it external (but this does present security and integrity risks), or<br />
* refresh the local file copy regularly and automatically<br />
* refresh the file manually if desired<br />
<br />
Once in Moodle, it is subject to the [[File API]] for access control like any other file.<br />
<br />
==Repository requirements==<br />
<br />
From the Moodle point of view, each repository is just a hierarchy of nodes.<br />
<br />
The repository MUST provide:<br />
# A URI to download each node (eg file).<br />
# 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).<br />
<br />
The repository can OPTIONALLY:<br />
# Require some authentication credentials <br />
# Provide more metadata about each node (mime type, size, dates, related files, dublin core stuff, etc)<br />
# Describe a search facility (so that Moodle can construct a search form)<br />
# Provide copyright and usage rules (or just information about the rules)<br />
<br />
==Repository plugins==<br />
<br />
Some plugins I'd like to see developed for the first version are:<br />
* box - an interface to [http://box.net box.net]<br />
* mahara - an interface to a Mahara installation<br />
* Server Files - very similar to the current course-based file manager, except user-based<br />
* Remote Moodle - an interface to another Moodle site, accessed over a secure mnet connection<br />
* googledocs - an interface to [http://docs.google.com Google Docs]<br />
* s3 - an interface to [http://www.amazon.com/gp/browse.html?node=16427261 Amazon S3]<br />
* flickr - an interface to [http://flickr.com flickr]<br />
* WebDAV - to access arbitrary external WebDAV servers<br />
* merlot - an interface to the learning materials in [http://www.merlot.org/merlot/materials.htm Merlot.org]<br />
* File System - a plugin to list files on local file system, of course, you can mount remote files to this local directory<br />
* youtube - an interface to [http://youtube.com YouTube]<br />
* jsr170 - an interface that can talk to anything that supports jsr170 (eg [http://www.alfresco.com/ Alfresco])<br />
* oki - an OKI emulator allowing us to access things with OKI interfaces,like [http://www.fedora.info/ Fedora]<br />
* briefcase - an interface to [http://briefcase.yahoo.com/ Yahoo Briefcase]<br />
* myspace - an interface to MySpace files (perhaps via [http://www.programmableweb.com/api/myspace this MySpace API])<br />
* skydrive - an interface to Microsoft's [http://skydrive.live.com/ SkyDrive] files<br />
* Dropbox - an interface to Dropbox files [http://www.dropbox.com]<br />
* facebook - an interface to Facebook files<br />
* [http://www.dspace.org/ Dspace] - a repository from MIT<br />
* DOOR - another popular open source repository<br />
* 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.<br />
<br />
==Tables==<br />
<br />
=== repository ===<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|'''Field''' <br />
|'''Type''' <br />
|'''Default''' <br />
|'''Info''' <br />
<br />
|-<br />
|'''id'''<br />
|int(10)<br />
|<br />
|autoincrementing <br />
<br />
|-<br />
|'''type'''<br />
|varchar(255)<br />
|<br />
|The type of the repository <br />
<br />
|-<br />
|'''visible'''<br />
|tinyint(1)<br />
|<br />
|<br />
<br />
|-<br />
|sortorder<br />
|int(10)<br />
|<br />
|<br />
|}<br />
<br />
=== repository_instances ===<br />
<br />
This table contains one entry for every configured external repository instance.<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|'''Field''' <br />
|'''Type''' <br />
|'''Default''' <br />
|'''Info''' <br />
<br />
|-<br />
|'''id'''<br />
|int(10)<br />
|<br />
|autoincrementing <br />
<br />
|-<br />
|name<br />
|varchar 255<br />
|<br />
|A custom name for this repository (non-unique)<br />
<br />
|-<br />
|'''typeid''' <br />
|int(10)<br />
| <br />
|The id of repository type<br />
<br />
|-<br />
|'''userid''' <br />
|int(10)<br />
| <br />
|The person who created this repository instance<br />
<br />
|-<br />
|'''contextid''' <br />
|int(10)<br />
| <br />
|The context that this repository is available to ( = system context for site-wide ones)<br />
<br />
|-<br />
|username<br />
|varchar(255)<br />
| <br />
|username to log in with, if required (almost never!)<br />
<br />
|-<br />
|password<br />
|varchar(255)<br />
| <br />
|password to log in with, if required (almost never!)<br />
<br />
|-<br />
|timecreated<br />
|int(10)<br />
|<br />
|The time this repository was created<br />
<br />
|-<br />
|timemodified<br />
|int(10)<br />
|<br />
|The last time the repository was modified<br />
|}<br />
<br />
=== repository_instance_config ===<br />
<br />
{| border="1" cellpadding="2" cellspacing="0"<br />
|'''Field''' <br />
|'''Type''' <br />
|'''Default''' <br />
|'''Info''' <br />
<br />
|-<br />
|'''id'''<br />
|int(10)<br />
|<br />
|autoincrementing <br />
<br />
|-<br />
|'''instanceid'''<br />
|int(int)<br />
|<br />
|<br />
<br />
|-<br />
|'''name'''<br />
|varchar(255)<br />
|<br />
|<br />
<br />
|-<br />
|value<br />
|Text<br />
|<br />
|<br />
|}<br />
<br />
===File types===<br />
<br />
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). <br />
<br />
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).<br />
<br />
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<br />
<br />
==Technical walkthrough==<br />
<br />
(See also the functional spec for the [[Repository_File_Picker]] )<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Case 1: As part of a Moodleform with Javascript===<br />
<br />
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:<br />
<br />
eg $mform->addElement('filepicker', 'uniqueelementid', $fullname, $data)<br />
<br />
2. When rendering the form, Moodle will display a read-only filename field with an '''"Add 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).<br />
<br />
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)<br />
<br />
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.<br />
<br />
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. <br />
<br />
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. <br />
<br />
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.<br />
<br />
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:<br />
<br />
eg $mform->store_local_file('uniqueelementid', $context, $filearename, $itemid, $filepath);<br />
<br />
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).<br />
<br />
===Case 2: As part of a Moodleform without Javascript===<br />
<br />
Steps 1-2 are the same as for the case with Javascript.<br />
<br />
3. The add file button is a submit button for the form with a different value. When the add file button is pressed,<br />
* the whole form will be ''submitted'' to the original location (but with a different submit button value)<br />
* 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<br />
* moodleforms get_data() then redirects the user to a new page showing the main picker interface<br />
<br />
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.<br />
<br />
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.<br />
<br />
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).<br />
<br />
Steps 8-9 are the same as for the case with Javascript.<br />
<br />
===Case 3: As part of a HTML editor===<br />
<br />
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.<br />
<br />
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'''<br />
<br />
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.)<br />
<br />
3. The path parameter also needs to be added to the editor configuration in the current page.<br />
<br />
4. Editor plugins can be modified to look for these variables in the editor configuration.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Repository plugins==<br />
<br />
===Required elements===<br />
<br />
Each repository plugin is required to contain the following elements:<br />
<br />
====class repository()====<br />
<br />
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<br />
<br />
===Optional elements===<br />
<br />
Repositories can redefine any of these methods as required (and in some instances, MUST redefine them):<br />
<br />
====__construct($repositoryid, $contextid, $options=array(), $readonly)====<br />
<br />
'''MUST''' redefine<br />
<br />
Accept necessary parameters, and do initialization of repository.<br />
<br />
====get_file($url, $file = '')====<br />
<br />
Given a URL, download a file from there, save the file in a temporary directory.<br />
<br />
====get_link($info)====<br />
Get the url of external resource<br />
<br />
====get_listing($path='/', $page='''''''')====<br />
<br />
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.<br />
<br />
====search($keyword)====<br />
Search repository by given keyword, it will return an array of the same format of get_listing<br />
<br />
====print_login()====<br />
<br />
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.<br />
<br />
====print_search==== <br />
<br />
Print the search form, it will return a json string<br />
<br />
====get_meta()====<br />
Return information for creating ajax request, it is private function, you don't need to rewrite it.<br />
<br />
====create()====<br />
Create an instance<br />
<br />
====delete()====<br />
Delete this instance from `repository` table<br />
<br />
====hide()====<br />
Hide a repository instance from file picker list<br />
<br />
====set_option()====<br />
set options in data1-data5 fields, can be overrided<br />
<br />
====get_option()====<br />
get option list or a specific option from database<br />
<br />
====get_type_option_names()====<br />
If this plugin needs admin settings, please refine this function to return option names.<br />
<br />
====type_config_form()====<br />
If get_type_option_names return non empty array, this function '''MUST''' redefine, it will help to build the setting form.<br />
<br />
====type_form_validation()====<br />
This function can be used for validating the data submitted by plugin setting form.<br />
<br />
====get_instance_option_names()====<br />
If plugin instance needs settings, this function will return instance option names.<br />
<br />
====instance_config_form()====<br />
If get_instance_option_names return non empty array, this function '''MUST''' redefine, it will help to build the instance setting form.<br />
<br />
====instance_form_validation()====<br />
This function can be used for validating the data submitted by instance setting form.<br />
<br />
====supported_filetypes()====<br />
What file types are supported by this repository plugin, it will return an array, the file type name is defined in a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file in lib/file/file_types.mm<br />
<br />
====supported_returntypes()====<br />
The repository plugin could support external link or copying files to moodle. If the plugin support file link only, developer should override this function to return FILE_EXTERNAL, if plugin support copying file only, it should return FILE_INTERNAL, by default, plugin supports both.<br />
<br />
====filter()====<br />
Filter file listing to exclude specific file types<br />
<br />
===icon.png===<br />
<br />
A logo that represents the repository. Ideally square but we should handle all sizes.<br />
<br />
==See also==<br />
<br />
* [[Repository Administration Specification]]<br />
* [[Repository Interface for Moodle/Course/User]]<br />
* [[Repository plugins]]<br />
* [[Repository File Picker]]<br />
* [[File API]]<br />
* [[Portfolio API]]<br />
* MDL-13766 and MDL-16543 Repository API Meta issues<br />
<br />
[[Category:Repositories]]<br />
<br />
[[ja:開発:リポジトリAPI]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=NanoGong/Converting_to_Moodle_2.0&diff=29389NanoGong/Converting to Moodle 2.02011-09-11T14:06:45Z<p>Nakohdo: /* Documentation */</p>
<hr />
<div>{{Work in progress}}<br />
<br />
This page is for collecting relevant information for converting NanoGong to Moodle 2.0. Any help is welcome!<br />
--[[User:Frank Ralf|Frank Ralf]] 10:35, 7 April 2011 (UTC)<br />
<br />
{{Moodle 2.0}}<br />
<br />
== Java settings ==<br />
(Not sure if this is relevant, but better to keep in mind ...)<br />
* see [[Question type plugin how to#Configuration settings for your question type]]<br />
<br />
== Filter ==<br />
General information on filters in Moodle 2.0 can be found at [[Filters 2.0]] and for developers at [[Filters 2.0]].<br />
<br />
=== Language folder ===<br />
Add language folder: '''\lang\en\filter_nanogong.php''' with the following content:<br />
<br />
<code php><br />
$string['filtername'] = 'NanoGong audio';<br />
</code><br />
<br />
=== Filter function ===<br />
<br />
The filter function is wrapped inside a class:<br />
<br />
<code php><br />
class filter_nanogong extends moodle_text_filter {<br />
function filter($text, array $options = array()){<br />
...<br />
}<br />
}<br />
</code><br />
<br />
'''Note''': The callback function has to be '''outside''' this class definition!<br />
<br />
=== Preventing caching ===<br />
<br />
$CFG->currenttextiscacheable = false;<br />
<br />
is deprecated, outcommented<br />
<br />
=== File API ===<br />
<br />
==== Proof of concept ====<br />
* Instead of the old '''file.php''' the new File API uses '''pluginfile.php'''.<br />
* I uploaded a test file (sentence.wav) as a resource to find out the internal URL Moodle uses for serving this file.<br />
* I then added this full URL as attribute to the NanoGong tag:<br />
<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="http://localhost/moodle-MOODLE_20_WEEKLY/pluginfile.php/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
* As the URL is already in its full format I just commented out the following lines in '''filter.php'''.<br />
<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url; # = "{$CFG->wwwroot}/file.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
* This works as a proof of concept.<br />
<br />
==== Getting closer ... ====<br />
<br />
This modification does also work:<br />
<br />
; NanoGong tag<br />
<code php><br />
<nanogong <br />
caption="Testing NanoGong..." <br />
url="/130/mod_resource/content/1/sentence.wav"<br />
/><br />
</code><br />
<br />
; filter.php<br />
<code php><br />
if ($url != "") {<br />
if ($CFG->slasharguments)<br />
$url = "{$CFG->wwwroot}/pluginfile.php$url";<br />
else<br />
$url; # = "{$CFG->wwwroot}/file.php?file=$url";<br />
}<br />
</code><br />
<br />
==== Documentation ====<br />
* see [[File API]] and [[Using the File API]]<br />
<br />
* [[File_API#File_serving]]<br />
* [[Using_the_file_API#Serving_files_to_users]]<br />
* [[File_storage_conversion_Quiz_and_Questions#Serving_files]]<br />
* [[Using the File API in Moodle forms]]<br />
<br />
== See also ==<br />
<br />
; Necessary updating for Moodle 1.9<br />
* see [[User:Frank Ralf/NanoGong/1.9|subpage on Moodle 1.9]]<br />
<br />
; Migrating to Moodle 2.0<br />
* [[Migrating contrib code to 2.0]]<br />
* [[Migrating to 2.0 checklist]]<br />
* [[Migrating contrib code to 2.0/Experience of converting a module to Moodle 2]]<br />
<br />
; Forums<br />
* [http://moodle.org/mod/forum/discuss.php?d=170422 Release of NanoGong 4.1, an important update for Moodle users]<br />
<br />
; Moodle plugin database <br />
* [http://moodle.org/mod/data/view.php?d=13&mode=list&perpage=50&search=&sort=44&order=ASC&advanced=0&filter=1&advanced=1&f_44=&f_45=nanogong all NanoGong plugins]<br />
<br />
; NanoGong documentation<br />
* http://gong.ust.hk/nanogong/moodle.html<br />
* http://gong.ust.hk/nanogong/info_php.html<br />
* [http://gong.ust.hk/moodle/course/view.php?id=2 Gong and NanoGong Demonstration]<br />
<br />
<br />
[[Category:Moodle 2.0|NanoGong]]<br />
[[Category:Project]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Setting_up_Netbeans&diff=29351Setting up Netbeans2011-09-06T14:52:49Z<p>Nakohdo: /* Optimization */</p>
<hr />
<div>[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).<br />
<br />
== Features ==<br />
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...<br />
* Ctrl+Click: Go to declaration<br />
* Export/Import Diff Patch<br />
* Easy navigation<br />
* List of functions<br />
* Code completion<br />
* Instant rename<br />
* HTML, CSS, JavaScript support<br />
* MySQL manager<br />
* Quick Search<br />
* Very few bugs<br />
<br />
== Installation ==<br />
<br />
* Download the latest stable version from http://netbeans.org. Get the bundle that contains only PHP support.<br />
* Install and run it.<br />
<br />
== Set up for Moodle development ==<br />
<br />
* Checkout your Moodle project with a '''CVS client''' - see [[:en:CVS for Administrators]] or [[CVS for developers|CVS for Developers]].<br />
<br />
* Open File > New Project > PHP > PHP Application > Next <br />
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.<br />
<br />
: Example:<br />
<br />
Project Name: Moodle 1.9 Stable<br />
Project Location: C:\Users\jerome\Documents\NetBeansProjects<br />
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable<br />
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle<br />
Project URL: http://localhost/moodle19/<br />
Index File: index.php<br />
Create: unchecked<br />
Default Encoding: UTF-8<br />
Set as Main Project: unchecked<br />
<br />
* Click on Finish.<br />
<br />
* Start coding!<br />
<br />
== CVS with NetBeans ==<br />
<br />
NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.<br />
<br />
=== Anonymous checkout ===<br />
<br />
# In NetBeans, select Window->Versioning->CVS->Checkout<br />
# Select Team->CVS->Checkout<br />
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''<br />
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)<br />
# Click ''Next''<br />
# Browse or enter into ''Module:'' moodle<br />
# Browse or enter into ''Branch:'' MOODLE_19_STABLE<br />
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs<br />
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)<br />
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."<br />
# Select PHP Application with Existing Sources, and click Next<br />
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle<br />
# Enter into ''Project Name:'' moodle<br />
# Keep the other defaults and click next<br />
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''<br />
# Enter into Project URL http://localhost/moodle/<br />
# Browse or enter into ''Index File:'' index.php<br />
# Click ''Finish''<br />
<br />
=== Checkout for developers with write access ===<br />
<br />
As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will need to use the internal SSH and your password (which you can choose to save).<br />
<br />
If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:<br />
<br />
====Checkout of main Moodle codebase====<br />
<br />
# Follow the above instructions except for point 3<br />
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''<br />
# Follow the rest of the instructions as above<br />
<br />
If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).<br />
<br />
====Checkout of contrib code====<br />
<br />
# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.<br />
# Click 'Browse...' next to the 'Module' dialogue<br />
# Find the plugin you wish to work with in CONTRIB<br />
# Click 'OK'<br />
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.<br />
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.<br />
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.<br />
<br />
Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)<br />
<br />
===Adding a branch to your plugin===<br />
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.<br />
<br />
# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE<br />
# You will end up with an empty folder, which you copy into place as above.<br />
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...<br />
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.<br />
<br />
There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.<br />
<br />
=== A few warnings ===<br />
<br />
Some of these warnings could also apply to other IDEs:<br />
<br />
* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.<br />
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.<br />
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.<br />
<br />
== Git with NetBeans ==<br />
<br />
=== NBGit | Git Support for NetBeans ===<br />
<br />
"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module." <br />
(http://nbgit.org)<br />
<br />
<p class="note orange"><br />
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)<br />
</p><br />
<br />
== Optimization ==<br />
<br />
=== Sun JDK ===<br />
1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit: <br />
<br />
netbeans_jdkhome="your_JDK_path"<br />
<br />
2. To change the NetBeans look and feel run netbeans in the command line with this parameter:<br />
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel <br />
<br />
3. If NetBeans starts to slow down, give it more memory<br />
"netbeans" -J-Xmx600m<br />
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].<br />
<br />
=== ScanOnDemand ===<br />
To prevent NetBeans from scanning the whole code with every start up you can use the following plug-in: http://wiki.netbeans.org/ScanOnDemand<br />
<br />
== Coding faster ==<br />
<br />
=== Keyboard shortcuts ===<br />
(Note: Some shortcuts might not work for PHP development.)<br />
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts] <br />
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]<br />
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]<br />
<br />
=== PHPUnit support ===<br />
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.<br />
<br />
===JIRA support===<br />
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within NetBeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to ''Tools->plugins->available plugins'' and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.<br />
<br />
== See also: ==<br />
Moodle forums <br />
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]<br />
<br />
Online resources<br />
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]<br />
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]<br />
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]<br />
<br />
Book<br />
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing <br />
<br />
[[Category:Developer tools|NetBeans]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Required_code_upgrades&diff=29317Required code upgrades2011-08-30T10:30:09Z<p>Nakohdo: /* See also: */</p>
<hr />
<div>This page lists all changes that may be needed to be done in 3rd party modules and other integration code.<br />
<br />
=Moodle 2.0=<br />
<br />
Note to developrs: please keep adding more info here ;-)<br />
<br />
==Mandatory==<br />
<br />
===New Data Manipulation Layer (DML)===<br />
* All database calls must be updated - new bound parameters syntax, magic quotes not used any more, see [https://docs.moodle.org/en/Development:DB_layer_2.0_migration_docs DB layer 2.0 migration].<br />
<br />
===File API===<br />
It consists of [https://docs.moodle.org/en/Development:File_API three parts]:<br />
# file storage - modules can not access the course files anymore, they must store alll files in own area<br />
# file browsing - each module/plugin defines what files are browsable and acessible<br />
# file serving - each plugin/module is responsible for file sending though pluginfile.php<br />
<br />
* Handling of files in backup/restore needs to be fully rewritten too.<br />
* File uploading in formslib fully rewritten - old API should not be used<br />
<br />
===Upgrade code===<br />
* Upgrade allowed only from 1.9.x (upgrade of contrib modules does not do version tests yet)<br />
* Backup/restore must use new DDL API.<br />
* Concurrent upgrades are now prevented.<br />
<br />
=== Messaging reimplemented ===<br />
Mailing and notifications from modules needs to be updated (not finished yet)<br />
<br />
==Optional==<br />
<br />
* [https://docs.moodle.org/en/Development:Portfolio_API Portfolio integration]<br />
* [https://docs.moodle.org/en/Development:Conditional_activities Conditional activities]<br />
<br />
==Other changes==<br />
These changes might affect some unsupported core code customisations. Modules and other plugins should not be affected.<br />
<br />
* rewritten course category sorting<br />
<br />
== See also: ==<br />
* [[Migrating contrib code to 2.0]]<br />
* [[User:Frank Ralf/Experience of converting a module to Moodle 2]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Required_code_upgrades&diff=29315Required code upgrades2011-08-30T10:27:03Z<p>Nakohdo: /* See also: */ section added</p>
<hr />
<div>This page lists all changes that may be needed to be done in 3rd party modules and other integration code.<br />
<br />
=Moodle 2.0=<br />
<br />
Note to developrs: please keep adding more info here ;-)<br />
<br />
==Mandatory==<br />
<br />
===New Data Manipulation Layer (DML)===<br />
* All database calls must be updated - new bound parameters syntax, magic quotes not used any more, see [https://docs.moodle.org/en/Development:DB_layer_2.0_migration_docs DB layer 2.0 migration].<br />
<br />
===File API===<br />
It consists of [https://docs.moodle.org/en/Development:File_API three parts]:<br />
# file storage - modules can not access the course files anymore, they must store alll files in own area<br />
# file browsing - each module/plugin defines what files are browsable and acessible<br />
# file serving - each plugin/module is responsible for file sending though pluginfile.php<br />
<br />
* Handling of files in backup/restore needs to be fully rewritten too.<br />
* File uploading in formslib fully rewritten - old API should not be used<br />
<br />
===Upgrade code===<br />
* Upgrade allowed only from 1.9.x (upgrade of contrib modules does not do version tests yet)<br />
* Backup/restore must use new DDL API.<br />
* Concurrent upgrades are now prevented.<br />
<br />
=== Messaging reimplemented ===<br />
Mailing and notifications from modules needs to be updated (not finished yet)<br />
<br />
==Optional==<br />
<br />
* [https://docs.moodle.org/en/Development:Portfolio_API Portfolio integration]<br />
* [https://docs.moodle.org/en/Development:Conditional_activities Conditional activities]<br />
<br />
==Other changes==<br />
These changes might affect some unsupported core code customisations. Modules and other plugins should not be affected.<br />
<br />
* rewritten course category sorting<br />
<br />
== See also: ==<br />
[TODO]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Required_code_upgrades&diff=29314Required code upgrades2011-08-30T10:26:25Z<p>Nakohdo: /* Mandatory */</p>
<hr />
<div>This page lists all changes that may be needed to be done in 3rd party modules and other integration code.<br />
<br />
=Moodle 2.0=<br />
<br />
Note to developrs: please keep adding more info here ;-)<br />
<br />
==Mandatory==<br />
<br />
===New Data Manipulation Layer (DML)===<br />
* All database calls must be updated - new bound parameters syntax, magic quotes not used any more, see [https://docs.moodle.org/en/Development:DB_layer_2.0_migration_docs DB layer 2.0 migration].<br />
<br />
===File API===<br />
It consists of [https://docs.moodle.org/en/Development:File_API three parts]:<br />
# file storage - modules can not access the course files anymore, they must store alll files in own area<br />
# file browsing - each module/plugin defines what files are browsable and acessible<br />
# file serving - each plugin/module is responsible for file sending though pluginfile.php<br />
<br />
* Handling of files in backup/restore needs to be fully rewritten too.<br />
* File uploading in formslib fully rewritten - old API should not be used<br />
<br />
===Upgrade code===<br />
* Upgrade allowed only from 1.9.x (upgrade of contrib modules does not do version tests yet)<br />
* Backup/restore must use new DDL API.<br />
* Concurrent upgrades are now prevented.<br />
<br />
=== Messaging reimplemented ===<br />
Mailing and notifications from modules needs to be updated (not finished yet)<br />
<br />
==Optional==<br />
<br />
* [https://docs.moodle.org/en/Development:Portfolio_API Portfolio integration]<br />
* [https://docs.moodle.org/en/Development:Conditional_activities Conditional activities]<br />
<br />
==Other changes==<br />
These changes might affect some unsupported core code customisations. Modules and other plugins should not be affected.<br />
<br />
* rewritten course category sorting</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Required_code_upgrades&diff=29313Required code upgrades2011-08-30T10:25:24Z<p>Nakohdo: /* Optional */ better link format</p>
<hr />
<div>This page lists all changes that may be needed to be done in 3rd party modules and other integration code.<br />
<br />
=Moodle 2.0=<br />
<br />
Note to developrs: please keep adding more info here ;-)<br />
<br />
==Mandatory==<br />
<br />
===New Data Manipulation Layer (DML)===<br />
* All database calls must be updated - new bound parameters syntax, magic quotes not used any more [https://docs.moodle.org/en/Development:DB_layer_2.0_migration_docs]<br />
<br />
===File API===<br />
It consists of three parts [https://docs.moodle.org/en/Development:File_API]:<br />
# file storage - modules can not access the course files anymore, they must store alll files in own area<br />
# file browsing - each module/plugin defines what files are browsable and acessible<br />
# file serving - each plugin/module is responsible for file sending though pluginfile.php<br />
<br />
* Handling of files in backup/restore needs to be fully rewritten too.<br />
* File uploading in formslib fully rewritten - old API should not be used<br />
<br />
===Upgrade code===<br />
* Upgrade allowed only from 1.9.x (upgrade of contrib modules does not do version tests yet)<br />
* Backup/restore must use new DDL API.<br />
* Concurrent upgrades are now prevented.<br />
<br />
=== Messaging reimplemented ===<br />
Mailing and notifications from modules needs to be updated (not finished yet)<br />
<br />
==Optional==<br />
<br />
* [https://docs.moodle.org/en/Development:Portfolio_API Portfolio integration]<br />
* [https://docs.moodle.org/en/Development:Conditional_activities Conditional activities]<br />
<br />
==Other changes==<br />
These changes might affect some unsupported core code customisations. Modules and other plugins should not be affected.<br />
<br />
* rewritten course category sorting</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Template:Back_from_dev&diff=29185Template:Back from dev2011-08-15T17:00:37Z<p>Nakohdo: </p>
<hr />
<div><noinclude><br />
* This template redirects pages from the Developer Docs back to Moodle 2.0 Docs.<br />
* Especially useful for accidentally cloned user pages, see [[User:Frank_Ralf/NanoGong]] for an example.<br />
--[[User:Frank Ralf|Frank Ralf]] 00:55, 16 August 2011 (WST)<br />
</noinclude><br />
{{Note|<br />
Please see the original page at https://docs.moodle.org/20/en/{{FULLPAGENAMEE}} - thanks!<br />
}}</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=User:Frank_Ralf/NanoGong&diff=29184User:Frank Ralf/NanoGong2011-08-15T16:57:20Z<p>Nakohdo: </p>
<hr />
<div>{{Back from dev}}<br />
<br />
--[[User:Frank Ralf|Frank Ralf]] 00:57, 16 August 2011 (WST)</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Template:Back_from_dev&diff=29183Template:Back from dev2011-08-15T16:56:50Z<p>Nakohdo: </p>
<hr />
<div><noinclude><br />
* This template redirects pages from the Developer Docs back to Moodle 2.0 Docs.<br />
* Especially useful for accidentally cloned user pages.<br />
--[[User:Frank Ralf|Frank Ralf]] 00:55, 16 August 2011 (WST)<br />
</noinclude><br />
{{Note|<br />
Please see the original page at https://docs.moodle.org/20/en/{{FULLPAGENAMEE}} - thanks!<br />
}}</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Template:Back_from_dev&diff=29182Template:Back from dev2011-08-15T16:55:32Z<p>Nakohdo: Created page with "<noinclude> * This template redirects pages from the Developer Docs back to Moodle 2.0 Docs. * Especially useful for accidentally cloned user pages. --~~~~ </noinclude> {{Note| P..."</p>
<hr />
<div><noinclude><br />
* This template redirects pages from the Developer Docs back to Moodle 2.0 Docs.<br />
* Especially useful for accidentally cloned user pages.<br />
--[[User:Frank Ralf|Frank Ralf]] 00:55, 16 August 2011 (WST)<br />
</noinclude><br />
{{Note|<br />
Please see the original page at https://docs.moodle.org/20/en/{{FULLPAGENAME}} - thanks!<br />
}}</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=User:Frank_Ralf/NanoGong&diff=29181User:Frank Ralf/NanoGong2011-08-15T16:52:09Z<p>Nakohdo: </p>
<hr />
<div>See https://docs.moodle.org/20/en/User:Frank_Ralf/NanoGong --[[User:Frank Ralf|Frank Ralf]] 00:51, 16 August 2011 (WST)<br />
<br />
{{FULLPAGENAME}}</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=User:Frank_Ralf/NanoGong&diff=29180User:Frank Ralf/NanoGong2011-08-15T16:51:47Z<p>Nakohdo: Replaced content with "See https://docs.moodle.org/20/en/User:Frank_Ralf/NanoGong --~~~~"</p>
<hr />
<div>See https://docs.moodle.org/20/en/User:Frank_Ralf/NanoGong --[[User:Frank Ralf|Frank Ralf]] 00:51, 16 August 2011 (WST)</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=User:Frank_Ralf/NanoGong/1.9&diff=29179User:Frank Ralf/NanoGong/1.92011-08-15T16:50:13Z<p>Nakohdo: Replaced content with "See https://docs.moodle.org/20/en/User:Frank_Ralf/NanoGong/1.9"</p>
<hr />
<div>See https://docs.moodle.org/20/en/User:Frank_Ralf/NanoGong/1.9</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=User:Frank_Ralf&diff=29178User:Frank Ralf2011-08-15T11:41:32Z<p>Nakohdo: deleted everything and redirect to other user page</p>
<hr />
<div>Please see my user profile at https://docs.moodle.org/20/en/User:Frank_Ralf --[[User:Frank Ralf|Frank Ralf]] 19:41, 15 August 2011 (WST)</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=User:Frank_Ralf/NanoGong/1.9&diff=29130User:Frank Ralf/NanoGong/1.92011-08-13T20:11:50Z<p>Nakohdo: /* See also: */</p>
<hr />
<div>NanoGong for Moodle 1.9 also needs some updating.<br />
<br />
== build_navigation() ==<br />
Navigation needs to be updated to use build_navigation()<br />
<br />
<br />
print_header() was sent a string as 3rd (-> NanoGongs -> NanoGong) parameter. <br />
This is deprecated in favour of an array built by build_navigation(). Please upgrade your code.<br />
<br />
* line 2539 of lib\weblib.php: call to debugging()<br />
* line 61 of mod\nanogong\view.php: call to print_header()<br />
<br />
* line 3759 of lib\weblib.php: call to debugging()<br />
* line 37 of theme\standard\header.html: call to print_navigation()<br />
* line 2765 of lib\weblib.php: call to include()<br />
* line 61 of mod\nanogong\view.php: call to print_header()<br />
<br />
See [[lib/weblib.php#function_build_navigation]]<br />
<br />
=== Moodle 2.0 ===<br />
* [[Navigation 2.0]]<br />
* [[Navigation 2.0 implementation plan]]<br />
<br />
== $cm ==<br />
The field $cm->modname should be set if you call build_navigation with a $cm parameter. <br />
If you get $cm using ''get_coursemodule_from_instance'' or '''get_coursemodule_from_id''', <br />
this will be done automatically.<br />
<br />
* line 3894 of lib\weblib.php: call to debugging()<br />
* line 59 of mod\nanogong\view.php: call to build_navigation()<br />
<br />
== "No sound has been submitted for the message." ==<br />
See <br />
* [http://moodle.org/mod/forum/discuss.php?d=92516 Release of NanoGong 2 with Full Moodle Integration]<br />
* [http://moodle.org/mod/forum/discuss.php?d=135714 won't start recording]<br />
<br />
== Github repository ==<br />
The current code is available at https://github.com/nakohdo/moodle-mod_nanogong<br />
<br />
== See also: ==<br />
* [http://gitorious.org/~doctorlard/moodle/doctorlards-moodle/commit/eac1256499273f638ee89dd14f2f1d0d5d65e433 Patch for adding NanoGong recording applet and HTMLArea button] by [http://moodle.org/user/profile.php?id=155540 Jonathan Harker] <br />
<br />
[[Category:Moodle 1.9|NanoGong]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Languages:Tim%27s_crazy_proposal_based_on_maketext&diff=28688Languages:Tim's crazy proposal based on maketext2011-07-20T16:34:50Z<p>Nakohdo: </p>
<hr />
<div>They say that the border between madness and genius is is very narrow. Here goes.<br />
<br />
The best article I know about the problems of localising software is http://search.cpan.org/~ferreira/Locale-Maketext-1.13_82/lib/Locale/Maketext/TPJ13.pod. I particularly like the narrative in the first half. Also, I must warn you that I have not read much about localisation, so my endorsement may not mean much.<br />
: The article mentioned is also available from the authors' homepage: [http://interglacial.com/tpj/13/ "Localizing Your Perl Programs"] --[[User:Frank Ralf|Frank Ralf]] 00:34, 21 July 2011 (WST)<br />
<br />
OK, so the key point it makes is that really, a language string like "There have been $a quiz attempts" is really a function (in the mathematical sense of a mapping, not necessarily as a programming language construct). Depending on $a, we want it to output<br />
* There have been no quiz attempts<br />
* There has been one quiz attempt<br />
* There have been 42 quiz attempts<br />
<br />
So the question is, why not make it a function in the programming language construct sense as well.<br />
<br />
<br />
==Two representations==<br />
<br />
Up to Moodle 1.9, the files Moodle used at runtime were exactly the same as the files that translators edited. That was convenient, but limited us to a human-readable and editable format. Also, it meant that Moodle had to do a lot of searching at runtime.<br />
<br />
In Moodle 2.0 we are already proposing to split the representations, which lets us optimise the runtime format to be pretty much whatever we like, without making the format edited by translators impossible.<br />
<br />
<br />
==Proposed runtime lang file syntax==<br />
<br />
In <tt>moodledata/lang/</tt> there are subfolders like <tt>en/</tt> (note we lose the legacy <tt>_utf8</tt>) that contains files like <tt>mod_quiz.php</tt> or <tt>core_moodle.php</tt>, that is, using the new component naming convention.<br />
<br />
Suppose we have a hypothetical plugin <tt>admin/report/dylan</tt> with its current lang file <tt>admin/report/dylan/lang/en_utf8/report_dylan.php</tt> that contains:<br />
<code php><br />
<?php<br />
$string['howmanyroads'] = 'How many roads must a man walk down?';<br />
$string['roadsx'] = 'Roads: $a';<br />
$string['xroadsfromytowns'] = '$a->numroads roads from at least $a->numcities different cities.';<br />
// Can't really handle pluralisation in that last one in Moodle :-(<br />
</code><br />
<br />
In my new proposal, <tt>moodledata/lang/en/report_dylan.php</tt> will contain:<br />
<code php><br />
<?php<br />
class strings_en_report_capability extends strings_base {<br />
protected static $helper = lang_helper_en::get(); // Get singleton instance.<br />
public function howmanyroads($a) { return 'How many roads must a man walk down?'; }<br />
public function roadsx($a) { return self::$helper->quant($a, 'road'); }<br />
public function xroadsfromytowns($a) { <br />
return self::$helper->quant($a->numroads, 'road') . ' from at least ' .<br />
self::$helper->quant($a-> numcities, 'different city', 'different cities') . '.';<br />
}<br />
}<br />
</code><br />
(I manually line-wrapped that last example to make it readable. in reality, remember that this file is being automatically compiled from some more human-readiable source.)<br />
<br />
Also note that <tt>moodledata/lang/fr/report_dylan.php</tt> will look like:<br />
<code php><br />
<?php<br />
include_once($CFG->langdir . '/en/report_dylan.php');<br />
class strings_fr_report_capability extends strings_en_report_capability {<br />
protected static $helper = lang_helper_fr::get(); // Get singleton instance.<br />
public function howmanyroads() { return 'Combien de rue ...'; }<br />
// etc.<br />
}<br />
</code><br />
<br />
And <tt>moodledata/lang/fr_ca/report_dylan.php</tt> is:<br />
<br />
<code php><br />
<?php<br />
include_once($CFG->langdir . '/fr/report_dylan.php');<br />
class strings_fr_ca_report_capability extends strings_en_report_capability {<br />
}<br />
</code><br />
<br />
==Using that runtime format==<br />
<br />
Then, <tt>string_manager()</tt> becomes:<br />
<code php><br />
class string_manager {<br />
protected $stringclasses = array();<br />
public function get_string($identifier, $component = '', $a = null) {<br />
$component = $this->fix_legacy_component_names($component);<br />
$this->get_string_class(current_language(), $component)->$identifier($a);<br />
}<br />
protected function get_string_class($lang, $component) {<br />
global $CFG;<br />
if (!isset($this->stringclasses[$lang][$component])) {<br />
$this->stringclasses[$lang][$component] = <br />
$this->load_string_class($lang, $component)();<br />
}<br />
return $this->stringclasses[$lang][$component];<br />
}<br />
protected function load_string_class($lang, $component) {<br />
$file = "$CFG->langdir/$lang/$component.php";<br />
$class = "strings_{$lang}_{$component}";<br />
if ($CFG->langediting && !$this->is_up_to_date($file)) {<br />
compile_lang_strings($lang, $component);<br />
}<br />
if (!is_readable($file)) {<br />
return new strings_base(); // See below.<br />
}<br />
include_once($file);<br />
if (!class_exists()) {<br />
throw new coding_exception($file . ' did not define the ' . $class .<br />
'class. There must be a bug in compile_lang_strings.');<br />
}<br />
return new $class();<br />
}<br />
// A few other methods omitted.<br />
}<br />
</code><br />
Note that if you have a developer/translator flag on (<tt>$CFG->langediting</tt>) then <tt> is_up_to_date</tt> checks various file timestamps, so that lang files can automatically be recompiled as needed for those people, without hurting runtime performance for production sites. <br />
<br />
As a final bit of magic, we have<br />
<code php><br />
class strings_base {<br />
public function __call($name, $arguments) {<br />
return "[[$name]]";<br />
}<br />
}<br />
</code><br />
<br />
Remember that the strings_en_report_capability inherited form this. This gives us our classing missing string fallback. Also:<br />
<br />
<code php><br />
class lang_helper_en {<br />
private static $inst = null;<br />
public static get() {<br />
if (!$inst) {<br />
$inst = new lang_helper_en();<br />
}<br />
return $inst;<br />
}<br />
public function quant($number, $singular, $plural = '') {<br />
if ($number = 1) {<br />
return "$number $singular";<br />
} else if ($plural) {<br />
return "$number $plural";<br />
} else {<br />
return "$number {$singular}s";<br />
}<br />
}<br />
// Other helper functions.<br />
}<br />
</code><br />
<br />
<br />
==Problems==<br />
<br />
I think this gives us the fastest possible runtime performance (particularly when combined with a PHP accelerator. Of course, it leaves open the following problems:<br />
* what string format do translators to edit? (I suggest we copy the maketext format.)<br />
* can we write the <tt>compile_lang_strings</tt> function?<br />
<br />
<br />
==See also==<br />
<br />
* [[Languages]]<br />
<br />
[[Category:Language]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Talk:Themes_FAQ&diff=26554Talk:Themes FAQ2011-07-01T16:22:01Z<p>Nakohdo: /* Only for developers? */</p>
<hr />
<div>== Only for developers? ==<br />
<br />
I'm not happy to see this FAQ categorized as developer documentation. They contain much information on issues regularly asked in the forum. [[Firebug]] on the other hand, which is really for developers, is still "normal" documentation. --[[User:Frank Ralf|Frank Ralf]] 00:20, 2 July 2011 (WST)</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Talk:Themes_FAQ&diff=26553Talk:Themes FAQ2011-07-01T16:20:24Z<p>Nakohdo: Only for developers?</p>
<hr />
<div>== Only for developers? ==<br />
<br />
I'm not happy to see this FAQ categorized as developer documentation. They contain much information on issues regularly asked in the forum. --[[User:Frank Ralf|Frank Ralf]] 00:20, 2 July 2011 (WST)</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Plugin_contribution&diff=26539Plugin contribution2011-06-30T13:31:22Z<p>Nakohdo: /* How to request that your code be tested/reviewed */</p>
<hr />
<div>This page describes the various ways to share and work collaboratively on contributed code. In the past, Moodle CONTRIB code was often stored on the Moodle CVS server. As Moodle code transitions to [https://docs.moodle.org/en/Git Git], CONTRIB code will also be transitioning with a goal of having all code maintained via git repositories by August 2011. Don't worry if you have code on CVS and do not know Git as there are many people willing to help you with the transition especially [https://docs.moodle.org/en/User:Anthony_Borrow Anthony Borrow]. <br />
<br />
For those neither familiar with CVS nor Git, it is recommended that you [https://docs.moodle.org/en/Git#Books_and_tutorials learn Git basics]. The nice thing about using Git is that it will leave control of the code in the hands of contributor. <br />
<br />
*'''Sharing code''' - Contributed code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.).<br />
*'''Reviewing code''' - If you would like your code to be tested and reviewed, please create an issue in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB]. <br />
*'''Documenting code''' - You can maintain helpful documentation of the features and installation instructions in [https://docs.moodle.org Moodle Docs]<br />
*'''Distributing code''' - You can help others find your code by adding an entry to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database] <br />
*'''Discussing the code''' - You can discuss the functionality and answer questions about how to use your code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]. Users can ask questions, discuss possible ideas for improvement, etc. Once the discussion matures to a point where you may want to take action, then you can create an issue in the [http://tracker.moodle.org/ Moodle Tracker]. <br />
*'''Maintaining code''' - You can further develop your code by fixing issues, adding features, and responding to other issues with the [http://tracker.moodle.org/ Moodle Tracker]. Each plugin or patch can have its own component in the CONTRIB project; however, you will need to request that the component be created in the CONTRIB project. Once created, users can easily create issues related to your contributed code. The primary maintainer of the code will be assigned as the component lead and have their tracker privileges bumped so that they can manage issues related to their contributed code. Those issues will automatically be assigned to the component lead/primary maintainer. <br />
<br />
==The CONTRIB Frequently Asked Question (FAQ)==<br />
'''Question:''' I have written a new block, activity, patch or theme to share with the Moodle community. What is the process for contributing the code? <br />
<br />
'''Answer:''' First, thank you for your generosity and desire to share your work with the rest of the Moodle community. Code contributions are highly valued and Moodle wants to encourage creativity and generosity in keeping with [https://docs.moodle.org/en/Pedagogy Moodle's social constructionist pedagogy]. <br />
<br />
As mentioned, there are various tools to help you share and support your contribution. By using a consistent methodology, your Moodle related code will be more easily found, tested, used, maintained, documented, and evaluated by fellow Moodlers and developers. Learning to use the various tools common among Moodle developers will help you to efficiently and effectively develop, share and maintain your contributed code. <br />
<br />
==How to submit code==<br />
You have created some code that you would like to contribute to the Moodle community. The first step is to choose which Git code hosting site you want to use. Both [http://github.com/ github.com] and [http://gitorious.org/ gitorious.org] are popular. Follow the instructions for creating a public repository for your code. This will allow others to download your code as well as suggest possible patches. As you become more familiar with collaborating with others you can also control who else you want to be able to push changes into your repository (i.e. write access). <br />
<br />
In order to facilitate a common naming convention of Moodle related repositories, it is suggested that you use the following format: moodle-{plugintype}_{pluginname}. For example, the birthday block has a repository name of moodle-block_birthday and is located at https://github.com/arborrow/moodle-block_birthday. Other developers can fork the code and work from their repositories.<br />
<br />
==How to request that your code be tested/reviewed==<br />
<br />
#If you do not already have an account on the [http://tracker.moodle.org Moodle Tracker], create one and login. <br />
#Create a new "Task" issue in the "Non-core contributed modules" project. Your issue will be a request that the code be tested and reviewed. <br />
#Provide the link to the repository (i.e. https://github.com/arborrow/moodle-block_birthday) <br />
#Provide a clear description of what the code does and the functionality that it adds to Moodle. <br />
#Provide any other links to supporting documentation<br />
<br />
The Contrib Coordinator will then work directly with the code contributor via the Tracker to help evaluate the code, work on resolving any questions/issues found, etc. <br />
<br />
*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].<br />
<br />
*Contributors are encouraged to maintain a branch for each major Moodle release (i.e. 1.8, 1.9, etc.). The HEAD branch should be used as the development branch. <br />
<br />
*Contributors are encouraged to associate each change made to an issue in the tracker. This practice is done by Moodle core developers and it is a good habit to get into so that you can go back and see why various changes were made to the code. Simple practices like these help to create good documentation of the code as it develops and matures. Commits should begin with the Moodle tracker issue number followed by a brief description of the change.<br />
<br />
==How to provide documentation==<br />
Having great code available to the community is wonderful. It is also important to educate users about how to use the code with documentation in [[Main Page|Moodle Docs]]. See [[MoodleDocs:Guidelines for contributors|guidelines for contributors]] for more help. <br />
<br />
A documentation page for a contributed module should have some basic elements. A brief introduction of what the code does, a "Features" heading, perhaps a "Installation", "Tips and tricks" and "See also" headings, all with content of course. Sometimes a screenshot is worth 1000 words. In the "See also" put a link to the Modules and Plug database, with a note that this is the place to download versions, and the forum where questions can be answered at moodle.org.<br />
<br />
Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.<br />
<br />
===Possible format for a contributed code Moodle Docs page===<br />
You can copy and paste the below into your Moodle documentation page. Please add the URL links. '''This is only a suggestion'''. <br />
Start with a 2-4 line introduction. The Plug In Name works with the activity module. <br />
It makes the life of the teacher easier by ... <br />
==Features==<br />
* Add features list or overview description here <nowiki><br></nowiki><br />
<nowiki> [[Image:Sample_screen_shot|thumb|500px|center|Title of screenshot]]</nowiki><br />
==Installation==<br />
Place install instructions here<br />
==Tips and tricks==<br />
*Optional section, usually added by users later<br />
==See also==<br />
*[Place http_address_for_M&P_entry_here Name of Entry here] is a Modules and plugins database page that has download links and more information.<br />
*Discussions: [Place http_address_for_moodle_forum_or_thread_here Name of forum]<br />
<br />
When no thread or forum exists for discussion, put a link to the Contributed Code forum.<br />
*Discussions: Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki><br />
<br />
==Share code with modules and plugins database==<br />
Now you have a place for users to get your code, how will they know it exists? Moodle users can easily find information about contributed code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]. When you add an entry to this database, remember that it is searchable by any field. Every field is not required, but providing as much information as possible will help people who would like to find, read about, and then install your contribution. In particular, the name of the module and the description of its function are important. Screen shots are helpful (but please, not larger than 350px wide!). Links to discussion (on Moodle.org or other forum) and documentation (link to your page in the [https://docs.moodle.org Moodle docs] or another location) should be included if possible. <br />
<br />
Users may leave comments on your entry, so please check it periodically for questions and bug reports. If you include contact information or a link to a discussion, your users may be able to contact you more directly. The comments are not emailed automatically.<br />
<br />
Keep in mind that entries added to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database] require approval by a moderator before they will be visible to other Moodle users.<br />
<br />
==Support code and get feedback with forums==<br />
As users become familiar with the contributed code, discussions about the code are likely to emerge. We strongly urge you to place links to at least one forum at moodle.org in your Modules and Plugins entry as well as in MoodleDocs. <br />
<br />
It is important to respond to users who have questions about how to use the code, suggestions for how to make it better, etc. If it looks like there is sufficient need for some contributed code to have its own forum, please create a request via the tracker in the MDL-SITE section. Moodle has included many contributed code projects and ideas into its core. <br />
<br />
*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".<br />
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects. <br />
*[http://moodle.org/course/ A list of] other language forums and special areas in Moodle<br />
<br />
==Maintain and refine code with Tracker==<br />
<br />
In order to facilitate keeping track of feature requests, bugs, and other code issues, the contributor may request that a component be created in the CONTRIB section of the Moodle tracker. (This is the section where you initially made the request to have code included in CVS.moodle.org.)<br />
<br />
The contributor can be added to the group of CONTRIB developers in the tracker to manage the issues assigned to them and better coordinate with other developers. Users of the contributed code can then add issues which can be assigned directly to the maintainer. The tracker helps to manage the work flow involved in fixing bugs, working through feature requests, and maintaining the code. When committing changes, maintainers are strongly encouraged to begin the commit comment with a tracker number. <br />
<br />
We strongly encourage users to involve themselves in the process of creating a useful issue in tracker. For the developer and code contributor, describing the fix can help clarify the need for the code change. Further, it helps to establish good documentation about how the code developed. Others will be able to identify the issues addressed and understand why a particular decision was made.<br />
<br />
==Summary==<br />
<br />
It is hoped that following this procedure, will help guide contributors of code in the process of learning the tools and skills used by the Moodle developers. Learning to submit code by using the tracker, work the code with CVS, support the code by providing documentation, share code in Modules and Plugins, maintain the code by using the tracker, and evolve the code by using the Moodle.org forums will assist you in successfully contributing to the Moodle community and working with Moodle's developers. <br />
<br />
Throughout this process, the CONTRIB Coordinator is here to encourage and support those contributing code to the Moodle community and fostering the development of tomorrow's Moodle developers.<br />
<br />
Eventually, the community may wish for the code to become part of the Moodle core. By following the steps above, the developers will be able to evaluate the merit of the contributed code, understand how users have used the code, see the issues that have emerged and thus have more information to make an informed decision about whether or not to incorporate the contributed code into core.<br />
<br />
==Most common recommendations for contributed code==<br />
<br />
There are several small issues that the CONTRIB Coordinator will typically check for when reviewing the code prior to committing to the CVS server. These issues help to ensure consistency and quality of code. Any suggestions made by the CONTRIB Coordinator should be considered recommendations aimed to help folks new to the Moodle community collaborate in a way consistent with standard practices within the Moodle community. The suggestions are meant to help avoid potential issues and facilitate the acceptance of your code.<br />
<br />
=== Does the file structure conform to Moodle standards? ===<br />
Generally speaking, each file should have an appropriate extension (i.e. php, html, css, txt, etc.). To avoid issues with case sensitivity, folders and files are normally lower case; however, there are exceptions to this. Another common recommendation is to place the lang folder within the block or module rather than asking the user to copy files into the main lang folder. Changes made in the get_string function for Moodle 1.9 and onward make it possible to do this which goes a long way in keeping things modular. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.<br />
<br />
=== Does the code work without any obvious errors? ===<br />
The CONTRIB Coordinator will try to install the block or module on a fresh Moodle installation and report back any errors. This testing is done with Debugging set to show All PHP notices and errors (not developer mode). The most common notices have to do with attempting to use a variable that has not been initialized or checked for existence. <br />
<br />
=== Does the code use the config_plugins table? ===<br />
<br />
Contributed blocks and modules are encouraged to make use of the '''config_plugins''' table rather than the config table. Maintainers are encouraged to read the documentation provided for the [http://xref.moodle.org/lib/moodlelib.php.html#get_config get_config()] and [http://xref.moodle.org/lib/moodlelib.php.html#set_config set_config()]] functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated.<br />
<br />
=== Does the code follow the [[Coding|Coding Guidelines]]? ===<br />
The CONTRIB Coordinator will look at the code for general readability and point out any obvious deviations from the [[Coding|Coding Guidelines]]. While not all code needs to conform with each and every guideline, maintainers are encouraged to follow those guidelines as closely as possible. One useful tool for Moodle 2.0 is the [http://moodle.org/mod/data/view.php?d=13&rid=4682|Code checker local plugin] which helps to identify many issues.<br />
<br />
==See also==<br />
<br />
*[[Migrating contrib code to 2.0]]<br />
*[[contrib]] CONTRIB is an area in the Moodle CVS <br />
*[[Translation]] for information on the translation of contributed code<br />
*[[Overview]]<br />
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion<br />
<br />
[[Category:Guidelines for contributors]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=CSS&diff=26533CSS2011-06-29T15:25:41Z<p>Nakohdo: /* See Also */</p>
<hr />
<div>CSS or Cascading Style Sheets are used to control the way web pages look. By changing a CSS definition, the change is made on every Moodle webpage that uses that definition. <br />
<br />
CSS files are located in the [[Theme|theme]] folder being used by Moodle. The normal Moodle practice is to have 3 main CSS files: [[CSS styles_ color.css|styles_color]], [[CSS styles_layout.css|styles_layout]], [[CSS styles_fonts.css|styles_fonts]]. When a CSS definition is not found in a theme CSS file, the CSS files located in the standard theme serves as the default. <br />
<br />
There may also be CSS files for Internet Explorer, Mozilla or other internet browsers.<br />
<br />
==Basic Moodle page parts==<br />
A web page is broken up into pieces or elements. Not every page contains the same parts.<br />
<br />
These parts or elements include: core, forms, header, footer,admin, blocks, blog, calendar, course, doc, grades, login, message, notes, mymoodle, question, tabs, tags, user and many of the modules.<br />
<br />
==Basic CSS files==<br />
*[[CSS styles_ layout.css]] contains the layout specifications for various page elements. <br />
<br />
*[[CSS styles_color.css]] contains the colors used in the page elements. <br />
<br />
*[[CSS styles_fonts.css]] defines the fonts used in the page elements.<br />
<br />
== See Also ==<br />
<br />
* [[CSS FAQ]]<br />
* [[Themes FAQ]]<br />
* [[CSS styles moz.css]]<br />
* [[Themes]]<br />
* [http://en.wikipedia.org/wiki/Cascading_Style_Sheets Wikipedia Cascading Style Sheets]<br />
* [http://www.w3schools.com/css/default.asp W3schools]<br />
<br />
[[Category:Themes]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Web_developer_extension&diff=26521Web developer extension2011-06-24T12:05:03Z<p>Nakohdo: /* See also */</p>
<hr />
<div>The '''Web developer extension''' for [[Firefox]] is an essential tool for web developers. It has too many functions to list them all but some of the most useful for use with Moodle development are explained below. Visit the [http://chrispederick.com/work/webdeveloper/documentation/ web developer extension's homepage] to download and install and for more documentation. Or get it from the [https://addons.mozilla.org/en-US/firefox/addon/60 Firefox Add-on page].<br />
<br />
== For CSS development ==<br />
<br />
These functions are useful for anyone creating and debugging [[CSS]]:<br />
<br />
* Disable Cache - this prevents Firefox from storing old versions of CSS files as you make changes<br />
* Edit CSS - this allows you to make changes to the CSS and see the changes instantly. Great for exploring and testing.<br />
* Display Element Information - show information about page elements, such as ancestors as you hover over them with the mouse.<br />
* Display Id & Class details - displays all class and id names where-ever they are used.<br />
* Enable only print style in normal view - useful for developing [[Print style|print styles]].<br />
<br />
== For HTML development ==<br />
<br />
These functions are useful when creating HTML code:<br />
<br />
* Outline Tables/Headings/Deprecated elements - the outline function puts colored boxes around the elements you specify to make them easier to locate and work with.<br />
* Validate local HTML - sends the HTML you are looking at to the [[W3C_validation| Validator]]. Most Moodle pages are protected by passwords so validators cannot visit them, which is the usual practice.<br />
<br />
== For accessibility ==<br />
<br />
See the [[Accessibility]] page for more tools.<br />
<br />
* Replace images with alt attributes - lets you read what those with images unavailable or turned off will receive.<br />
* Linearize page - shows the order in which audio or small screen browsers will present information<br />
<br />
== See also ==<br />
* [[Firebug]] for information about Firebug, another powerful Firefox extension for web developers<br />
* [http://www.microsoft.com/downloadS/details.aspx?familyid=E59C3964-672D-4511-BB3E-2D5E1DB91038&displaylang=en Internet Explorer Developer Toolbar] for a similar tool for Microsoft Internet Explorer<br />
* [http://www.sitepoint.com/blogs/2010/03/23/chrome-web-developer-toolbar/ "The Web Developer Toolbar Comes to Chrome"] <br />
* [https://addons.mozilla.org/en-US/firefox/addon/toggle-web-developer-toolbar/ Toggle Web Developer Toolbar] Firefox add-on<br />
<br />
<br />
[[Category:Developer tools]]<br />
[[Category:Themes]]<br />
[[Category:Firefox extensions]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Web_developer_toolbar&diff=26520Web developer toolbar2011-06-24T12:04:21Z<p>Nakohdo: Redirected page to dev:Web developer extension</p>
<hr />
<div>#REDIRECT [[Dev:Web_developer_extension]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Maintaining_Moodle_customisations_with_Git&diff=26384Maintaining Moodle customisations with Git2011-06-21T10:42:02Z<p>Nakohdo: /* See also: */</p>
<hr />
<div>{{draft}}<br />
<br />
Git makes it very easy to maintain local customisations to Moodle alongside updates from the official Moodle repository.<br />
This page assumes you installed Moodle following [[Installing Moodle from Git repository]]. It also assumes you understand basic version control principles (repositories, branches, conflicts) and have a basic working knowledge of Git.<br />
<br />
First, from your moodle directory, create a branch of <tt>master</tt> which will contain your customised Moodle. This is the branch you'll publish to other servers.<br />
git checkout master<br />
git checkout -b mycustommoodle<br />
<br />
Switched to a new branch 'mycustommoodle'<br />
Next, create a new branch for developing your customisation, and move to that branch:<br />
git checkout -b myfeature<br />
<br />
Switched to a new branch 'myfeature'<br />
This will give you a seperate copy of the Moodle code to work on without affecting the master branch. It's not recommended that you do this on your production server, as it will cause the code to be available immediately as it's saved.<br />
<br />
Do your customisations, add any new files to git, and commit the changes<br />
git add .<br />
git status<br />
git commit -m "Description of the change"<br />
<br />
Switch back to the <tt>mycustommoodle</tt> branch and merge the changes<br />
git checkout mycustommoodle<br />
git merge myfeature<br />
Any future development can take place on the myfeature branch, and be merged into mycustommoodle in this way<br />
<br />
Even after local modifications have been made, you can pull in updates from the official git repository<br />
git checkout master<br />
git fetch<br />
git merge origin/master<br />
git checkout mycustommoodle<br />
git merge master<br />
<br />
=== Conflicts ===<br />
If you create a local modification to a file, and that same file is modified in the official repository, you may find that a conflict is created when you do <tt>git merge origin/master</tt>.<br />
<br />
To resolve this, you will need to find the conflicts (the attempt to merge will tell you where they are) and resolve them. The [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html|<tt>git merge</tt> man page] has more information on the presentation and resolution of conflicts.<br />
<br />
After the conflict is resolved, you'll need to commit the resolved files.<br />
git commit -a<br />
Once a conflict has been resolved, even if you keep your local modification over the upstream modification, there wont be a conflict next time you merge.<br />
<br />
== See also ==<br />
; Moodle forum discussions<br />
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]<br />
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]<br />
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]<br />
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]<br />
<br />
; External resources <br />
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]<br />
* [http://gitref.org/ Git Reference]<br />
* [http://progit.org/book/ Pro Git book]<br />
<br />
[[Category:Git]]</div>Nakohdohttps://docs.moodle.org/dev/index.php?title=Git_repositories_for_contrib_modules&diff=26383Git repositories for contrib modules2011-06-21T10:41:44Z<p>Nakohdo: /* Moving a plugin to it's own repository */</p>
<hr />
<div>{{draft}}<br />
<br />
The instructions here assume that you have a working knowledge of git.<br />
<br />
Managing contrib plugin with git makes it easy to make local modifications and pull in updates.<br />
There are several options for managing a contrib plugin with git:<br />
# Add the module to your main moodle git repository<br />
# Create a self-contained repository for the plugin in a subdirectory<br />
# Create a git submodule, which creates a repository for the plugin but tracks updates in the main repository too. It also allows you to clone the plugins with the main repository<br />
Having used all of the above, the method I'd recommend is number 2, as it's most convenient. The main disadvantage of 1 is that you can't easily pull in updates, and the main disadvantage of 3 is that you have to make each commit to the module twice (once in the submodule, and once in the main repo).<br />
<br />
== Creating a new plugin ==<br />
If you intend to publish the plugin, I highly recommend creating a [http://github.org github] repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is <tt>moodle-plugintype_pluginname</tt>.<br />
<br />
Github will give you instructions for cloning your (blank) repository. If you're using option 2 above, navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local) and run the <tt>git clone</tt> command there. This will create a subdirectory called <tt>moodle-plugintype_pluginname</tt>, rename this to <tt>pluginname</tt> and you're good to go. <tt>cd</tt> into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository.<br />
<br />
You can then develop and test your changes locally, and when you're ready to publish, run<br />
git push origin<br />
<br />
== Installing a third-party plugin ==<br />
Installing a plugin developed by a third party differs depending on whether they have used git or not.<br />
If they have used git, you can follow the instructions above, but skip out the part where you create a new github repository and clone their own github (or other public repository) instead.<br />
<br />
If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin<br />
mkdir ~/moodle/blocks/newblock<br />
Initialise a new git repository there<br />
cd ~/moodle/blocks/newblock<br />
git init<br />
unzip or copy the files to the repository<br />
cd ~<br />
tar -xf newblock.tar.gz<br />
cp newblock/* ~/moodle/blocks/newblock<br />
add and commit the files<br />
cd ~/moodle/blocks/newblock<br />
git add .<br />
git commit . -m "Added files for newblock"<br />
When installing updates, you'll need to copy the new files in place of the old one, and re run the <tt>git add</tt> and <tt>git commit</tt> commands.<br />
<br />
== Moving a plugin to it's own repository ==<br />
You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using <tt>git filter-branch</tt>, we can achieve this and maintain all existing history for the plugin's files.<br />
<br />
First, you'll need a fresh copy of moodle (this will become your new moodle repository)<br />
mkdir ~/newmoodle<br />
cd ~/newmoodle<br />
git clone git://git.moodle.org/moodle.git<br />
This will create a clone of Moodle without your plugins in ~/newmoodle/moodle<br />
Next, you need to clone your local Moodle repository (why will become clear).<br />
mkdir ~/moodleclone<br />
cd ~/moodleclone<br />
git clone ~/moodle<br />
This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle<br />
Now, we'll use the <tt>git filter-branch</tt> command to reduce this clone to just the plugin. <br />
cd ~/moodleclone/moodle<br />
git filter-branch --subdirectory-filter blocks/myblock/<br />
The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone).<br />
You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.<br />
cd ~/newmoodle/blocks<br />
git clone ~/moodleclone/moodle myblock<br />
This will clone the block's files, with the full history, into their own repository in the myblock subdirectory.<br />
You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.<br />
<br />
== See also ==<br />
; Moodle forum discussions<br />
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]<br />
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]<br />
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]<br />
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]<br />
<br />
; External resources <br />
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]<br />
* [http://gitref.org/ Git Reference]<br />
* [http://progit.org/book/ Pro Git book]<br />
<br />
[[Category:Git]]</div>Nakohdo