MoodleDocs - User contributions [en]

Filters

2014-11-10T20:24:15Z

Scyrma: My mistake.

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

{{Moodle 2.0}}

'''Filters''' are a way to automatically transform content before it is output. For example
* render embedded equations to images (the TeX filter)
* Links to media files can be automatically converted to an embedded applet for playing the media.
* Mentions of glossary terms can be automatically converted to links.
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.

==Before you start==

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

==Creating a basic filter==

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

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

2. Inside that folder, we create a file called 'filter.php'.

3. Inside that PHP file, we define a class called filter_helloworld, that extends the moodle_text_filter class.
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
// ...
}
?>
</code>

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
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
return str_replace('world', 'hello world!', $text);
}
}
</code>

That is basically all there is to it!

==Giving your filter a name==

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.

When you do, you will find that your plugin does not have a name. We missed a step:

5. Inside the 'filter/helloworld' folder, create a folder called 'lang', and in there, create a folder called 'en'.

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

7. In that file, put
<code php>
<?php // $Id$
// Language string for filter/helloworld.

$string['filtername'] = 'Hello world!';
</code>

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

==Trying out your filter==

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.

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.

==Adding a global settings screen==

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:

8. Create a file called 'filtersettings.php' inside the 'filter/helloworld' folder. Use standard 'settings.php' file in Moodle 2.6 and later.

9. In the 'filtersettings.php' file, put something like:
<code php>
$settings->add(new admin_setting_configtext('filter_helloworld_word',
get_string('word', 'filter_helloworld'),
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));
</code>

10. In the language file 'filter/helloworld/lang/en/filter_helloworld.php' add the necessary strings:
<code php>
$string['word'] = 'The thing to greet';
$string['word_desc'] = 'The hello world filter will add the word \'hello\' in front of every occurrence of this word in any content.';
</code>

11. Change the filter to use the new setting:
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
return str_replace($CFG->filter_helloworld_word,
"hello $CFG->filter_helloworld_word!", $text);
}
}
</code>

In standard Moodle, the censor, mediaplugin and tex filters all provide good examples of of how filters use global configuration like this.

==A note about performance==

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

==Local configuration==

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.

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:

12. Create a file called 'filterlocalsettings.php' inside the 'filter/helloworld' folder.

13. In the 'filterlocalsettings.php' file, put:
<code php>
class helloworld_filter_local_settings_form extends filter_local_settings_form {
protected function definition_inner($mform) {
$mform->addElement('text', 'word', get_string('word', 'filter_helloworld'), array('size' => 20));
$mform->setType('word', PARAM_NOTAGS);
}
}
?>
</code>

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
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
if (isset($this->localconfig['word'])) {
$word = $this->localconfig['word'];
} else {
$word = $CFG->filter_helloworld_word;
}
return str_replace($word, "hello $word!", $text);
}
}
?>
</code>

==Two types of filter==

In the past, Moodle supported two different types of filter:
* 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.
* 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.
The second option no longer exists in Moodle 2.5 and later. 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.

==Dynamic content==

From Moodle 2.7:
On (very few) pages - it is possible that page content is loaded by ajax *after* the page is loaded (e.g. equations in a glossary popup). In certain filter types (e.g. MathJax) javascript is required to be run on the output of the filter in order to do the final markup. For these types of filters, a javascript event is triggered when new content is added to the page (the content will have already been processed by the filter in php). The javascript for a filter can listen for these event notifications and reprocess the affected dom nodes.

To subscribe to the event:

// Listen for events triggered when new text is added to a page that needs
// processing by a filter.
Y.on(M.core.event.FILTER_CONTENT_UPDATED, this.contentUpdated, this);

To handle the event:

/**
* Handle content updated events - typeset the new content.
* @method contentUpdated
* @param Y.Event - Custom event with "nodes" indicating the root of the updated nodes.
*/
contentUpdated: function(event) {
var self = this;
Y.use('mathjax', function() {
self._setLocale();
event.nodes.each(function (node) {
node.all('.filter_mathjaxloader_equation').each(function(node) {
MathJax.Hub.Queue(["Typeset", MathJax.Hub, node.getDOMNode()]);
});
});
});
}

See: filter/mathjaxloader/yui/src/loader/js/loader.js

==See also==

* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system
* [[:en:Filters]] user documentation about filters.
* [https://moodle.org/plugins/browse.php?list=category&id=7 - List of filters in the Plugins database].

[[Category:Filter]]
[[Category:Plugins]]

Filters

2014-11-10T20:23:21Z

Scyrma:

Filters

2014-11-10T20:23:02Z

Scyrma: Broken link - forgot to put language prefix

Filters

2014-11-10T20:20:46Z

Scyrma: /* See also */ Link sending user back to this same page. Probably meant for /Filters

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

{{Moodle 2.0}}

'''Filters''' are a way to automatically transform content before it is output. For example
* render embedded equations to images (the TeX filter)
* Links to media files can be automatically converted to an embedded applet for playing the media.
* Mentions of glossary terms can be automatically converted to links.
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.

==Before you start==

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

==Creating a basic filter==

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

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

2. Inside that folder, we create a file called 'filter.php'.

3. Inside that PHP file, we define a class called filter_helloworld, that extends the moodle_text_filter class.
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
// ...
}
?>
</code>

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
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
return str_replace('world', 'hello world!', $text);
}
}
</code>

That is basically all there is to it!

==Giving your filter a name==

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.

When you do, you will find that your plugin does not have a name. We missed a step:

5. Inside the 'filter/helloworld' folder, create a folder called 'lang', and in there, create a folder called 'en'.

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

7. In that file, put
<code php>
<?php // $Id$
// Language string for filter/helloworld.

$string['filtername'] = 'Hello world!';
</code>

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

==Trying out your filter==

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.

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.

==Adding a global settings screen==

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:

8. Create a file called 'filtersettings.php' inside the 'filter/helloworld' folder. Use standard 'settings.php' file in Moodle 2.6 and later.

9. In the 'filtersettings.php' file, put something like:
<code php>
$settings->add(new admin_setting_configtext('filter_helloworld_word',
get_string('word', 'filter_helloworld'),
get_string('word_desc', 'filter_helloworld'), 'world', PARAM_NOTAGS));
</code>

10. In the language file 'filter/helloworld/lang/en/filter_helloworld.php' add the necessary strings:
<code php>
$string['word'] = 'The thing to greet';
$string['word_desc'] = 'The hello world filter will add the word \'hello\' in front of every occurrence of this word in any content.';
</code>

11. Change the filter to use the new setting:
<code php>
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
return str_replace($CFG->filter_helloworld_word,
"hello $CFG->filter_helloworld_word!", $text);
}
}
</code>

In standard Moodle, the censor, mediaplugin and tex filters all provide good examples of of how filters use global configuration like this.

==A note about performance==

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

==Local configuration==

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.

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:

12. Create a file called 'filterlocalsettings.php' inside the 'filter/helloworld' folder.

13. In the 'filterlocalsettings.php' file, put:
<code php>
class helloworld_filter_local_settings_form extends filter_local_settings_form {
protected function definition_inner($mform) {
$mform->addElement('text', 'word', get_string('word', 'filter_helloworld'), array('size' => 20));
$mform->setType('word', PARAM_NOTAGS);
}
}
?>
</code>

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
<code php>
<?php
class filter_helloworld extends moodle_text_filter {
public function filter($text, array $options = array()) {
global $CFG;
if (isset($this->localconfig['word'])) {
$word = $this->localconfig['word'];
} else {
$word = $CFG->filter_helloworld_word;
}
return str_replace($word, "hello $word!", $text);
}
}
?>
</code>

==Two types of filter==

In the past, Moodle supported two different types of filter:
* 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.
* 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.
The second option no longer exists in Moodle 2.5 and later. 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.

==Dynamic content==

From Moodle 2.7:
On (very few) pages - it is possible that page content is loaded by ajax *after* the page is loaded (e.g. equations in a glossary popup). In certain filter types (e.g. MathJax) javascript is required to be run on the output of the filter in order to do the final markup. For these types of filters, a javascript event is triggered when new content is added to the page (the content will have already been processed by the filter in php). The javascript for a filter can listen for these event notifications and reprocess the affected dom nodes.

To subscribe to the event:

// Listen for events triggered when new text is added to a page that needs
// processing by a filter.
Y.on(M.core.event.FILTER_CONTENT_UPDATED, this.contentUpdated, this);

To handle the event:

/**
* Handle content updated events - typeset the new content.
* @method contentUpdated
* @param Y.Event - Custom event with "nodes" indicating the root of the updated nodes.
*/
contentUpdated: function(event) {
var self = this;
Y.use('mathjax', function() {
self._setLocale();
event.nodes.each(function (node) {
node.all('.filter_mathjaxloader_equation').each(function(node) {
MathJax.Hub.Queue(["Typeset", MathJax.Hub, node.getDOMNode()]);
});
});
});
}

See: filter/mathjaxloader/yui/src/loader/js/loader.js

==See also==

* [[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.
* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system
* [[Filters]] user documentation about filters.
* [https://moodle.org/plugins/browse.php?list=category&id=7 - List of filters in the Plugins database].

[[Category:Filters]]
[[Category:Filter]]

[[Category:Plugins]]

PHPUnit integration

2014-10-06T20:04:46Z

Scyrma:

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described below.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

==Class and file naming rules==
The class names of all testcases need to be unique, Frankenstyle prefix is used to guarantee this. Since 2.6 it is possible to use automatic class loader when executing individual unit tests.

* All test case classes start with Frankenstyle prefix, for example: '''mod_forum_''', '''block_html_''', '''core_'''.
* All test case classes end with '''_testcase''' suffix.
* File names are constructed from the class names - the Frankenstyle prefix is removed, suffix '''_testcase''' is replaced with '''_test'''

Example:
* class '''mod_forum_lib_testcase''' is expected in file '''/mod/forum/tests/lib_test.php''', executed as <code>vendor/bin/phpunit mod_forum_lib_testcase</code>
* class '''core_text_testcase''' is expected in file '''/lib/texts/text_test.php''', executed as <code>vendor/bin/phpunit core_text_testcase</code>

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests. The expected file name for this test case is '''/mod/myplugin/tests/sample_basic_test.php'''.

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

The expected file name for this test case is '''/mod/myplugin/tests/some_permission_test.php'''.

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

Enrolment plugins

2014-06-17T15:38:13Z

Scyrma:

Since Moodle 2.0 all enrolment plugins must extend [https://github.com/moodle/moodle/blob/master/lib/enrollib.php enrol_plugin] base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods together with developer documentation.

Course enrolment information is stored in tables <code>enrol</code> and <code>user_enrolments</code> and optionally other custom database tables defined by individual enrolment plugins. Each plugin has complete total over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.

Enrolment gives users following privileges:
* User with active enrolment may enter course, other users need either temporary guest access right or moodle/course:view capability.
* "My courses" shows list of active enrolments for current user.
* Course participation - some activities restrict participation to enrolled users only. The behaviour is defined independently by each activity, for example only enrolled users with submit capability may submit assignments, the capability alone is not enough.
* Only enrolled users may be members of groups.
* Gradebook tracks grades of all enrolled users, visibility of grades is controlled by role membership.

Enrolments and role assignments are now separate concepts, you may be enrolled and not have any role and you may have a role in course and not be enrolled. Roles at course context level and below may be controlled by enrolment plugins.

==User enrolment process==

Manual enrolment plugins are the simplest way to handle user enrolments. This simplest plugin is enrol_manual, users with necessary permissions may enrol or unenrol users manually. enrol_flatfile plugin allows automation of enrolment and unernolment actions.

Fully automatic plugins are configured at the system level, they synchronise user enrolments with information stored in external systems (ex.: enrol_ldap, enrol_database and enrol_category). Some non-interactive plugins may require configuration of enrolment instances (ex.: enrol_cohort and enrol_meta).

Interactive enrolment plugins require user interaction during enrolment (ex.: enrol_self and enrol_paypal). These plugins need to override <code>enrol_plugin::show_enrolme_link()</code>, <code>enrol_plugin::enrol_page_hook()</code> and to implement adding and editing of enrol instance.

==Enrolment expiration and suspending==
User has active enrolment if all following conditions are met:
* user has record in <code>user_enrolments</code> table,
* user enrolment already started,
* user enrolment is not past timeend,
* user enrolment has active status,
* enrol instance has active status in <code>enrol</code> table,
* enrol plugin is enabled.

Most synchronisation plugins include a setting called ''External unenrol action''. It is used to decide what happens when previously enrolled user is not supposed to be enrolled any more. Synchronisation is usually executed from cli/sync.php or as part of standard cron.

Time based expiration was implemented in Moodle 2.5. Plugins that set timeend in user_enrolments table may want to specify expiration action and optional expiration notification, see <code>enrol_plugin::process_expirations()</code> and <code>enrol_plugin::send_expiry_notifications()</code>.

==Manual enrolment modifications==

The standard user enrolment UI does not use the following methods directly, so developers need to describe all possible UI enrolments actions via <code>enrol_plugin::get_user_enrolment_actions()</code>. It is very important to obey these restrictions in all externallib methods!

The following methods describe the allowed modifications for each enrolment instance:

* <code>enrol_plugin::roles_protected()</code> - True means that protected roles (nonempty component+itemid) cannot be modified by any other plugin. Return false if you want to allow users to remove all roles assigned by this plugin. Since Moodle 2.5 it is allowed to assign roles with component+itemid even if roles are not protected.
* <code>enrol_plugin::allow_enrol()</code> - True means other code may call <code>enrol_plugin::enrol_user()</code>, false means only plugin may enrol users. Each plugin is responsible for implementing its own UI for enrolment. See <code>enrol_plugin::get_manual_enrol_link()</code>.
* <code>enrol_plugin::allow_unenrol()</code> and <code>enrol_plugin::allow_unenrol_user()</code> - Is other code allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment.
* <code>enrol_plugin:allow_manage()</code> - Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.

==Standard capabilities==

* '''enrol/xxx:enrol''' - Must be defined when <code>enrol_plugin::allow_enrol()</code> returns true.
* '''enrol/xxx:unenrol''' - Must be implemented when <code>enrol_plugin::allow_unenrol()</code> or <code>enrol_plugin::allow_unenrol_user()</code> returns true.
* '''enrol/xxx:manage''' - Must be implemented when <code>enrol_plugin::allow_manage()</code> returns true.
* '''enrol/xxx:unenrolself''' - Usually implemented when plugin support self-unenrolment.
* '''enrol/xxx:config''' - Implemented when plugin allows user to modify instance properties. Automatic synchronisation plugins do not usually need this capability.

==Restore support==

Enrolment and role restore is supported since Moodle 2.4, earlier versions can restore only manual and self enrolments.

Plugins with automatic synchronisation may use <code>enrol_plugin:restore_sync_course()</code> hook to synchronise enrolments in newly created courses. The restore process starts with instance restore which must set mapping information <code>enrol_plugin::restore_instance()</code> (plugins may decide to map enrolments to other plugin type), then plugin must restore users enrolments <code>enrol_plugin::restore_user_enrolment()</code>, protected roles <code>enrol_plugin::restore_role_assignment()</code> and protected group membership <code>enrol_plugin::restore_group_member()</code>.

==See also==
* [[Enrolment API]]
* [[Enrolment usage overview]]
* [[New enrolments in 2.0]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]
[[Category:Plugins]]

Enrolment plugins

2014-06-17T13:28:30Z

Scyrma: /* Manual enrolment modifications */

Since Moodle 2.0 all enrolment plugins must extend [https://github.com/moodle/moodle/blob/master/lib/enrollib.php enrol_plugin] base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods together with developer documentation.

Course enrolment information is stored in tables <code>enrol</code> and <code>user_enrolments</code> and optionally other custom database tables defined by individual enrolment plugins. Each plugin has complete total over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.

Enrolment gives users following privileges:
* User with active enrolment may enter course, other users need either temporary guest access right or moodle/course:view capability.
* "My courses" shows list of active enrolments for current user.
* Course participation - some activities restrict participation to enrolled users only. The behaviour is defined independently by each activity, for example only enrolled users with submit capability may submit assignments, the capability alone is not enough.
* Only enrolled users may be members of groups.
* Gradebook tracks grades of all enrolled users, visibility of grades is controlled by role membership.

Enrolments and role assignments are now separate concepts, you may be enrolled and not have any role and you may have a role in course and not be enrolled. Roles at course context level and bellow may be controlled by enrolment plugins.

==User enrolment process==

Manual enrolment plugins are the simplest way to handle user enrolments. This simplest plugin is enrol_manual, users with necessary permissions may enrol or unenrol users manually. enrol_flatfile plugin allows automation of enrolment and unernolment actions.

Fully automatic plugins are configured at the system level, they synchronise user enrolments with information stored in external systems (ex.: enrol_ldap, enrol_database and enrol_category). Some non-interactive plugins may require configuration of enrolment instances (ex.: enrol_cohort and enrol_meta).

Interactive enrolment plugins require user interaction during enrolment (ex.: enrol_self and enrol_paypal). These plugins need to override <code>enrol_plugin::show_enrolme_link()</code>, <code>enrol_plugin::enrol_page_hook()</code> and to implement adding and editing of enrol instance.

==Enrolment expiration and suspending==
User has active enrolment if all following conditions are met:
* user has record in <code>user_enrolments</code> table,
* user enrolment already started,
* user enrolment is not past timeend,
* user enrolment has active status,
* enrol instance has active status in <code>enrol</code> table,
* enrol plugin is enabled.

Most synchronisation plugins include a setting called ''External unenrol action''. It is used to decide what happens when previously enrolled user is not supposed to be enrolled any more. Synchronisation is usually executed from cli/sync.php or as part of standard cron.

Time based expiration was implemented in Moodle 2.5. Plugins that set timeend in user_enrolments table may want to specify expiration action and optional expiration notification, see <code>enrol_plugin::process_expirations()</code> and <code>enrol_plugin::send_expiry_notifications()</code>.

==Manual enrolment modifications==

The standard user enrolment UI does not use the following methods directly, so developers need to describe all possible UI enrolments actions via <code>enrol_plugin::get_user_enrolment_actions()</code>. It is very important to obey these restrictions in all externallib methods!

The following methods describe the allowed modifications for each enrolment instance:

* <code>enrol_plugin::roles_protected()</code> - True means that protected roles (nonempty component+itemid) cannot be modified by any other plugin. Return false if you want to allow users to remove all roles assigned by this plugin. Since Moodle 2.5 it is allowed to assign roles with component+itemid even if roles are not protected.
* <code>enrol_plugin::allow_enrol()</code> - True means other code may call <code>enrol_plugin::enrol_user()</code>, false means only plugin may enrol users. Each plugin is responsible for implementing its own UI for enrolment. See <code>enrol_plugin::get_manual_enrol_link()</code>.
* <code>enrol_plugin::allow_unenrol()</code> and <code>enrol_plugin::allow_unenrol_user()</code> - Is other code allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment.
* <code>enrol_plugin:allow_manage()</code> - Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.

==Standard capabilities==

* '''enrol/xxx:enrol''' - Must be defined when <code>enrol_plugin::allow_enrol()</code> returns true.
* '''enrol/xxx:unenrol''' - Must be implemented when <code>enrol_plugin::allow_unenrol()</code> or <code>enrol_plugin::allow_unenrol_user()</code> returns true.
* '''enrol/xxx:manage''' - Must be implemented when <code>enrol_plugin::allow_manage()</code> returns true.
* '''enrol/xxx:unenrolself''' - Usually implemented when plugin support self-unenrolment.
* '''enrol/xxx:config''' - Implemented when plugin allows user to modify instance properties. Automatic synchronisation plugins do not usually need this capability.

==Restore support==

Enrolment and role restore is supported since Moodle 2.4, earlier versions can restore only manual and self enrolments.

Plugins with automatic synchronisation may use <code>enrol_plugin:restore_sync_course()</code> hook to synchronise enrolments in newly created courses. The restore process starts with instance restore which must set mapping information <code>enrol_plugin::restore_instance()</code> (plugins may decide to map enrolments to other plugin type), then plugin must restore users enrolments <code>enrol_plugin::restore_user_enrolment()</code>, protected roles <code>enrol_plugin::restore_role_assignment()</code> and protected group membership <code>enrol_plugin::restore_group_member()</code>.

==See also==
* [[Enrolment API]]
* [[Enrolment usage overview]]
* [[New enrolments in 2.0]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment]]
[[Category:Plugins]]

Theme changes in 2.0

2013-07-05T18:01:32Z

Scyrma: /* Other API changes */ layouts are in base, not standard

{{Work in progress}}
{{Infobox Project
|name = Theme changes
|state = Implementation
|tracker = MDL-20204
|discussion = [http://moodle.org/mod/forum/discuss.php?d=140089 HEADS UP: Major theme changes landing]
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] + feedback and ideas from other developers
}}
{{Moodle 2.0}}

=Goals=
The main goals are:
# easier theme customisations - both CSS and images
# simplify core and themes code
# significant performance improvements
# solve majority of browser caching problems
# use YUI CSS foundation
# allow themes to be stored in separate directory without www access (such as dataroot)

It should be easy to upgrade simple older themes. I think it is better if old themes are completely disabled with reasonable fallback mechanism. Why should we display broken themes during upgrade? Imagine users or teachers can select "broken" themes in the course edit page or a profile, I think it is more professional to display only new and upgraded themes in selectors instead of pretending old themes will work 100%. We have to make sure old themes will not cause fatal white screen errors.

=Design overview=

All theme files are served through two files ''/theme/styles.php'' and ''/theme/image.php''. More advanced themes may serve extra javascript files through the ''/theme/javascripts.php'' file and a new config option with list of JS files. This approach allows us to parse the resulting CSS and replace all image placeholders and theme settings with current values.

All CSS style sheets (including YUI, plugin CSS and parent themes) are merged into a single large CSS file served via the /theme/styles.php file. This script accepts following parameters:
* '''theme''' (string) - name of the theme
* '''rev''' (int) - theme revision number stored in $CFG->themerevision

All options and features are reviewed and optimised. Backwards compatibility is not a primary concern, future possibilities and easy maintenance are always favoured.

==Theme directory structure==

{| class="nicetable"
|-
! <center>''File/folder'''</center>
! <center>'''Description''</center>
|-
| db/ (optional)
| Installation and upgrade hooks - use of db tables is not recommended.
|-
| lang/
| Folder with standard language files - name of theme, usage information, settings. Standard themes store lang files in /lang/ for now.
|-
| layout/*.php
| Folder with page layout templates
|-
| pix/
| Folder with theme pictures - used from CSS or layout only, not used from other plugins.
|-
| pix_core/ (optional)
| Folder with overridden core images and icons from /pix/ folder
|-
| pix_plugins/ (optional)
| Folder with overridden plugin icons - structure is typeofplugin/pluginname/ which maps to pix folder in plugins
|-
| style/*.css
| Style sheet files referenced from the config.php.
|-
| config.php
| Theme configuration - see bellow.
|-
| lib.php (optional)
| Library functions - custom css post-processing, custom render factory, theme init function
|-
| renderers.php (optional)
| Custom renderers used from custom renderer factories.
|-
| settings.php (optional)
| Custom theme settings - colours, logos, etc. Settings are applied in custom css post-processing function.
|-
| [[version.php]]
| Needed for install and upgrade hooks, states compatibility with specific Moodle versions. Used for triggering of cache purging.
|}

==Theme config.php==

The theme config.php structure is simplified and a bit more flexible. The goal is to make overriding of parent themes simple and easy to understand. Please note global $THEME variable is not available any more, use theme property in current page instance instead.

<code php>$THEME->parents = array('standard', 'purple');</code>
Lists all parents top-down, each theme contains the full list of parents, this is non-recursive and more flexible specification without any limits. Originally the number of parent levels was restricted.

<code php>$THEME->sheets = array('styles_layout', 'styles_fonts', 'styles_color');</code>
The same as before, lists files from current theme directory.

<code php>$THEME->parents_exclude_sheets = array('standard'=>array('styles_moz'), 'purple'=>array('styles_fonts'));</code>
It is also posssible to use ''true'' instead of array in order to specify ''all'' sheets or all sheets in all parents, if not specified the value from the parent theme is used.

<code php>$THEME->editor_sheets = array('styles_tinymce');</code>
We can not load the full CSS file into the HTML editor's content area, instead we load editor sheet from lib/editor/editorname/editor_sheets.css and also sheets specified in theme.

<code php>$THEME->plugins_exclude_sheets('mod_book', 'gradereport_grader');</code>
Ideally all plugin specific CSS should be stored in styles.css file separately in each plugin. This option lists plugins that should be excluded from this theme, if not specified the value from the parent theme is used.

<code php>$THEME->layouts = array(...);</code>
The complete list of layouts is in theme/base/config.php. Page layouts are in fact high level templates that are using PHP syntax. The template files are stored in layout/ subdirectory. Each page layout has specification of block areas and link to template file. Themes may also reference layouts files from other themes.

<code php>$THEME->resource_mp3player_colors, $THEME->filter_mediaplugin_colors</code>
Obsoleted. If not specified the value from the parent theme is used. All these should be moved to real theme settings.

<code php>$THEME->rendererfactory = 'standard_renderer_factory';</code>
The same as before. It is the name of class that returns needed instances of core and plugin renderers. defined in core some library or theme/themename/lib.php or theme/themename/renderers.php

<code php>$THEME->csspostprocess = 'csspostprocess';</code>
Name of custom CSS post-processing function, this function is usually defined in theme/themename/lib.php.

<code php>
$THEME->javascripts = array('navigation');
$THEME->javascripts_footer = array('someJSlibrary');
</code>
List of extra javascript files that are included on each page. Themes can not include extra scripts from the theme folder because the folder may not be accessible via web.

=Implementation=

==One huge CSS sheet==

Each page includes only one huge style sheet. All theme sheets are served by a /theme/styles.php script. Page parameters specify the theme name and revision.

The CSS concatenation is done from the YUI CSS, styles.css from all plugins and theme style sheets starting with top most parent and current theme last, please note the order is very important. The algorithm is following:
# YUI2 CSS
## merge all YUI2 CSS into one file, respect correct order of files
# plugins CSS
## go through all plugins and search for styles.css - put the list into array, use component names as keys, locations as values
## filter out excluded sheets specified in current $THEME->plugins_exclude_sheets
# theme CSS
## go through all sheets defined in all parents and store all $THEME->sheets in array
## filter out excluded sheets specified in current $THEME->parent_exclude_sheets
# resolve real image locations
## regex search for <nowiki>[[pix:componentname|imagewithsibdirnoext]]</nowiki>
## priority is: current theme, parent themes, then plugin or YUI fodlers
## images in web accessible areas are linked directly, images in dataroot would have to go through /theme/image.php?theme=xxx&file=/sub/img&component=moodle&rev=-1
# apply theme admin settings - values and image locations

Please note that the current $PAGE->requires->css() is suitable mostly for user supplied CSS for data content such as the custom CSS used in mod/data/ module.

The YUI3 reset CSS is loaded separated before this huge combined CSS stylesheet, YUI3 loader may load CSS on the fly from Javascript.

==Theme caching==

Potential problems are:
* server performance - the merging of all CSS, parent themes and image resolving is relatively expensive
* bandwidth - longer caching, fewer files and optional gzip compression
* stale data in browser caches - different file needs to be served when anything in CSS changes

The theme CSS content depends on:
* current theme
* theme revision

The theme revision is stored in $CFG->themerev, it is an integer counter incremented after installation/upgrade of any plugin or core. The revision value -1 is used in theme designer mode to prevent the caching completely.

All images used both from PHP and CSS have to be cached too. This is handled automatically in /theme/image.php which accepts similar parameters like the styles.php script.

==The theme designer mode==

Administrator, theme designers and developers often need to tweak CSS or images. In previous versions users had to purge the browser caches manually.

In theme designer mode no CSS is cached on server or in browser, each changes are immediately visible. The switching on of this mode immediately invalidates old caches, the caching is turned on again after switching it off. This mode causes higher server load.

This mode also disables all CSS cleanup and compression, all comments are kept and extra debug information can be included in CSS.

This setting is available from the Appearance settings page.

==Performance improvements==

There are several possibilities for more performance improvements:
* storing of final CSS files in dataroot - caches need to be deleted after each theme revision change; this could significantly reduce server load
* longer lifetimes - revision parameter eliminates the stale CSS in browser cache completely , lower bandwidth consumption
* gzip compression - faster page loading on first page
* remove comments and useless white space
* etc.

==Browser hacks==

Old meta.php was used mostly for conditional loading of IE specific hacks. Open University developed alternative solution which adds browser specific classes to body html element. This can be implemented in the pagelib method returning standard body tags.

<body class="ie ie7">

#mypage .whatever {
/** normal rules */
}
.ie6#mypage .whatever {
/** broken rules */
}

OU used these hacks not only for IE ;-)

==RTL support==

Originally RTL tweaks were stored in separate files. Now we use the same body class tweaks as described above.

<body class="dir-rtl">

#mypage .whatever {
/** normal rules */
}
.dir-rtl #mypage .whatever {
/** RTL rules */
}

==YUI==

Moodle started using YUI framework around 1.7, until 2.0dev we did not use any UI widgets that required CSS. The problem is that the YUI needs to be loaded before theme and plugin CSS, second problem is that standard YUI CSS requires reset CSS which greatly improves A-grade browser compatibility and helps theme designers.

YUI3 implements new loaders both for CSS and JS, there is a complementing PHP dependency loader for YUI.

===YUI CSS foundation===

Moodle styles are based on YUI foundation? Why not? The benefits are:
* eliminates some different HTML defaults (margins, paddings, font sizes, etc.) [http://developer.yahoo.com/yui/reset/ (YUI CSS Reset)]
* consistent font sizing and better font-family degradation [http://developer.yahoo.com/yui/fonts/ (YUI CSS Fonts)]
* the standard YUI CSS is already built on top of this foundation
* incredibly simple table-less page layouts that include nesting [http://developer.yahoo.com/yui/fonts/ (YUI CSS Grids)] (optional, themes do not have to use it for layout)

===YUI widgets customisation===

The standard YUI CSS has to be loaded after YUI CSS Base (Reset+Fonts+Grids), but before our own CSS. Overriding of YUI stylesheets should not depend on the order of loading, we only guarantee that the YUI CSS foundation sheets are loaded before any other CSS, customisations of YUI skins has to use moodle class selectors.

===YUI versioning===

In 1.9 we store all YUI files in /lib/yui/ folder, this was a problem when upgrading to YUI version from upstream because the old files could be still cached in browsers.

In 2.0 we are finally replicating the YAHOO directory structures, each new version is stored in separate directory.

===Combination of YUI 2 and 3===

YUI 3 uses JS autoloading which is a great step forward and simplification. Unfortunately we still need the YUI2 libraries around for some time, luckily YUI2 libraries may coexist with YUI3 code.

==The image resolver==

Images are used in html code and in CSS style sheets. The problem is easy to solve in PHP code, partial solution was already present in Moodle 1.9 - see $CFG->pixpath

In 2.0dev there was implemented a new icon_finder class, it can be replaced by much simpler rules, we could also add pix support into all plugins.

Image locations:
* /mod/modulename/pix/, blocks/blockname/pix/ - in all plugins
* /theme/themename/pix/ - theme images
* /theme/themename/pix_core/ - overridden images from core /pix/ folder
* /theme/themename/pix_plugins/plugin/plugintype/ - overriding of plugin images in themes

The standard API is <code>$OUTPUT->pix_url($componentname, $imagename, encoded)</code> when used from PHP and <nowiki>[[pix:componentname|imagename]]</nowiki> if used in CSS.

Image resolved allows us to serve images from dataroot via /theme/image.php script and also solves all browser caching issues.

==Themes in extra directory==

Themes in dataroot is a frequently requested feature. Some admins might not like this, it should be optional. Some really advanced themes with lots of custom files might not be compatible at first. In fact it does not have to be dataroot, this location is configurable via $CFG->themedir.

In the stable branch we have a strange mix of standard themes. Moodle 2.0 is expected to include following themes:
* base - bare bones minimal theming that most other themes build on
* standard - basic theme that can be used as base for really simple themes (the exact look of new standard theme is not decided yet)
* customcolor - standard with admin specified colour palette and custom logos (not confirmed)
* and many other fancy modern themes like anomaly ( optionally with multiple configuration settings)

Other contrib themes could be available via web interface from Moodle configuration in some future Moodle version.

==Admin theme settings==

Very often users need to make small tweaks to standard themes such as different colour or logos. There should be a way to keep this settings in config_plugin and files separately in dataroot. Settings are placed in /theme/themename/settings.php. This new feature could significantly reduce known theme upgrade problems in the future.

This feature replaces the original CSS constants and will probably use the same syntax. The original CSS constants required modifications in dirroot which was in some cases unacceptable. CSS constants would not be compatible with automatic updates vie web interface anyway.

This feature requires advanced caching of CSS. These settings and files should be available in layouts and renderers too.

The actual replacing of setting placeholders by setting values is performed in custom css post-processing function specified in config.php. Logos and other custom images would be specified as external URLs, later we could also add basic support for storage of these custom theme files in standard Moodle filesystem.

==Page layout==
Each page may specify one of standard page layouts that are defined in theme/base/config.php. It is not possible to add custom layouts.

Layout definition consists of:
* template file specification - template name + file name without extension
* definition of regions
* default region

New layouts will not be added in the STABLE CVS branches.

==Renderers==

Renderers are small methods that render visual elements using functional programming - our old style PHP style.

Module may define own renderer class and use own renderer methods. Themes may override both core and plugin renderers however you need to have some more advanced understanding of PHP and Moodle design in general.

==Templates (maybe in future)==

Similar to page layouts but much smaller parts of UI that are embedded into pages. This is a new feature that is not used in Moodle core yet.

Code developers may choose to use templates instead of renderers for some larger parts of UI, they may also use renderers from templates. The major difference is that templates accept just one $DATA object with all parameters, templates might be also much easier to use&understand for typical theme designers.

The original emulated templates approach was replaced because it was designed for code developers, not designers. I think it is much easier to just copy templates from core or plugins into themes and tweak them, instead of the reverse engineering of the renderers.

Please note this does not mean that Moodle is switching to templates now, but technically we could, plugin developers would decide to do so independently. This topic should be revisited in Moodle 2.1dev.

==Other API changes==

* added ''course'' layout
* $PAGE->set_generaltype() replaced by $PAGE->set_pagelayout() because it really switches to one of the layouts from the standard theme; also the complete list of layouts is given in theme/base/config.php - there is no way to add plugin layouts, the $PAGE->set_pagelayout() is used from core and plugin code, not from themes, so it is not possible to add new layouts at all (and never was)
* name things ''moodle_*'' only if potential conflicts exist, everything plugin related should be named ''componentname_'' (mod_ is usually an exception)- this was discussed several times before; renamed ''moodle_core_renderer' class to ''core_renderer'', etc.
* themes are now real plugins with capabilities, lang packs, upgrade code, settings, upgrade code, etc. - it is not recommended to create new db table though

=Backwards compatibility and upgrades=

BC is very limited, all themes and modules need to be manually updated. Keeping old themes during the upgrade must not cause fatal PHP errors. Old themes can be detected by searching for /theme/oldtheme/styles.php, this file will not be present in the new themes any more. Moodle core would simply use the specified parent theme or the standard theme.

==Theme upgrade steps==
# delete styles.php
# redefine all config.php options - in majority of cases change parent value to parents array
# rename styles_ie6.css and styles_ie7.css to styles_layout_ie6.css and styles_layout_ie7.css - each normal sheet may have an extra sheet with _ieX suffix now, these are loaded automatically, excluding is applied based on $THEME->parents_exclude_sheets() info from the current theme
# rename rtl.css to styles_layout_rtl.css - again each normal style sheet may have extra sheet with _rtl suffix similar to IE hacks sheets
# delete header.html, footer.html and meta.php - obsoleted by $THEME->layouts option and new layout files
# add custom layouts and rendereds

In order to minimize confusion during the upgrade, the old themes will be ignored and will be listed os "Incompatible" on the theme selection page - this page is probably the first place admins go in order to diagnose theme problems.

==Module upgrade steps==
* rename mod/modname/styles.php to styles.css
* put all images into mod/modname/pix/
* replace $CFG->pixpath with $OUTPUT->pix_url('imagename', 'mod_modname')

==Removed features==
# '''sometheme/meta.php''' - used mostly for IE6/7 hacks, custom layouts may be used instead
# '''smartpix''' - completely obsoleted by the new image location resolution algorithm
# '''styles.php''' replaced by styles.css, supported in all plugin types - the PHP syntax is not needed anymore because images are specified using <nowiki>[[pix:component|dir/image]]</nowiki> syntax and we can also use custom css post-processors
# '''$CFG->pixpath''' replaced by $OUTPUT->pix_url()
# '''CSS constants''' replaced by the admin theme settings
# separate IE6 and IE7 sheets - replaced by body class attributes
# separate RTL sheets - replaced by body class attribute

=Expected reactions=

{| class="nicetable"
|-
! <center>'''User type'''</center>
! <center>'''Negative'''</center>
! <center>'''Positive'''</center>
|-
| Core developer
| none
| No backwards compatibility headaches. Powerful new features. More flexible API.
|-
| Contrib developer
| Has to learn new API and upgrade current code.
| New useful pix folder and standard styles.css in all plugins. $OUTPUT->pix_url() more flexible then old pixpath.
|-
| Theme designer
| Has to learn new theme API. Old advanced themes has to be completely redesigned. Has to understand YUI CSS foundation.
| They can finally override core and plugin images. Easier distribution of custom themes. New income opportunity. Basic theme structure is simplified. No browser caching issues when designing themes.
|-
| Administrator
| All themes need to be updated. Old themes are ignored.
| Much easier installation (optionally in dataroot) and easy customisation without code modification (images and colours for example). Much safer upgrades. Possibility to upgrade theme via web interface. No browser caching issues when upgrading themes. Better performance and lower server load.
|}

==See also==

Using Moodle forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=131219 Yet more theme changes proposal]
* [http://moodle.org/mod/forum/discuss.php?d=140089 HEADS UP: Major theme changes landing]
* [[Output_renderers]]

[[Category:Themes]]

Question Engine 2:Overview

2012-07-12T17:17:52Z

Scyrma: /* Brief digression: who controls the model, the quiz or the question? */

{{Template:Question_engine_2}}
This page outlines how I think the question engine should work in Moodle 2.0 or 2.1.

Previous section: [[Question Engine 2:Rationale|Rationale]]

==Normalise the database structure==

At the moment, the some parts of the question_sessions and question_states tables and their relations are not normalised. This is a technical term for describing database designs. Basically, if the tables are normalised, then each 'fact' is stored in exactly one place. A normalised database is much less likely to get into an inconsistent state. Changing to a normalised structure should therefore increase robustness.

In addition, I wish to change the tables, so the the responses received from the student are stored in a much more 'raw' form. That will mean that the responses can be saved much earlier in the sequence of processing, which will again increase robustness. It will also allow the sequence of responses from the student to be replayed more easily, making it easier to continue after a server crash, to regrade, and to write automatic test scripts.

The detailed design describes the new database structure.

(+++Robustness, +Correctness)

==New concept: Question behaviours==

At the moment, the various sequences of states that a question can move through in response to student input is hard-coded. It is controlled by a combination of the compare_responses and grade_responses methods of the question types, and tangled logic in the question_process_responses function. This makes it difficult to add new ways on interacting with questions, for example certainty based marking. Also, the current code is tricky to keep working.

I would like to separate out the control of how a question moves through different states, into what I will call question behaviours. Currently, Moodle has three or four of these:

===Deferred feedback===

This is how the quiz currently work when adaptive mode is off. The student enters a response to each question, then does Submit all and finish at the end of their attempt. Only then do they get feedback and/or grades on each question, depending on the review settings.

===Adaptive===

In this mode there is a separate submit button beside each question, so the student can submit each question individually during the attempt, and if they are wrong, try to improve their answer, although for a reduced grade.

Currently, the way adaptive mode works from the student point of view is not very good. I propose to replace it with a new Interactive mode. See below.

===Manually graded===

Essay questions need to be manually graded by the teacher, so you cannot really use them in adaptive mode (although currently there is nothing in the Quiz to stop you, which leads to confusing results). And it is not quite the same as Deferred feedback mode, because the student must wait for the teacher to grade their response after clicking submit all and finish.

===Each attempt builds on last===

This is very similary to the deferred feedback model, except that in subsequent attempts, each question does not start blank, but instead with the student's last response from the previous attempt.

Currently in Moodle there is nothing to stop you trying to combine Each attempt builds on last with Adaptive mode, although that combination does not make any sense to me. I think it simplifies things to treat this as a separate mode, although, of course, it will share code with Deferred feedback mode.

There are also some new modes that I propose to add, either immediately, or shortly after the main part of the work:

===Interactive===

This will replace adaptive mode. This is the model that has been used successfully for several years in the OU's [http://www.open.ac.uk/openmarkexamples/ OpenMark] system. The OU has also modified Moodle to work like this, but because of the way the quiz core currently works, I was not happy just merging the OU changes into Moodle core. In a sense, this whole document grew out of my thoughts about how to implement the OU changes in Moodle core properly.

In the existing adaptive mode, after the student has clicked submit, the question both shows the feedback for the last answer the student submitted, while also letting the student change their answer. This can lead to weird results. For example create a numerical question 2 + 2 = 4. Attempt it. Enter 4. Click Submit. Enter 5. Click Save. You will see a page that seems to say that your answer is 5 and it is correct!

In Interactive mode, the question is either in a state for the student to enter their answer, with a Submit button; or it is showing feedback for the student's previous attempt, with a Try again button to get back to the first state.

The other difference is that students are only allowed a limited number of tries at each question (typically three). When they submit their third try, or when they submit a correct answer, that question is finished and they must go onto the next one.

(This is quite difficult to explain. Try [https://students.open.ac.uk/openmark/s205.ayrf/ this example] and you should see how it works.)

===Immediate feedback===

This would be like cross between Deferred feedback an Interactive. Each question has a submit button beside it, like in interactive mode, so the student can get the feedback immediately while they still remember their thought processes while answering the question. However, unlike the interactive model, there is no try again button. You only get one chance at each question.

This is a necessary prerequisite for implementing MDL-11047, which is fairly frequently asked for in the quiz forum.

===Certainty based marking with deferred feedback===

This takes any question that can use the deferred feedback model, and adds three radio buttons to the UI (higher, medium, lower) for the student to use to indicate how certain they are that their answer is correct. If they are more certain, the get more marks if they are right, but lose marks if they are wrong. This encourages students to reflect about their level of knowledge.

===Certainty based marking with immediate feedback===

This is like immediate feedback mode with the certainty based marking feature.

===Delegate to a remote system===

The Opaque question type from contrib, which is used to run both OpenMark and [http://stack.bham.ac.uk/ STACK] questions inside a Moodle quiz was very difficult to implement within the current code. Since the remote system controls the flow of the question, it makes sense to use a custom behaviour for this question type, and that will be possible in the new code.

===Information item===

Used for descriptions. There is no grade. Item gets marked as complete after the student has seen it once. Displays general feedback after the attempt is over.

===Missing===

This is like the Missing question type. This behaviour is used in the situation:
# Admin installs some behaviour.
# Student attempts quiz using that model.
# Admin uninstalls that model.
# Teacher tries to review that student's attempt.
The missing question behaviour does the best job it can to allow the review of the attempt with the missing model, while displaying an on-screen warning.

So, what exactly does the behaviour control? Given the current state of the question, it limits the range of actions that are possible. For example, in adaptive mode, there is a submit button next to each question. In non-adaptive mode, the only option is to enter an answer and have it saved, until the submit all and finish button is pressed. That is, there will be a class in the PHP code for each model, and it will have methods that replace the old question_extract_responses, question_process_responses, question_process_comment and save_question_state functions in the current code.

(+++Richness, ++Correctness, +Robustness)

===Brief digression: who controls the model, the quiz or the question?===

There is one design decisions that it took a long time for me to resolve, and I want to mention it here.

The question is: Is the behaviour a property of the question, or the quiz?

At the moment, there is a setting in the quiz that lets you change all the questions in the quiz from adaptive mode to non-adaptive mode at the flick of a switch. Or, at least, it allows you to re-use the same questions in both adaptive and non-adaptive mode. This suggest that the behaviour is a property of the quiz.

On the other hand, suppose that you wanted to introduce the feature that, in adaptive mode, the student gets different amounts of feedback after each try at getting the question right. For example, the first time they get it wrong the only get a brief hint. If they are wrong the second time they get a more detailed comment, and so on. In order to do this, you need more data (the various hints) in order to define an adaptive question that is irrelevant to a non-adaptive question. Also, certain question types (e.g. Opaque, from contrib) have to, of necessity, ignore the adaptive, non-adaptive setting. And I suggested above that, manually graded question types like Essay should really be considered to have a separate behaviour. This suggests that the behaviour is a property of the individual question. (Although usability considerations suggest that a single quiz should probably be constructed from questions with similar behaviour.)

I eventually concluded that both answers are right. That is, it is a good idea for the quiz to have a setting like adaptive/non-adaptive that sets out the teacher's intention of how each question in this quiz should behave. However, the exact choice of behaviour to use is up to the different question types. When a quiz attempts is started, each question type is asked something like "A quiz attempt is starting using 'adaptive mode'. Exactly which behaviour should be used for questions of this type in this attempt?" This gives questions that can only work in a certain way (for example essay questions) a chance to override the quiz setting.

==Clarifying question states==

Although there is a database table called question_states, the column there that stores the type of state is called event, and the values stored there are active verbs like open, save, grade. The question_process_responses function is written in terms of these actions too. One nasty part is that during the processing, the event type can be changed several times, before it is finally stored in the database as a state.

I would like to clearly separate the concept of the current state that a question is in, and the various actions that lead to a change of state. The actions will be handled by the behaviours, and the state will be stored in the database as a state.

The list of available states will also be changed slightly to match the following diagram. This came from thinking about what information it was important to display in the quiz navigation block.

[[Image:Question_state_diagram.png]]

(+Correctness, +Richness).

==What are the parts of a question?==

When we come to think of outputting a question on-screen, we can now see that there are several things that affect what it will look like:
# The question type (multichoice, shortanswer, essay, ...)
# The behaviour (deferred feedback, interactive, CBM, ...)
# What state the question is in (has the student answered yet, has it been graded, ...)
# The options from the particular activity (whether any marks are available for this question, are students allowed to see their grades, how many decimal places to use to display grades, does this user have permission to make a manual comment ...)

Also, we want different question type and behaviours to have the freedom to display whatever they like to the students; but we also want all the questions in a quiz to look and behave consistently, so that the experience is not confusing.

In the sketch below, I try to summarise the bits that may be present in a typical question. If all questions can have these bits in this order, then that is probably enough consistency. The flexibility comes from allowing the question type or behaviour to put whatever it likes inside those bits.

We can divide what you see when looking at a question is into three main parts:
# Information (meta-data): Which question number this is, a summary of what state it is currently in, what grade you have got for it (or how many marks are available, if any), whether you have flagged it. This has a grey background in the sketch below.
# The question and the response to it. This has a blue background in the sketch.
# The outcome from submitting that response. This has a yellow background.

[[Image:Parts of a question2.png]]

The full list of options that control which of those bits are visible at any time are:

; correctness : (hidden / visible) whether the student gets told whether their answer was (in/partially)correct in the status summary under the question number, or instead are told something vague like 'Finished'.
; marks : (hidden / max only / actual mark and max / actual mark and max with explanation ) whether the student can see the number of marks available, and how many marks they got, and how much detail of the marking to display.
; marks d.p. : (0 .. 7) how many decimal places marks are displayed to.
; flags: (hidden / visible / visible and editable) this is the feature that lets students bookmark or flag a question in an attempt for later reference.
; read-only: Whether the question just shows the response was already entered, or whether it gives controls to the user enter/change their response.
; specific feedback: (hidden / visible) feedback that relates to the particular response the student entered.
; general feedback : (hidden / visible) whether the general feedback (same for all students) is visible.
; correct response : (hidden / visible) whether the automatically generated message or other indication of the correct answer is visible.
; manual comment: (hidden / visible / visible and editable) whether the comment manually added by the teacher is visible and editable by the current user.
; response history : (hidden / visible) whether the list of steps the student went through to answer the question is displayed.

These options are initially set by whatever it is that is using the question (for example the quiz will initialise them from the quiz settings). Then these options are modified by the behaviour. For example it should ensure that no feedback is displayed until the student has actually submitted an answer, or that after they have submitted their final answer, the question only appears in read-only mode.

==Reorganise the code==

There will, of course, be a new class for each behaviour, that all inherit from the same base class.

At the moment question type classes have multiple responsibilities.
# They is information about the question types, and loading and saving, importing and exporting, backing up and restoring questions of that type.
# Then there is the processing of student responses for a particular instances of that question type.
# And then there is displaying the question in its various states.
(Fortunately, 4. Displaying an editing form, is already in a separate class.)

Moodle 2.0 introduces the [[Theme_engines_for_Moodle%3F|renderer concept]]. Introducing qtype renderers will move the output code (3) into separate classes. This change to the question engine is the appropriate time to introduce qtype renderes.

I will also introduce a new set of classes to store the state of a question within a quiz attempt. That is basically the combination of the $question and $state objects that are passed around at the moment, but with a specific subclass for each question type. This moves all the processing logic (2) into a separate class. That leaves the question type class itself just responsible for (1).

Of course the behaviour classes and the question_state classes need to work together, and this is clearly a situation for the [http://en.wikipedia.org/wiki/Strategy_pattern strategy pattern]. However, I have not yet decided whether the question type is the context, and the iteration model is the strategy, or vice versa. I will have to see which comes out better when I do the implementation.

Finally, there will be a new class in questionlib.php for managing the set of questions in an attempt. Already, in the Moodle 2.0 quiz developments, I have changed the quiz code to create a quiz_attempt class. This keeps track of all the questions in the quiz attempt. However, this really needs to be split into two bits. The job of tracking a set of questions and what state they are in is exactly the job of the question engine. Therefore we should have a question_set_attempt class that does that job. That class will take over the job of a number of functions in questionlib.php, for example question_load_states. Then the quiz_attempt class can just focus on the quiz-specific things, and use the question_set_attempt class. This new class should make it easier to use questions in other modules.

It should be possible to organise the code so that only the question_set_attempt class had to load or save data to or from the database. It will then pass that data on to wherever it is needed. That should be good for efficiency.

(+Robustness, +Efficiency)

==Simplified API for question types==

In the summary of how the quiz currently works, I said, "The student enters an answer to each question which is saved. Then when they submit the quiz attempt, all the questions are graded." In fact, that was a lie. Whenever a response is saved, the grade_responses method of the question type is called, even in the state is only being saved. This is confusing, to say the least, and very bad for performance in the case of a question type like JUnit (in contrib) which takes code submitted by the student, and compiles it in order to grade it.

So some of the API will only change to the extent that certain functions will in future only be called when one would expect them to be. I think this can be done in a backwards-compatible way.

Another change will be that, at the moment, question types have to implement tricky load/save_question_state methods that, basically, have to unserialise/serialise some of the state data in a custom way, so it can be stored in the answer column. This is silly design, and leads to extra, unnecessary database queries. The changes to the database structure will to eliminate the need for these methods.

Hopefully the above changes to how the code is organised will make it mauch easier to write new question types.

(+Richness, +Correctness, +Efficiency)

==Introduce more automated testing==

Since the question_set_attempt class keeps track of all the data that is needed when processing questions, it should be very easy to write automatic tests (unit tests) for all the other parts of the question engine. That should greatly help in eliminating bugs.

I am intending to take a [http://en.wikipedia.org/wiki/Test-driven_development test-driven] approach to implementing this proposal.

(+++Correctness, ++Robustness)

==See also==

In the next section, [[Question Engine 2:Design|Design]], gives the detailed design of the above solution.

* Back to [[Question_Engine_2|Question Engine 2]]

Question Engine 2:Overview

2012-07-12T17:16:33Z

Scyrma: /* Brief digression: who controls the model, the quiz or the question? */

{{Template:Question_engine_2}}
This page outlines how I think the question engine should work in Moodle 2.0 or 2.1.

Previous section: [[Question Engine 2:Rationale|Rationale]]

==Normalise the database structure==

At the moment, the some parts of the question_sessions and question_states tables and their relations are not normalised. This is a technical term for describing database designs. Basically, if the tables are normalised, then each 'fact' is stored in exactly one place. A normalised database is much less likely to get into an inconsistent state. Changing to a normalised structure should therefore increase robustness.

In addition, I wish to change the tables, so the the responses received from the student are stored in a much more 'raw' form. That will mean that the responses can be saved much earlier in the sequence of processing, which will again increase robustness. It will also allow the sequence of responses from the student to be replayed more easily, making it easier to continue after a server crash, to regrade, and to write automatic test scripts.

The detailed design describes the new database structure.

(+++Robustness, +Correctness)

==New concept: Question behaviours==

At the moment, the various sequences of states that a question can move through in response to student input is hard-coded. It is controlled by a combination of the compare_responses and grade_responses methods of the question types, and tangled logic in the question_process_responses function. This makes it difficult to add new ways on interacting with questions, for example certainty based marking. Also, the current code is tricky to keep working.

I would like to separate out the control of how a question moves through different states, into what I will call question behaviours. Currently, Moodle has three or four of these:

===Deferred feedback===

This is how the quiz currently work when adaptive mode is off. The student enters a response to each question, then does Submit all and finish at the end of their attempt. Only then do they get feedback and/or grades on each question, depending on the review settings.

===Adaptive===

In this mode there is a separate submit button beside each question, so the student can submit each question individually during the attempt, and if they are wrong, try to improve their answer, although for a reduced grade.

Currently, the way adaptive mode works from the student point of view is not very good. I propose to replace it with a new Interactive mode. See below.

===Manually graded===

Essay questions need to be manually graded by the teacher, so you cannot really use them in adaptive mode (although currently there is nothing in the Quiz to stop you, which leads to confusing results). And it is not quite the same as Deferred feedback mode, because the student must wait for the teacher to grade their response after clicking submit all and finish.

===Each attempt builds on last===

This is very similary to the deferred feedback model, except that in subsequent attempts, each question does not start blank, but instead with the student's last response from the previous attempt.

Currently in Moodle there is nothing to stop you trying to combine Each attempt builds on last with Adaptive mode, although that combination does not make any sense to me. I think it simplifies things to treat this as a separate mode, although, of course, it will share code with Deferred feedback mode.

There are also some new modes that I propose to add, either immediately, or shortly after the main part of the work:

===Interactive===

This will replace adaptive mode. This is the model that has been used successfully for several years in the OU's [http://www.open.ac.uk/openmarkexamples/ OpenMark] system. The OU has also modified Moodle to work like this, but because of the way the quiz core currently works, I was not happy just merging the OU changes into Moodle core. In a sense, this whole document grew out of my thoughts about how to implement the OU changes in Moodle core properly.

In the existing adaptive mode, after the student has clicked submit, the question both shows the feedback for the last answer the student submitted, while also letting the student change their answer. This can lead to weird results. For example create a numerical question 2 + 2 = 4. Attempt it. Enter 4. Click Submit. Enter 5. Click Save. You will see a page that seems to say that your answer is 5 and it is correct!

In Interactive mode, the question is either in a state for the student to enter their answer, with a Submit button; or it is showing feedback for the student's previous attempt, with a Try again button to get back to the first state.

The other difference is that students are only allowed a limited number of tries at each question (typically three). When they submit their third try, or when they submit a correct answer, that question is finished and they must go onto the next one.

(This is quite difficult to explain. Try [https://students.open.ac.uk/openmark/s205.ayrf/ this example] and you should see how it works.)

===Immediate feedback===

This would be like cross between Deferred feedback an Interactive. Each question has a submit button beside it, like in interactive mode, so the student can get the feedback immediately while they still remember their thought processes while answering the question. However, unlike the interactive model, there is no try again button. You only get one chance at each question.

This is a necessary prerequisite for implementing MDL-11047, which is fairly frequently asked for in the quiz forum.

===Certainty based marking with deferred feedback===

This takes any question that can use the deferred feedback model, and adds three radio buttons to the UI (higher, medium, lower) for the student to use to indicate how certain they are that their answer is correct. If they are more certain, the get more marks if they are right, but lose marks if they are wrong. This encourages students to reflect about their level of knowledge.

===Certainty based marking with immediate feedback===

This is like immediate feedback mode with the certainty based marking feature.

===Delegate to a remote system===

The Opaque question type from contrib, which is used to run both OpenMark and [http://stack.bham.ac.uk/ STACK] questions inside a Moodle quiz was very difficult to implement within the current code. Since the remote system controls the flow of the question, it makes sense to use a custom behaviour for this question type, and that will be possible in the new code.

===Information item===

Used for descriptions. There is no grade. Item gets marked as complete after the student has seen it once. Displays general feedback after the attempt is over.

===Missing===

This is like the Missing question type. This behaviour is used in the situation:
# Admin installs some behaviour.
# Student attempts quiz using that model.
# Admin uninstalls that model.
# Teacher tries to review that student's attempt.
The missing question behaviour does the best job it can to allow the review of the attempt with the missing model, while displaying an on-screen warning.

So, what exactly does the behaviour control? Given the current state of the question, it limits the range of actions that are possible. For example, in adaptive mode, there is a submit button next to each question. In non-adaptive mode, the only option is to enter an answer and have it saved, until the submit all and finish button is pressed. That is, there will be a class in the PHP code for each model, and it will have methods that replace the old question_extract_responses, question_process_responses, question_process_comment and save_question_state functions in the current code.

(+++Richness, ++Correctness, +Robustness)

===Brief digression: who controls the model, the quiz or the question?===

There is one design decisions that it took a long time for me to resolve, and I want to mention it here.

The question is: Is the behaviour a property of the question, or the quiz?

At the moment, there is a setting in the quiz that lets you change all the questions in the quiz from adaptive mode to non-adaptive mode at the flick of a switch. Or, at least, it allows you to re-use the same questions in both adaptive and non-adaptive mode. This suggest that the behaviour is a property of the quiz.

On the other hand, suppose that you wanted to introduce the feature that, in adaptive mode, the student gets different amounts of feedback after each try at getting the question right. For example, the first time they get it wrong the only get a brief hint. If they are wrong the second time they get a more detailed comment, and so on. In order to do this, you need more data (the various hints) in order to define an adaptive question that is irrelevant to a non-adaptive question. Also, certain question types (e.g. Opaque, from contrib) have to, of necessity, ignore the adaptive, non-adaptive setting. And I suggested above that, manually graded question types like Essay should really be considered to have a separate behaviour. This suggests that the behaviour is a properly of the individual question. (Although usability considerations suggest that a single quiz should probably be constructed from questions with similar behaviour.)

I eventually concluded that both answers are right. That is, it is a good idea for the quiz to have a setting like adaptive/non-adaptive that sets out the teacher's intention of how each question in this quiz should behave. However, the exact choice of behaviour to use is up to the different question types. When a quiz attempts is started, each question type is asked something like "A quiz attempt is starting using 'adaptive mode'. Exactly which behaviour should be used for questions of this type in this attempt?" This gives questions that can only work in a certain way (for example essay questions) a chance to override the quiz setting.

==Clarifying question states==

Although there is a database table called question_states, the column there that stores the type of state is called event, and the values stored there are active verbs like open, save, grade. The question_process_responses function is written in terms of these actions too. One nasty part is that during the processing, the event type can be changed several times, before it is finally stored in the database as a state.

I would like to clearly separate the concept of the current state that a question is in, and the various actions that lead to a change of state. The actions will be handled by the behaviours, and the state will be stored in the database as a state.

The list of available states will also be changed slightly to match the following diagram. This came from thinking about what information it was important to display in the quiz navigation block.

[[Image:Question_state_diagram.png]]

(+Correctness, +Richness).

==What are the parts of a question?==

When we come to think of outputting a question on-screen, we can now see that there are several things that affect what it will look like:
# The question type (multichoice, shortanswer, essay, ...)
# The behaviour (deferred feedback, interactive, CBM, ...)
# What state the question is in (has the student answered yet, has it been graded, ...)
# The options from the particular activity (whether any marks are available for this question, are students allowed to see their grades, how many decimal places to use to display grades, does this user have permission to make a manual comment ...)

Also, we want different question type and behaviours to have the freedom to display whatever they like to the students; but we also want all the questions in a quiz to look and behave consistently, so that the experience is not confusing.

In the sketch below, I try to summarise the bits that may be present in a typical question. If all questions can have these bits in this order, then that is probably enough consistency. The flexibility comes from allowing the question type or behaviour to put whatever it likes inside those bits.

We can divide what you see when looking at a question is into three main parts:
# Information (meta-data): Which question number this is, a summary of what state it is currently in, what grade you have got for it (or how many marks are available, if any), whether you have flagged it. This has a grey background in the sketch below.
# The question and the response to it. This has a blue background in the sketch.
# The outcome from submitting that response. This has a yellow background.

[[Image:Parts of a question2.png]]

The full list of options that control which of those bits are visible at any time are:

; correctness : (hidden / visible) whether the student gets told whether their answer was (in/partially)correct in the status summary under the question number, or instead are told something vague like 'Finished'.
; marks : (hidden / max only / actual mark and max / actual mark and max with explanation ) whether the student can see the number of marks available, and how many marks they got, and how much detail of the marking to display.
; marks d.p. : (0 .. 7) how many decimal places marks are displayed to.
; flags: (hidden / visible / visible and editable) this is the feature that lets students bookmark or flag a question in an attempt for later reference.
; read-only: Whether the question just shows the response was already entered, or whether it gives controls to the user enter/change their response.
; specific feedback: (hidden / visible) feedback that relates to the particular response the student entered.
; general feedback : (hidden / visible) whether the general feedback (same for all students) is visible.
; correct response : (hidden / visible) whether the automatically generated message or other indication of the correct answer is visible.
; manual comment: (hidden / visible / visible and editable) whether the comment manually added by the teacher is visible and editable by the current user.
; response history : (hidden / visible) whether the list of steps the student went through to answer the question is displayed.

These options are initially set by whatever it is that is using the question (for example the quiz will initialise them from the quiz settings). Then these options are modified by the behaviour. For example it should ensure that no feedback is displayed until the student has actually submitted an answer, or that after they have submitted their final answer, the question only appears in read-only mode.

==Reorganise the code==

There will, of course, be a new class for each behaviour, that all inherit from the same base class.

At the moment question type classes have multiple responsibilities.
# They is information about the question types, and loading and saving, importing and exporting, backing up and restoring questions of that type.
# Then there is the processing of student responses for a particular instances of that question type.
# And then there is displaying the question in its various states.
(Fortunately, 4. Displaying an editing form, is already in a separate class.)

Moodle 2.0 introduces the [[Theme_engines_for_Moodle%3F|renderer concept]]. Introducing qtype renderers will move the output code (3) into separate classes. This change to the question engine is the appropriate time to introduce qtype renderes.

I will also introduce a new set of classes to store the state of a question within a quiz attempt. That is basically the combination of the $question and $state objects that are passed around at the moment, but with a specific subclass for each question type. This moves all the processing logic (2) into a separate class. That leaves the question type class itself just responsible for (1).

Of course the behaviour classes and the question_state classes need to work together, and this is clearly a situation for the [http://en.wikipedia.org/wiki/Strategy_pattern strategy pattern]. However, I have not yet decided whether the question type is the context, and the iteration model is the strategy, or vice versa. I will have to see which comes out better when I do the implementation.

Finally, there will be a new class in questionlib.php for managing the set of questions in an attempt. Already, in the Moodle 2.0 quiz developments, I have changed the quiz code to create a quiz_attempt class. This keeps track of all the questions in the quiz attempt. However, this really needs to be split into two bits. The job of tracking a set of questions and what state they are in is exactly the job of the question engine. Therefore we should have a question_set_attempt class that does that job. That class will take over the job of a number of functions in questionlib.php, for example question_load_states. Then the quiz_attempt class can just focus on the quiz-specific things, and use the question_set_attempt class. This new class should make it easier to use questions in other modules.

It should be possible to organise the code so that only the question_set_attempt class had to load or save data to or from the database. It will then pass that data on to wherever it is needed. That should be good for efficiency.

(+Robustness, +Efficiency)

==Simplified API for question types==

In the summary of how the quiz currently works, I said, "The student enters an answer to each question which is saved. Then when they submit the quiz attempt, all the questions are graded." In fact, that was a lie. Whenever a response is saved, the grade_responses method of the question type is called, even in the state is only being saved. This is confusing, to say the least, and very bad for performance in the case of a question type like JUnit (in contrib) which takes code submitted by the student, and compiles it in order to grade it.

So some of the API will only change to the extent that certain functions will in future only be called when one would expect them to be. I think this can be done in a backwards-compatible way.

Another change will be that, at the moment, question types have to implement tricky load/save_question_state methods that, basically, have to unserialise/serialise some of the state data in a custom way, so it can be stored in the answer column. This is silly design, and leads to extra, unnecessary database queries. The changes to the database structure will to eliminate the need for these methods.

Hopefully the above changes to how the code is organised will make it mauch easier to write new question types.

(+Richness, +Correctness, +Efficiency)

==Introduce more automated testing==

Since the question_set_attempt class keeps track of all the data that is needed when processing questions, it should be very easy to write automatic tests (unit tests) for all the other parts of the question engine. That should greatly help in eliminating bugs.

I am intending to take a [http://en.wikipedia.org/wiki/Test-driven_development test-driven] approach to implementing this proposal.

(+++Correctness, ++Robustness)

==See also==

In the next section, [[Question Engine 2:Design|Design]], gives the detailed design of the above solution.

* Back to [[Question_Engine_2|Question Engine 2]]

Question Engine 2:Overview

2012-07-12T17:15:51Z

Scyrma: missing [ to set link up

{{Template:Question_engine_2}}
This page outlines how I think the question engine should work in Moodle 2.0 or 2.1.

Previous section: [[Question Engine 2:Rationale|Rationale]]

==Normalise the database structure==

At the moment, the some parts of the question_sessions and question_states tables and their relations are not normalised. This is a technical term for describing database designs. Basically, if the tables are normalised, then each 'fact' is stored in exactly one place. A normalised database is much less likely to get into an inconsistent state. Changing to a normalised structure should therefore increase robustness.

In addition, I wish to change the tables, so the the responses received from the student are stored in a much more 'raw' form. That will mean that the responses can be saved much earlier in the sequence of processing, which will again increase robustness. It will also allow the sequence of responses from the student to be replayed more easily, making it easier to continue after a server crash, to regrade, and to write automatic test scripts.

The detailed design describes the new database structure.

(+++Robustness, +Correctness)

==New concept: Question behaviours==

At the moment, the various sequences of states that a question can move through in response to student input is hard-coded. It is controlled by a combination of the compare_responses and grade_responses methods of the question types, and tangled logic in the question_process_responses function. This makes it difficult to add new ways on interacting with questions, for example certainty based marking. Also, the current code is tricky to keep working.

I would like to separate out the control of how a question moves through different states, into what I will call question behaviours. Currently, Moodle has three or four of these:

===Deferred feedback===

This is how the quiz currently work when adaptive mode is off. The student enters a response to each question, then does Submit all and finish at the end of their attempt. Only then do they get feedback and/or grades on each question, depending on the review settings.

===Adaptive===

In this mode there is a separate submit button beside each question, so the student can submit each question individually during the attempt, and if they are wrong, try to improve their answer, although for a reduced grade.

Currently, the way adaptive mode works from the student point of view is not very good. I propose to replace it with a new Interactive mode. See below.

===Manually graded===

Essay questions need to be manually graded by the teacher, so you cannot really use them in adaptive mode (although currently there is nothing in the Quiz to stop you, which leads to confusing results). And it is not quite the same as Deferred feedback mode, because the student must wait for the teacher to grade their response after clicking submit all and finish.

===Each attempt builds on last===

This is very similary to the deferred feedback model, except that in subsequent attempts, each question does not start blank, but instead with the student's last response from the previous attempt.

Currently in Moodle there is nothing to stop you trying to combine Each attempt builds on last with Adaptive mode, although that combination does not make any sense to me. I think it simplifies things to treat this as a separate mode, although, of course, it will share code with Deferred feedback mode.

There are also some new modes that I propose to add, either immediately, or shortly after the main part of the work:

===Interactive===

This will replace adaptive mode. This is the model that has been used successfully for several years in the OU's [http://www.open.ac.uk/openmarkexamples/ OpenMark] system. The OU has also modified Moodle to work like this, but because of the way the quiz core currently works, I was not happy just merging the OU changes into Moodle core. In a sense, this whole document grew out of my thoughts about how to implement the OU changes in Moodle core properly.

In the existing adaptive mode, after the student has clicked submit, the question both shows the feedback for the last answer the student submitted, while also letting the student change their answer. This can lead to weird results. For example create a numerical question 2 + 2 = 4. Attempt it. Enter 4. Click Submit. Enter 5. Click Save. You will see a page that seems to say that your answer is 5 and it is correct!

In Interactive mode, the question is either in a state for the student to enter their answer, with a Submit button; or it is showing feedback for the student's previous attempt, with a Try again button to get back to the first state.

The other difference is that students are only allowed a limited number of tries at each question (typically three). When they submit their third try, or when they submit a correct answer, that question is finished and they must go onto the next one.

(This is quite difficult to explain. Try [https://students.open.ac.uk/openmark/s205.ayrf/ this example] and you should see how it works.)

===Immediate feedback===

This would be like cross between Deferred feedback an Interactive. Each question has a submit button beside it, like in interactive mode, so the student can get the feedback immediately while they still remember their thought processes while answering the question. However, unlike the interactive model, there is no try again button. You only get one chance at each question.

This is a necessary prerequisite for implementing MDL-11047, which is fairly frequently asked for in the quiz forum.

===Certainty based marking with deferred feedback===

This takes any question that can use the deferred feedback model, and adds three radio buttons to the UI (higher, medium, lower) for the student to use to indicate how certain they are that their answer is correct. If they are more certain, the get more marks if they are right, but lose marks if they are wrong. This encourages students to reflect about their level of knowledge.

===Certainty based marking with immediate feedback===

This is like immediate feedback mode with the certainty based marking feature.

===Delegate to a remote system===

The Opaque question type from contrib, which is used to run both OpenMark and [http://stack.bham.ac.uk/ STACK] questions inside a Moodle quiz was very difficult to implement within the current code. Since the remote system controls the flow of the question, it makes sense to use a custom behaviour for this question type, and that will be possible in the new code.

===Information item===

Used for descriptions. There is no grade. Item gets marked as complete after the student has seen it once. Displays general feedback after the attempt is over.

===Missing===

This is like the Missing question type. This behaviour is used in the situation:
# Admin installs some behaviour.
# Student attempts quiz using that model.
# Admin uninstalls that model.
# Teacher tries to review that student's attempt.
The missing question behaviour does the best job it can to allow the review of the attempt with the missing model, while displaying an on-screen warning.

So, what exactly does the behaviour control? Given the current state of the question, it limits the range of actions that are possible. For example, in adaptive mode, there is a submit button next to each question. In non-adaptive mode, the only option is to enter an answer and have it saved, until the submit all and finish button is pressed. That is, there will be a class in the PHP code for each model, and it will have methods that replace the old question_extract_responses, question_process_responses, question_process_comment and save_question_state functions in the current code.

(+++Richness, ++Correctness, +Robustness)

===Brief digression: who controls the model, the quiz or the question?===

There is one design decisions that it took a long time for me to resolve, and I want to mention it here.

The question is: Is the behaviour a property of the question, or the quiz?

At the moment, there is a setting in the quiz that lets you change all the questions in the quiz from adaptive mode to non-adptive mode at the flick of a switch. Or, at least, it allows you to re-use the same questions in both adaptive and non-adaptive mode. This suggest that the behaviour is a property of the quiz.

On the other hand, suppose that you wanted to introduce the feature that, in adaptive mode, the student gets different amounts of feedback after each try at getting the question right. For example, the first time they get it wrong the only get a brief hint. If they are wrong the second time they get a more detailed comment, and so on. In order to do this, you need more data (the various hints) in order to define an adaptive question that is irrelevant to a non-adaptive question. Also, certain question types (e.g. Opaque, from contrib) have to, of necessity, ignore the adaptive, non-adaptive setting. And I suggested above that, manually graded question types like Essay should really be considered to have a separate behaviour. This suggests that the behaviour is a properly of the individual question. (Although usability considerations suggest that a single quiz should probably be constructed from questions with similar behaviour.)

I eventually concluded that both answers are right. That is, it is a good idea for the quiz to have a setting like adaptive/non-adaptive that sets out the teacher's intention of how each question in this quiz should behave. However, the exact choice of behaviour to use is up to the different question types. When a quiz attempts is started, each question type is asked something like "A quiz attempt is starting using 'adaptive mode'. Exactly which behaviour should be used for questions of this type in this attempt?" This gives questions that can only work in a certain way (for example essay questions) a chance to override the quiz setting.

==Clarifying question states==

Although there is a database table called question_states, the column there that stores the type of state is called event, and the values stored there are active verbs like open, save, grade. The question_process_responses function is written in terms of these actions too. One nasty part is that during the processing, the event type can be changed several times, before it is finally stored in the database as a state.

I would like to clearly separate the concept of the current state that a question is in, and the various actions that lead to a change of state. The actions will be handled by the behaviours, and the state will be stored in the database as a state.

The list of available states will also be changed slightly to match the following diagram. This came from thinking about what information it was important to display in the quiz navigation block.

[[Image:Question_state_diagram.png]]

(+Correctness, +Richness).

==What are the parts of a question?==

When we come to think of outputting a question on-screen, we can now see that there are several things that affect what it will look like:
# The question type (multichoice, shortanswer, essay, ...)
# The behaviour (deferred feedback, interactive, CBM, ...)
# What state the question is in (has the student answered yet, has it been graded, ...)
# The options from the particular activity (whether any marks are available for this question, are students allowed to see their grades, how many decimal places to use to display grades, does this user have permission to make a manual comment ...)

Also, we want different question type and behaviours to have the freedom to display whatever they like to the students; but we also want all the questions in a quiz to look and behave consistently, so that the experience is not confusing.

In the sketch below, I try to summarise the bits that may be present in a typical question. If all questions can have these bits in this order, then that is probably enough consistency. The flexibility comes from allowing the question type or behaviour to put whatever it likes inside those bits.

We can divide what you see when looking at a question is into three main parts:
# Information (meta-data): Which question number this is, a summary of what state it is currently in, what grade you have got for it (or how many marks are available, if any), whether you have flagged it. This has a grey background in the sketch below.
# The question and the response to it. This has a blue background in the sketch.
# The outcome from submitting that response. This has a yellow background.

[[Image:Parts of a question2.png]]

The full list of options that control which of those bits are visible at any time are:

; correctness : (hidden / visible) whether the student gets told whether their answer was (in/partially)correct in the status summary under the question number, or instead are told something vague like 'Finished'.
; marks : (hidden / max only / actual mark and max / actual mark and max with explanation ) whether the student can see the number of marks available, and how many marks they got, and how much detail of the marking to display.
; marks d.p. : (0 .. 7) how many decimal places marks are displayed to.
; flags: (hidden / visible / visible and editable) this is the feature that lets students bookmark or flag a question in an attempt for later reference.
; read-only: Whether the question just shows the response was already entered, or whether it gives controls to the user enter/change their response.
; specific feedback: (hidden / visible) feedback that relates to the particular response the student entered.
; general feedback : (hidden / visible) whether the general feedback (same for all students) is visible.
; correct response : (hidden / visible) whether the automatically generated message or other indication of the correct answer is visible.
; manual comment: (hidden / visible / visible and editable) whether the comment manually added by the teacher is visible and editable by the current user.
; response history : (hidden / visible) whether the list of steps the student went through to answer the question is displayed.

These options are initially set by whatever it is that is using the question (for example the quiz will initialise them from the quiz settings). Then these options are modified by the behaviour. For example it should ensure that no feedback is displayed until the student has actually submitted an answer, or that after they have submitted their final answer, the question only appears in read-only mode.

==Reorganise the code==

There will, of course, be a new class for each behaviour, that all inherit from the same base class.

At the moment question type classes have multiple responsibilities.
# They is information about the question types, and loading and saving, importing and exporting, backing up and restoring questions of that type.
# Then there is the processing of student responses for a particular instances of that question type.
# And then there is displaying the question in its various states.
(Fortunately, 4. Displaying an editing form, is already in a separate class.)

Moodle 2.0 introduces the [[Theme_engines_for_Moodle%3F|renderer concept]]. Introducing qtype renderers will move the output code (3) into separate classes. This change to the question engine is the appropriate time to introduce qtype renderes.

I will also introduce a new set of classes to store the state of a question within a quiz attempt. That is basically the combination of the $question and $state objects that are passed around at the moment, but with a specific subclass for each question type. This moves all the processing logic (2) into a separate class. That leaves the question type class itself just responsible for (1).

Of course the behaviour classes and the question_state classes need to work together, and this is clearly a situation for the [http://en.wikipedia.org/wiki/Strategy_pattern strategy pattern]. However, I have not yet decided whether the question type is the context, and the iteration model is the strategy, or vice versa. I will have to see which comes out better when I do the implementation.

Finally, there will be a new class in questionlib.php for managing the set of questions in an attempt. Already, in the Moodle 2.0 quiz developments, I have changed the quiz code to create a quiz_attempt class. This keeps track of all the questions in the quiz attempt. However, this really needs to be split into two bits. The job of tracking a set of questions and what state they are in is exactly the job of the question engine. Therefore we should have a question_set_attempt class that does that job. That class will take over the job of a number of functions in questionlib.php, for example question_load_states. Then the quiz_attempt class can just focus on the quiz-specific things, and use the question_set_attempt class. This new class should make it easier to use questions in other modules.

It should be possible to organise the code so that only the question_set_attempt class had to load or save data to or from the database. It will then pass that data on to wherever it is needed. That should be good for efficiency.

(+Robustness, +Efficiency)

==Simplified API for question types==

In the summary of how the quiz currently works, I said, "The student enters an answer to each question which is saved. Then when they submit the quiz attempt, all the questions are graded." In fact, that was a lie. Whenever a response is saved, the grade_responses method of the question type is called, even in the state is only being saved. This is confusing, to say the least, and very bad for performance in the case of a question type like JUnit (in contrib) which takes code submitted by the student, and compiles it in order to grade it.

So some of the API will only change to the extent that certain functions will in future only be called when one would expect them to be. I think this can be done in a backwards-compatible way.

Another change will be that, at the moment, question types have to implement tricky load/save_question_state methods that, basically, have to unserialise/serialise some of the state data in a custom way, so it can be stored in the answer column. This is silly design, and leads to extra, unnecessary database queries. The changes to the database structure will to eliminate the need for these methods.

Hopefully the above changes to how the code is organised will make it mauch easier to write new question types.

(+Richness, +Correctness, +Efficiency)

==Introduce more automated testing==

Since the question_set_attempt class keeps track of all the data that is needed when processing questions, it should be very easy to write automatic tests (unit tests) for all the other parts of the question engine. That should greatly help in eliminating bugs.

I am intending to take a [http://en.wikipedia.org/wiki/Test-driven_development test-driven] approach to implementing this proposal.

(+++Correctness, ++Robustness)

==See also==

In the next section, [[Question Engine 2:Design|Design]], gives the detailed design of the above solution.

* Back to [[Question_Engine_2|Question Engine 2]]

How to create a patch

2008-07-01T08:00:40Z

Scyrma: /* Creating a patch using CVS (command line) */

If you have made some changes to the code that you would like to share with the community, particularly if you want to send them to one of the core developers for possible inclusion in Moodle Core, it is very helpful if you can provide them as a patch file. Sometimes also called a diff file.

This page explains how you can make a patch file. Patch is a standard format, and there are many options for how to create one. Pick the one that is easiest for you.

''Note, I have not been able to test most of these instructions. They are about right, but I am hoping that as people use them, they will fill in any gaps, correct any details, and so on.[[User:Tim Hunt|Tim Hunt]] 08:40, 25 June 2007 (CDT)''

==Introduction: what does a patch file look like==

This is a simple example:

<pre><nowiki>
Index: lang/en_utf8/quiz.php
===================================================================
RCS file: /cvsroot/moodle/moodle/lang/en_utf8/quiz.php,v
retrieving revision 1.57.2.10
diff -u -r1.57.2.10 quiz.php
--- lang/en_utf8/quiz.php 29 May 2007 17:47:25 -0000 1.57.2.10
+++ lang/en_utf8/quiz.php 25 Jun 2007 12:58:34 -0000
@@ -252,7 +255,6 @@
$string['indivresp'] = 'Responses of Individuals to Each Item';
$string['info'] = 'Info';
$string['introduction'] = 'Introduction';
-$string['invalidcategory'] = 'Category ID is invalid';
$string['invalidnumericanswer'] = 'One of the answers you entered was not a valid number.';
$string['invalidnumerictolerance'] = 'One of the tolerances you entered was not a valid number.';
$string['invalidsource'] = 'The source is not accepted as valid.';
@@ -375,8 +377,10 @@
$string['questiontypesetupoptions'] = 'Setup options for question types:';
$string['quiz:attempt'] = 'Attempt quizzes';
$string['quiz:deleteattempts'] = 'Delete quiz attempts';
+$string['quiz:emailconfirmsubmission'] = 'Receive own quiz submission notification';
+$string['quiz:emailnotifysubmission'] = 'Receive student quiz submission notifications';
$string['quiz:grade'] = 'Grade quizzes manually';
-$string['quiz:ignoretimelimits'] = 'Ignores time limit on quizzes';
+$string['quiz:ignoretimelimits'] = 'Ignores time limit on quizs';
$string['quiz:manage'] = 'Manage quizzes';
$string['quiz:preview'] = 'Preview quizzes';
$string['quiz:view'] = 'View quiz information';
</nowiki></pre>

At the top it says which file is being affected. Changes to several files can be included in one patch. Lines added are shown with a '+', lines removed are shown with a '-', lines changed are shown as the old line being removed and the new one added.

Patch files are good because they only show the changed parts of the file. This has two advantages: it easy to understand the change; and if other parts of the same files change between the patch being made an being used, there is no problem, the patch will still apply.

==Creating a patch using diff==

diff is the a linux command line program, and is where patch files originated. It requires that you have two copies of the code, one with your changes, and one without. Suppose these two copies are in folders called 'standard_moodle' and 'my_moodle' which are subdirectories of the current folder. Then to create the patch, type:

diff -ur standard_moodle my_moodle > patch.txt

==Creating a patch using CVS (command line)==

It is easier if you are using CVS to manage your development, because you don't need to keep the copy of 'standard_moodle'. CVS takes care of that for you. In you workspace (sandbox) type:

cvs diff -uN > patch.txt

If you have unversioned files to include in your patch, you will notice that the above command simply adds the file's name to the top of your patch, prefixed with a question mark. This is because your new file is not tagged for adding to the repository. Just do

cvs add newfile

Then

cvs diff -uNa > patch.txt

This should add the correct code to the patch, so that someone applying the patch to their working copy will have a new file created at the right place (hopefully!).

If your patch, for some reason, contains a lot of white space changes in many files, you might want to add -Bbw to the diff call. Make sure these changes are really not significant (like adding or removing a space at the end of a line - editors like Eclipse sometimes do this automatically). This can make a patch a lot smaller, and thus easier to review. The complete call would then be

cvs diff -uNawbB > patch.txt

==Creating a patch using Tortoise CVS==

[http://www.tortoisecvs.org/ Tortoise CVS] is a Windows GUI front end for CVS. To create a patch, right-click on a folder in CVS, and choose '''CVS -> Make patch ...''' from the context menu.

==Creating a patch using Eclipse==

See [[Setting_up_Eclipse#Creating_a_patch]]. Eclipse makes creating patches really easy, once you have got it set up correctly.

==Creating a patch using WinMerge==

[http://winmerge.org/ WinMerge] is a nice windows GUI for comparing folders. In this sense it is like the original command-line 'diff' program. You need a copy of 'standard_moodle' and 'my_moodle'. Use '''File -> Open...''' to open the two versions for comparison. This will give you a nice view of what you have changed. Then do '''Tools -> Generate patch ...'''. In the dialogue box, make sure you select Style: Unified in the Format box.

Talk:Setting up Eclipse

2008-06-26T01:28:32Z

Scyrma: New section: Eclipse and whitespace

Really nice work, Tim, thanks! I've been through and I'm trying it out. [[User:Martin Dougiamas|Martin Dougiamas]] 09:05, 5 September 2006 (CDT)

----

The stuff about changing editors under General -> Editors -> File Associations doesn't work any more if an Eclipse plugin has 'locked' a file type or content type. Not sure how to fix this
--[[User:Andy Baker|Andy Baker]] 06:40, 28 November 2006 (CST)

Hopefully it will be the PHP plugin, and it will have locked *.php to the setting you want anyway. If not, can you tell us exactly what you are seeing.[[User:Tim Hunt|Tim Hunt]] 04:24, 29 November 2006 (CST)

== Problems with Ubuntu 6.10... ==

I'd really like to switch completely to Linux and Eclipse on my Moodle developments. However, I can't get the PHPEclipse plug-in to work with Eclipse 3.2 that came with Ubuntu 6.10. After the Eclipse restart required by the "add . to the include path" tweak, the "PHPEclipse stuff" is gone from the menus (forgot what it said), and when I try to open a PHP file in Eclipse I get:
"Failed to execute runnable (java.lang.NoClassDefFoundError: net.sourceforge.phpeclipse.phpeditor.PHPUnitEditor)" and "Unhandled event loop exception"... Going to Google around a bit, but there seems to be a lot of other issues with the JVM also: Eclipse crashed when I tried to search the help, for example. --[[User:Samuli Karevaara|Samuli Karevaara]] 04:07, 20 December 2006 (CST)
:Just reporting that now the error message has changed to "Problems occurred when invoking code from plug-in: "org.eclipse.jface"." or I was reading the wrong part of the error log before... --[[User:Samuli Karevaara|Samuli Karevaara]] 04:11, 20 December 2006 (CST)
:One headache later I was able to get Eclipse to open the PHP files. Apparently it was about the Java Runtime Environment version after all. I had "sun-java5-bin : Sun Java(TM) Runtime Environment (JRE) 5.0" package installed but it didn't help. After completely removing everything "Java 1.4" ("j2re1.4" and friends) and upgrading "libgjc" packages I got it to work. I reeeeally not a friend of Java versioning and library packaging! --[[User:Samuli Karevaara|Samuli Karevaara]] 06:05, 20 December 2006 (CST)

== Ubuntu Eclipse Improvements ==

Just found this:
http://wiki.liferay.com/index.php/Liferay_Development_Environment:_Ubuntu_Linux#Eclipse_IDE

It may help a bit.

There is a problem wiht the different java VM. If you set that the vm is the one of sun it must be like this everywere
I did that:

$ sudo aptitude install eclipse-sdk

Remove any reference to gcj in
/etc/eclipse/java_home.

edit the file /usr/bin/eclipse and comment

-Dgnu.gcj.precompiled.db.path=/var/lib/gcj-4.1/classmap.db et
-Dgnu.gcj.runtime.VMClassLoader.library_control=never.

For me now eclipse runs with no problem

== Prefs file missing? ==

Working through this bit:

Open the file net.sourceforge.phpeclipse.ui.prefs that is in the directory (your
workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings in a text editor.

the file is not there. net.sourceforge.phpeclipse.prefs is present, but does not have the line described.

Also,

Under Team -> CVS -> SSH2 Connection Method,

this path does not exist (working on Xandros with linux eclipse)

[[User:Matt Gibson|Matt Gibson]] 16:48, 17 January 2008 (CST)

== net.sourcegorge.phpeclipse.ui.prefs ==

Note that in the documentation is:
- Look for a line in the file that starts _php_include_paths= '''If it is not there, add it at the end'''.

In my case, it was nothing there, so I add the line
_php_include_paths=.
and work.

== Under Team -> CVS -> SSH2 Connection Method ==

I found this to be '''General -> Network Connections -> SSH2 -> Key Management''' (the documentation is updated).

After generating a DSA key, and following the rest of the instructions, I finally finish setting up Eclipse.

== Eclipse and whitespace ==

(Moving this out of main page, so as not to confuse people with discussion...) I suggested ... Under '''General -> Compare/Patch''', turn on '''Ignore white space''' if you plan to exchange patches with other developers or send patches on the tracker. This will make patches smaller and easier to compare. [[User:Mathieu Petit-Clair|Mathieu Petit-Clair]] 20:28, 25 June 2008 (CDT)

Tim replied: but that is a very bad idea. Whitespace is important, you should not change it unnecessarily, and so whitespace changes should be included in patches.''

You've got good point there, whitespace is significant. But Eclipse seems to remove trailing space (eg. at the end of lines) by itself, and this makes patches I receive from Eclipse users impossible to apply after a few days of hacking in cvs head. :( Is there a way to tell Eclipse not to remove whitespace by itself? I really like to work with patches, but when they're twice as big as they should be and don't apply, it makes it a nightmare... [[User:Mathieu Petit-Clair|Mathieu Petit-Clair]] 20:28, 25 June 2008 (CDT)

Setting up Eclipse

2008-06-26T01:23:33Z

Scyrma: /* General settings */

[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that some Moodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

This article started off as a brain-dump by [[User:Tim Hunt|Tim Hunt]]. Since then, several other people have worked through it and made corrections, so the information here should be pretty accurate.

==Prerequisites==

Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux, in each case with 1GB of memory, and that is plenty.

==Installing Eclipse==

Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says '''Eclipse Classic'''. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, unzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

==The first time you run Eclipse==

The first time you launch Eclipse it does a bit of setup stuff, for instance, it create a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Use this as the default and do not ask again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probably don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

==Installing the necessary plugins==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step.

From the '''Help''' menu choose '''Software Updates -> Find and Install'''.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.

In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://phpeclipse.sourceforge.net/update/releases/; then click '''OK'''.

''Note, there is now also another PHP editor for Eclipse. The update URL ishttp://download.eclipse.org/tools/pdt/updates/. I am just trying it--[[User:Tim Hunt|Tim Hunt]] 11:39, 7 November 2007 (CST)''

Back in the wizard, turn on just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Europa Discovery Site''' (or possibly '''Callisto Discovery Site'''.
Then click '''Finish'''.

It goes off sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want. The ones you want (you may have to search the tree structure) are, '''PHPeclipse''' (from your newly created PHPEclipse Update Site) and all the '''Web Standard Tools (WST)''' (usually under Callisto Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the '''Select Required''' button which should resolve dependencies and remove the warning message you are probably worrying about. Then you can click the '''Next >''' button.

Read and agree to all the license agreements. Then click '''Next >'''.

Click '''Finish''', and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation build digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.

Finally, a window will pop up asking you to restart Eclipse. Do so.

==Setting the preferences for Moodle development==

Now go to the '''Window''' menu, and choose '''Preferences ...''' ('''Eclipse''' menu on Mac OS X).

The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

===General settings===

If you have strong feelings about fonts (I would hate to edit code an anything except Andale Mono), choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.

Under '''General -> Editors -> File Associations''', if it is not already there, add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box. With '''*.html''' selected in the top box, select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '''Internet -> Proxy Settings'''. (Yes, I know you have entered them somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

These are all hidden under the '''PHPeclipse Web Development''' bit of the tree.

Under '''PHPeclipse Web Development -> Browser Preview Defaults''', turn off both checkboxes.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, check '''Show line numbers''' to display line numbers in the left margin (optional). NOTE.- When you are editing a PHP file, you could left-click in the left margin and tick the '''Show Line Numbers''' line in the contextual menu. However, this toggle only applies to plain text files, ''not'' to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.

Under '''PHPeclipse Web Development -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments''' and '''Remove trailing spaces on editor save'''. It would be nice to turn on more of these options, but most of the rest don't work very well.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''.

Under '''PHPeclipse Web Development -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>print_object(${word_selection}${cursor}); // DONOTCOMMIT</pre>
You can do other useful things with templates too. Here are two more I use:
<pre>debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT</pre>
<pre>$$string['${word_selection}${cursor}'] = '.';</pre>
That is, a simple debug message with a stack trace, and a new language string.

There is a really stupid bug. Under '''PHPeclipse Web Development -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.
# Close Eclipse.
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.
# Change this line to say '''_php_include_paths=.'''
# Run Eclipse again.

===SSH2===
Information about generating SSH2 keys for the purpose of connecting to cvs.moodle.org can be found here at https://docs.moodle.org/en/Development:SSH_key , but please finish reading this section before reading that material.

The Eclipse installation has its own SSH client plugin so you do not have to use a separate ssh client in connection with your use of Eclipse (this is one reason you will be using extssh below, instead of just ext, however, if you wish you may alter the configuration to use an external client but please post news of your success and configuration). See, http://www.jcraft.com/eclipse-cvsssh2/ , for additional information on this plugin.

'' Since Eclipse 3.0M6 the CVSSSH plugin is incorporated into Eclipse, [http://www.jroller.com/prane/entry/eclipse_3_0_cvs_support as "extssh" instead of "extssh2"] - --[[User:Olli Savolainen|Olli Savolainen]] 07:54, 23 June 2008 (CDT)''

Please note that Eclipse is fully equipped to generate ssh2 rsa and dsa keys as well as import keys. You may encounter issues with passphrases that are too long (a bug reportedly fixed but which may still in fact be present) and some issues with using keypairs generated by other applications have been seen, so it may be best to generate a key pair with Eclipse. Additional details on how to do this will be added.

Sourceforge, at http://sourceforge.net/docs/F02/ , provides instructions on how to create a SSH key for it's CVS (remember, Moodle does not use sourceforge for its CVS now and you will need to generate keys for cvs.moodle.org, not sourceforge). This is mentioned by way of general explanation, not for the purposes of providing instructions on how to generate your keys for Eclipse. To make use of the public key, login to Moodle.org and add it via the Update My Developer Information tab under CVS Developers (http://moodle.org/cvs). Remember, public keys provided to Moodle must be in the Openssh format.

===CVS Settings===

These are almost all hidden under the '''Team''' bit of the tree.

Under '''General -> Network Connections -> SSH2 -> Key Management''', you can set up a public/private key pair. If you do this, you won't have to keep typing your password when doing CVS operations.

The rest of the ones in this section are personal preferences, but I recommend them because the default settings are very irritating.

Under '''Team''', set '''Perspectives''' to '''None'''.

Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.

Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.

===Web and XML settings===

Foreach XXX in CSS, HTML, Javascript, XML:

Under '''Web and XML -> XXX Files ->XXX Source''', choose '''Indent using spaces''' and '''indentation size''' 4.

==Checking out the Moodle code==

From the '''File''' menu, choose '''New -> Project ...'''.

In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.

Select '''Create a new repository location''', then click '''Next >'''.

Fill in
<div style="float: right; border: 1px solid orange; padding: 0 1em;">
For anonymous CVS access use
;Host
:XX.cvs.moodle.org
where XX.cvs.moodle.org is one of [[CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:cvs.moodle.org
;Repository path
:/cvsroot/moodle
;User
:(your Moodle CVS username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)
;Connection type
:extssh
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.

On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.

On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.

Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.

Click '''Finish'''.

Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.

Make up a project name. '''moodle''' would be sensible.

Click '''Finish''', and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.

If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:
* This time you can choose '''Use an existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch. If you don't see the branch you want, see [https://docs.moodle.org/en/Development:Setting_up_Eclipse#Resetting_the_branch_information this Troubleshooting tip].
* Use a different project name (e.g. moodle16, moodle17, etc.).

==Let your development web server know where your files are==

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

==Quick tour of some cool features, and remaining configuration changes==

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

===Navigator===

To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-hightlighted.

===Error highlighting===

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should fine that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

===Outline===

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.

Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.

===Code navigation===

In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the mouse pointer over the function name '''insert_record''', then click. Eclipse should load '''dmllib.php''', and scroll you to where this function is defined.

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.

===Open resource===

From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

===Multi-file search===

Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

===Synchronize view===

I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.

Under '''Scope''', choose '''Workspace''', then click '''Finish'''.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project.... That is, it is listing just the files you have edited, but not checked in yet.

'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!

If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.

That's all the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

===Creating a patch===

In the synchronise view, right click on an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right click on an item and choose '''Team -> Create Patch...'''.

This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.

On the second page, you can set some options, but normally you don't need to change the defaults which are '''Unified''' diff format, and Patch root set to '''Workspace'''. Well, sometimes it is helpful to change the second one to '''Project''' but it is not important.

There is a corresponding apply patch wizard that you can use to apply a patch to a project.

===Switching to another branch or version===

Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.
# Right click on the moodle project in the navigator view, and select '''Team -> Switch to Another Branch or Version ...'''.
# choose the second radio button: '''Select the tag from the following list'''.
# If the branch you want is not in the '''Matching tags''' box, see [[Setting_up_Eclipse#Resetting the branch information|Resetting the branch information]] below.
# Select the branch you want and click '''Finish'''.

==Troubleshooting==

Some tips on how to solve common problems that may crop up.

===Resetting the branch information===

Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:

#Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").
#Click on Configure tags ... (not Refresh tags).
#Select config-dist.php in the top left box (if this is a Moodle checkout).
#Click Add Checked tags.
#Click OK.
#Then you will have all tags.

(thanks to Tim Hunt)

This info saved my day to find all branches:
1. Window->Show View->Other. Select CVS->CVS Repositories.
2. Context Menu->New->Repository Location...
3. Fill in the location information identifying your repository and click Finish.
4. Expand the newly-created repository location.
5. Add the branch:
1. right click on it and expand configure branches and versions
2. Expand HEAD and select the project moodle.
3. Context Menu->Configure Branches and Versions...
4. In the "Browse files for tags" table, select one or more files
that contain tags you would like to see (for example scroll down
to find config.php).
5. On the right the existing tags will appear.
6. select the tags: for example MOODLE_15_STABLE
7. Click "Add Selected Tags".
8. Click "OK".
6. locate branches, MOODLE_19_STABLE, moodle MOODLE_19_STABLE.
7. Context Menu->Check Out As Project.
("stolen" from Joan Codina Filba
General developer forum -> Moodle floating "block"/toolbar released -> Re: Moodle floating "block--PATCH FOR GRADES & ASIGNMENT --PROBLEM)

===Error loading php files after Ubuntu 7.04 Install===

A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to:
http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.

After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.

==Related Links==

There is an excellent series of articles published by IBM on using Eclipse for Drupal developement here : [http://www-128.ibm.com/developerworks/ibm/osource/index.html Using open source software to design, develop, and deploy a collaborative Web site Tools and techniques for getting relatively complicated Web sites up and running quickly].

[[Category:Setting up Eclipse]]

Setting up Eclipse

2008-06-25T07:10:39Z

Scyrma: /* General settings */ ignore whitespace in patches

[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that some Moodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

This article started off as a brain-dump by [[User:Tim Hunt|Tim Hunt]]. Since then, several other people have worked through it and made corrections, so the information here should be pretty accurate.

==Prerequisites==

Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux, in each case with 1GB of memory, and that is plenty.

==Installing Eclipse==

Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says '''Eclipse Classic'''. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, unzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

==The first time you run Eclipse==

The first time you launch Eclipse it does a bit of setup stuff, for instance, it create a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Use this as the default and do not ask again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probably don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

==Installing the necessary plugins==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step.

From the '''Help''' menu choose '''Software Updates -> Find and Install'''.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.

In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://phpeclipse.sourceforge.net/update/releases/; then click '''OK'''.

''Note, there is now also another PHP editor for Eclipse. The update URL ishttp://download.eclipse.org/tools/pdt/updates/. I am just trying it--[[User:Tim Hunt|Tim Hunt]] 11:39, 7 November 2007 (CST)''

Back in the wizard, turn on just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Europa Discovery Site''' (or possibly '''Callisto Discovery Site'''.
Then click '''Finish'''.

It goes off sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want. The ones you want (you may have to search the tree structure) are, '''PHPeclipse''' (from your newly created PHPEclipse Update Site) and all the '''Web Standard Tools (WST)''' (usually under Callisto Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the '''Select Required''' button which should resolve dependencies and remove the warning message you are probably worrying about. Then you can click the '''Next >''' button.

Read and agree to all the license agreements. Then click '''Next >'''.

Click '''Finish''', and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation build digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.

Finally, a window will pop up asking you to restart Eclipse. Do so.

==Setting the preferences for Moodle development==

Now go to the '''Window''' menu, and choose '''Preferences ...''' ('''Eclipse''' menu on Mac OS X).

The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

===General settings===

If you have strong feelings about fonts (I would hate to edit code an anything except Andale Mono), choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under '''General -> Compare/Patch''', turn on '''Ignore white space''' if you plan to exchange patches with other developers or send patches on the tracker. This will make patches smaller and easier to compare.

Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.

Under '''General -> Editors -> File Associations''', if it is not already there, add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box. With '''*.html''' selected in the top box, select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '''Internet -> Proxy Settings'''. (Yes, I know you have entered them somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

These are all hidden under the '''PHPeclipse Web Development''' bit of the tree.

Under '''PHPeclipse Web Development -> Browser Preview Defaults''', turn off both checkboxes.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, check '''Show line numbers''' to display line numbers in the left margin (optional). NOTE.- When you are editing a PHP file, you could left-click in the left margin and tick the '''Show Line Numbers''' line in the contextual menu. However, this toggle only applies to plain text files, ''not'' to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.

Under '''PHPeclipse Web Development -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments''' and '''Remove trailing spaces on editor save'''. It would be nice to turn on more of these options, but most of the rest don't work very well.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''.

Under '''PHPeclipse Web Development -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>print_object(${word_selection}${cursor}); // DONOTCOMMIT</pre>
You can do other useful things with templates too. Here are two more I use:
<pre>debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT</pre>
<pre>$$string['${word_selection}${cursor}'] = '.';</pre>
That is, a simple debug message with a stack trace, and a new language string.

There is a really stupid bug. Under '''PHPeclipse Web Development -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.
# Close Eclipse.
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.
# Change this line to say '''_php_include_paths=.'''
# Run Eclipse again.

===SSH2===
Information about generating SSH2 keys for the purpose of connecting to cvs.moodle.org can be found here at https://docs.moodle.org/en/Development:SSH_key , but please finish reading this section before reading that material.

The Eclipse installation has its own SSH client plugin so you do not have to use a separate ssh client in connection with your use of Eclipse (this is one reason you will be using extssh below, instead of just ext, however, if you wish you may alter the configuration to use an external client but please post news of your success and configuration). See, http://www.jcraft.com/eclipse-cvsssh2/ , for additional information on this plugin.

'' Since Eclipse 3.0M6 the CVSSSH plugin is incorporated into Eclipse, [http://www.jroller.com/prane/entry/eclipse_3_0_cvs_support as "extssh" instead of "extssh2"] - --[[User:Olli Savolainen|Olli Savolainen]] 07:54, 23 June 2008 (CDT)''

Please note that Eclipse is fully equipped to generate ssh2 rsa and dsa keys as well as import keys. You may encounter issues with passphrases that are too long (a bug reportedly fixed but which may still in fact be present) and some issues with using keypairs generated by other applications have been seen, so it may be best to generate a key pair with Eclipse. Additional details on how to do this will be added.

Sourceforge, at http://sourceforge.net/docs/F02/ , provides instructions on how to create a SSH key for it's CVS (remember, Moodle does not use sourceforge for its CVS now and you will need to generate keys for cvs.moodle.org, not sourceforge). This is mentioned by way of general explanation, not for the purposes of providing instructions on how to generate your keys for Eclipse. To make use of the public key, login to Moodle.org and add it via the Update My Developer Information tab under CVS Developers (http://moodle.org/cvs). Remember, public keys provided to Moodle must be in the Openssh format.

===CVS Settings===

These are almost all hidden under the '''Team''' bit of the tree.

Under '''General -> Network Connections -> SSH2 -> Key Management''', you can set up a public/private key pair. If you do this, you won't have to keep typing your password when doing CVS operations.

The rest of the ones in this section are personal preferences, but I recommend them because the default settings are very irritating.

Under '''Team''', set '''Perspectives''' to '''None'''.

Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.

Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.

===Web and XML settings===

Foreach XXX in CSS, HTML, Javascript, XML:

Under '''Web and XML -> XXX Files ->XXX Source''', choose '''Indent using spaces''' and '''indentation size''' 4.

==Checking out the Moodle code==

From the '''File''' menu, choose '''New -> Project ...'''.

In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.

Select '''Create a new repository location''', then click '''Next >'''.

Fill in
<div style="float: right; border: 1px solid orange; padding: 0 1em;">
For anonymous CVS access use
;Host
:XX.cvs.moodle.org
where XX.cvs.moodle.org is one of [[CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:cvs.moodle.org
;Repository path
:/cvsroot/moodle
;User
:(your Moodle CVS username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)
;Connection type
:extssh
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.

On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.

On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.

Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.

Click '''Finish'''.

Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.

Make up a project name. '''moodle''' would be sensible.

Click '''Finish''', and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.

If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:
* This time you can choose '''Use an existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch. If you don't see the branch you want, see [https://docs.moodle.org/en/Development:Setting_up_Eclipse#Resetting_the_branch_information this Troubleshooting tip].
* Use a different project name (e.g. moodle16, moodle17, etc.).

==Let your development web server know where your files are==

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

==Quick tour of some cool features, and remaining configuration changes==

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

===Navigator===

To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-hightlighted.

===Error highlighting===

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should fine that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

===Outline===

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.

Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.

===Code navigation===

In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the mouse pointer over the function name '''insert_record''', then click. Eclipse should load '''dmllib.php''', and scroll you to where this function is defined.

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.

===Open resource===

From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

===Multi-file search===

Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

===Synchronize view===

I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.

Under '''Scope''', choose '''Workspace''', then click '''Finish'''.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project.... That is, it is listing just the files you have edited, but not checked in yet.

'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!

If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.

That's all the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

===Creating a patch===

In the synchronise view, right click on an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right click on an item and choose '''Team -> Create Patch...'''.

This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.

On the second page, you can set some options, but normally you don't need to change the defaults which are '''Unified''' diff format, and Patch root set to '''Workspace'''. Well, sometimes it is helpful to change the second one to '''Project''' but it is not important.

There is a corresponding apply patch wizard that you can use to apply a patch to a project.

===Switching to another branch or version===

Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.
# Right click on the moodle project in the navigator view, and select '''Team -> Switch to Another Branch or Version ...'''.
# choose the second radio button: '''Select the tag from the following list'''.
# If the branch you want is not in the '''Matching tags''' box, see [[Setting_up_Eclipse#Resetting the branch information|Resetting the branch information]] below.
# Select the branch you want and click '''Finish'''.

==Troubleshooting==

Some tips on how to solve common problems that may crop up.

===Resetting the branch information===

Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:

#Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").
#Click on Configure tags ... (not Refresh tags).
#Select config-dist.php in the top left box (if this is a Moodle checkout).
#Click Add Checked tags.
#Click OK.
#Then you will have all tags.

(thanks to Tim Hunt)

This info saved my day to find all branches:
1. Window->Show View->Other. Select CVS->CVS Repositories.
2. Context Menu->New->Repository Location...
3. Fill in the location information identifying your repository and click Finish.
4. Expand the newly-created repository location.
5. Add the branch:
1. right click on it and expand configure branches and versions
2. Expand HEAD and select the project moodle.
3. Context Menu->Configure Branches and Versions...
4. In the "Browse files for tags" table, select one or more files
that contain tags you would like to see (for example scroll down
to find config.php).
5. On the right the existing tags will appear.
6. select the tags: for example MOODLE_15_STABLE
7. Click "Add Selected Tags".
8. Click "OK".
6. locate branches, MOODLE_19_STABLE, moodle MOODLE_19_STABLE.
7. Context Menu->Check Out As Project.
("stolen" from Joan Codina Filba
General developer forum -> Moodle floating "block"/toolbar released -> Re: Moodle floating "block--PATCH FOR GRADES & ASIGNMENT --PROBLEM)

===Error loading php files after Ubuntu 7.04 Install===

A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to:
http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.

After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.

==Related Links==

There is an excellent series of articles published by IBM on using Eclipse for Drupal developement here : [http://www-128.ibm.com/developerworks/ibm/osource/index.html Using open source software to design, develop, and deploy a collaborative Web site Tools and techniques for getting relatively complicated Web sites up and running quickly].

[[Category:Setting up Eclipse]]

XMLDB defining an XML structure

2008-06-24T01:36:45Z

Scyrma: moving out of sourceforge

[[XMLDB Documentation|XMLDB Documentation]] > [[XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the underlying RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==
[[XMLDB_editor | Main article]]

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the edition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Miscellaneous tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Coding#Database_structures| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB Problems#NOT NULL fields using a DEFAULT <nowiki>''</nowiki> clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## This convention is only applicable for relations INSIDE one file. Don't generate FK constraints against other files (courseid, userid), use indexes there.
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://cvs.moodle.org/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false), '''enum''' (true/false), '''enumvalues''' (the list of values if the field has been declared as enum, for example <tt>'frog','toad','newt'</tt>) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' that conform it. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://cvs.moodle.org/moodle/lib/db/install.xml?view=co Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.dtd?view=co automatically generated DTD] for the XMLDB files. Also one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.xsd?view=co automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:XMLDB]]

Moodle Wishlist

2008-06-20T01:56:09Z

Scyrma:

This page is a brainstorm about a complete rewrite/refactor for Moodle 3.0.

Please add your ideas! They don't need to be consistent yet, just make sure your ideas are here to be boiled down later on.

Think Big!

===One type of plugin===

All plugins/modules could be subclassed from one plugin class, making installation easier and simplifying the API a lot.

===Look at new framework===

Possibly base Moodle 3.0 on new existing frameworks? Ruby on Rails? Drupal?

=== Moodlets===

Individual-independent-activities backup/restore + metadata - Eloy

=== Support for alternate interfaces ===

Completely flash-based interface? Designed for offline clients?

=== Integrated category/taxonomy system ===

Putting together the "course categories", "tags" into a generic taxonomy system.

HTML editor 2.0

2008-06-04T08:59:10Z

Scyrma: /* Plan of action */

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes, cleaning up current code as much as possible
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
* Support - Developed by an active community that will support it for a long time.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Highlighting (not text background color, with "set-on" operation--Word style)
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (possibly modified) content (see [http://wiki.moxiecode.com/examples/tinymce/installation_example_07.php this TinyMCE example of this])
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
* Submit drafts in the background, using ajax.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.

== Plan of action ==

See: MDL-11113 and MDL-14739

* Get latest TinyMCE in HEAD before 13 May 2008 so that work can be done there (done, MDL-14739)
* Have the XHTML profile active by default in TinyMCE (done)
* Attack each Moodle plugin in turn, keeping modifications to TinyMCE code base as modular and minimal as possible

=== Plugins to write ===
Some plugins will have to be written for each editor to make integration with Moodle possible. These should be as abstracted as possible, to make as much code as possible common between each. Since editors will be located under /lib/editor, let's store this common code under /lib/editormod.

* File browser: the file browser (especially with the [[File API]]) will be Moodle specific
* Emoticons (smileys): Moodle defines its own list of emoticons, we need to make sure the editors use these consistently
* Language files: Moodle has a lot more languages than any editors, and some strings will be Moodle-specific. We need a way to make for each editor to use Moodle strings, reusing as many existing strings as possible, and using lang/xx/editor.php for the rest.
* Equation editor: there is [[DragMath_equation_editor| ongoing work]] to get [http://www.dragmath.bham.ac.uk/ Dragmath] working in Moodle, making a common plugin could be a nice improvement
* Multilang: all editors need to support multilang properly.

It also may be possible to use Moodle's CSS files to define editors themes/skins, this needs investigation

'''Editor-specific information:'''
* TinyMCE makes it possible to have [http://tinymce.moxiecode.com/punbb/viewtopic.php?pid=9317#p9317 self-registering plugins], that don't need to be under it's /plugins folder (and so could be in a moodle-specific folder).
* FCKeditor [http://docs.fckeditor.net/FCKeditor_2.x/Developers_Guide/Customization/Plug-ins needs to have its plugins in a specific place].

=== Change in formats ===

There is a bug (MDL-4868) about Markdown not being converted to HTML when using the HTML editor (after creating a post with Markdown).

This really applies to all non-HTML formats.

Proposal: whenever the HTML editor is used to edit existing non-HTML text, we convert the text to HTML for use in the editor. Saving the changes will save the text (and format) as HTML.

Although we are losing some information, we feel it's an acceptable tradeoff against overall usability, particularly as the HTML editor works on a wider range of browsers and we make XHTML compliance a requirement.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific customisations to the HTML editor]]

Using Moodle General developer forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=88382 TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=96160 The most important decision on editor integration]

[[Category:HTML editor]]

HTML editor 2.0

2008-06-04T08:57:17Z

Scyrma: /* Plugins to write */

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes, cleaning up current code as much as possible
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
* Support - Developed by an active community that will support it for a long time.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Highlighting (not text background color, with "set-on" operation--Word style)
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (possibly modified) content (see [http://wiki.moxiecode.com/examples/tinymce/installation_example_07.php this TinyMCE example of this])
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
* Submit drafts in the background, using ajax.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.

== Plan of action ==

See: MDL-xxxx

* Get latest TinyMCE in HEAD before 13 May 2008 so that work can be done there
* Have the XHTML profile active by default in TinyMCE
* Attack each Moodle plugin in turn, keeping modifications to TinyMCE code base as modular and minimal as possible

=== Plugins to write ===
Some plugins will have to be written for each editor to make integration with Moodle possible. These should be as abstracted as possible, to make as much code as possible common between each. Since editors will be located under /lib/editor, let's store this common code under /lib/editormod.

* File browser: the file browser (especially with the [[File API]]) will be Moodle specific
* Emoticons (smileys): Moodle defines its own list of emoticons, we need to make sure the editors use these consistently
* Language files: Moodle has a lot more languages than any editors, and some strings will be Moodle-specific. We need a way to make for each editor to use Moodle strings, reusing as many existing strings as possible, and using lang/xx/editor.php for the rest.
* Equation editor: there is [[DragMath_equation_editor| ongoing work]] to get [http://www.dragmath.bham.ac.uk/ Dragmath] working in Moodle, making a common plugin could be a nice improvement
* Multilang: all editors need to support multilang properly.

It also may be possible to use Moodle's CSS files to define editors themes/skins, this needs investigation

'''Editor-specific information:'''
* TinyMCE makes it possible to have [http://tinymce.moxiecode.com/punbb/viewtopic.php?pid=9317#p9317 self-registering plugins], that don't need to be under it's /plugins folder (and so could be in a moodle-specific folder).
* FCKeditor [http://docs.fckeditor.net/FCKeditor_2.x/Developers_Guide/Customization/Plug-ins needs to have its plugins in a specific place].

=== Change in formats ===

There is a bug (MDL-4868) about Markdown not being converted to HTML when using the HTML editor (after creating a post with Markdown).

This really applies to all non-HTML formats.

Proposal: whenever the HTML editor is used to edit existing non-HTML text, we convert the text to HTML for use in the editor. Saving the changes will save the text (and format) as HTML.

Although we are losing some information, we feel it's an acceptable tradeoff against overall usability, particularly as the HTML editor works on a wider range of browsers and we make XHTML compliance a requirement.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific customisations to the HTML editor]]

Using Moodle General developer forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=88382 TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=96160 The most important decision on editor integration]

[[Category:HTML editor]]

HTML editor 2.0

2008-06-04T08:53:44Z

Scyrma: /* Plugins to write */

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes, cleaning up current code as much as possible
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
* Support - Developed by an active community that will support it for a long time.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Highlighting (not text background color, with "set-on" operation--Word style)
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (possibly modified) content (see [http://wiki.moxiecode.com/examples/tinymce/installation_example_07.php this TinyMCE example of this])
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
* Submit drafts in the background, using ajax.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.

== Plan of action ==

See: MDL-xxxx

* Get latest TinyMCE in HEAD before 13 May 2008 so that work can be done there
* Have the XHTML profile active by default in TinyMCE
* Attack each Moodle plugin in turn, keeping modifications to TinyMCE code base as modular and minimal as possible

=== Plugins to write ===
Some plugins will have to be written for each editor to make integration with Moodle possible. These should be as abstracted as possible, to make as much code as possible common between each. Since editors will be located under /lib/editor, let's store this common code under /lib/editormod.

* File browser: the file browser (especially with the [[File API]]) will be Moodle specific
* Emoticons (smileys): Moodle defines its own list of emoticons, we need to make sure the editors use these consistently
* Language files: Moodle has a lot more languages than any editors, and some strings will be Moodle-specific. We need a way to make for each editor to use Moodle strings, reusing as many existing strings as possible, and using lang/xx/editor.php for the rest.
* Equation editor: there is [[DragMath_equation_editor| ongoing work]] to get [http://www.dragmath.bham.ac.uk/ Dragmath] working in Moodle, making a common plugin could be a nice improvement
* Multilang: all editors need to support multilang properly.

It also may be possible to use Moodle's CSS files to define editors themes/skins, this needs investigation

Editor-specific information:
* TinyMCE makes it possible to have [http://tinymce.moxiecode.com/punbb/viewtopic.php?pid=9317#p9317 self-registering plugins], that don't need to be under it's /plugins folder (and so could be in a moodle-specific folder).
* FCKeditor [http://docs.fckeditor.net/FCKeditor_2.x/Developers_Guide/Customization/Plug-ins needs to have its plugins in a specific place].

=== Change in formats ===

There is a bug (MDL-4868) about Markdown not being converted to HTML when using the HTML editor (after creating a post with Markdown).

This really applies to all non-HTML formats.

Proposal: whenever the HTML editor is used to edit existing non-HTML text, we convert the text to HTML for use in the editor. Saving the changes will save the text (and format) as HTML.

Although we are losing some information, we feel it's an acceptable tradeoff against overall usability, particularly as the HTML editor works on a wider range of browsers and we make XHTML compliance a requirement.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific customisations to the HTML editor]]

Using Moodle General developer forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=88382 TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=96160 The most important decision on editor integration]

[[Category:HTML editor]]

HTML editor 2.0

2008-06-04T08:48:57Z

Scyrma: /* Plugins to write */

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes, cleaning up current code as much as possible
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
* Support - Developed by an active community that will support it for a long time.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Highlighting (not text background color, with "set-on" operation--Word style)
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (possibly modified) content (see [http://wiki.moxiecode.com/examples/tinymce/installation_example_07.php this TinyMCE example of this])
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
* Submit drafts in the background, using ajax.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.

== Plan of action ==

See: MDL-xxxx

* Get latest TinyMCE in HEAD before 13 May 2008 so that work can be done there
* Have the XHTML profile active by default in TinyMCE
* Attack each Moodle plugin in turn, keeping modifications to TinyMCE code base as modular and minimal as possible

=== Plugins to write ===
Some plugins will have to be written for each editor to make integration with Moodle possible. These should be as abstracted as possible, to make as much code as possible common between each. Since editors will be located under /lib/editor, let's store this common code under /lib/editormod.

* File browser: the file browser (especially with the [[File API]]) will be Moodle specific
* Emoticons (smileys): Moodle defines its own list of emoticons, we need to make sure the editors use these consistently
* Language files: Moodle has a lot more languages than any editors, and some strings will be Moodle-specific. We need a way to make for each editor to use Moodle strings, reusing as many existing strings as possible, and using lang/xx/editor.php for the rest.
* Equation editor: there is [[DragMath_equation_editor| ongoing work]] to get [http://www.dragmath.bham.ac.uk/ Dragmath] working in Moodle, making a common plugin could be a nice improvement
* Multilang: all editors need to support multilang properly.

It also may be possible to use Moodle's CSS files to define editors themes/skins, this needs investigation

Editor-specific information:
* tinymce makes it possible to have [http://tinymce.moxiecode.com/punbb/viewtopic.php?pid=9317#p9317 self-registering plugins], that don't need to be under it's /plugins folder (and so could be in a moodle-specific folder).

=== Change in formats ===

There is a bug (MDL-4868) about Markdown not being converted to HTML when using the HTML editor (after creating a post with Markdown).

This really applies to all non-HTML formats.

Proposal: whenever the HTML editor is used to edit existing non-HTML text, we convert the text to HTML for use in the editor. Saving the changes will save the text (and format) as HTML.

Although we are losing some information, we feel it's an acceptable tradeoff against overall usability, particularly as the HTML editor works on a wider range of browsers and we make XHTML compliance a requirement.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific customisations to the HTML editor]]

Using Moodle General developer forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=88382 TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=96160 The most important decision on editor integration]

[[Category:HTML editor]]

User:Mathieu Petit-Clair

2008-05-08T05:11:01Z

Scyrma:

See http://moodle.org/user/view.php?id=423027&course=1 for details.

Overview

2008-05-07T06:44:32Z

Scyrma: /* The key players */

A lot of people ask how the development of Moodle operates. This page should give you a working overview that should help in understanding a lot of other developer documentation.

==The key players==

;Martin Dougiamas: Martin is the lead developer of Moodle. Generally he tries to facilitate democracy and meritocracy but occasionally has to make executive decisions on things.

;Moodle HQ: The mostly-Australian team of developers who are directly funded by the Moodle project to work full-time on core developments. Developers include Martin Dougiamas (moodler), Eloy Lafuente (stronk7), Petr Skoda (skodak), Mathieu Petit-Clair (scyrma), Nicolas Connault, Donsheng Cai, Jérôme Mouneyrac, Helen Foster (wildgirl) and occasionally Jamie Pratt (jamiesensei). Pictures of everyone can be found here: http://moodle.com/hq/.

;Catalyst: The team of developers working for Moodle clients via Catalyst Ltd in New Zealand, resulting in a lot of core development. Developers include Martin Langhoff, Penny Leach (mjollnir), Matt Clarkson, and Donal McMullan.

;Open University: The team of developers working on Moodle implementations at Open University in the UK. Developers include Tim Hunt, Sam Marshall, Nick Freear, Thanh Le and Jenny Gray.

There are many other people contributing to Moodle in many ways, these are just the main groups currently working on core development. See [http://moodle.org/cvs the full list of people with write access to Moodle]

==Moodle versions==

Moodle major releases occur roughly 6 months or more apart, on no fixed schedule. Each major release increments the version number by 0.1. Minor releases (no new features, just fixes) on each stable branch can occur at any time, whenever enough bug fixes have been made to justify them. The full details can be seen in the [[Release notes]].

The current development version is always on the trunk of CVS (i.e. HEAD), while stable branches are split off for every major version (e.g. MOODLE_18_STABLE).

==Release cycles==

Generally a cycle works like this:
;Rapid Development:Long period of several months adding code to the HEAD version of Moodle. At the same time, all fixes that don't involve database changes or radical core changes are backported to the last two or three stable branches.
;Head Freeze:At some point Martin Dougiamas declares a freeze on new work for a while to stabilise the core. All database changes and all major core changes need to have explicit permission from Martin. All developers should be wrapping up work on new features and fixing bugs in new code. This period may be 1 or 2 weeks.
;Beta period:Once the HEAD version becomes fairly stable, Martin declares a BETA version and this point is marked on HEAD as MOODLE_XX_BETA (e.g. MOODLE_19_BETA). Install packages are generated daily from the latest version for wider testing and feedback via the tracker. The freeze continues, testing and bug fixing continues. This testing period may be anywhere from 2 to 6 weeks.
;Major release:When the core code passes all the testing we can throw at it, the MOODLE_XX_BETA flag is moved up to mark the current point as a branch point, and a new stable branch named MOODLE_XX_STABLE is created. Packages are created, and the release is announced.

Then it all starts again!

==Quality control==

Issue tracking is an important part of a continuous quality control process. It involves reporting of problems (bugs), ideas for improvement and new features. Unlike most proprietary software programs, Moodle issue reporting and tracking information is open to everyone. Moodle's issue tracking system is called the [[Tracker]].

All Moodle users are encouraged to be active participants when it comes to testing. Anyone with a Tracker user account can create, view, comment on, vote, and watch bugs.

===Testers===

Testers are responsible for verifying the accuracy of changes made by developers. Testers choose which bugs they want to test, according to their area of expertise, and use the QA Assignee field to identify themselves as the tester.

If the bug passes testing, then the tester changes the status of the bug from 'resolved' to 'closed'. If the bug fails testing, or if the fix is incomplete, then the tester reopens the bug.

A Moodle release will be deemed ready when all "blocker" bugs fixed for a particular version have been closed.

===Weekly Code Review===

Every Tuesday (all time zones), testers and core developers stop developing new code and focus on reviewing changes made to the stable releases in the past week (both at a code level and an interface level).

This process is intended to improve the quality of the latest download packages and to catch any new bugs that might have been created while fixing old ones.

The latest stable packages are tagged as MOODLE_19_WEEKLY (these tags are updated after the weekly review is over).

See [[Weekly Code Review]] for more details.

==Coding Standards==

The full [[Coding|Coding Guide]] gives all the details, but here are some of the major things your code needs to hit:

===XMLDB===

All our database schema are created using the XML ''install.php'' files, and upgraded using database-agnostic commands in ''upgrade.php'' files. Any version of any part of Moodle can be smoothly upgraded to any later version in this fashion (on a wide variety of supported databases).

===XHTML===

All output from Moodle must be compliant with XHTML Strict 1.0, and also compliant with all common accessibility guidelines (such as W3C WAG).

===Forms===

All forms should use the Moodleforms library if possible. This results in a standardised accessible output that designers can style consistently and well.

===Parameters===

All parameters should be checked using require_param() and optional_param() which will safely clean all incoming data for use and provide defaults to your code. Moodleforms will do this automatically for you.

===Output===

All textual output should be output using the format_text or format_string functions. This will ensure that text is cleaned and filtered appropriately.

===Access===

All permissions-checking should use the "Access library" to check against current capabilities. The most common function you'll use is has_capability() which checks the permissions of the current user in an efficient way to see if they are allowed to do this specific operation. Do not check for specific roles in your code (e.g. teacher/student) as that will make your code useless.

===Other core libraries===

The other major libraries you should get familiar with are:
# ''moodlelib.php'' - a useful bin of all kinds of useful functions and constants
# ''datalib.php'' - all the functions you need to interface with the database
# ''weblib.php'' - all the functions you'll need to create and output XHTML

===Plugins===

Moodle has about 22 different types of plugins last time I counted. Plugins can generally be self-contained in a single directory containing scripts, images, stylesheets and language files all in one package that can be dropped into the Moodle script directory in the right place. After that the admin just needs to visit the admin page to install them.

Most plugins work in one of two ways, they either provide a ''lib.php'' filled with common functions and some scripts with standard names, or they subclass a proto-plugin and override a few method functions to achieve their goals.

The best way to learn is to pick an example from the core code that is similar to what you want to do and start playing with it. There are also some template plugins to help get you started.

==Development processes==
Not all Moodle development happens exactly like this, but it really should. :-)

===Major Development===
A major development is a significant piece of new code, adding new functionality to Moodle.

====Make sure it's a good idea====
Firstly, you should look at the roadmap and talk the idea over with some Moodle developers to see if someone else is working on it already and whether others think the general idea has merit. Use the forums if you wish, or whatever means you have. If you have a client, you may need to work with them to work out what they REALLY want (perhaps it isn't actually a new development for Moodle).

====Create a specification in Moodle Docs====
Start a new page in the Moodle Docs wiki, similar to [[Grades]]. Your page should outline the database table design, the GUI, the hows and whys etc. Include as much detail as you need (even mock screenshots) but try to keep it clear and logically organised.

====Seek and absorb community feedback====
Post about the new page in the appropriate forums on [http://moodle.org/course/view.php?id=5 Using Moodle] to help draw attention to it and to stimulate some discussion around your development. The more feedback you have the better, especially if it includes a wide variety of users (developers, teachers, students etc).

Edit your page in response to the feedback, or invite people to do so themselves. try to evolve the specification into something that all users are happy with. Sometimes it's worth working harder to find the "best" way to do something without adding Yet Another Option.

====Set up tasks in the Moodle Tracker====
Once the specification has settled down, it's time to start work. Create a new task for yourself in the Moodle Tracker, and add sub-tasks in roughly chronological order for all the different parts of the job. This not only helps you keep track of where you are, but allows the community to "watch you" develop and to help you where they can. If there are different people working on different parts, you can assign subtasks to different people. It's really very convenient to use once you get the hang of it.

====Use CVS and link commits to Tracker====
If possible, develop the code in an open code repository (and preferably Moodle CVS!). If you need CVS write access to the core code or the contrib repository, contact support@moodle.com with details. Gaining access to the main core code is quite difficult, but we are generally very free with access to the contrib area.

Every time you make a commit, include a detailed message about the new code and always include a Moodle Tracker bug number (e.g. MDL-7777). This will ensure that the Moodle Tracker is able to detect your commit and attach it to the relevant bug report.

====Comment on milestones in forums and tracker====
If you hit a major milestone, or want testers to try something, feel free to post about it in the relevant forum on Using Moodle. The more people you can attract to look and try out your code the better it will be, trust me.

====Respond to bug reports====
Of course you need to listen to your users (well, most of them :-)). Encourage people to file bugs, and fix them. If you need help setting up a project category in the Tracker contact support@moodle.com. This will ensure that all your bugs are easy to find and to track.

===Minor Development===

For smaller modules, fixes, improvements and other issues.

====Create a new issue in the tracker====

You should definitely create an issue in the tracker to describe your development and to act as a focus point for all discussion. You can reference the bug number from forum discussions and in commit messages etc. This way everyone can easily find out exactly what they are talking about.

====Attach a patch====

If you have some code, please attach it to the tracker issue, or if it's on your own site then link to it from the tracker issue. Don't attach code in the Moodle forums ... it will "rot" quickly there and just clogs up moodle.org with useless old code.

====Promote the patch====

By all means draw attention to your work in the Moodle forums (mentioning the bug number) or email developers directly to help make them aware of it. You can also add developers as "watchers" to the tracker issue if you want, this means they will get email for every change on the issue.

==See also==

* [[Finding your way into the Moodle code]]
* [[Working with the Community]]

[[Category:Overview]]

HTML editor 2.0

2008-05-06T09:40:20Z

Scyrma:

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes, cleaning up current code as much as possible
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
* Support - Developed by an active community that will support it for a long time.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Highlighting (not text background color, with "set-on" operation--Word style)
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (possibly modified) content (see [http://wiki.moxiecode.com/examples/tinymce/installation_example_07.php this TinyMCE example of this])
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
* Submit drafts in the background, using ajax.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.

== Plan of action ==
* Get code in HEAD before 13 May 2008 so that work can be done there
* Have the XHTML profile active by default in TinyMCE

=== Change in formats ===

This is actually more a related issue... There is a [[http://tracker.moodle.org/browse/MDL-4868 | long-standing bug]] about Markdown not being converted to HTML when using the HTML editor (after creating a post with Markdown). As the HTML editor becomes available on more browsers (and being more stable), most people will probably want to use it instead of Markdown, so we should solve this bug, by properly converting the Markdown text to HTML, the first time it is displayed in the editor.

=== Plugins to write ===
Some plugins will have to be written for each editor to make integration with Moodle possible. These should be as abstracted as possible, to make as much code as possible common between each
* Language files: Moodle has a lot more languages than any editors, and some strings will be Moodle-specific. We need a way to make the editors use Moodle strings
* File browser: the file browser (especially with the [[Repository API]]) will be Moodle specific
* Emoticons (smileys): Moodle defines it's own list of emoticons, we need to make a plugin to use them
* Equation editor: there is [[DragMath_equation_editor| ongoing work]] to get [http://www.dragmath.bham.ac.uk/ Dragmath] working in Moodle, making a common plugin could be a nice improvement
* It may be possible to use Moodle's CSS files to define editors themes/skins, this needs investigation

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific customisations to the HTML editor]]

Using Moodle General developer forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=88382 TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=96160 The most important decision on editor integration]

[[Category:HTML editor]]

HTML editor 2.0

2008-05-06T09:08:45Z

Scyrma:

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes, cleaning up current code as much as possible
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
* Support - Developed by an active community that will support it for a long time.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Highlighting (not text background color, with "set-on" operation--Word style)
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (possibly modified) content (see [http://wiki.moxiecode.com/examples/tinymce/installation_example_07.php this TinyMCE example of this])
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
* Submit drafts in the background, using ajax.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.

== Plan of action ==
* Get code in HEAD before 13 May 2008 so that work can be done there
* Have the XHTML profile active by default in TinyMCE

=== Problems & Solutions ===

=== Plugins to write ===
Some plugins will have to be written for each editor to make integration with Moodle possible. These should be as abstracted as possible, to make as much code as possible common between each
* Language files: Moodle has a lot more languages than any editors, and some strings will be Moodle-specific. We need a way to make the editors use Moodle strings
* File browser: the file browser (especially with the [[Repository API]]) will be Moodle specific
* Emoticons (smileys): Moodle defines it's own list of emoticons, we need to make a plugin to use them
* Equation editor: there is [[DragMath_equation_editor| ongoing work]] to get [http://www.dragmath.bham.ac.uk/ Dragmath] working in Moodle, making a common plugin could be a nice improvement
* It may be possible to use Moodle's CSS files to define editors themes/skins, this needs investigation

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific customisations to the HTML editor]]

Using Moodle General developer forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=88382 TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=96160 The most important decision on editor integration]

[[Category:HTML editor]]

HTML editor 2.0

2008-05-05T08:26:08Z

Scyrma: /* Wishes */

HTML editor 2.0

2008-04-24T03:42:31Z

Scyrma: /* Requirements */

HTML editor 2.0

2008-04-16T06:21:06Z

Scyrma: /* Requirements */

HTML editor 2.0

2008-04-16T06:19:03Z

Scyrma:

This page details the specification of the HTML editor in Moodle 2.0.
== What we want ==
Ticket MDL-11113 discusses most issues.
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.
=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Image uploading
* Mathematical formulas/equation editing
* Possible to turn it on and off on demand (on the page) without losing (modified) content
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)
=== Wishes ===
* Make it possible to change to a different editor (provided someone comes up with the necessary code to "plug it" in Moodle)
* Possible to run many instances on the same page (see MDL-11101 in tracker)
* Fix [http://tracker.moodle.org/secure/IssueNavigator.jspa?reset=true&pid=10011&resolution=-1&component=10070&sorter/field=summary&sorter/order=ASC&sorter/field=resolution&sorter/order=ASC&sorter/field=status&sorter/order=ASC&sorter/field=priority&sorter/order=DESC all the bugs] related to the HTML editor
== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],
As of 16 April 2008, the preference goes to TinyMCE.
== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific_customisations_to_the_HTML_editor]]
* [http://moodle.org/mod/forum/discuss.php?d=88382 Using Moodle - General developer forum: TinyMCE3 Integration]
* [http://moodle.org/mod/forum/discuss.php?d=93475 Using Moodle - General developer forum: XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=76912 Using Moodle - General developer forum: What is the current position with the HTML editor?]

HTML editor 2.0

2008-04-16T05:44:32Z

Scyrma: /* Links to forum discussions, tracker, docs, etc. */

This page details the specification of the HTML editor in Moodle 2.0.

== What we want ==
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Image uploading
* Mathematical formulas editing
* Possible to turn it on and off on demand (on the page) without losing (modified) content
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

Ticket MDL-11113 discusses most issues.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],

As of 16 April 2008, the preference goes to TinyMCE.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [[Moodle-specific_customisations_to_the_HTML_editor]]
* [http://moodle.org/mod/forum/discuss.php?d=76912 Using Moodle - General developer forum: What is the current position with the HTML editor?]
* [http://moodle.org/mod/forum/discuss.php?d=93475 Using Moodle - General developer forum: XINHA has started to support Opera and Safari]
* [http://moodle.org/mod/forum/discuss.php?d=88382 Using Moodle - General developer forum: TinyMCE3 Integration]

HTML editor 2.0

2008-04-16T04:34:29Z

Scyrma:

This page details the specification of the HTML editor in Moodle 2.0.

== What we want ==
=== Requirements ===
* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.

=== Features ===
Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Image uploading
* Mathematical formulas editing
* Possible to turn it on and off on demand (on the page) without losing (modified) content
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

Ticket MDL-11113 discusses most issues.

== Possibilities and evaluation ==
* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],

As of 16 April 2008, the preference goes to TinyMCE.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [http://moodle.org/mod/forum/discuss.php?d=76912 Using Moodle: What is the current position with the HTML editor?]
* [[Moodle-specific_customisations_to_the_HTML_editor]]

HTML editor 2.0

2008-04-16T04:33:17Z

Scyrma:

This page details the specification of the HTML editor in Moodle 2.0.

== What we want ==

* Integration - With Moodle (smileys, different formats, etc.) with a minimum of changes
* Compatibility - With web browsers (mostly FF, IE, Safari, Opera)
* Standard - Outputs valid XHTML code
* Accessibility - Is it 100% keyboard accessible? Is it usable in JAWS? Etc.
* Configurability - Possibility to make it show different options and buttons according to the user, the context, etc.

Some features that should be evaluated:
* Handling of Word documents
* HTML code direct editing
* Image uploading
* Mathematical formulas editing
* Possible to turn it on and off on demand (on the page) without losing (modified) content
* Right-to-left text input
* Smileys (has to be possible to use the Moodle list of smileys)
* Special characters
* Tables
* Themeable (possible to make a theme that fits with Moodle's)

Ticket MDL-11113 discusses most issues.

== Possibilities and evaluation ==

* [http://en.wikipedia.org/wiki/Comparison_of_WYSIWYG_HTML_editors Comparison of WYSIWYG HTML editors on Wikipedia]
* [http://tinymce.moxiecode.com/ TinyMCE]: [http://wiki.moxiecode.com/index.php/TinyMCE:Compatibility Compatibility], [http://wiki.moxiecode.com/index.php/TinyMCE:Index Documentation], [http://tinymce.moxiecode.com/example_full.php?example=true Demo]
* [http://www.fckeditor.net/ FCKeditor]: [http://docs.fckeditor.net/FCKeditor_3.x/Design_and_Architecture/Browsers_Compatibility Compatibility] [http://docs.fckeditor.net/ Documentation], [http://www.fckeditor.net/demo Demo]
* [http://xinha.webfactional.com/ Xinha]: [http://xinha.webfactional.com/wiki/Documentation Documentation], [http://xinha.webfactional.com/wiki/Examples Demo]
* [http://developer.yahoo.com/yui/editor/ Yahoo RTE]: [http://developer.yahoo.com/yui/docs/module_editor.html Documentation], [http://developer.yahoo.com/yui/examples/editor/index.html Demo],

As of 16 April 2008, the preference goes to TinyMCE.

== Links to forum discussions, tracker, docs, etc. ==
* [http://tracker.moodle.org/browse/MDL-11113 MDL-11113 - Get a fully working HTML editor in Moodle]
* [http://moodle.org/mod/forum/discuss.php?d=76912 Using Moodle: What is the current position with the HTML editor?]
* [[Moodle-specific_customisations_to_the_HTML_editor]]

Setting up Eclipse

2008-04-14T04:09:51Z

Scyrma: /* Checking out the Moodle code */

[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that some Moodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

This article started off as a brain-dump by [[User:Tim Hunt|Tim Hunt]]. Since then, several other people have worked through it and made corrections, so the information here should be pretty accurate.

==Prerequisites==

Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux, in each case with 1GB of memory, and that is plenty.

==Installing Eclipse==

Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says '''Eclipse Classic'''. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, unzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

==The first time you run Eclipse==

The first time you launch Eclipse it does a bit of setup stuff, for instance, it create a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Use this as the default and do not ask again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probably don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

==Installing the necessary plugins==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step.

From the '''Help''' menu choose '''Software Updates -> Find and Install'''.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.

In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://phpeclipse.sourceforge.net/update/releases/; then click '''OK'''.

''Note, there is now also another PHP editor for Eclipse. The update URL ishttp://download.eclipse.org/tools/pdt/updates/. I am just trying it--[[User:Tim Hunt|Tim Hunt]] 11:39, 7 November 2007 (CST)''

Back in the wizard, turn on just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Europa Discovery Site''' (or possibly '''Callisto Discovery Site'''.
Then click '''Finish'''.

It goes off sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want. The ones you want (you may have to search the tree structure) are, '''PHPeclipse''' (from your newly created PHPEclipse Update Site) and all the '''Web Standard Tools (WST)''' (usually under Callisto Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the '''Select Required''' button which should resolve dependencies and remove the warning message you are probably worrying about. Then you can click the '''Next >''' button.

Read and agree to all the license agreements. Then click '''Next >'''.

Click '''Finish''', and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation build digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.

Finally, a window will pop up asking you to restart Eclipse. Do so.

==Setting the preferences for Moodle development==

Now go to the '''Window''' menu, and choose '''Preferences ...''' ('''Eclipse''' menu on Mac OS X).

The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

===General settings===

If you have strong feelings about fonts (I would hate to edit code an anything except Andale Mono), choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.

Under '''General -> Editors -> File Associations''', if it is not already there, add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box. With '''*.html''' selected in the top box, select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '''Internet -> Proxy Settings'''. (Yes, I know you have entered them somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

These are all hidden under the '''PHPeclipse Web Development''' bit of the tree.

Under '''PHPeclipse Web Development -> Browser Preview Defaults''', turn off both checkboxes.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, check '''Show line numbers''' to display line numbers in the left margin (optional). NOTE.- When you are editing a PHP file, you could left-click in the left margin and tick the '''Show Line Numbers''' line in the contextual menu. However, this toggle only applies to plain text files, ''not'' to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.

Under '''PHPeclipse Web Development -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments''' and '''Remove trailing spaces on editor save'''. It would be nice to turn on more of these options, but most of the rest don't work very well.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''.

Under '''PHPeclipse Web Development -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>print_object(${word_selection}${cursor}); // DONOTCOMMIT</pre>
You can do other useful things with templates too. Here are two more I use:
<pre>debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT</pre>
<pre>$$string['${word_selection}${cursor}'] = '.';</pre>
That is, a simple debug message with a stack trace, and a new language string.

There is a really stupid bug. Under '''PHPeclipse Web Development -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.
# Close Eclipse.
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.
# Change this line to say '''_php_include_paths=.'''
# Run Eclipse again.

===CVS Settings===

These are all hidden under the '''Team''' bit of the tree.

Under '''Team -> CVS -> SSH2 Connection Method''', you can set up a public/private key pair. If you do this, you won't have to keep typing your Sourceforge password when doing CVS operations. See http://sourceforge.net/docs/F02/ for the instructions on what people used to do when the CVS was at Sourceforge. However, If you follow the Sourceforge instructions now you will spend a good deal of time trying to add a public key to your sourceforge profile to no purpose; the key generated is for cvs.moodle.org, NOT, sourceforge, and you add it via the Update My Developer Information tab on the moodle developers page at http://moodle.org/mod/cvsadmin/view.php?id=7134. Once you have uploaded your public key you can then try to fgure out how to make Eclipse use this keyset.

The rest of the ones in this section are personal preferences, but I recommend them because the default settings are very irritating.

Under '''Team''', set '''Perspectives''' to '''None'''.

Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.

Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.

===Web and XML settings===

Foreach XXX in CSS, HTML, Javascript, XML:

Under '''Web and XML -> XXX Files ->XXX Source''', choose '''Indent using spaces''' and '''indentation size''' 4.

==Checking out the Moodle code==

From the '''File''' menu, choose '''New -> Project ...''', then click '''Next >'''.

In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.

Select '''Create a new repository location''', then click '''Next >'''.

Fill in
<div style="float: right; border: 1px solid orange; padding: 0 1em;">
For anonymous CVS access use
;Host
:XX.cvs.moodle.org
where XX.cvs.moodle.org is one of [[CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:cvs.moodle.org
;Repository path
:/cvsroot/moodle
;User
:(your Moodle CVS username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)
;Connection type
:extssh
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.

On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.

On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.

Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.

Click '''Finish'''.

Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.

Make up a project name. '''moodle''' would be sensible.

Click '''Finish''', and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.

If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:
* This time you can choose '''Use an existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch. If you don't see the branch you want, see [https://docs.moodle.org/en/Development:Setting_up_Eclipse#Resetting_the_branch_information this Troubleshooting tip].
* Use a different project name (e.g. moodle16, moodle17, etc.).

==Let your development web server know where your files are==

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

==Quick tour of some cool features, and remaining configuration changes==

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

===Navigator===

To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-hightlighted.

===Error highlighting===

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should fine that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

===Outline===

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.

Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.

===Code navigation===

In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the mouse pointer over the function name '''insert_record''', then click. Eclipse should load '''dmllib.php''', and scroll you to where this function is defined.

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.

===Open resource===

From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

===Multi-file search===

Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

===Synchronize view===

I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.

Under '''Scope''', choose '''Workspace''', then click '''Finish'''.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project.... That is, it is listing just the files you have edited, but not checked in yet.

'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!

If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.

That's all the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

===Creating a patch===

In the synchronise view, right click on an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right click on an item and choose '''Team -> Create Patch...'''.

This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.

On the second page, you can set some options, but normally you don't need to change the defaults which are '''Unified''' diff format, and Patch root set to '''Workspace'''. Well, sometimes it is helpful to change the second one to '''Project''' but it is not important.

There is a corresponding apply patch wizard that you can use to apply a patch to a project.

===Switching to another branch or version===

Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.
# Right click on the moodle project in the navigator view, and select '''Team -> Switch to Another Branch or Version ...'''.
# choose the second radio button: '''Select the tag from the following list'''.
# If the branch you want is not in the '''Matching tags''' box, see [[Setting_up_Eclipse#Resetting the branch information|Resetting the branch information]] below.
# Select the branch you want and click '''Finish'''.

==Troubleshooting==

Some tips on how to solve common problems that may crop up.

===Resetting the branch information===

Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:

#Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").
#Click on Configure tags ... (not Refresh tags).
#Select config-dist.php in the top left box (if this is a Moodle checkout).
#Click Add Checked tags.
#Click OK.
#Then you will have all tags.

(thanks to Tim Hunt)

===Error loading php files after Ubuntu 7.04 Install===

A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to:
http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.

After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.

==Related Links==

There is an excellent series of articles published by IBM on using Eclipse for Drupal developement here : [http://www-128.ibm.com/developerworks/ibm/osource/index.html Using open source software to design, develop, and deploy a collaborative Web site Tools and techniques for getting relatively complicated Web sites up and running quickly].

[[Category:Setting up Eclipse]]

Weekly Code Review

2008-04-01T03:42:23Z

Scyrma: /* Test the fix */

Moodle has a weekly process of code review in the stable branches to help improve the quality of stable packages and to help detect any regressions that may have occurred in stable code.

Here is the process for testers and developers:

==Every Tuesday==

===Find bugs to test===

All developers and testers should be looking at:

Moodle 1.9 stable: [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10565 1.9.x Needs QA review]

(Make sure you can see the QA Assigned column)

Grab any bug that:

* is from the last week
* you did not fix
* does not have a QA assignee yet

and claim it by editing the bug to add your name as QA Assignee.

===Test the fix===

* Read the comments
* Look at the patch attached to the tracker
* Try the feature out to make sure it works as advertised
* Post new comments (or talk on Moodle HQ) if you need clarification

===If you find a problem===

* Post a comment on the bug with details (preferably including patch!)
* Reopen the bug
* If it looks like the original developer isn't seeing it, reassign to Eloy Lafuente for triage.
* If the fix is obvious and you have CVS access, fix it yourself.

===Mark the fix as reviewed===

* When you are satisfied the bug is correctly fixed, simply change the status from Resolved to Closed

==Every Wednesday==

* The download site will automatically tag the whole current stable codebase (eg MOODLE_19_WEEKLY) and then build download packages

Repository API

2008-03-31T09:09:09Z

Scyrma: /* Repository plugins */

This page describes the specification for a future feature, currently being worked on for Moodle 2.0. This spec is STILL UNDER CONSTRUCTION.

See MDL-13766 to track the status of the implementation.

The page is open for everyone so everyone can help correct mistakes and help evolution of this document. However, if you have questions, problems or major changes to suggest please add them to the [[Development_talk:Repository_API|page comments]], or start a discussion in the [http://moodle.org/mod/forum/view.php?id=1807 Repositories forum]. We'll endeavour to merge all such suggestions into the main spec before we start development.

==Objectives==

# Allow files to be added directly into Moodle (as we do now)
# Allow all Moodle users to easily bring content into Moodle from external repositories
# Allow content to be used in multiple Moodle contexts securely and simply via capabilities
# Consistency and simplicity for ALL file handling

==Overview==

The Repository API is a core set of interfaces that all Moodle code will use to:
# copy files from external servers
# store files within Moodle
# display files to Moodle users

It's important to remember that a repository will generally be treated as READ-ONLY. Management of the files will normally be done through the native interface provided by the repository. Publishing of Moodle content TO a repository is handled by the [[Portfolio API|Portfolio API]].

==Use cases==

===Teacher adding an external file as a new resource===

# Teacher wants to add a new resource to a course
# Teacher clicks the "Choose a resource" button
# Teacher is able to choose from a list of configured repositories (this step will be skipped if there's only one).
# Teacher is presented with a simple file picker to choose a file
# Teacher chooses a file
# File is COPIED into Moodle and included in the course.
# File is marked as owned by that user
# Access controls are automatically added for that file so that only those with privileges to see that course can see that file (the owner can change those permissions anytime)

===Student submitting an assignment===
# Student needs to submit an assignment and presses the "Choose files" button
# Student sees a "file picker" where they can see files listed on any of several configured repositories
# Student chooses MySpace from the list
# Student is prompted to enter MySpace username/password (a checkbox could be there to "remember this for next time" but for security perhaps not)
# Student sees their files in MySpace and chooses one or more
# Files are copied from MySpace to Moodle
# Assignment module gives the files permissions so that only the Student and assignment graders can see the file (other students would not have permission).

===Student attaching an image to a forum===
# Student needs to attach an image and presses the "Choose files" button in the posting screen
# Student sees a "file picker" where they can see files listed on any of several configured repositories
# Student chooses Mahara from the list
# Student is prompted to enter MySpace username/password (a checkbox could be there to "remember this for next time" but for security perhaps not)
# Student sees their files in Mahara and chooses one image
# Image is copied to Moodle
# Image file is attached to forum post by Forum module (by reference)
# Forum module gives permissions so that anyone who can read that forum can see that file

===Student attaching the same image in another forum===

# Student needs to submit an assignment and presses the "Choose files" button
# Student sees a "file picker" where they can see files listed on any of several configured repositories
# Student chooses Mahara from the list
# Student is prompted to enter MySpace username/password (a checkbox could be there to "remember this for next time" but for security perhaps not)
# Student sees their files in Mahara and chooses one image
# Moodle detects that the image already exists in Moodle so it it not copied again (or it's just updated)
# Image file is attached to forum post by Forum module (by reference)
# Forum module adds some permissions so that anyone who can read the current forum can also see that file

===User managing their files===
# User goes to the "Files" area (similar to current Moodle, but for all users)
# User sees two tabs
# First tab shows listing of current files belonging to self, with buttons to manage them, including buttons to modify the permissions (eg "Allow all people in Course X to see this"). You can also see what repository it came from, including the foreign path, and choose to "update from repository" and get a new copy of the file.
# Second tab shows listing of files belonging to others that you are able to see.

Please add more use cases in this same format

==General Architecture==

All file-handling areas in Moodle (eg adding a new resource, adding attachments to a forum post, uploading assignments) will be rewritten to talk to the standard API class methods in a standard way.

Each repository plugin (a standard Moodle plugin stored under /repository/xxx) will subclass the standard API and override methods specific to that repository.

As is usual in Moodle, there will be admin settings to disable/enable certain repository plugins as standard, as well as user settings so that users can add their own personal repositories to the standard list (eg [http://briefcase.yahoo.com Yahoo Briefcase] or [http://docs.google.com Google Docs]) and to select their default repository.

Once a repository has been used the file will usually be copied into Moodle there and then. However there will also be options to:
* only return the URL to the file if it's desired to keep it external (but this does present security and integrity risks), or
* refresh the local file copy regularly and automatically

All files in Moodle will be listed in a table (see below) allowing us to store various metadata about each file. The file contents will not be the database (though we could easily offer that option if we want to), they will be on disk with a name related to the id rather than the "human" name (this avoids a lot of OS Unicode problems).

The current "course file manager" will be replaced by a personal file manager, which basically is a user's view of the internal Moodle repository, showing the files that are available to you in that context (which may include files from other people, repositories etc) and a nice browse/search interface.

Finally, normal Moodle modules will have easy functions it can use to add/remove permissions to particular files, according to module rules. For example, the assignment plugin may, after allowing a student to select a file to be submitted, add permissions so that people who have grade permissions in that assignment can read it.

All files will be served via a single control script in Moodle, located at $CFG->fileroot. This could be the same as $CFG->wwwroot by default, but will be recommended (for security and avoiding XSS) that Moodle admins set up a second DNS name pointing to this script eg the main site could be at http://moodle.domain.edu but files would be served via http://moodlefiles.domain.edu/file.php. (We'll have to set session cookies on both domains and keep them in sync somehow).

The file.php will serve files using slasharguments almost as now. We just need to replace the courseid with a fileid: file.php/fileid/dir/dir/file.jpg (where dir/dir/file.jpg is the virtual path in Moodle).

==Repository requirements==

From the Moodle point of view, each repository is just a hierarchy of nodes.

The repository MUST provide:
# A URL to download each node (eg file).
# A list of the nodes (eg files and directories) under a given node (eg directory). This allows Moodle to construct a standard browse interface (much like a standard OS file picker). However some repository plugins may choose to completely override the repository_browse() method and implement their own interface, that's OK, as long as they end up with a URL for the file.

The repository can OPTIONALLY:
# Require some authentication credentials
# Provide more metadata about each node (mime type, size, dates, related files, dublin core stuff, etc)
# Describe a search facility (so that Moodle can construct a search form)
# Provide copyright and usage rules (or just information about the rules)

==Repository plugins==

Some plugins I'd like to see developed for the first version are:
* local - very similar to the current course-based file manager, except user-based
* moodle - an interface to another Moodle site, accessed over a secure mnet connection
* jsr170 - an interface that can talk to anything that supports jsr170 (eg [http://www.alfresco.com/ Alfresco])
* oki - an OKI emulator allowing us to access things with OKI interfaces,like [http://www.fedora.info/ Fedora]
* briefcase - an interface to [http://briefcase.yahoo.com/ Yahoo Briefcase]
* myspace - an interface to MySpace files (perhaps via [http://www.programmableweb.com/api/myspace this MySpace API])
* googledocs - an interface to [http://docs.google.com Google Docs]
* skydrive - an interface to Microsoft's [http://skydrive.live.com/ SkyDrive] files
* facebook - an interface to Facebook files
* merlot - an interface to the learning materials in [http://www.merlot.org/merlot/materials.htm Merlot.org]
* flickr - an interface to [http://flickr.com flickr]
* youtube - an interface to [http://youtube.com YouTube]
* mahara - an interface to a Mahara installation

==Local Files==

In general, all external files will be copied locally and stored in Moodle. This section describes the storage of the files and how we define ACLs (access control lists) for them. All existing files in the Moodle dataroot course areas will be moved into this new system during the upgrade.

The files will not be stored as they have been in the past. The new file system is "flat" with each file stored as an id. The name and path are stored in tables. To avoid running out of nodes we'll use a hash-like structure like the users directory does, ie:

dataroot
/files
/0
/10000
/20000
/30000
/3076.jpg

==Tables==

=== repository ===

This table contains one entry for every configured external repository instance.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|repositoryname
|varchar
|
|A custom name for this reopsitory (non-unique)

|-
|'''repositorytype'''
|varchar
|
|The name of the plugin being used

|-
|'''userid'''
|int(10)
|
|The person who created this repository instance

|-
|'''contextid'''
|int(10)
|
|The context that this repository is available to ( = system context for site-wide ones)

|-
|username
|varchar
|
|username to log in with, if required

|-
|password
|varchar
|
|password to log in with, if required

|-
|option1
|varchar
|
|Other information useful to the plugin

|-
|option2
|varchar
|
|Other information useful to the plugin

|-
|option3
|varchar
|
|Other information useful to the plugin

|-
|option4
|varchar
|
|Other information useful to the plugin

|-
|option5
|varchar
|
|Other information useful to the plugin

|-
|timecreated
|int(10)
|
|The time this repository was created

|-
|timemodified
|int(10)
|
|The last time the repository was modified
|}

=== file ===

This table contains one entry for every file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''userid'''
|int(10)
|
|The owner of the file (person who created this entry)

|-
|filename
|varchar
|
|The full Unicode name of this file

|-
|'''repositoryid'''
|int(10)
|
|The repository instance this is associated with

|-
|updates
|int(10)
|
|Specifies the update schedule (0 = none, 1 = on demand, other = some period in seconds)

|-
|cachetime
|int(10)
|
|Specifies how long this file can be cached by browsers

|-
|moodlepath
|text
|
|The virtual path to the file locally (so we can still have apparent subdirectories etc)

|-
|repositorypath
|text
|
|The full path to the original file on the repository

|-
|timeimportfirst
|int(10)
|
|The first time this file was imported into Moodle

|-
|timeimportlast
|int(10)
|
|The most recent time that this file was imported into Moodle

|-
|timecreated
|int(10)
|
|The time this file was created (if known), otherwise same as time imported

|-
|timemodified
|int(10)
|
|The last time the file was modified

|-
|timeaccessed
|int(10)
|
|The last time this file was accessed for any reason
|}

=== file_instances ===

This table contains one entry for every "place" a file is published to. For example, one file might appear in an assignment but also in a forum attachment, so there would be two entries here.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''fileid'''
|int(10)
|
|The file we are defining access for

|-
|instancetype
|varchar
|
|This defines the table in Moodle that this instance is associated with (eg 'forum_posts', 'assignment_submissions' etc

|-
|'''instanceid'''
|int(10)
|
|The id in the foreign table (of name instancetype) that this instance is associated with
|}

=== file_access ===

This table describes the ACL for each file, so that checks can easily be made on whether someone can see this file or not. Note there can be multiple entries per file. Users can ALWAYS see their own files, so there are no entries here for that.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''fileid'''
|int(10)
|
|The file we are defining access for

|-
|'''contextid'''
|int(10)
|
|The context where this file is being published

|-
|'''capability'''
|text
|
|The capability that is required to see this file
|}

==Class methods==

===Repository class===

This class implements the interface to a particular repository, for browsing, selecting and updating files.

====get_file($path)====

====get_listing($parent='/', $search='''''''')====

====cron()====

====etc====

===File class===

This class implements the display and management of files from local storage, with full access checking. Some of the functions are for single files, while some are optimised for bulk display and searching (eg in the personal files interface).

====display_file()====

sort of like file.php is now, except smarter

====set_access($fileid, $accessstuff)====

Grant some access to people to a file

====has_access($fileid, $userid=NULL)====

Returns true or false depending on access to a file

==Areas in Moodle that need re-writing==

Activity modules

2007-12-20T06:34:15Z

Scyrma: /* See also */

'''Activity modules''' reside in the 'mod' directory. Each module is in a separate subdirectory and consists of the following mandatory elements (plus extra scripts unique to each module):

* ''mod.html'' - a form to set up or update an instance of this module
* ''version.php'' - defines some meta-info and provides upgrading code
* ''icon.gif'' - a 16x16 icon for the module
* ''db/'' - SQL dumps of all the required db tables and data (for each database type)
* ''index.php'' - a page to list all instances in a course
* ''view.php'' - a page to view a particular instance
* ''lib.php'' - any/all functions defined by the module should be in here. If the modulename is called widget, then the required functions include:
:* widget_install() - will be called during the installation of the module
:* widget_add_instance() - code to add a new instance of widget
:* widget_update_instance() - code to update an existing instance
:* widget_delete_instance() - code to delete an instance
:* widget_user_outline() - given an instance, return a summary of a user's contribution
:* widget_user_complete() - given an instance, print details of a user's contribution
:* Other functions available but not required are:
:** widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
:** widget_process_options() - code to pre-process the form data from module settings
:** [[Implementing Reset course functionality in a module|widget_reset_course_form() and widget_delete_userdata()]] - used to implement [[Reset course]] feature.
:* To avoid possible conflict, any module functions should be named starting with widget_ and any constants you define should start with WIDGET_
* ''config.html'' - (optional) a form to set up or update global settings of this module
* ''lang/en_utf8/resource_widget.php'' - (optional) Lastly, each module will have some language files that contain strings for that module.

IMPORTANT: When creating a new module, the new name of the module must not contain numbers or other special characters!

You should also make sure that your activity module provides appropriate support for groups and metacourses.

==See also==

* Tracker issue [http://tracker.moodle.org/browse/CONTRIB-52 CONTRIB-52 Improvements to make NEWMODULE really useful] - including download link for new module template supporting roles, formslib etc. (unfinished)
* http://download.moodle.org/plugins16/mod/NEWMODULE.zip - new module template for versions of Moodle prior to 1.7. Please follow the README instructions inside the zip.
* Using Moodle [http://moodle.org/course/view.php?id=5 Activity modules] forum
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=66165 A new resource type: where do I put the language strings?] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=65986 New Module Template Code for Moodle 1.7] forum discussion

[[Category:Modules]]
[[Category:Modules]]

[[es:Módulos de actividades (desarrollador)]]
[[fr:Modules (développeur)]]
[[ja:モジュール (開発者)]]

Releases

2007-12-12T05:04:52Z

Scyrma: /* Moodle 1.9 */

==Release History==

See [[Release_Notes|Release Notes]] for more details.

==Moodle 1.0==
*Moodle 1.0 - 20 August 2002
*Moodle 1.0.1 - 26 August 2002
*Moodle 1.0.2 - 2 September 2002
*Moodle 1.0.3 - 5 September 2002
*Moodle 1.0.4 - 10 September 2002
*Moodle 1.0.5 - 27 September 2002
*Moodle 1.0.6 - 26 October 2002
:: 1.0.6.1 - 6 Nov
:: 1.0.6.2 - 11 Nov
:: 1.0.6.3 - 14 Nov
:: 1.0.6.4 - 25 Nov
*Moodle 1.0.7 - 9 December 2002
*Moodle 1.0.8 - 7 January 2003
*Moodle 1.0.9 - 30 May 2003

==Moodle 1.1==
*Moodle 1.1 - 29 August 2003
*Moodle 1.1.1 - 11 September 2003

==Moodle 1.2==
*Moodle 1.2 - 20 March 2004
*Moodle 1.2.1 - 25 March 2004

==Moodle 1.3==
*Moodle 1.3 - 25 May 2004
*Moodle 1.3.1 - 4 June 2004
*Moodle 1.3.2 - 9 July 2004
*Moodle 1.3.3 - 16 July 2004
*Moodle 1.3.4 - 11 August 2004

==Moodle 1.4==
*Moodle 1.4 - 31 August 2004
*Moodle 1.4.1 - 12 September 2004
*Moodle 1.4.2 - 5 November 2004
*Moodle 1.4.3 - 21 December 2004
*Moodle 1.4.4 - 7 March 2005
*Moodle 1.4.5 - 7 May 2005

==Moodle 1.5==
*Moodle 1.5 - 5 June 2005
*Moodle 1.5.1 - 8 July 2005
*Moodle 1.5.2 - 16 July 2005
*Moodle 1.5.3 - 11 November 2005
*Moodle 1.5.4 - 21 May 2006

==Moodle 1.6==
*Moodle 1.6 - 20 June 2006
*Moodle 1.6.1 - 20 July 2006
*Moodle 1.6.2 - 12 September 2006
*Moodle 1.6.3 - 10 October 2006
*Moodle 1.6.4 - 17 January 2007
*Moodle 1.6.5 - 30 March 2007

==Moodle 1.7==
*Moodle 1.7 - 7 November 2006
*Moodle 1.7.1 - 17 January 2007
*Moodle 1.7.2 - 30 March 2007
*Moodle 1.7.3 - 11 October 2007

==Moodle 1.8==
*Moodle 1.8 - 30 March 2007
*Moodle 1.8.1 - 14 June 2007
*Moodle 1.8.2 - 8 July 2007
*Moodle 1.8.3 - 11 October 2007

==Moodle 1.9==
*Moodle 1.9 beta 2 - 11 October 2007
*Moodle 1.9 beta 3 - 6 December 2007

[[Category:Administrator]]
[[Category:Developer]]

[[fr:Historique des versions]]
[[es:Historia de las versiones]]