MoodleDocs - User contributions [en]

User:Valery Fremaux

2013-02-21T12:46:07Z

Vf:

Hi

I am now full time independant architect for Moodle Integrations in France.

I was originally graduated in Electronics Engineering but leaved quite a long time ago the Dark Side of the force...
I got a further master degree in Ethnomethodology related to Computer Sciences topics, and a master degree in Hypermedia and Sociologic Issues.

I was working as ICT teacher in EISTI where i developped my Applied Research Lab in Web technologies and Web app based architectures.

I now work on Moodle quite full time (even twice time) for 10 years, starting with a Moodle evaluation in 2003 for a European funded project.

==My Key topics==

===Technical architecture===
* Moodle MNET working in consistant Moodle arrays or constellations
* Distributes Moodle service architectures

===Top level usages===
* Hi level content editorialization in Moodle
* Course management, publishing cycle management

===Pedagogic Items===
* Cognitive engines
* Coordination and cooperation activities

==My major contribs==
* Techproject Module
* Customlabel Module
* Magtest Module
* Coursehop block

In total more than 50 contributions packaged in of plugin types...

Developer documentation

2010-01-04T21:44:59Z

Vf: /* Resources */

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.
* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].

'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches. 

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Sort key]]</nowiki></code> to provide a sort key other than the default page name.

==How Moodle development works==

The [[Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[PHPXref|PHPXref]].

===Core components that affect everything===

*[[Database schema introduction|The database schema]]
*[[What happens when you require config.php|What happens when you require config.php]]
*lib/moodlelib.php
*[[lib/weblib.php|lib/weblib.php]] for outputting stuff
*[[JavaScript_functions|JavaScript function available on the client side]]
*[[XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Groups|Groups system]]
*[[Grades|Gradebook]]
*[[Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[lib/graphlib|lib/graphlib]]
*[[Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Modules|Activity modules]], see also [[NEWMODULE Documentation]] (work in progress)
*[[Admin reports|Admin reports]]
*[[Assignment types|Assignment types]]
*[[Authentication plugins|Authentication plugins]]
*[[Blocks|Blocks]]
*[[Course formats]]
*[[Course Report Plugins|Course reports]]
*[[Database fields|Database fields]]
*[[Database presets|Database presets]]
*[[Enrolment plugins|Enrolment plugins]]
*[[Filters|Filters]]
*[[Gradebook plugins|Gradebook plugins]] (1.9 onwards)
**[[Gradebook_Report_Tutorial|Gradebook report]]
**[[Gradebook export|Gradebook export]]
**[[Gradebook import|Gradebook import]]
*[[Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Question_type_plugin_how_to|Question types]]
*[[Question import/export formats|Question import/export formats]]
*[[How to write a quiz report plugin|Quiz reports]]
*[[Repository plugins|Repository plugins]] (2.0 onwards)
*[[Resource types|Resource types]]
*[[Search engine adapters|Search engine adapters]]

General information that applies to all types of plugins
*[[Places to search for lang strings|Where to put language strings for your plugin]]
*[[Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled nightly from the comment attached to each class and function in the code.
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[vim|Setting up Vim for Moodle development]]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Firebug]].
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]

Developer documentation

2009-12-21T16:03:43Z

Vf: /* Resources */

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.
* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].

'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches. 

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Sort key]]</nowiki></code> to provide a sort key other than the default page name.

==How Moodle development works==

The [[Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[PHPXref|PHPXref]].

===Core components that affect everything===

*[[Database schema introduction|The database schema]]
*[[What happens when you require config.php|What happens when you require config.php]]
*lib/moodlelib.php
*[[lib/weblib.php|lib/weblib.php]] for outputting stuff
*[[JavaScript_functions|JavaScript function available on the client side]]
*[[XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Groups|Groups system]]
*[[Grades|Gradebook]]
*[[Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[lib/graphlib|lib/graphlib]]
*[[Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Modules|Activity modules]], see also [[NEWMODULE Documentation]] (work in progress)
*[[Admin reports|Admin reports]]
*[[Assignment types|Assignment types]]
*[[Authentication plugins|Authentication plugins]]
*[[Blocks|Blocks]]
*[[Course formats]]
*[[Course Report Plugins|Course reports]]
*[[Database fields|Database fields]]
*[[Database presets|Database presets]]
*[[Enrolment plugins|Enrolment plugins]]
*[[Filters|Filters]]
*[[Gradebook plugins|Gradebook plugins]] (1.9 onwards)
**[[Gradebook_Report_Tutorial|Gradebook report]]
**[[Gradebook export|Gradebook export]]
**[[Gradebook import|Gradebook import]]
*[[Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Question_type_plugin_how_to|Question types]]
*[[Question import/export formats|Question import/export formats]]
*[[How to write a quiz report plugin|Quiz reports]]
*[[Repository plugins|Repository plugins]] (2.0 onwards)
*[[Resource types|Resource types]]
*[[Search engine adapters|Search engine adapters]]

General information that applies to all types of plugins
*[[Places to search for lang strings|Where to put language strings for your plugin]]
*[[Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled nightly from the comment attached to each class and function in the code. '''Attention : Due to physical migration of the whole data center at EISTI (France), the phpdoc volumes WILL NOT BE available till the end of the year. We hope migration will allow us to feed back the community with the PHPDoc generated code documentation as soon as possible.'''
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[vim|Setting up Vim for Moodle development]]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Firebug]].
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]

Developer documentation

2009-10-12T10:33:37Z

Vf: /* Documentation for core components */

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.
* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].

'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches. 

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Sort key]]</nowiki></code> to provide a sort key other than the default page name.

==How Moodle development works==

The [[Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[PHPXref|PHPXref]].

===Core components that affect everything===

*[[Database schema introduction|The database schema]]
*[[What happens when you require config.php|What happens when you require config.php]]
*lib/moodlelib.php
*[[lib/weblib.php|lib/weblib.php]] for outputting stuff
*[[JavaScript_functions|JavaScript function available on the client side]]
*[[XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Groups|Groups system]]
*[[Grades|Gradebook]]
*[[Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[lib/graphlib|lib/graphlib]]
*[[Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Modules|Activity modules]], see also [[NEWMODULE Documentation]] (work in progress)
*[[Admin reports|Admin reports]]
*[[Assignment types|Assignment types]]
*[[Authentication plugins|Authentication plugins]]
*[[Blocks|Blocks]]
*[[Course formats]]
*[[Course Report Plugins|Course reports]]
*[[Database fields|Database fields]]
*[[Database presets|Database presets]]
*[[Enrolment plugins|Enrolment plugins]]
*[[Filters|Filters]]
*[[Gradebook plugins|Gradebook plugins]] (1.9 onwards)
**[[Gradebook_Report_Tutorial|Gradebook report]]
**[[Gradebook export|Gradebook export]]
**[[Gradebook import|Gradebook import]]
*[[Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Question_type_plugin_how_to|Question types]]
*[[Question import/export formats|Question import/export formats]]
*[[How to write a quiz report plugin|Quiz reports]]
*[[Repository plugins|Repository plugins]] (2.0 onwards)
*[[Resource types|Resource types]]
*[[Search engine adapters|Search engine adapters]]

General information that applies to all types of plugins
*[[Places to search for lang strings|Where to put language strings for your plugin]]
*[[Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled from the comment attached to each class and function in the code
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[vim|Setting up Vim for Moodle development]]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Firebug]].
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]

Developer documentation

2009-10-10T21:44:19Z

Vf: /* Documentation for core components */

This [[:Category:Developer|Developer]] section of Moodle Docs is aimed at developers who contribute to the Moodle code, plugins, themes, and so on.
* If you manage a Moodle site, [[Administrator documentation]] may suit your needs better.
* If you teach using Moodle, try [[Teacher documentation]].

'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches. 

A page may be added to the Developer category by adding the template <code><nowiki>{{CategoryDeveloper}}</nowiki></code> to the bottom of the page. - If required, you can use <code><nowiki>[[Category:Sort key]]</nowiki></code> to provide a sort key other than the default page name.

==How Moodle development works==

The [[Overview|overview of the Moodle development process]] explains how Moodle development occurs and how people become Moodle developers. Current plans are listed on the [[Roadmap]].

You can also enrol in one of the [http://dev.moodle.org Moodle Developer Courses].

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Fast portable SQL]] shows SQL techniques that are fast, efficient, and known to work on all supported DBs.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes|developer notes]] or on the [[Roadmap|roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code.

'''(For technical plant cooling desease reasons, the phpdoc servers might be unavailable or unstable for some days. Please appologize - Valery)'''

And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online] using [[PHPXref|PHPXref]].

===Core components that affect everything===

*[[Database schema introduction|The database schema]]
*[[What happens when you require config.php|What happens when you require config.php]]
*lib/moodlelib.php
*[[lib/weblib.php|lib/weblib.php]] for outputting stuff
*[[JavaScript_functions|JavaScript function available on the client side]]
*[[XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what
*[[lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things
*[[Using_the_file_API|File API]] @ v[[2.0]] for managing files stored by Moodle

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Groups|Groups system]]
*[[Grades|Gradebook]]
*[[Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[lib/graphlib|lib/graphlib]]
*[[Admin settings|Admin settings]]

===Modules included in the standard distribution===

*[[Lesson Specification|Lesson Specification]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Modules|Activity modules]], see also [[NEWMODULE Documentation]] (work in progress)
*[[Admin reports|Admin reports]]
*[[Assignment types|Assignment types]]
*[[Authentication plugins|Authentication plugins]]
*[[Blocks|Blocks]]
*[[Course formats]]
*[[Course Report Plugins|Course reports]]
*[[Database fields|Database fields]]
*[[Database presets|Database presets]]
*[[Enrolment plugins|Enrolment plugins]]
*[[Filters|Filters]]
*[[Gradebook plugins|Gradebook plugins]] (1.9 onwards)
**[[Gradebook_Report_Tutorial|Gradebook report]]
**[[Gradebook export|Gradebook export]]
**[[Gradebook import|Gradebook import]]
*[[Writing_a_Portfolio_Plugin|Portfolio plugins]] (2.0 onwards)
*[[Question_type_plugin_how_to|Question types]]
*[[Question import/export formats|Question import/export formats]]
*[[How to write a quiz report plugin|Quiz reports]]
*[[Repository plugins|Repository plugins]] (2.0 onwards)
*[[Resource types|Resource types]]
*[[Search engine adapters|Search engine adapters]]

General information that applies to all types of plugins
*[[Places to search for lang strings|Where to put language strings for your plugin]]
*[[Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

Please see the [[Guidelines for contributed code|Guidelines for contributed code]] for an overview of how to contribute to the Moodle code.

Sometimes it is not possible to write a proper plugin for what you want to do, in which case you may have to resort to using the [[Local_customisation|local customisations]] hook.

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first. See [[Overview#Major_Development]] for more details.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap|roadmap]] or in the form of [[Developer notes|developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer meetings]]

== Resources ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
**[[Firefox tracker search#Firefox Search Plugins|Firefox Search Plugins]] - Find tracked issues even more easily
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to [[HEAD]]
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled from the comment attached to each class and function in the code
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]

== Tools ==
Some tools people use when working on Moodle code:

=== IDEs ===

* [[Setting_up_Netbeans|Setting up NetBeans for Moodle development]] - NetBeans for PHP is a great out-of-the-box editor.
* [[Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
* [[vim|Setting up Vim for Moodle development]]

=== Browser add-ons ===
*[http://getfirebug.com Firebug], see [[Firebug]].
* [[Web developer extension]]
* [https://addons.mozilla.org/en-US/firefox/addon/394 ViewSourceWith] - The main goal is to view page source with external applications, but you can do a lot of other things as well.

=== Miscellaneous ===
*[[ctags|Ctags]] - Using a tags file to navigate code
*[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
*[[Windows Installer|Windows Installer]] - Windows Installer documentation for developer.

See also: [http://dev.moodle.org/mod/forum/view.php?id=18 Useful Development Tools forum]in the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming course]

==See also==

*[http://moodle.org/security/ Moodle Security Announcements]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[Category:Developer tools]]

[[ru:Development:Краткий обзор]]

Authentication plugins

2009-04-28T11:36:10Z

Vf: /* See also */

== Overview of Moodle authentication process ==
The authentication use case in Moodle starts when a user clicks on the Login link in the UI. Then the following happens (skipping some minor details and rarer scenarios):

# If using the default login page, the page /login/index.php is displayed, asking for the user's credentials. OR, if a system administrator has set the Alternate Login URL on the "Manage authentication" page, that URL will be displayed.
# User enters their credentials and submits the form.
# The handler code in /login/index.php runs:
## It gets a list of enabled authentication plugins.
## It runs loginpage_hook() for each plugin, in case any of them needs to intercept the login request.
## It checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## It calls authenticate_user_login() in /lib/moodlelib.php, which returns a $user object. (Details of this code follow this main outline.)
## It determines whether authentication was successful (by checking whether $user is a valid object) and, if not, sends them back to the login page with an error message. Otherwise, it figures out where to send the user based on their original page request, whether their password is expired, etc., and redirects them there.

That's the main outline, but a lot of interesting stuff happens in authenticate_user_login():

# It gets a list of enabled authentication plugins.
# It looks up the username in the mdl_user table to see if they are allowed to log in, and which authentication plugin handles their login requests. (This will be the plugin that handled their first-ever login request.)
# It creates a user object, which will contain the data from mdl_user if the username is known; if not, it will be an empty object.
# It does the following with the authentication plugin (note that for a username unknown to Moodle, it will do these steps for each authenticated plugin until one succeeds or it has tried them all):
## Calls the user_login() function provided by that plugin, which returns a boolean value based on whether the credentials authenticate or not. If the result is false (not authenticated), skips the rest of the steps below and continues to the next plugin.
## If the plugin authenticates against an external system (not Moodle's user database), its update_user_record() function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's sync_roles() function (I am not clear what this is exactly supposed to do).
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's user_authenticated_hook() function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

== Creating and enabling an authentication plugin ==
To create and register an authentication plugin, do the following:

# Choose a name for your plugin. We'll use 'sentry' as an example below; change it to whatever name you have chosen.
# Under your Moodle installation root, create the directory /auth/sentry. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file /auth/sentry/auth.php. Within the file, create a class auth_plugin_sentry that extends auth_plugin_base from /lib/authlib.php. (You will need to require_once the authlib file.)
# Implement the user_login() function in your auth.php file, and create or override additional functions based on your plugin's requirements.
# Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication". You will see your plugin in the list, appearing as <nowiki>[[auth_sentrytitle]]</nowiki>. You can enable it and move it up and down in the order. '''At this point, with the plugin enabled, your plugin is registered and will be used by Moodle in its authentication process.'''
# If you don't like seeing <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory /auth/sentry/lang, and under it, a directory for each language that your installation needs to support. (Example: /auth/sentry/lang/en_us_utf8.) Within each of these language directories, create a file called auth_sentry.php. That file should set the desired value for $string['auth_sentrytitle'] for that language. You can also set the plugin description by setting $string['auth_sentrydescription'], and you can also assign other translatable strings that your plugin uses, in these files.
# If you want to configure your plugin through the Moodle UI, implement config_form() and process_config() in the plugin class. You might find it convenient to use the 'db' plugin as a model for this. The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the mdl_config_pluginstable in the database.

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion

[[Category:Authentication]]

[[fr:Méthodes_d'authentification]]

Development:Developer FAQ

2008-05-12T07:39:50Z

Vf: /* How do I insert/retrieve records in the database, without creating my own database connections? */

{{FAQ}}

==Help for new coders==

===Where can "newbies" to Moodle get help?===

The [http://moodle.org/mod/forum/view.php?f=33 General developer forum]! Feel free to ask any question, no matter how basic or advanced. Many people ask different levels of question every day, and the community is generally welcoming and quick to respond.

==Moodle's database==

===Where can I see a schema for the structure of the Moodle database?===

When installing Moodle, the database tables are generated and updated by various db-handling scripts located in various places. There is no canonical schema representation, although the [[Coding#Database_structures | coding guidelines for database structure]] give an outline of the general approach.

The reason that the database information isn't stored in one place is because of Moodle's '''modular structure'''. Each activity module, for example, comes as a folder with script files inside. If the module needs to store information in the database, it must include scripts in a "db" subfolder which define and update the database structure.

==How to get/set information when writing new Moodle code==

===How do I find out the currently-logged-on user?===

The global object $USER, which contains the numeric $USER->id among other things.

===How do I find out the current course?===
The global object $COURSE, which contains the numeric $COURSE->id

===How do I insert/retrieve records in the database, without creating my own database connections?===

Always use the "datalib" functions, such as insert_record() or get_record(). Since Moodle 1.7 these are found in lib/dmllib.php. Using these functions helps with database abstraction (e.g. running on either MySQL or Postgres) as well as maintaining a single database connection. Moodle uses ADODB for database abstraction.

Look at [http://phpdocs.moodle.org/19/moodlecore/_lib---datalib.php.html the documentation for datalib.php] for the list of functions and details of use.

===How do I get/set configuration settings?===

To get config values you would typically access the global $CFG object directly, which is automatically created by the core Moodle scripts. To set these "main" config values use set_config($name, $value). The values are stored in the Moodle "config" database table, but these functions take care of cacheing on your behalf, so you should always use these rather than fetching the records directly.

There is also a second table of config settings specifically for plugins ("config_plugin"). These are not automatically loaded into the $CFG object, so to fetch these you would use get_config($plugin, $name). To set them use set_config($name, $value, $plugin).

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=55719 How does date / time in DB convert to real Date / Time?] forum discussion

[[Category: Developer]]
[[Category: FAQ]]

[[es:FAQ Desarrollador]]
[[fr:FAQ de développement]]
[[pl:Developer FAQ]]

Developer FAQ

2008-05-12T07:39:50Z

Vf: /* How do I insert/retrieve records in the database, without creating my own database connections? */

Development:Developer FAQ

2008-05-12T07:39:17Z

Vf: /* How do I insert/retrieve records in the database, without creating my own database connections? */

{{FAQ}}

==Help for new coders==

===Where can "newbies" to Moodle get help?===

The [http://moodle.org/mod/forum/view.php?f=33 General developer forum]! Feel free to ask any question, no matter how basic or advanced. Many people ask different levels of question every day, and the community is generally welcoming and quick to respond.

==Moodle's database==

===Where can I see a schema for the structure of the Moodle database?===

When installing Moodle, the database tables are generated and updated by various db-handling scripts located in various places. There is no canonical schema representation, although the [[Coding#Database_structures | coding guidelines for database structure]] give an outline of the general approach.

The reason that the database information isn't stored in one place is because of Moodle's '''modular structure'''. Each activity module, for example, comes as a folder with script files inside. If the module needs to store information in the database, it must include scripts in a "db" subfolder which define and update the database structure.

==How to get/set information when writing new Moodle code==

===How do I find out the currently-logged-on user?===

The global object $USER, which contains the numeric $USER->id among other things.

===How do I find out the current course?===
The global object $COURSE, which contains the numeric $COURSE->id

===How do I insert/retrieve records in the database, without creating my own database connections?===

Always use the "datalib" functions, such as insert_record() or get_record(). Since Moodle 1.7 these are found in lib/dmllib.php. Using these functions helps with database abstraction (e.g. running on either MySQL or Postgres) as well as maintaining a single database connection. Moodle uses ADODB for database abstraction.

Look at [http://phpdocs.moodle.org/19/moodlecore/_lib---datalib.php.html the documentation for datalib.php - Broken Link] for the list of functions and details of use.

===How do I get/set configuration settings?===

To get config values you would typically access the global $CFG object directly, which is automatically created by the core Moodle scripts. To set these "main" config values use set_config($name, $value). The values are stored in the Moodle "config" database table, but these functions take care of cacheing on your behalf, so you should always use these rather than fetching the records directly.

There is also a second table of config settings specifically for plugins ("config_plugin"). These are not automatically loaded into the $CFG object, so to fetch these you would use get_config($plugin, $name). To set them use set_config($name, $value, $plugin).

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=55719 How does date / time in DB convert to real Date / Time?] forum discussion

[[Category: Developer]]
[[Category: FAQ]]

[[es:FAQ Desarrollador]]
[[fr:FAQ de développement]]
[[pl:Developer FAQ]]

Developer FAQ

2008-05-12T07:39:17Z

Vf: /* How do I insert/retrieve records in the database, without creating my own database connections? */

{{FAQ}}

==Help for new coders==

===Where can "newbies" to Moodle get help?===

The [http://moodle.org/mod/forum/view.php?f=33 General developer forum]! Feel free to ask any question, no matter how basic or advanced. Many people ask different levels of question every day, and the community is generally welcoming and quick to respond.

==Moodle's database==

===Where can I see a schema for the structure of the Moodle database?===

When installing Moodle, the database tables are generated and updated by various db-handling scripts located in various places. There is no canonical schema representation, although the [[Coding#Database_structures | coding guidelines for database structure]] give an outline of the general approach.

The reason that the database information isn't stored in one place is because of Moodle's '''modular structure'''. Each activity module, for example, comes as a folder with script files inside. If the module needs to store information in the database, it must include scripts in a "db" subfolder which define and update the database structure.

==How to get/set information when writing new Moodle code==

===How do I find out the currently-logged-on user?===

The global object $USER, which contains the numeric $USER->id among other things.

===How do I find out the current course?===
The global object $COURSE, which contains the numeric $COURSE->id

===How do I insert/retrieve records in the database, without creating my own database connections?===

Always use the "datalib" functions, such as insert_record() or get_record(). Since Moodle 1.7 these are found in lib/dmllib.php. Using these functions helps with database abstraction (e.g. running on either MySQL or Postgres) as well as maintaining a single database connection. Moodle uses ADODB for database abstraction.

Look at [http://phpdocs.moodle.org/19/moodlecore/_lib---datalib.php.html the documentation for datalib.php - Broken Link] for the list of functions and details of use.

===How do I get/set configuration settings?===

To get config values you would typically access the global $CFG object directly, which is automatically created by the core Moodle scripts. To set these "main" config values use set_config($name, $value). The values are stored in the Moodle "config" database table, but these functions take care of cacheing on your behalf, so you should always use these rather than fetching the records directly.

There is also a second table of config settings specifically for plugins ("config_plugin"). These are not automatically loaded into the $CFG object, so to fetch these you would use get_config($plugin, $name). To set them use set_config($name, $value, $plugin).

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=55719 How does date / time in DB convert to real Date / Time?] forum discussion

[[Category: Developer]]
[[Category: FAQ]]

[[es:FAQ Desarrollador]]
[[fr:FAQ de développement]]
[[pl:Developer FAQ]]

User:Valery Fremaux

2008-02-06T15:48:31Z

Vf:

Valery Fremaux is Computer Sciences and IT teacher at the EISTI, french graduate school of computer sciences.

He has a master degree in Ethnomethodology related to Computer Sciences topics, and a master degree in Hypermedia and Sociologic Issues.

He is working on IT architectures for 12 years, has developped some complete technologies such as the DIML templating language and is Perl and Php expert.

User:Valery Fremaux

2008-02-06T15:47:52Z

Vf:

Valery Fremaux is Computer Sciences and IT teacher at the EISTI, french graduate school of computer sciences.

He has a master degree in Ethnomethodology related to Computer Sciences topics, and a master degree in Hypermedia and Sociologic Issues.

He is working on IT architectures for 12 years, and has developped some complete technologies such as the DIML templating language.

User:Valery Fremaux

2008-02-06T15:44:17Z

Vf:

Valery Fremaux is Computer Sciences and IT teacher at the EISTI, french graduate school of computer sciences.

He has a master degree in Ethnomethodology related to Computer Sciences topics, and a master degree of Hypermedia.

He is working on IT architectures for 12 years, and has developped some complete technologies such as the DIML templating language.

Search engine adapters

2007-11-29T22:48:03Z

Vf:

The Global Search Engine of Moodle, available as experimental feature till the Moodle 1.9 release, allows plugin new document types for being searched and indexed by the Lucene indexer.

Each module or block should have an adapter written to wrap the plugin's internal data model to a searchable document. The actual implementation allows a module to provide the search engine with a set of virtual documents. The search engine will index the text content of these documents, recording sufficiant data to access back the exact context in which it was appearing (i.e, access URL, course context, etc.).

Virtual documents are defined as subclasses of the SearchDocument class. Only the constructor of the subclass must be written in order to map an input record to an internal document definition.

The goals of the adapter are :

* extract all virtual documents from the module data model and give them to the indexer (index first construction) through an ''iterator''.
* extract a single document for index update
* provide sufficiant information for index delete of obsolete content
* define the access URL that will access back the resource
* define the access check algorithm so that the user will only access resources he is allowed to

== Adapters For Modules And Blocks ==

Any adapter for a module or a block must reside in the <pre>/search/documents</pre> subdirectory, and will be named such as <pre><module>_document.php</pre>

=== Search defines ===

Each searchable module should add at least both (typical) following defines in /search/lib.php :

<pre>
define('SEARCH_TYPE_<MODULE>', '<module>');
define('PATH_FOR_SEARCH_TYPE_<MODULE>', 'mod/<module>');
</pre>

or

<pre>
define('SEARCH_TYPE_<BLOCK>', '<block>');
define('PATH_FOR_SEARCH_TYPE_<BLOCK>', 'blocks/<block>');
</pre>

=== Constructor ===

The constructor of the SearchDocument class has the following signature :

<pre>
public function __construct(&$doc, &$data, $course_id, $group_id, $user_id, $path)
</pre>

where :
* '''&$doc''' is a reference onto a PHP object that should provide the fields :
** docid : the id of the document, as suitable for reconstructing the access URL.
** documenttype : in general, the name of the module itself
** itemtype : a subclassifier, if the module provides more than one virtual document to the search engine.
** contextid : the context object id that should be considered when checking accessor's capabilities
** title : the title string to appear in search results as a caption
** author : if the author is known, the user id (mdl_user.id) representing the author.
** contents : a text bulk from the document content, filtered out from any formatting attributes or tags
** url : the document url, that will be constructed by the adapter to access back the resource
** date : usually the date when the resource was created
* '''&$data''' is a reference onto a contextual metadata object that will be serialized among with the record, but will not be used as searchable content
* '''$course_id''' is the current course the ressource is within
* '''$group_id''' is the current group the resource belongs to, if the ressource is in a group scope (i.e. separate group wiki attachements), 0 elsewhere.
* '''$user_id''' is the id of the user the resource beslongs to, in case the ressource is in a user specific scope (i.e. post or assignment attachements), 0 elsewhere.
* '''$path''' is one of the above PATH defines for the module.

== Providing The indexer Documents From The Module ==

When first constructing the index, The Indexer needs scanning all the instances of the plugin.

The adapter API must provide the

<pre>
<module>_iterator(){ ... }
</pre>

function that will give a set of consistant plugin instances. Here is a ''very standard'' template code for this method :

<pre>
function <module>_iterator() {
$<module> = get_records('<module>');
return $<module>;
} //<module>_iterator
</pre>

On each instance, the function :

<pre>
function <module>_get_content_for_index(&$plugininstance) { ... }
</pre>

is called for constructing relevant instances of the SearchDocument subclass. This function MUST return an array of SearchDocuments or false. The typical synopsis of this function is :

<pre>
function <module>_get_content_for_index(&$plugininstance){
$documents = array();

// invalid plugin
if (!$plugininstance) return $documents;

// TODO : get an indexable item set

foreach($indexableitems as $indexableitem) {

// TODO : Prepare params with

$documents[] = new ForumSearchDocument(... params ...);
}
return $documents;
}
</pre>

=== Making The Backaccess Link ===

The constructor of the SearchDocument subclass must construct a backaccess link for the document, and give it as the 'url' attribute of the first constructor parameter (&$doc). this is usually done using a callback to the document API. the synopsys is :

<pre>
function <module>_make_link(...contextual params...) {
global $CFG;

return $CFG->wwwroot.<moodle path expression that drives back to the content>;
} //<module>_make_link
</pre>

Contextual params are usually ids of course module, or internal entities depending on the module construction, modal values...

== Updating The index Database ==

The search engine, once fed with its first indexing results from scratch, will be regularily updating by a cron job. The index is updated in diff mode, so only modified entries in the Moodle data model should be considered.

The update process will :
* add new items, as far as they are handled by the search engine
* update modified items
* drop indexes on deleted resources and contents

An API callback tells each of these three actions where the items to consider are in the Moodle database. This callback SHOULD return an array of arrays of strings, each containing the following fieldset :
* primary id fieldname,
* table name,
* time created field name,
* time modified field name,
* itemtype,
* [additional SELECT clause for filtering rows] // optional

Here comes a synopsys for such code. There should be as many arrays as known document subtypes in the module.

<pre>
function <module>_db_names() {
return array(
array('id', '<module>_<entity>', 'created', 'modified', '<itemtype>', '')
);
} //<module>_db_names
</pre>

Note : 'created' and 'modified' have several expression among the variety of modules/blocks. Sometimes, both of these informations are not available. Consider using the dates of a parent dependency in case they are missing.

Knowing where the items to update/add/delete are, both first operation will use a "Single Document Wrapper" to process to the update/add operation individually. This is the purpose of the

<pre>
function <module>_single_document($id, $itemtype) { ... }
</pre>

function. Here comes a rough prototype for such a callback :

<pre>
function <module>_single_document($id, $itemtype) {

switch($itemtype){
case <type1>:
... get content holding record ...
... get module_obj from previous ...
break;
case <type2>:
... get content holding record ...
... get module_obj from previous ...
break;
... and so on ...
}

$coursemodule = get_field('modules', 'id', 'name', '<module>');
$cm = get_record('course_modules', 'course', $<module_obj>->course,
'module', $coursemodule, 'instance', $<module_obj>->id);
if ($cm){
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
... preparing some data eventually ...
return new <ModuleItem>SearchDocument(get_object_vars($<content_obj>),
$<module_obj>->id, $<module_obj>->course, $itemtype, $context->id);
}
return null;
} // <module>_single_document
</pre>

Note : we need use get_object_vars() as historical implementation uses a hash in constructors rather than an object.

For deletion, you will have to reproduce a callback which remains from an old unexplained implementation :

<pre>
function <module>_delete($info, $itemtype) {
$object->id = $info;
$object->itemtype = $itemtype;
return $object;
} // <module>_delete
</pre>

Just rewrite it AS IS, nothing to think about here.

== Checking Access Back To The Content ==

When searching, the Zend Lucene engine dig into its own word index organization, and then retrieves a set of matching "Documents". You will want now to filter out those documents that the user who activated the search engine DO NOT have permission to see.

The search results function calls back an access checker for each results, depending on the known document type. This is the :

<pre>
function <module>_check_text_access($path, $itemtype, $this_id, $user, $group_id, $context_id){ ... }
</pre>

function, that will have to implement the access policy, depending on the plugin's contextual logic. The function traps any access revocation condition (and than will return false). In cas no trap was triggered, it will return true. The admin role bypasses this check call and will access all documents.

Here comes a standard synopsys for that implementation :

<pre>
function <module>_check_text_access($path, $itemtype, $this_id, $user, $group_id, $context_id){
global $CFG, $USER;

// may include some plugins libs
include_once("{$CFG->dirroot}/{$path}/lib.php");

... get the course module and content record ...

// this part is very standard for modules, reconsider it for blocks
// or other stuff
$context = get_record('context', 'id', $context_id);
$cm = get_record('course_modules', 'id', $context->instanceid);
if (!$cm->visible and !has_capability('moodle/course:viewhiddenactivities', $context)){
// nice for debugging undued visibility or non visibility
if (!empty($CFG->search_access_debug))
echo "search reject : <reject cause> ";
return false;
}

// user check : entries should not be owner private or we are that user

// group check : entries should be in accessible groups

// date checks : we are in an open window

return true;
} //<module>_check_text_access
</pre>

'''Note : Debugging access policy'''

Use the above construction for any ''false'' you will return :

<pre>
if (!empty($CFG->search_access_debug)){
echo "search reject : <reject cause> ";
return false;

</pre>

For debugging, add a simple key in {$CFG->prefix}_config table :

<pre>
INSERT INTO {$CFG->prefix}_config VALUES ('search_access_debug', 1);
</pre>

Delete it for normal operations :

<pre>
DELETE FROM {$CFG->prefix}_config WHERE name = 'search_access_debug';
</pre>

== Physical Document Adapters ==

Search engine adapters

2007-11-18T14:46:43Z

Vf: /* Checking Access Back To The Content */

The global search engine of Moodle, available as experimental feature till the Moodle 1.9 release, allows plugin new document types for being searched and indexed by the Lucene indexer.

Each module or block should have an adapter written to wrap the plugin's internal data model to a searchable document. The actual implementation allows a module to provide the search engine with a set of virtual documents. The search engine will index the text content of these documents, recording sufficiant data to access back the exact context in which it was appearing (i.e, access URL, course context, etc.).

Virtual documents are defined as subclasses of the SearchDocument class. Only the constructor of the subclass must be written in order to map an input record to an internal document definition.

The goals of the adapter are :

* extract all virtual documents from the module data model and give them to the indexer (index first construction) through an ''iterator''.
* extract a single document for index update
* provide sufficiant information for index delete of obsolete content
* define the access URL that will access back the resource
* define the access check algorithm so that the user will only access resources he is allowed to

== Adapters For Modules And Blocks ==

Any adapter for a module or a block must reside in the <pre>/search/documents</pre> subdirectory, and will be named such as <pre><module>_document.php</pre>

=== Search defines ===

Each searchable module should add at least both (typical) following defines in /search/lib.php :

<pre>
define('SEARCH_TYPE_<MODULE>', '<module>');
define('PATH_FOR_SEARCH_TYPE_<MODULE>', 'mod/<module>');
</pre>

or

<pre>
define('SEARCH_TYPE_<BLOCK>', '<block>');
define('PATH_FOR_SEARCH_TYPE_<BLOCK>', 'blocks/<block>');
</pre>

=== Constructor ===

The constructor of the SearchDocument class has the following signature :

<pre>
public function __construct(&$doc, &$data, $course_id, $group_id, $user_id, $path)
</pre>

where :
* '''&$doc''' is a reference onto a PHP object that should provide the fields :
** docid : the id of the document, as suitable for reconstructing the access URL.
** documenttype : in general, the name of the module itself
** itemtype : a subclassifier, if the module provides more than one virtual document to the search engine.
** contextid : the context object id that should be considered when checking accessor's capabilities
** title : the title string to appear in search results as a caption
** author : if the author is known, the user id (mdl_user.id) representing the author.
** contents : a text bulk from the document content, filtered out from any formatting attributes or tags
** url : the document url, that will be constructed by the adapter to access back the resource
** date : usually the date when the resource was created
* '''&$data''' is a reference onto a contextual metadata object that will be serialized among with the record, but will not be used as searchable content
* '''$course_id''' is the current course the ressource is within
* '''$group_id''' is the current group the resource belongs to, if the ressource is in a group scope (i.e. separate group wiki attachements), 0 elsewhere.
* '''$user_id''' is the id of the user the resource beslongs to, in case the ressource is in a user specific scope (i.e. post or assignment attachements), 0 elsewhere.
* '''$path''' is one of the above PATH defines for the module.

== Providing The indexer Documents From The Module ==

When first constructing the index, The Indexer needs scanning all the instances of the plugin.

The adapter API must provide the

<pre>
<module>_iterator(){ ... }
</pre>

function that will give a set of consistant plugin instances. Here is a ''very standard'' template code for this method :

<pre>
function <module>_iterator() {
$<module> = get_records('<module>');
return $<module>;
} //<module>_iterator
</pre>

On each instance, the function :

<pre>
function <module>_get_content_for_index(&$plugininstance) { ... }
</pre>

is called for constructing relevant instances of the SearchDocument subclass. This function MUST return an array of SearchDocuments or false. The typical synopsis of this function is :

<pre>
function <module>_get_content_for_index(&$plugininstance){
$documents = array();

// invalid plugin
if (!$plugininstance) return $documents;

// TODO : get an indexable item set

foreach($indexableitems as $indexableitem) {

// TODO : Prepare params with

$documents[] = new ForumSearchDocument(... params ...);
}
return $documents;
}
</pre>

=== Making The Backaccess Link ===

The constructor of the SearchDocument subclass must construct a backaccess link for the document, and give it as the 'url' attribute of the first constructor parameter (&$doc). this is usually done using a callback to the document API. the synopsys is :

<pre>
function <module>_make_link(...contextual params...) {
global $CFG;

return $CFG->wwwroot.<moodle path expression that drives back to the content>;
} //<module>_make_link
</pre>

Contextual params are usually ids of course module, or internal entities depending on the module construction, modal values...

== Updating The index Database ==

The search engine, once fed with its first indexing results from scratch, will be regularily updating by a cron job. The index is updated in diff mode, so only modified entries in the Moodle data model should be considered.

The update process will :
* add new items, as far as they are handled by the search engine
* update modified items
* drop indexes on deleted resources and contents

An API callback tells each of these three actions where the items to consider are in the Moodle database. This callback SHOULD return an array of arrays of strings, each containing the following fieldset :
* primary id fieldname,
* table name,
* time created field name,
* time modified field name,
* itemtype,
* [additional SELECT clause for filtering rows] // optional

Here comes a synopsys for such code. There should be as many arrays as known document subtypes in the module.

<pre>
function <module>_db_names() {
return array(
array('id', '<module>_<entity>', 'created', 'modified', '<itemtype>', '')
);
} //<module>_db_names
</pre>

Note : 'created' and 'modified' have several expression among the variety of modules/blocks. Sometimes, both of these informations are not available. Consider using the dates of a parent dependency in case they are missing.

Knowing where the items to update/add/delete are, both first operation will use a "Single Document Wrapper" to process to the update/add operation individually. This is the purpose of the

<pre>
function <module>_single_document($id, $itemtype) { ... }
</pre>

function. Here comes a rough prototype for such a callback :

<pre>
function <module>_single_document($id, $itemtype) {

switch($itemtype){
case <type1>:
... get content holding record ...
... get module_obj from previous ...
break;
case <type2>:
... get content holding record ...
... get module_obj from previous ...
break;
... and so on ...
}

$coursemodule = get_field('modules', 'id', 'name', '<module>');
$cm = get_record('course_modules', 'course', $<module_obj>->course,
'module', $coursemodule, 'instance', $<module_obj>->id);
if ($cm){
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
... preparing some data eventually ...
return new <ModuleItem>SearchDocument(get_object_vars($<content_obj>),
$<module_obj>->id, $<module_obj>->course, $itemtype, $context->id);
}
return null;
} // <module>_single_document
</pre>

Note : we need use get_object_vars() as historical implementation uses a hash in constructors rather than an object.

For deletion, you will have to reproduce a callback which remains from an old unexplained implementation :

<pre>
function <module>_delete($info, $itemtype) {
$object->id = $info;
$object->itemtype = $itemtype;
return $object;
} // <module>_delete
</pre>

Just rewrite it AS IS, nothing to think about here.

== Checking Access Back To The Content ==

When searching, the Zend Lucene engine dig into its own word index organization, and then retrieves a set of matching "Documents". You will want now to filter out those documents that the user who activated the search engine DO NOT have permission to see.

The search results function calls back an access checker for each results, depending on the known document type. This is the :

<pre>
function <module>_check_text_access($path, $itemtype, $this_id, $user, $group_id, $context_id){ ... }
</pre>

function, that will have to implement the access policy, depending on the plugin's contextual logic. The function traps any access revocation condition (and than will return false). In cas no trap was triggered, it will return true. The admin role bypasses this check call and will access all documents.

Here comes a standard synopsys for that implementation :

<pre>
function <module>_check_text_access($path, $itemtype, $this_id, $user, $group_id, $context_id){
global $CFG, $USER;

// may include some plugins libs
include_once("{$CFG->dirroot}/{$path}/lib.php");

... get the course module and content record ...

// this part is very standard for modules, reconsider it for blocks
// or other stuff
$context = get_record('context', 'id', $context_id);
$cm = get_record('course_modules', 'id', $context->instanceid);
if (!$cm->visible and !has_capability('moodle/course:viewhiddenactivities', $context)){
// nice for debugging undued visibility or non visibility
if (!empty($CFG->search_access_debug))
echo "search reject : <reject cause> ";
return false;
}

// user check : entries should not be owner private or we are that user

// group check : entries should be in accessible groups

// date checks : we are in an open window

return true;
} //<module>_check_text_access
</pre>

'''Note : Debugging access policy'''

Use the above construction for any ''false'' you will return :

<pre>
if (!empty($CFG->search_access_debug)){
echo "search reject : <reject cause> ";
return false;

</pre>

For debugging, add a simple key in {$CFG->prefix}_config table :

<pre>
INSERT INTO {$CFG->prefix}_config VALUES ('search_access_debug', 1);
</pre>

Delete it for normal operations :

<pre>
DELETE FROM {$CFG->prefix}_config WHERE name = 'search_access_debug';
</pre>

== Physical Document Adapters ==

Search engine adapters

2007-11-18T14:30:21Z

Vf: /* Updating The index Database */

Search engine adapters

2007-11-18T14:27:14Z

Vf: /* Updating The index Database */

The global search engine of Moodle, available as experimental feature till the Moodle 1.9 release, allows plugin new document types for being searched and indexed by the Lucene indexer.

Each module or block should have an adapter written to wrap the plugin's internal data model to a searchable document. The actual implementation allows a module to provide the search engine with a set of virtual documents. The search engine will index the text content of these documents, recording sufficiant data to access back the exact context in which it was appearing (i.e, access URL, course context, etc.).

Virtual documents are defined as subclasses of the SearchDocument class. Only the constructor of the subclass must be written in order to map an input record to an internal document definition.

The goals of the adapter are :

* extract all virtual documents from the module data model and give them to the indexer (index first construction) through an ''iterator''.
* extract a single document for index update
* provide sufficiant information for index delete of obsolete content
* define the access URL that will access back the resource
* define the access check algorithm so that the user will only access resources he is allowed to

== Adapters For Modules And Blocks ==

Any adapter for a module or a block must reside in the <pre>/search/documents</pre> subdirectory, and will be named such as <pre><module>_document.php</pre>

=== Search defines ===

Each searchable module should add at least both (typical) following defines in /search/lib.php :

<pre>
define('SEARCH_TYPE_<MODULE>', '<module>');
define('PATH_FOR_SEARCH_TYPE_<MODULE>', 'mod/<module>');
</pre>

or

<pre>
define('SEARCH_TYPE_<BLOCK>', '<block>');
define('PATH_FOR_SEARCH_TYPE_<BLOCK>', 'blocks/<block>');
</pre>

=== Constructor ===

The constructor of the SearchDocument class has the following signature :

<pre>
public function __construct(&$doc, &$data, $course_id, $group_id, $user_id, $path)
</pre>

where :
* '''&$doc''' is a reference onto a PHP object that should provide the fields :
** docid : the id of the document, as suitable for reconstructing the access URL.
** documenttype : in general, the name of the module itself
** itemtype : a subclassifier, if the module provides more than one virtual document to the search engine.
** contextid : the context object id that should be considered when checking accessor's capabilities
** title : the title string to appear in search results as a caption
** author : if the author is known, the user id (mdl_user.id) representing the author.
** contents : a text bulk from the document content, filtered out from any formatting attributes or tags
** url : the document url, that will be constructed by the adapter to access back the resource
** date : usually the date when the resource was created
* '''&$data''' is a reference onto a contextual metadata object that will be serialized among with the record, but will not be used as searchable content
* '''$course_id''' is the current course the ressource is within
* '''$group_id''' is the current group the resource belongs to, if the ressource is in a group scope (i.e. separate group wiki attachements), 0 elsewhere.
* '''$user_id''' is the id of the user the resource beslongs to, in case the ressource is in a user specific scope (i.e. post or assignment attachements), 0 elsewhere.
* '''$path''' is one of the above PATH defines for the module.

== Providing The indexer Documents From The Module ==

When first constructing the index, The Indexer needs scanning all the instances of the plugin.

The adapter API must provide the

<pre>
<module>_iterator(){ ... }
</pre>

function that will give a set of consistant plugin instances. Here is a ''very standard'' template code for this method :

<pre>
function <module>_iterator() {
$<module> = get_records('<module>');
return $<module>;
} //<module>_iterator
</pre>

On each instance, the function :

<pre>
function <module>_get_content_for_index(&$plugininstance) { ... }
</pre>

is called for constructing relevant instances of the SearchDocument subclass. This function MUST return an array of SearchDocuments or false. The typical synopsis of this function is :

<pre>
function <module>_get_content_for_index(&$plugininstance){
$documents = array();

// invalid plugin
if (!$plugininstance) return $documents;

// TODO : get an indexable item set

foreach($indexableitems as $indexableitem) {

// TODO : Prepare params with

$documents[] = new ForumSearchDocument(... params ...);
}
return $documents;
}
</pre>

=== Making The Backaccess Link ===

The constructor of the SearchDocument subclass must construct a backaccess link for the document, and give it as the 'url' attribute of the first constructor parameter (&$doc). this is usually done using a callback to the document API. the synopsys is :

<pre>
function <module>_make_link(...contextual params...) {
global $CFG;

return $CFG->wwwroot.<moodle path expression that drives back to the content>;
} //<module>_make_link
</pre>

Contextual params are usually ids of course module, or internal entities depending on the module construction, modal values...

== Updating The index Database ==

The search engine, once fed with its first indexing results from scratch, will be regularily updating by a cron job. The index is updated in diff mode, so only modified entries in the Moodle data model should be considered.

The update process will :
* add new items, as far as they are handled by the search engine
* update modified items
* drop indexes on deleted resources and contents

An API callback tells each of these three actions where the items to consider are in the Moodle database. This callback SHOULD return an array of arrays of strings, each containing the following fieldset :
* primary id fieldname,
* table name,
* time created field name,
* time modified field name,
* itemtype,
* [additional SELECT clause for filtering rows] // optional

Here comes a synopsys for such code. There should be as many arrays as known document subtypes in the module.

<pre>
function <module>_db_names() {
return array(
array('id', '<module>_<entity>', 'created', 'modified', '<itemtype>', '')
);
} //<module>_db_names
</pre>

Note : 'created' and 'modified' have several expression among the variety of modules/blocks. Sometimes, both of these informations are not available. Consider using the dates of a parent dependency in case they are missing.

Knowing where the items to update/add/delete are, both first operation will use a "Single Document Wrapper" to process to the update/add operation individually. This is the purpose of the

<pre>
function <module>_single_document($id, $itemtype) { ... }
</pre>

function. Here comes a rough prototype for such a callback :

<pre>
function <module>_single_document($id, $itemtype) {

switch($itemtype){
case <type1>:
... get content holding record ...
... get module_obj from previous ...
break;
case <type2>:
... get content holding record ...
... get module_obj from previous ...
break;
... and so on ...
}

$coursemodule = get_field('modules', 'id', 'name', '<module>');
$cm = get_record('course_modules', 'course', $<module_obj>->course, 'module', $coursemodule, 'instance', $<module_obj>->id);
if ($cm){
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
... preparing some data eventually ...
return new <ModuleItem>SearchDocument(get_object_vars($<content_obj>), $<module_obj>->id, $<module_obj>->course, $itemtype, $context->id);
}
return null;
} // <module>_single_document
</pre>

Note : we need use get_object_vars() as historical implementation uses a hash in constructors rather than an object.

== Checking Access Back To The Content ==

== Physical Document Adapters ==

Search engine adapters

2007-11-18T14:26:38Z

Vf: /* Making The Backaccess Link */

The global search engine of Moodle, available as experimental feature till the Moodle 1.9 release, allows plugin new document types for being searched and indexed by the Lucene indexer.

Each module or block should have an adapter written to wrap the plugin's internal data model to a searchable document. The actual implementation allows a module to provide the search engine with a set of virtual documents. The search engine will index the text content of these documents, recording sufficiant data to access back the exact context in which it was appearing (i.e, access URL, course context, etc.).

Virtual documents are defined as subclasses of the SearchDocument class. Only the constructor of the subclass must be written in order to map an input record to an internal document definition.

The goals of the adapter are :

* extract all virtual documents from the module data model and give them to the indexer (index first construction) through an ''iterator''.
* extract a single document for index update
* provide sufficiant information for index delete of obsolete content
* define the access URL that will access back the resource
* define the access check algorithm so that the user will only access resources he is allowed to

== Adapters For Modules And Blocks ==

Any adapter for a module or a block must reside in the <pre>/search/documents</pre> subdirectory, and will be named such as <pre><module>_document.php</pre>

=== Search defines ===

Each searchable module should add at least both (typical) following defines in /search/lib.php :

<pre>
define('SEARCH_TYPE_<MODULE>', '<module>');
define('PATH_FOR_SEARCH_TYPE_<MODULE>', 'mod/<module>');
</pre>

or

<pre>
define('SEARCH_TYPE_<BLOCK>', '<block>');
define('PATH_FOR_SEARCH_TYPE_<BLOCK>', 'blocks/<block>');
</pre>

=== Constructor ===

The constructor of the SearchDocument class has the following signature :

<pre>
public function __construct(&$doc, &$data, $course_id, $group_id, $user_id, $path)
</pre>

where :
* '''&$doc''' is a reference onto a PHP object that should provide the fields :
** docid : the id of the document, as suitable for reconstructing the access URL.
** documenttype : in general, the name of the module itself
** itemtype : a subclassifier, if the module provides more than one virtual document to the search engine.
** contextid : the context object id that should be considered when checking accessor's capabilities
** title : the title string to appear in search results as a caption
** author : if the author is known, the user id (mdl_user.id) representing the author.
** contents : a text bulk from the document content, filtered out from any formatting attributes or tags
** url : the document url, that will be constructed by the adapter to access back the resource
** date : usually the date when the resource was created
* '''&$data''' is a reference onto a contextual metadata object that will be serialized among with the record, but will not be used as searchable content
* '''$course_id''' is the current course the ressource is within
* '''$group_id''' is the current group the resource belongs to, if the ressource is in a group scope (i.e. separate group wiki attachements), 0 elsewhere.
* '''$user_id''' is the id of the user the resource beslongs to, in case the ressource is in a user specific scope (i.e. post or assignment attachements), 0 elsewhere.
* '''$path''' is one of the above PATH defines for the module.

== Providing The indexer Documents From The Module ==

When first constructing the index, The Indexer needs scanning all the instances of the plugin.

The adapter API must provide the

<pre>
<module>_iterator(){ ... }
</pre>

function that will give a set of consistant plugin instances. Here is a ''very standard'' template code for this method :

<pre>
function <module>_iterator() {
$<module> = get_records('<module>');
return $<module>;
} //<module>_iterator
</pre>

On each instance, the function :

<pre>
function <module>_get_content_for_index(&$plugininstance) { ... }
</pre>

is called for constructing relevant instances of the SearchDocument subclass. This function MUST return an array of SearchDocuments or false. The typical synopsis of this function is :

<pre>
function <module>_get_content_for_index(&$plugininstance){
$documents = array();

// invalid plugin
if (!$plugininstance) return $documents;

// TODO : get an indexable item set

foreach($indexableitems as $indexableitem) {

// TODO : Prepare params with

$documents[] = new ForumSearchDocument(... params ...);
}
return $documents;
}
</pre>

=== Making The Backaccess Link ===

The constructor of the SearchDocument subclass must construct a backaccess link for the document, and give it as the 'url' attribute of the first constructor parameter (&$doc). this is usually done using a callback to the document API. the synopsys is :

<pre>
function <module>_make_link(...contextual params...) {
global $CFG;

return $CFG->wwwroot.<moodle path expression that drives back to the content>;
} //<module>_make_link
</pre>

Contextual params are usually ids of course module, or internal entities depending on the module construction, modal values...

== Updating The index Database ==

The search engine, once fed with its first indexing results from scratch, will be regularily updating by a cron job. The index is updated in diff mode, so only modified entries in the Moodle data model should be considered.

The update process will :
* add new items, as far as they are handled by the search engine
* update modified items
* drop indexes on deleted resources and contents

An API call back tells each of these three actions where the items to consider are in the Moodle database. This callback SHOULD return an array of arrays of strings, each containing the following fieldset :
* primary id fieldname,
* table name,
* time created field name,
* time modified field name,
* itemtype,
* [additional SELECT clause for filtering rows] // optional

Here comes a synopsys for such code. There should be as many arrays as known document subtypes in the module.

<pre>
function <module>_db_names() {
return array(
array('id', '<module>_<entity>', 'created', 'modified', '<itemtype>', '')
);
} //<module>_db_names
</pre>

Note : 'created' and 'modified' have several expression among the variety of modules/blocks. Sometimes, both of these informations are not available. Consider using the dates of a parent dependency in case they are missing.

Knowing where the items to update/add/delete are, both first operation will use a "Single Document Wrapper" to process to the update/add operation individually. This is the purpose of the

<pre>
function <module>_single_document($id, $itemtype) { ... }
</pre>

function. Here comes a rough prototype for such a callback :

<pre>
function <module>_single_document($id, $itemtype) {

switch($itemtype){
case <type1>:
... get content holding record ...
... get module_obj from previous ...
break;
case <type2>:
... get content holding record ...
... get module_obj from previous ...
break;
... and so on ...
}

$coursemodule = get_field('modules', 'id', 'name', '<module>');
$cm = get_record('course_modules', 'course', $<module_obj>->course, 'module', $coursemodule, 'instance', $<module_obj>->id);
if ($cm){
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
... preparing some data eventually ...
return new <ModuleItem>SearchDocument(get_object_vars($<content_obj>), $<module_obj>->id, $<module_obj>->course, $itemtype, $context->id);
}
return null;
} // <module>_single_document
</pre>

Note : we need use get_object_vars() as historical implementation uses a hash in constructors rather than an object.

== Checking Access Back To The Content ==

== Physical Document Adapters ==

Search engine adapters

2007-11-18T14:04:42Z

Vf: /* Providing The indexer Documents From The Module */

Search engine adapters

2007-11-17T21:56:18Z

Vf: /* Providing The indexer Documents From The Module */

Search engine adapters

2007-11-17T21:55:36Z

Vf: /* Providing The indexer Documents From The Module */

Search engine adapters

2007-11-17T21:49:44Z

Vf: /* Providing The indexer Documents From The Module */

Search engine adapters

2007-11-17T21:49:20Z

Vf: /* Providing Documents From The Module */

Search engine adapters

2007-11-17T21:39:27Z

Vf: /* Adapters for modules and blocks */

Search engine adapters

2007-11-17T21:39:07Z

Vf: /* Physical document adapters */

Search engine adapters

2007-11-17T21:37:53Z

Vf: /* Adapters for modules and blocks */

Search engine adapters

2007-11-17T21:37:09Z

Vf: /* Constructor */

Search engine adapters

2007-11-17T21:36:23Z

Vf: /* Constructor */

Search engine adapters

2007-11-17T21:32:35Z

Vf:

Search engine adapters

2007-11-17T21:15:40Z

Vf:

Search engine adapters

2007-11-17T21:14:07Z

Vf:

Developer documentation

2007-11-17T21:00:15Z

Vf: /* Make a new plugin */

'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches. A page may be added to the Developer category by typing <code><nowiki>[[Category:New page name]]</nowiki></code> at the bottom of the page.

==How Moodle development works==

This [[Overview|overview of the Moodle development process]] may be handy in understanding how the development of Moodle occurs and how people become Moodle developers.

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Unit tests]] explains how to run the unit tests, and how to write new test cases.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code. And don't forget that the most up-to-date and detailed description of how the code works is the code itself. Moodle code should be easy to read and understand. Use the source, Luke!

===Core components that affect everything===

*[[Database schema introduction|The database schema]]
*lib/moodlelib.php
*[[lib/weblib.php|lib/weblib.php]] for outputting stuff.
*[[XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what.
*[[lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things.

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Moodle Network|Moodle Network]]
*[[Email processing]]
*[[Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.

===Modules included in the standard distribution===

*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Modules|Activity modules]]
*[[Admin reports|Admin reports]]
*[[Assignment types|Assignment types]]
*[[Authentication plugins|Authentication plugins]]
*[[Blocks|Blocks]]
*[[Course formats]]
*[[Course Report Plugins|Course reports]]
*[[Database fields|Database fields]]
*[[Database presets|Database presets]]
*[[Enrolment plugins|Enrolment plugins]]
*[[Filters|Filters]]
*[[Grade export/import|Grade export/import]]
*[[Grade report|Grade report]]
*[[Question engine|Question engine]]
*[[Question import/export formats|Question import/export formats]]
*[[Quiz reports]]
*[[Resource types|Resource types]]
*[[SSO plugins|SSO plugins]]
*[[Search engine adapters|Search engine adapters]]
*[[Course Report Plugins|Course Report Plugins]]

When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 Moodle modules and plugins database].

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Database schemas|Database schemas]]
*[[Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer conferences]]

== Resources and tools ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD
*Browse the code online:
**[http://moodle.cvs.sourceforge.net/moodle/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled from the comment attached to each class and function in the code
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]
*Some tools people use when working on Moodle code:
**[[Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
**[[vim|Setting up Vim for Moodle development]]
**[[ctags|Ctags]] - Using a tags file to navigate code

==See also==

*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]

Roles

2007-09-21T22:37:12Z

Vf: /* Core-level Capabilities */

{{Moodle 1.7}}
'''Roles and permissions''' is in Moodle 1.7 onwards.

==Definitions==

A role is an identifier of the user's status in some context. For example: Teacher, Student and Forum moderator are examples of roles.

A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, ''mod/forum:replypost'' is a capability.

A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.

A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.

==The existing system==

In versions prior to v1.7, Moodle uses a fixed set of roles i.e. primary admin, admins, course creators, editing teachers, non-editing teachers, students, and guests. For each role, the capability or actions that they can perform are fixed. For example, the role student allows the user to submit an assignment, but doesn't allow the user to browse/edit other users' work. By using this setup we limit ourselves to a rather rigid set of capabilities for each role. If we want, say a particular student or group to be able to mark assignments in a particular course, we can't do that without giving these users teacher privileges.

==The new roles and capability system==

With v1.7 and greater, Moodle introduces a roles and capabilities system.

Role has two primary functions:
# define list of permissions - role definition is global for all contexts, but can be changed by local context overrides
# replace old course enrolments - role assignment in course context is simitar to the old enrolment process

The new system will allow authorized users to define an arbitrary number of roles (eg a teacher)

A role consists of a list of permissions for different possible actions within Moodle (eg delete discussions, add activities etc)

Roles can be applied to users in a context (eg assign Fred as a teacher in a particular course)

Here are the possible contexts, listed from the most general to the most specific.

#CONTEXT_SYSTEM -- the whole site
#CONTEXT_PERSONAL -- yourself
#CONTEXT_USER -- another user
#CONTEXT_COURSECAT -- a course category
#CONTEXT_COURSE -- a course
'''#CONTEXT_GROUP -- a group
#CONTEXT_MODULE -- an activity module
#CONTEXT_BLOCK -- a block

[[Image:Moodle-contexts-1.8.png|right|thumb|A diagram of the contexts in Moodle 1.8, based on the [[Talk:Roles_and_capabilities|text diagram by Martin Dougiamas]]. Click on the diagram to see a more detailed view of it.]]

An authorized user will be able to assign an arbitrary number of roles to each user in any context.

Capabilities can have the following permissions:

#CAP_INHERIT
#CAP_ALLOW
#CAP_PREVENT
#CAP_PROHIBIT

If no permission is defined, then the capability permission is inherited from a context that is more general than the current context. If we define different permission values for the same capability in different contexts, we say that we are overriding the capability in the more specific context.

Since the capabilities in each role could be different, there could be conflict in capabilities. This is resolved by enforcing the rule that the capability defined for a more specific context will win, unless a prohibit is encountered in a less specific context.

For example, Mark has a student role at course level, which allows him to write into a wiki. But Mark also got assigned a Visitor role at a module context level (for a particular wiki) which prevents him from writing to the wiki (read only). Therefore, for this particular wiki, Mark will not be able to write to the wiki since the more specific context wins.

If we set a PROHIBIT on a capability, it means that the capability cannot be overridden and will ALWAYS have a permission of prevent (deny). Prohibit always wins. For example, Jeff has a naughty student role that prohibits him from postings in any forums (for the whole site), but he's also assigned a facilitator role in "Science forum" in the course Science and Math 101. Since prohibit always wins, Jeff is unable to post in "Science forum".

Allow and prevent will cancel each other out if set for the same capability at the same context level. If this happens, we refer to the previous context level to determine the permission for the capability.

This may sound more complex than it really is in practice. The upshot is that the system can be flexible enough to allow pretty much any combination of permissions.

===Capability-locality changes in v1.9===

When resolving conflicts between "allow" and "prevent" in v1.7 and v1.8 the locality of the capability is taken into account, although with less weight than the locality of the role assignment. In v1.9 the process has been simplified, we consider locality of the role assignment when dealing with allow/prevent conflicts, but ignore where the capability has been defined (as long as it applies to the context).

For example - for the situation where there is

* two roles assigned to one user in a context (eg student role and teacher role)
* one override on one of those roles ( eg student role), at the same context

then

* '''1.7/1.8''' The override used to ''always'' win over the settings from the combined roles.

* '''1.9''' The override is combined with the student role first. and then the roles are combined. This is more logical, as the override is acting like a modification to the student role.

For more details, see [http://tracker.moodle.org/browse/MDL-11218 MDL-11218]

==Upgrading from 1.6==

A smooth upgrade will be provided with 1.7. The existing roles (admin, teacher, student, etc), and the existing capabilities will be automatically retained. This is done by creating default roles at site/course levels, and assigning the current users to these roles accordingly. The default roles will have default capabilities associated with them, mirroring what we have in 1.6. With no modifications, Moodle will operate exactly the same before and after the upgrade.

===Admins===

Admin users will be assigned the default legacy admin role in the system (site) context

===Course Creators===

Course Creators will be assigned the default legacy course creator role in the system (site) context

===Teachers===

Users who were teachers will be assigned the default legacy teacher role (or non-editing teacher role) in all courses they were teacher.

===Students===

Users who were students will be assigned the default student role in all courses they were student.

===Guests===

There will still be a single guest user with no default role at site level. For each course that allows guest access, the guest role will be assigned to the guest user for that course context. The guest control for the course will be modified from three to two options (guests always need to enter enrolment key - on/off). This setting is checked as now to force guests to enter key.

==Capabilities==

This will be a comprehensive list of capabilities (it's not complete yet). It is important that capability names are unique.

===Core-level Capabilities===

Moodle core capability names start with 'moodle/'. The next word indicates what type of core capability it is, and the last word is the actual capability itself. The capabilities for the Moodle core are defined in lib/db/access.php

#moodle/legacy:guest - legacy capabilities are used to transition existing users to the new roles system during the upgrade to Moodle 1.7
#moodle/legacy:student
#moodle/legacy:teacher
#moodle/legacy:editingteacher
#moodle/legacy:coursecreator
#moodle/legacy:admin
#moodle/site:doanything - special capability, meant for admins, if is set, overrides all other capability settings
#moodle/site:config - applicable in admin/index.php and config.php (might break down later) : 1)admin/config.php 2)admin/configure.php 3)blocks/admin/block_admin.php load_content_for_site()
#moodle/site:readallmessages - reads all messages and history
#moodle/site:approvecourse - approves a pending course
#moodle/site:manageblocks - adding/removing/editing blocks (site, course contexts only for now) : 1)_add_edit_controls moodleblock.class.php
#moodle/site:backup - can create a course backup : 1)course/category.php 2)block_admin.php
#moodle/site:restore - can restore into this context : 1)course/category.php 2)block_admin.php
#moodle/site:import - can import other courses into this context : 1)block_admin.php
#moodle/site:accessallgroups - able to access all groups irrespective of what group the user is in
#moodle/site:accessdb - directly accessing db (phpmyadmin)
#moodle/site:viewfullnames - able to see fullnames of other users
#moodle/site:viewparticipants - able to view participants
#moodle/site:viewreports - able to view site/course reports
#moodle/site:trustcontent - ability to use trusttext feature and bypass cleaning in specific areas
#moodle/site:uploadusers - ability to upload/update users from text file; moodle/role:assign capability is needed for course enrolling
#moodle/blog:view - read blogs (usable in system or course context)
#moodle/blog:create - write new blog posts (usable in system context only)
#moodle/blog:manageofficialtags - create/delete official blog tags that others can use (usable in system context only)
#moodle/blog:managepersonaltags - delete personal blog tags that others can use (usable in system context only) Note: users can always add own personal tags. This setting should be off for students by default.
#moodle/blog:manageentries - edit/delete all blog entries (usable in system context only)
#moodle/course:setcurrentsection - mark course section
#moodle/course:create - create courses : 1)course/edit.php 2)course/category.php 3)course/index.php
#moodle/course:delete - create courses : 1)course/category.php
#moodle/course:update - update course settings
#moodle/course:view - can use this to find participants
#moodle/course:viewparticipants - allows a user to view participant list
#moodle/course:viewscales - view scales (i.e. in a help window?) : 1)course/scales.php
#moodle/course:manageactivities - adding/removing/editing activities and resources (don't think it makes any sense to split these)
#moodle/course:managescales - add, delete, edit scales, move scales up and down : 1)blocks/block_admin.php 2)course/scales.php
#moodle/course:managegroups - managing groups, add, edit, delete : 1)course/groups.php 2)course/group.php
#moodle/course:managefiles - manage course files and folders
#moodle/course:managequestions - manage course questions
#moodle/course:managemetacourse - manage child courses in metacourse
#moodle/course:reset - able to reset the course
#moodle/course:useremail - Can use the enable/disable email stuff
#moodle/course:visibility - hide/show courses : 1)course/category.php
#moodle/course:viewhiddencourses - see hidden courses
#moodle/course:activityvisibility - hide/show activities within a course
#moodle/course:viewhiddenactivities - able to see activities that have been hidden
#moodle/course:sectionvisibility - hide/show sections
#moodle/course:viewhiddensections - view hidden sections
#moodle/course:viewcoursegrades - views all grades in course
#moodle/course:viewhiddenuserfields - view all hidden user fields
#moodle/course:managegrades - manages grades settings in course
#moodle/category:create - create category : 1)course/index.php
#moodle/category:delete - delete category : 1)course/index.php
#moodle/category:update - update category settings (sort and rename) this is currently an admin capability : 1)course/category.php
#moodle/category:visibility - hide/show categories : 1)course/index.php
#moodle/user:viewusergrades - view your own, or other user's grades (with specified context)
#moodle/user:create - create user : 1) user/edit.php
#moodle/user:delete - delete user : 1) admin/user.php
#moodle/user:readuserblogs - read blog entries
#moodle/user:update - update user settings : 1) user/edit.php
#moodle/user:viewdetails - view personally-identifying user details (e.g. name, photo).
#moodle/user:viewhiddendetails - view user details marked as "hidden"
#moodle/calendar:manageownentries - create/edit/delete
#moodle/calendar:manageentries - create/edit/delete
#moodle/role:assign - assign roles to users
#moodle/role:override - can override role capabilities (depending on context)
#moodle/role:manage - create/edit/delete roles, set capability permissions for each role
#moodle/role:unassignself - unassign yourself from your own roles
#moodle/role:viewhiddenassigns - view role assignments that have been marked as hidden
#moodle/question:import - imports questions (course level?) - Yes, question permissions currently need to be course-level.--[[User:Tim Hunt|Tim Hunt]]
#moodle/question:export - exports questions (course level?)
#moodle/question:managecategory - add/delete/edit question categories (course level?)
#moodle/question:manage - add/edit/delete a question (course level)

===User-level Capabilities===
# moodle/user:readuserposts -read individual user posts on profile page (parent?)
# moodle/user:readuserblogs -read individual user blogs on profile page (parent?)
# moodle/user:viewuseractivitiesreport-read individual activity report on profile page (parent?)
# moodle/user:editprofile - edit profile (normally used in CONTEXT_USERID and CONTEXT_SYSTEM)

===Module-level Capabilities===
The capabilities are cached into a database table when a module is installed or updated. Whenever the capability definitions are updated, the module version number should be bumped up so that the database table can be updated.

The naming convention for capabilities that are specific to modules and blocks is 'mod/mod_name:capability'. The part before the colon is the full path to the module in the Moodle code. The module capabilities are defined in mod/mod_name/db/access.php.

#Assignment
##mod/assignment:view- reading the assignment description
##mod/assignment:submit - turn assignment in
##mod/assignment:grade - grading, viewing of list of submitted assignments
#Chat
##mod/chat:chat - allows a user to participate in this chat
##mod/chat:readlog - allows a user to read past chat session logs
##mod/chat:deletelog - allows a user to delete past chat logs
#Choice
##mod/choice:choose - make a choice
##mod/choice:readresponses - read all responses
##mod/choice:deleteresponses - deletes all responses
##mod/choice:downloadresponses - download responses
#Database
##mod/data:viewentry - reads other people's entry
##mod/data:writeentry - add / edit and delete (own) entries
##mod/data:managetemplates - add, delete, edit fields and templates
##mod/data:manageentries - edit/delete all entries
##mod/data:comment - comment
##mod/data:managecomments - edit/delete all comments
##mod/data:rate - rate an entry
##mod/data:viewrating
##mod/data:approve - approves an entry
##mod/data:uploadentries - batch upload of entries
#Exercise
##mod/exercise:assess
#Forum
##mod/forum:viewdiscussion
##mod/forum:viewdiscussionsfromallgroups
##mod/forum:viewhiddentimedposts
##mod/forum:startdiscussion
##mod/forum:replypost
##mod/forum:viewrating
##mod/forum:viewanyrating
##mod/forum:rate
##mod/forum:createattachment
##mod/forum:deleteownpost
##mod/forum:deleteanypost
##mod/forum:splitdiscussions
##mod/forum:movediscussions
##mod/forum:editanypost
##mod/forum:viewqandawithoutposting
##mod/forum:viewsubscribers
##mod/forum:managesubscriptions
##mod/forum:throttlingapplies
#Glossary
##mod/glossary:write - add entries
##mod/glossary:manageentries - add, edit, delete entries
##mod/glossary:managecategories - create, delete, edit categories
##mod/glossary:comment - comment on an entry
##mod/glossary:managecomments - edit, delete comments
##mod/glossary:import - import glossaries
##mod/glossary:export - export glossaries
##mod/glossary:approve - approve glossaries
##mod/glossary:rate - rates glossary
##mod/glossary:viewrating - view ratings
#Hotpot
##mod/hotpot:attempt - attempt a hotpot
##mod/hotpot:viewreport - review and view reports
##mod/hotpot:grade - (grade? and) regrade
##mod/hotpot:deleteattempt - deletes attempts
#Label
##none
#Lams
##mod/lams:participate - original student
##mod/lams:manage - original teacher
#Lesson
##mod/lesson:edit - add and edit pages
##mod/lesson:manage - view student attempts
#Quiz
##mod/quiz:grade - comment, override grade, manual grade
##mod/quiz:preview - previews the quiz
##mod/quiz:viewreports - view quiz result reports
##mod/quiz:manage - add/delete/move (up or down) questions for a quiz
##mod/quiz:attempt - attempt the quiz--[[User:Tim Hunt|Tim Hunt]]
#Resource
#Scorm
##mod/scorm:viewgrades
#Survey
##mod/survey:download - downloads survery result
##mod/survey:participate - participate/ do survey
##mod/survey:readresponses - read all user's responese
#Wiki
##mod/wiki:participate - original student, meaning depends of type and course setting
##mod/wiki:manage - original teacher, manages assigned group; moodle/site:accessallgroups is needed to manage all groups
##(Waiting on new wiki)
#Workshop
##mod/workshop:participate - original student, allows user to submit and assess
##mod/workshop:manage - original teacher, user can manage others
##(Waiting on new Workshop)

===Enrolment-level Capabilities===

The naming convention for capabilities that are specific to enrolment is 'enrol/enrol_name:capability'. The enrolment capabilities are defined in enrol/enrol_name/db/access.php.

#Authorize.net Payment Gateway
##enrol/authorize:managepayments - manage user payments, capture, void, refund, delete etc.

===Blocks===
#activity_modules
##None
#admin
#admin_2
#admin_bookmarks
#blog_menu
#blog_tags
#calendar_month
#calendar_upcoming
#course_list
#course_summary
#glossary_random
#html
#loancalc
#login
#messages
#news_items
#online_users
#participants
#quiz_results
#recent_activity
#rss_client
##block/rss_client:createprivatefeeds
##block/rss_client:createsharedfeeds
##block/rss_client:manageownfeeds
##block/rss_client:manageanyfeeds
#search
#search_forums
#section_links
#site_main_menu
#social_activities

===Questions===
I am adding question categories here because they seem to have been forgotten in the whole scheme of things since having been removed from the quiz module itself. I've made a suggestion on how these could be handled in [http://www.moodle.org/bugs/bug.php?op=show&bugid=6118&pos= bug 6118].

See [http://moodle.org/mod/forum/discuss.php?d=51143 this forum thread] for a discussion about the current problems wth publishing question categories.[[User:Tim Hunt|Tim Hunt]] 18:50, 8 August 2006 (WST)

==Programming Interface==

Although the Roles system may look complicated at first glance, implementing it in Moodle code is fairly simple.

* You need to define each capability once, so that Moodle can upgrade existing roles to take advantage of it. You do this in an access.php inside the db folder of any module (eg see mod/forum/db/access.php). The array contains entries like this (note the descriptions for the legacy roles which provides forward compatibility):
'mod/forum:viewforum' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'legacy' => array(
'guest' => CAP_PREVENT,
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'coursecreator' => CAP_ALLOW,
'admin' => CAP_ALLOW
)
),
* To load/change these capabilities you need to bump the module version. There's no need to provide changes or differences as Moodle will scan the whole array and sort it out.
* On each page you need to find the context the user is working in, using the get_context_instance() function. For example, in the forum module:

$context = get_context_instance(CONTEXT_MODULE, $cm->id);
* or to at the course level:
$context = get_context_instance(CONTEXT_COURSE, $id);
* Then, whenever you want to check that the current user has rights to do something, call has_capability() like this:
if (!has_capability('mod/forum:viewforum', $context)) {
print_error('nopermissiontoviewforum');
}
* If you just want to assert a capability and then finish with an error message if it's not met (as we did above), then a shorter way it to use require_capability() like this:

require_capability('mod/forum:viewforum', $context);

* Note that there are extra parameters you can specify to get a custom error message, otherwise users get an automated "No permissions" message that lists the permission they were missing.

As a result of the new Roles System, all calls to isadmin(), iscoursecreator, isteacheredit(), isteacher(), isstudent(), and isguest() will have to be replaced with calls to has_capability() or require_capability(). However, these functions will be retained for some backward compatibility with old code, using the legacy capabilities to try and work out what to do.

==Metacourses==

The behaviour of metacourses in Moodle 1.7 changed slightly, in that where it used to just synch students from child courses to the parent course, it will now synch ALL roles. Teachers etc of the child courses will have the same role in the meta course. Technically metacourse synchronises all role assignments in CONTEXT_COURSE with its child courses; the only exception are users with moodle/course:managemetacourse capability, these users are synchronized only upwards, they are not unenrolled from metacourse when unenroling from child course or when removing the child from metacourse.

In order to import/enrol other courses into metacoure you need to have moodle/course:managemetacourse capability. You can add manually only participants with moodle/course:managemetacourse, all other participants are automatically synced with child courses - if you try to manually enrol user without this capability error is displayed. Similar error is shown also when you try to manually unenrol participant from meta course while still being enrolled in child course.

Sample setup:
* metacourse manager has been assigned role with moodle/course:managemetacourse capability in system or course category context
* students are enrolled in several child courses
* teachers are enrolled in separate child course(s)

==Problem areas we are working on ==

===Student view===

The "Student view" button has been removed completely.

If there is time and a secure way can be found, it will be replaced by a menu to let the user assume a temporary role in the context of that course.

===Teacher forum===

Teacher forums were always a curious exception to normal forums, as they were not part of a course as such, and were not backed up.

We're taking the opportunity to rectify this. The upgrade converts teacher forums with content to normal forums in section 0 of the course, and ensures that only teachers can access them. If the teacher forum had not been used in the course then it's not converted and will just dissappear.

===Enrolment plugins===

====Process of logging in====

# load_user_capability() is called to load all the capabilities
# check_enrolment_plugins() is called at the top of load_user_capability() to check all the enrolment plugins.
# For each active plugin:
##Check for setup_enrolments($user) and run it. This function will do all the processing needed to assign or unassign roles from the current user.
# load_user_capability() continues and loads up all the roles
# load_defaultuser_role() is called to add default site permissions (all users)

====Process of checking access to a course====

require_login($course->id) is called by the script and has logic like this:

# Is the user a guest at site level?
## Yes: Does the course allow guests?
### Yes: return true (and further capabilities are checked by the script)
### No: send the user to course/enrol.php for enrolment
## No: continue below

# Does the user have moodle/course:view in that (course) context?
## Yes: then they can enter (and further capabilities are checked by the script)
## No: is guest access allowed on the course?
### Yes: assign temporary guest role to that user for that context (in session cache).
### No: send the user to course/enrol.php for enrolment.

====Process of enrolling====

(more soon)

==Scenario brainstorming==

This section is for brainstorming some example roles that we would like to support. Note some of these *may* not be possible in 1.7.

===Student===
Obviously.

===Site Designers===
Is there a role for people involved in how the site looks but not full administrators? Thinking here of online control of themes rather than FTP theme uploading. But in either case they caneditlogos, caneditcss, candeditlevelatwhichthemeapplies.

===Educational Authority Adviser===
Someone who would want to browse the site and may be asked to comment or contribute to particular discussions or developments in school. Access for this role would be controlled by the school in the case of school level moodles but may be different if there were to be a Local Authority wide Moodle.

===Educational Inspector===
Someone who will visit the site to verify the school's self review that comments on home school relationships, extending the classroom etc. They may want to see summaries of usage and reports from surveys garnering parent and pupil views.

===Second Marker / Moderator===
A teacher within ths site that has access to assignments and quizzes from another teacher's course for second marking purposes. This may need additional functionality adding to the assignment module so that two sets of grades/feedback can be given to one set of assignments.

===Peer observer of teaching===
Many institutions encourage peer observation of teaching, to encourage reflection on practice. In online environments this will be similar to moderation or inspection. The peer observer would need to be able to experience the course "as a student", but also to be able to view summaries of usage, transcripts of interactions (forums/surveys/polls etc), grades assigned (e.g. in assignments).

===External Examiner===
Has all the rights of inspectors, but would also need to be able to review assignments and feedback, view forums, glossaries etc. However, would not want to post, feedback onto the site at all.

===Parent===
A parent will have one or more children in one or more institutions which could be using one or more moodle instances or a mixture of Learning Platforms. A parent's role will vary depending on the age of their children and whether they are contributing as a parent or a school supporter.

In Early Years (EY=3+4 yr olds) and Key Stage 1 (KS1=5+6 yr olds) they may play/learn on an activity or write for the child. Parents often interpret homework tasks and read to their children perhaps filling in a joint reading diary. In Key Stage 2 (KS2=7-11 yr olds) parents would be more monitoring but may join in as well.

In Key stages 3 (KS3=12-14 yr olds) and 4 (KS4=15+16 yr olds) this changes to more of a monitoring/awareness role where a parent would expect to have a summary report of attendance, attainment and general achievement on a weekly/monthly/termly or annual basis. Parents will often be asked to sign and write back comments about this review report.

In all Key Stages there is a great need for parents to receive communication from the school which they can confirm they have received by signing a form. In some cases this may also involve making choices from a list. It may also involve payment for a trip or disco being returned so there could be the possibility of electronic payments. Also in all Key Satges there may be a home-school agreement which may be signed up to. Could this form part of a site policy system that incorporates a tickable list of activities the parent agrees to the child using (blogs/wikis/forums etc.)?

Parent's evenings often involve complex booking systems that attempt to get parent's and teachers together. Easy for EY/KS1/KS2 very difficult for KS3/KS4. Wow would this help if it was built into the Learning Platform.

In some cases there needs to be confidential communication between the parent and the teacher without the child being party to this. It may involve teaching and learning but could also involve a behaviour or medical issue. Often this may be done via a sealed letter or face to face.

The latest incarnation of OfSTED with the Self Review Framework (SEF) there is a greater emphasis on schools gathering parent voice via surveys and discussion. There is a clear match here with parents have access to parental votes, questionnaires and discussions and for schools to be able to publish news, results and reports back to parents.

In the UK the LP framework and agenda as being pushed by the DfES via Becta emphasises that within the mandatory groups and roles functionality the parent role is likely to be required to meet the LP Framework procurement standard.

Again in the UK, parents have their own independent right of access to a child's educational records. Obviously, children's records must not be made available to other parties, including the parents of other children in the same class. Thus it would be necessary to associate parent accounts with their own child's accounts in such a way that they could, if so desired, have read access to their child's grades, answers and contributions, but generally not those of other children - this may be problematic in the case of wiki activities or forum posts.

There is some concern that children's forum contributions etc may be constrained if their parents are able to read all that they write; this may be particularly problematic in areas such as Personal, Social and Health Education (PSHE), where some schools may choose to use obfuscated usernames.

===Manager===
''Please add text here...''

===Weekly Seminar Leader===
''In a university seminar, typically 8-15 students in their 3rd/4th year, each student is responsible for leading one topic in a study series. I ask each student to research 5-10 resources, then give a powerpoint presentation to the other students. This is followed by an in-class discussion and then online homework. The homework involves some fun quiz questions and then some reflective journal questions. I ask each seminar leader to prepare the quiz questions and journal questions as well as their presentation. To do that, I would like to assign activity-making/authoring roles to the student--either for a short period, or for duration of the whole course. Thus "Allow Quiz Authoring Role" or "Allow Assignment Authoring Role" at the course level or, if possible, even the Topic level (in a topic or week format course) would be important.''

===Mentor/Mentee===
''Please add text here...''

===Community-Designed Rating Criteria===
''The gradebook tends to be the domain of the teacher. What if community/peer ratings/marks could also be entered there? What if peer assessment criteria could be designed by the students, not just the teacher?''

===Visitor===

This would be a role whereby one could allow a visitor to visit one's classroom. This might be a colleague interested in seeing your course, or a journalist who might be writing an article about one's site. They should not be able to see the names of any students anywhere (eg recent activity, forum posts) for privacy reasons. They should be able to try out things like quizzes, and lessons but no grades would be recorded (like in teacher preview mode). They would not be able to participate in choices and forums but could view them. It would be read only in a way like former-student role below but without access to a particular student's records that former student role would grant.

===Guest Speaker===

This role would be similar to the Visitor role above, but would allow seeing student names, and also allow both reading and posting to a specific forum or forums. We often have "guest speakers" who read and respond to student forum posts. Right now we have to add them as students, which isn't ideal.

===Former Student===
This role would be of particular use for courses with rolling enrollments. This role would be one where a student had completed all of the requirements of a course (ie assignments, quizzes etc.) but wished to have continued access to the course material for review or consultation. The key factor is that one would give access to the completed student to the notes he read, his work and the teacher's comments on it, but he would not be allowed to do anything that would take up the teacher's time. In other words, a sort-of read-only access to the course. How forums, which might contain pertinent information and would continue to grow, would be handled is a question. Perhaps the student would be shown only what was in the forums at the time he completed the course. He would not be allowed to see any new posts or add any himself. Same thing for database and glossary entries. In other words, a snapshot of the course at the time his regular enrollment ended. He shouldn't be able to see the names or profiles of any newly enrolled students for privacy reasons-hence the restrictions on forum access. One issue that would have to be dealt with would be changes to existing modules-such as resources. Does the student get access to the module as it was or as it is? We have no versioning of resources in Moodle so this would be a problem. What about a teacher changing a quiz question so that the answer is different? What would a former student see?

===Alumnus=== An ALUMNUS should be able to search for all other ALUMNI of the school, interact with them and be enrolled in a seperate course - which is like a META course with all the content of his learning and interaction - as well as capabilities to be a part of this ALUMNI only course. All the teachers of courses during school years should automatically be a part of the ALUMNI course .. which means when an ALUMNUS is enrolled in a course, the original teachers of all his courses get enrolled ? --[[User:Anil Sharma|Anil Sharma]] 20:54, 15 July 2006 (WST)

===Librarian===

Reference Librarians have an active role in most of the courses taught at some schools such as Earlham College (with Bibliographic Instruction). The Librarian role within Moodle could encompass default read access to all courses (unless prohibited by course teacher) and read access to all components of the course unless access is barred (again by teacher). The Librarians would also perhaps have a block called perhaps Reference Services or Reference Desk with write access where they could deposit resources. Also this block might have a chat applet whereby enrolled students could chat to the Reference Librarian on duty about their bibliographic research needs.

In schools there is often a book review system. This may be covered by the lending system database but may not in which case a librarian may neeed to have a course area they can create a database template to handle the reviews in which case they may have a normal teacher style role? Off topic but course an integration with common schools database systems would be great.

===Teacher===

Teachers should have read access to other Teacher's courses unless explictly prohibited. They should be able to set parts of their own course to be totally private (perhaps even to admin?). Just as each activity can currently be set to have group access, each activity could have a permissions field. Teachers could set default permissions for all activities on their course (eg they might disallow Librarian access for example) and then change the access permission for an individual activity.

I think that what is needed is a simple heirarchy of permissions and levels of granularity.

I would take issue with "teachers should have read access to other teacher's courses unless explicitly prohibited." This is a violation of the students' privacy as how they perform and what they do in one class isn't the business of another teacher. Moreover, in the real world a teacher wouldn't suddenly go sit in on a colleague's class without asking permission first. I would not have appreciated such an invasion of privacy as either a teacher or a student. It could be an option, but shouldn't be default.--[[User:N Hansen|N Hansen]] 19:54, 12 June 2006 (WST)

===Community Education Tutors/Trainers===
Teachers may be community adult education trainers making use of a school moodle so must only have access to their courses unless given access elsewhere. They would not necessarily get the default teacher privileges.

===Secretary/Student Worker===

We often have faculty who want their departmental secretary or student worker to scan and upload files and perhaps create resources. Currently they have to be given teacher access to the course. This is dangerous from a FERPA standpoint since they could easily get access to grades.

===Teaching Assistant===

Our Faculty frequently have undergraduate students acting as Teaching Assistants. These students need to be able to add resources, create assignments, and possibly grade assignments. However, due to FERPA they cannot have access to other students' overall grade information. I think the requirements here are slightly different than those of Secretary/Student Worker

===Student - FERPA rights===

A student that has asserted their FERPA rights to non-disclosure. Typically includes not publishing their name
in any public place. Could include this student only being seen with an "alias" within course spaces. Is this an attribute rather
than a role?

===Help Desk===

Help desk agents that have read access for the purposes of trouble shooting. Some care in placing this role within a hierarchy
of inheritance is needed, full access will be problematic with FERPA.

===Admin - Catgory based===

Basically a person in between full Admin and Creator that has the permissions of an Admin but only with respect to courses and students. Currently a Creator has permissions site-wide which does not always meet the requirements of a given organisation (e.g. Department A may not be happy that a person from Department B can create/modify courses within Department A's area). The ability to designate a Creator within a specific category would allow areas to be set up for a faculty/department/organisation and allow the Admin for that area to create/delete courses, upload users, add site-wide entries to the calendar etc.

===Process Roles===

organising the learning process for a group you wish to have the choice to place students in differnt roles: examples of this are:
* Give a student the role of forum-moderator with edit and chunk-rights
* Give students different roles & rights in a Webquest design (and change these roles next week
* Give students different resources, depending of their roles in a rolegame/simulation
* Give a student the rights to create the section content of next week (and only that week..)

==Things to finish for 1.7 Beta==
'''18 Sept 2006'''

#Remove core references to user_student, user_teacher, user_admin, user_coursecreator tables. [Yu]
#Address function: isteacher, isadmin, isstudent [Yu]
#Remove "view" capabilities from all modules unless required [Vy]
#Remove all old references from remaining Blocks [Vy]
#Metacourses [Skodak]
#Add risks to GUI[Skodak]
#Enrolment plugins [Martin and Alastair]
#[[Stats_roles_1.7|Statistics]] [Penny]
#Fix Loginas
#Add category-level assigns [Yu]
#[[Backup_roles_1.7|Backups]] [Eloy?]

===Proposal for interface enhancement===
Martin asked some questions, here are my answers. The sketches below are not worked out proposals. Their task is to visualize the idea. The exact colours and functionality may be defined after possible agreement about the proposals. The Green, orange and red columns support the meaning of the options from "allow" to "prohibit" (If you may want to see larger images please click onto the image or the "Enlarge" icon below the image.)

The list of possible settings is very long and '' "... the problem is not to overwhelm people with information" ''.

[[Image:01_moodle_define_roles_structured.png|thumb=01_moodle_define_roles_structured_pre.png]]

1) One proposal is to use colour to structure the sections and the columns. Picture 1 shows that the user can keep a much better overview when the list is divided into meaningful different coloured columns and clear sections.
 

[[Image:02_moodle_define_roles_collapsed.png|thumb=02_moodle_define_roles_collapsed_pre.png]]

2) A second proposal is to reduce the amount of information the user is shown at the same time. The YUI interface library offers great support to show/hide sections of the page by clicking on specific elements.

For example click on an icon beside the sub heading "Course categories" and show/hide all table rows with the CLASS "course-category".
 

[[Image:03_moodle_define_roles_tooltip.png|thumb=03_moodle_define_roles_tooltip_pre.png]]

3) '' "The main problem is the last column for risk ... we were thinking of putting little icons in there ..." ''
Icons are good when they tell the user more about possible actions/meanings then the letters. I am not sure if this is the case here. For both - icons or letters - the YUI tool-tip function would be able to give the user valuable information about the meaning.
 

==See also==

*[[Hardening new Roles system]]
*[[Roles and modules]]
*Using Moodle course:
**[http://moodle.org/mod/forum/view.php?f=941 Roles and Capabilities forum]
**Key discussions at Using Moodle forums:
***[http://moodle.org/mod/forum/discuss.php?d=38788 Roles and Permissions architecture]
***[http://moodle.org/mod/forum/discuss.php?d=56302#256313 An example of admin roles as set in the database]

[[Category:Roles]]
[[Category:Roles]]

[[fr:Developpement:Roles]]

Old Events API

2007-07-12T20:13:42Z

Vf: /* Handling an event */

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

==Overview==

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

===Triggering an event===

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

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

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

events_trigger('grade_updated', $eventdata);

===Handling an event===

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

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

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

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

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

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called event time an 'grade_added' event is triggered by a module.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'grade_updated'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /grade/export/lib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

All event names should follow a consistent naming pattern, such as modulename_noun_verb

== See also ==

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

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

lib/formslib.php

2007-06-22T09:56:05Z

Vf:

{{Formslib}}
{{Moodle 1.8}}
{{Moodle 1.7}}

The formslib api has now been backported and is available in Moodle 1.7. There may be a few minor styles missing from 1.7 stylesheets and be warned formslib has not been thoroughly tested in 1.7.

== Features of Formslib ==

* Created xhtml structure aiming for compliance with xhtml strict DTD and section 508 accessibility guidelines.
* Stylesheet for forms in Moodle standard themes.
* Accessibility improvements :
** Input fields labeled
** Tableless layout.
** Tested and optimised for use on major screenreaders Dragon and JAWS.
* New functionality :
** Facility to process form data securely as is currently done with required_param, optional_param using setType.
** Form elements process submitted data themselves and check the submitted data. For instance in select type only options that have been added to the select are accepted when submitted.
** Form validation with custom validation function or addRule QuickForms validation. QuickForms validation allows for clientside validation.
** Feedback to the user about required input and errors in user input.
** Facility to add Moodle help buttons to forms.
** upload_manager processes uploaded files securely.
** Many custom Moodle specific and non specific form elements to add to forms.
*** Moodle specific elements modgrade, modvisible, modgroupmode and choosecoursefile, format
*** Non specific elements htmleditor, dateselector, datetimeselector, selectyesno
*** Lots of modification to regular elements.
*** Easy to define your own custom elements.
* Some advanced functionality :
** Methods for adding repeated elements to a page. With button to add more elements.
** Working on hiding / unhiding advanced options on a form.

==Usage==

See the menu to the top right for pages on using formslib.php

== To Do ==

* Conversion of forms to use the new forms API. See list of initial forms to be done [http://tracker.moodle.org/browse/MDL-6937 in the tracker].

== Forms Which May Not Use Quick Forms But Need Some Recoding of HTML ==

Forms below were initially not deemed good candidates for migration to using the quickform library because they are either too big and complex or mostly because they are very small forms. (I don't see the problem with very small forms. I would still use the library, but I would not bother putting the form class definition in a separate file.[[User:Tim Hunt|Tim Hunt]]) But they do still need some recoding of the html to make it more accessible.

* auth\cas\index_form.html (18)
* auth\cas\index_form.html (32)
* auth\cas\index_form.html (45)
* blocks\search\block_search.php (49)
* blog\tags.html (13)
* blog\tags.html (43)
* blog\tags.html (79)
* blog\tags.html (90)
* calendar\event_delete.html (4)
* calendar\event_delete.html (21)
* calendar\event_delete.html (38)
* calendar\event_select.html (3)
* course\import\activities\mod.php (55)
* course\import\activities\mod.php (55)
* course\import\activities\mod.php (55)
* course\import\groups\mod.php (19)
* course\index.php (279)
* course\lib.php (1607)
* course\lib.php (1613)
* course\lib.php (1619)
* course\loginas.php (68)
* course\pending-reject.html(1)
* course\report\log\lib.php (154)
* course\report\participation\index.php (115)
* course\report\participation\index.php (181)
* course\report\participation\index.php (326)
* course\report\participation\mod.php (73)
* course\report\stats\lib.php (30)
* course\report\stats\report.php (15)
* course\search.php (162)
* course\teacher.php (214)
* enrol\authorize\locallib.php (193)
* enrol\manual\enrol.html (16)
* enrol\manual\enrol.html (44)
* error\index.php (33)
* files\index.php (180)
* files\index.php (191)
* files\index.php (321)
* files\index.php (332)
* files\index.php (362)
* files\index.php (372)
* files\index.php (408)
* files\index.php (420)
* files\index.php (466)
* files\index.php (476)
* files\index.php (506)
* files\index.php (554)
* files\index.php (702)
* files\index.php (832)
* files\index.php (843)
* files\index.php (852)
* files\index.php (858)
* grade\exceptions.html (107)
* grade\exceptions.html (128)
* grade\exceptions.html (150)
* grade\lib.php (2314)
* grade\lib.php (2368)
* grade\lib.php (2553)
* grade\lib.php (2566)
* grade\lib.php (2652)
* grade\lib.php (2804)
* install.php (667)
* install.php (870)
* iplookup\ipatlas\ip-atlas_prefs.php (106)
* iplookup\ipatlas\plot.php (132)
* lib\editor\htmlarea\coursefiles.php (232)
* lib\editor\htmlarea\coursefiles.php (242)
* lib\editor\htmlarea\coursefiles.php (336)
* lib\editor\htmlarea\coursefiles.php (346)
* lib\editor\htmlarea\coursefiles.php (375)
* lib\editor\htmlarea\coursefiles.php (384)
* lib\editor\htmlarea\coursefiles.php (412)
* lib\editor\htmlarea\coursefiles.php (423)
* lib\editor\htmlarea\coursefiles.php (468)
* lib\editor\htmlarea\coursefiles.php (477)
* lib\editor\htmlarea\coursefiles.php (506)
* lib\editor\htmlarea\coursefiles.php (553)
* lib\editor\htmlarea\coursefiles.php (698)
* lib\editor\htmlarea\coursefiles.php (817)
* lib\editor\htmlarea\plugins\SpellChecker\spell-check-ui.html (63)
* lib\editor\htmlarea\popups\createanchor.php (54)
* lib\editor\htmlarea\popups\fullscreen.php (171)
* lib\editor\htmlarea\popups\insert_image.php (181)
* lib\editor\htmlarea\popups\insert_image.php (285)
* lib\editor\htmlarea\popups\insert_image.php (287)
* lib\editor\htmlarea\popups\insert_image.php (289)
* lib\editor\htmlarea\popups\insert_image.php (291)
* lib\editor\htmlarea\popups\insert_image.php (319)
* lib\editor\htmlarea\popups\insert_image.php (328)
* lib\editor\htmlarea\popups\insert_image_std.php (154)
* lib\editor\htmlarea\popups\insert_table.php (83)
* lib\editor\htmlarea\popups\link.php (103)
* lib\editor\htmlarea\popups\link.php (105)
* lib\editor\htmlarea\popups\link.php (107)
* lib\editor\htmlarea\popups\link.php (109)
* lib\editor\htmlarea\popups\link.php (128)
* lib\editor\htmlarea\popups\link.php (136)
* lib\editor\htmlarea\popups\searchandreplace.php (107)
* lib\editor\htmlarea\popups\select_color.php (65)
* lib\editor\tinymce\jscripts\tiny_mce\plugins\advimage\image.htm (12)
* lib\editor\tinymce\jscripts\tiny_mce\plugins\fullscreen\fullscreen.htm (87)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\anchor.htm (9)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\editor_template_src.js (90)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\image.htm (11)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\jscripts\image.js (52)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\jscripts\link.js (46)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\link.htm (11)
* lib\editor\tinymce\jscripts\tiny_mce\themes\advanced\source_editor.htm (10)
* lib\editor\tinymce\jscripts\tiny_mce\tiny_mce_src.js (531)
* lib\editor\tinymce\jscripts\tiny_mce\tiny_mce_src.js (874)
* lib\html2text.php (94)
* lib\html2text.php (140)
* lib\questionlib.php (1174)
* lib\rsslib.php (465)
* lib\speller\controls.html (77)
* lib\uploadlib.php (466)
* lib\weblib.php (987)
* login\change_password_form.html (45)
* login\forgot_password.php (251)
* login\index_form.html (25)
* message\search.php (95)
* message\send.php (95)
* mod\assignment\lib.php (881)
* mod\assignment\lib.php (1183)
* mod\assignment\lib.php (1200)
* mod\assignment\type\online\assignment.class.php (132)
* mod\assignment\type\upload\assignment.class.php (826)
* mod\assignment\type\upload\assignment.class.php (1302)
* mod\assignment\type\upload\assignment.class.php (1318)
* mod\assignment\type\uploadsingle\assignment.class.php (86)
* mod\data\comment.php (65)
* mod\data\edit.php (238) --recode html in all 12 field.class.php files
* mod\data\edit.php (288)
* mod\data\field\latlong\field.class.php (98)
* mod\data\field.php (301)
* mod\data\lib.php (184) --recode html in all 12 field mod.html files
* mod\data\lib.php (953)
* mod\data\lib.php (1003)
* mod\data\lib.php (1150)
* mod\data\preset.php (297)
* mod\data\preset.php (319)
* mod\data\preset.php (625)
* mod\data\templates.php (139)
* mod\exercise\assessments.php (88)
* mod\exercise\assessments.php (274)
* mod\exercise\locallib.php (1573)
* mod\exercise\locallib.php (2374)
* mod\exercise\locallib.php (2874)
* mod\exercise\submissions.php (72)
* mod\exercise\view.php (254)
* mod\forum\lib.php (2316)
* mod\forum\lib.php (3197)
* mod\forum\prune.html (1)
* mod\glossary\comment.php (101)
* mod\glossary\editcategories.html (6)
* mod\glossary\editcategories.php (109)
* mod\glossary\export.php (65)
* mod\glossary\view.php (269)
* mod\glossary\view.php (332)
* mod\journal\edit.html (1)
* mod\journal\mod.html (20)
* mod\journal\report.php (116)
* mod\lesson\action\addbranchtable.php (36)
* mod\lesson\action\continue.php (817)
* mod\lesson\action\editpage.php (55)
* mod\lesson\import.php (86)
* mod\lesson\importppt.php (85)
* mod\lesson\view.php (142)
* mod\lesson\view.php (692)
* mod\lesson\view.php (917)
* mod\lesson\view.php (1195)
* mod\lesson\view.php (1649)
* mod\lesson\view.php (1986)
* mod\quiz\attempt.php (142)
* mod\quiz\attempt.php (475) --inlvolves rewriting question plugins
* mod\quiz\editlib.php (178)
* mod\quiz\editlib.php (310)
* mod\quiz\report\analysis\report.php (364)
* mod\quiz\report\grading\report.php (356)
* mod\quiz\report\overview\report.php (451)
* mod\quiz\report\overview\report.php (510)
* mod\resource\type\file\localfile.php (39)
* mod\resource\type\file\localpath.php (43)
* mod\scorm\coefficientsetting.php (173)
* mod\scorm\locallib.php (441)
* mod\survey\report.php (397)
* mod\survey\view.php (106)
* mod\wiki\admin.php (265)
* mod\wiki\checklinks.html (5)
* mod\wiki\ewiki\ewiki.php (524)
* mod\wiki\ewiki\ewiki.php (1478)
* mod\wiki\ewiki\ewiki.php (1535)
* mod\wiki\ewiki\ewiki.php (1607)
* mod\wiki\ewiki\plugins\email_protect.php (123)
* mod\wiki\ewiki\plugins\moodle\downloads.php (105)
* mod\wiki\ewiki\plugins\moodle\moodle_wikidump.php (68)
* mod\wiki\lib.php (1016)
* mod\wiki\removepages.html (8)
* mod\wiki\setpageflags.html (5)
* mod\wiki\strippages.html (5)
* mod\wiki\view.php (265)
* mod\workshop\assessments.php (95)
* mod\workshop\assessments.php (426)
* mod\workshop\locallib.php (1993)
* mod\workshop\locallib.php (2933)
* mod\workshop\submissions.php (77)
* mod\workshop\submissions.php (253)
* mod\workshop\view.php (156)
* question\category_class.php (192)
* question\category_class.php (445)
* question\category_class.php (598)
* question\editlib.php (167)
* question\editlib.php (172)
* question\editlib.php (328)
* question\export.php (157)
* question\format\coursetestmanager\format.php (122)
* question\preview.php (190)
* question\type\datasetdependent\categorydatasetdefinitions.php (71)
* question\type\datasetdependent\datasetitems.php (252)
* question\type\datasetdependent\datasetitems.php (266)
* question\type\rqp\types.php (162)
* question\type\editquestionstart.html (1)
* question\type\random\editquestionstart.html (1)
* question\type\rqp\editquestionstart.html (1)
* question\type\rqp\types.php (162)
* sso\hive\expired.php (29)
* user\extendenrol.php (48)
* user\index.php (174)
* user\index.php (311)
* user\index.php (574)
* user\message.html (1)

== These forms do not need any work ==

Admin forms have been worked on by others in a seperate project.

* auth\cas\index_form.html (59)
* auth\cas\index_form.html (76)
* blocks\search_forums\block_search_forums.php (31)
* blog\blogpage.php (173)
* blog\edit.php (62)
* calendar\export_basic.html (3)
* calendar\export_basic.html (34)
* calendar\lib.php (1224)
* calendar\view.php (207)
* calendar\view.php (330)
* calendar\view.php (525)
* course\category.php (434)
* course\reset.php (59)
* enrol\manual\enrol.html (32)
* enrol\paypal\enrol.html (7)
* filter\algebra\algebradebug.php (331)
* filter\tex\texdebug.php (208)
* filter\tex\texed.php (74)
* lang\en_utf8\help\quiz\multianswer.html (16)
* lang\en_utf8\help\quiz\multianswer.html (32)
* lib\adodb\adodb-perf.inc.php (675)
* lib\adodb\adodb-perf.inc.php (894)
* lib\speller\spellchecker.html (46)
* lib\speller\wordWindow.js (146)
* lib\weblib.php (674)
* lib\weblib.php (2840)
* lib\weblib.php (3675)
* lib\weblib.php (3704)
* lib\weblib.php (3722)
* lib\weblib.php (3752)
* lib\weblib.php (3778)
* lib\weblib.php (3802)
* lib\weblib.php (3826)
* lib\weblib.php (3854)
* lib\weblib.php (4021)
* lib\weblib.php (4026)
* lib\yui\container\container-debug.js (6469)
* lib\yui\container\container-debug.js (6481)
* lib\yui\container\container-debug.js (7017)
* lib\yui\container\container-debug.js (7053)
* lib\yui\container\container-debug.js (7073)
* lib\yui\container\container-min.js (457)
* lib\yui\container\container-min.js (505)
* lib\yui\container\container.js (6381)
* lib\yui\container\container.js (6393)
* lib\yui\container\container.js (6929)
* lib\yui\container\container.js (6965)
* lib\yui\container\container.js (6985)
* login\index_form.html (59)
* login\index_form.html (73)
* login\index_form.html (86)
* login\index_form.html (102)
* mod\assignment\type\common.html (1)
* mod\assignment\type\upload\assignment.class.php (102)
* mod\assignment\type\upload\assignment.class.php (129)
* mod\assignment\type\upload\assignment.class.php (163)
* mod\assignment\type\upload\assignment.class.php (1412)
* mod\chat\gui_header_js\chatinput.php (59)
* mod\chat\gui_header_js\chatinput.php (65)
* mod\chat\gui_sockets\chatinput.php (115)
* mod\chat\gui_sockets\chatinput.php (127)
* mod\chat\pagelib.php (68)
* mod\data\pagelib.php (71)
* mod\data\preset.php (120)
* mod\data\preset.php (131)
* mod\data\preset.php (148)
* mod\data\preset.php (161)
* mod\data\preset.php (168)
* mod\data\preset.php (193)
* mod\data\preset.php (326)
* mod\forum\lib.php (2991)
* mod\forum\lib.php (3517)
* mod\glossary\editcategories.php (178)
* mod\hotpot\hotpot-full.js (957)
* mod\hotpot\hotpot-full.js (4145)
* mod\hotpot\hotpot-full.js (4217)
* mod\hotpot\hotpot-full.js (5705)
* mod\hotpot\index.php (112)
* mod\hotpot\index.php (120)
* mod\hotpot\index.php (385)
* mod\hotpot\index.php (403)
* mod\hotpot\lib.php (1608)
* mod\hotpot\lib.php (1626)
* mod\hotpot\report\fullstat\report.php (425)
* mod\hotpot\report\overview\report.php (233)
* mod\hotpot\template\v6.php (2499)
* mod\hotpot\template\v6.php (2603)
* mod\hotpot\view.php (79)
* mod\lesson\mediafile.php (28)
* mod\lesson\report.php (106)
* mod\lesson\report.php (273)
* mod\lesson\view.php (81)
* mod\lesson\view.php (93)
* mod\quiz\index.php (29)
* mod\quiz\jstimer.php (35)
* mod\quiz\pagelib.php (69)
* mod\resource\type\repository\hive\openhive.php (43)
* mod\scorm\locallib.php (465)
* mod\wiki\ewiki\ewiki.php (1094)
* mod\wiki\ewiki\ewiki.php (1653)
* question\category_class.php (385)
* question\format\xhtml\format.php (128)
* question\type\datasetdependent\datasetitems.php (275)
* user\messageselect.php (79)
* user\view.php (312)
* user\view.php (317)
* user\view.php (325)
* user\view.php (340)
* user\view.php (353)
* user\view.php (357)
* user\view.php (365)

[[Category:Lib/formslib.php]]

[[fr:Developpement:lib/formslib.php]]

Roles

2007-06-22T09:24:04Z

Vf: /* See also */

{{Moodle 1.7}}
'''Roles and permissions''' is in Moodle 1.7 onwards.

==Definitions==

A role is an identifier of the user's status in some context. For example: Teacher, Student and Forum moderator are examples of roles.

A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, ''mod/forum:replypost'' is a capability.

A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.

A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.

==The existing system==

In versions prior to v1.7, Moodle uses a fixed set of roles i.e. primary admin, admins, course creators, editing teachers, non-editing teachers, students, and guests. For each role, the capability or actions that they can perform are fixed. For example, the role student allows the user to submit an assignment, but doesn't allow the user to browse/edit other users' work. By using this setup we limit ourselves to a rather rigid set of capabilities for each role. If we want, say a particular student or group to be able to mark assignments in a particular course, we can't do that without giving these users teacher privileges.

==The new roles and capability system==

With v1.7 and greater, Moodle introduces a roles and capabilities system.

Role has two primary functions:
# define list of permissions - role definition is global for all contexts, but can be changed by local context overrides
# replace old course erolments - role assignment in course context is simitar to the old enrolment process

The new system will allow authorized users to define an arbitrary number of roles (eg a teacher)

A role consists of a list of permissions for different possible actions within Moodle (eg delete discussions, add activities etc)

Roles can be applied to users in a context (eg assign Fred as a teacher in a particular course)

Here are the possible contexts, listed from the most general to the most specific.

#CONTEXT_SYSTEM -- the whole site
#CONTEXT_PERSONAL -- yourself
#CONTEXT_USER -- another user
#CONTEXT_COURSECAT -- a course category
#CONTEXT_COURSE -- a course
#CONTEXT_GROUP -- a group
#CONTEXT_MODULE -- an activity module
#CONTEXT_BLOCK -- a block

[[Image:Moodle-contexts-1.8.png|right|thumb|A diagram of the contexts in Moodle 1.8, based on the [[Talk:Roles_and_capabilities|text diagram by Martin Dougiamas]]. Click on the diagram to see a more detailed view of it.]]

An authorized user will be able to assign an arbitrary number of roles to each user in any context.

Capabilities can have the following permissions:

#CAP_INHERIT
#CAP_ALLOW
#CAP_PREVENT
#CAP_PROHIBIT

If no permission is defined, then the capability permission is inherited from a context that is more general than the current context. If we define different permission values for the same capability in different contexts, we say that we are overriding the capability in the more specific context.

Since the capabilities in each role could be different, there could be conflict in capabilities. This is resolved by enforcing the rule that the capability defined for a more specific context will win, unless a prohibit is encountered in a less specific context.

For example, Mark has a student role at course level, which allows him to write into a wiki. But Mark also got assigned a Visitor role at a module context level (for a particular wiki) which prevents him from writing to the wiki (read only). Therefore, for this particular wiki, Mark will not be able to write to the wiki since the more specific context wins.

If we set a PROHIBIT on a capability, it means that the capability cannot be overridden and will ALWAYS have a permission of prevent (deny). Prohibit always wins. For example, Jeff has a naughty student role that prohibits him from postings in any forums (for the whole site), but he's also assigned a facilitator role in "Science forum" in the course Science and Math 101. Since prohibit always wins, Jeff is unable to post in "Science forum".

Allow and prevent will cancel each other out if set for the same capability at the same context level. If this happens, we refer to the previous context level to determine the permission for the capability.

This may sound more complex than it really is in practice. The upshot is that the system can be flexible enough to allow pretty much any combination of permissions.

==Upgrading from 1.6==

A smooth upgrade will be provided with 1.7. The existing roles (admin, teacher, student, etc), and the existing capabilities will be automatically retained. This is done by creating default roles at site/course levels, and assigning the current users to these roles accordingly. The default roles will have default capabilities associated with them, mirroring what we have in 1.6. With no modifications, Moodle will operate exactly the same before and after the upgrade.

===Admins===

Admin users will be assigned the default legacy admin role in the system (site) context

===Course Creators===

Course Creators will be assigned the default legacy course creator role in the system (site) context

===Teachers===

Users who were teachers will be assigned the default legacy teacher role (or non-editing teacher role) in all courses they were teacher.

===Students===

Users who were students will be assigned the default student role in all courses they were student.

===Guests===

There will still be a single guest user with no default role at site level. For each course that allows guest access, the guest role will be assigned to the guest user for that course context. The guest control for the course will be modified from three to two options (guests always need to enter enrolment key - on/off). This setting is checked as now to force guests to enter key.

==Capabilities==

This will be a comprehensive list of capabilities (it's not complete yet). It is important that capability names are unique.

===Core-level Capabilities===

Moodle core capability names start with 'moodle/'. The next word indicates what type of core capability it is, and the last word is the actual capability itself. The capabilities for the Moodle core are defined in lib/db/access.php

#moodle/legacy:guest - legacy capabilities are used to transition existing users to the new roles system during the upgrade to Moodle 1.7
#moodle/legacy:student
#moodle/legacy:teacher
#moodle/legacy:editingteacher
#moodle/legacy:coursecreator
#moodle/legacy:admin
#moodle/site:doanything - special capability, meant for admins, if is set, overrides all other capability settings
#moodle/site:config - applicable in admin/index.php and config.php (might break down later) : 1)admin/config.php 2)admin/configure.php 3)blocks/admin/block_admin.php load_content_for_site()
#moodle/site:readallmessages - reads all messages and history
#moodle/site:approvecourse - approves a pending course
#moodle/site:manageblocks - adding/removing/editing blocks (site, course contexts only for now) : 1)_add_edit_controls moodleblock.class.php
#moodle/site:backup - can create a course backup : 1)course/category.php 2)block_admin.php
#moodle/site:restore - can restore into this context : 1)course/category.php 2)block_admin.php
#moodle/site:import - can import other courses into this context : 1)block_admin.php
#moodle/site:accessallgroups - able to access all groups irrespective of what group the user is in
#moodle/site:accessdb - directly accessing db (phpmyadmin)
#moodle/site:viewfullnames - able to see fullnames of other users
#moodle/site:viewparticipants - able to view participants
#moodle/site:viewreports - able to view site/course reports
#moodle/site:trustcontent - ability to use trusttext feature and bypass cleaning in specific areas
#moodle/site:uploadusers - ability to upload/update users from text file; moodle/role:assign capability is needed for course enrolling
#moodle/blog:view - read blogs (usable in system or course context)
#moodle/blog:create - write new blog posts (usable in system context only)
#moodle/blog:manageofficialtags - create/delete official blog tags that others can use (usable in system context only)
#moodle/blog:managepersonaltags - delete personal blog tags that others can use (usable in system context only) Note: users can always add own personal tags. This setting should be off for students by default.
#moodle/blog:manageentries - edit/delete all blog entries (usable in system context only)
#moodle/course:setcurrentsection - mark course section
#moodle/course:create - create courses : 1)course/edit.php 2)course/category.php 3)course/index.php
#moodle/course:delete - create courses : 1)course/category.php
#moodle/course:update - update course settings
#moodle/course:view - can use this to find participants
#moodle/course:viewparticipants - allows a user to view participant list
#moodle/course:viewscales - view scales (i.e. in a help window?) : 1)course/scales.php
#moodle/course:manageactivities - adding/removing/editing activities and resources (don't think it makes any sense to split these)
#moodle/course:managescales - add, delete, edit scales, move scales up and down : 1)blocks/block_admin.php 2)course/scales.php
#moodle/course:managegroups - managing groups, add, edit, delete : 1)course/groups.php 2)course/group.php
#moodle/course:managefiles - manage course files and folders
#moodle/course:managequestions - manage course questions
#moodle/course:managemetacourse - manage child courses in metacourse
#moodle/course:reset - able to reset the course
#moodle/course:useremail - Can use the enable/disable email stuff
#moodle/course:visibility - hide/show courses : 1)course/category.php
#moodle/course:viewhiddencourses - see hidden courses
#moodle/course:activityvisibility - hide/show activities within a course
#moodle/course:viewhiddenactivities - able to see activities that have been hidden
#moodle/course:sectionvisibility - hide/show sections
#moodle/course:viewhiddensections - view hidden sections
#moodle/course:viewcoursegrades - views all grades in course
#moodle/course:viewhiddenuserfields - view all hidden user fields
#moodle/course:managegrades - manages grades settings in course
#moodle/category:create - create category : 1)course/index.php
#moodle/category:delete - delete category : 1)course/index.php
#moodle/category:update - update category settings (sort and rename) this is currently an admin capability : 1)course/category.php
#moodle/category:visibility - hide/show categories : 1)course/index.php
#moodle/user:viewusergrades - view your own, or other user's grades (with specified context)
#moodle/user:create - create user : 1) user/edit.php
#moodle/user:delete - delete user : 1) admin/user.php
moodle/user:readuserblogs - read blog entries
#moodle/user:update - update user settings : 1) user/edit.php
#moodle/user:viewdetails - view personally-identifying user details (e.g. name, photo).
#moodle/user:viewhiddendetails - view user details marked as "hidden"
#moodle/calendar:manageownentries - create/edit/delete
#moodle/calendar:manageentries - create/edit/delete
#moodle/role:assign - assign roles to users
#moodle/role:override - can override role capabilities (depending on context)
#moodle/role:manage - create/edit/delete roles, set capability permissions for each role
#moodle/role:unassignself - unassign yourself from your own roles
#moodle/role:viewhiddenassigns - view role assignments that have been marked as hidden
#moodle/question:import - imports questions (course level?) - Yes, question permissions currently need to be course-level.--[[User:Tim Hunt|Tim Hunt]]
#moodle/question:export - exports questions (course level?)
#moodle/question:managecateory - add/delete/edit question categories (course level?)
#moodle/question:manage - add/edit/delete a question (course level)

===User-level Capabilities===
# moodle/user:readuserposts -read individual user posts on profile page (parent?)
# moodle/user:readuserblogs -read individual user blogs on profile page (parent?)
# moodle/user:viewuseractivitiesreport-read individual activity report on profile page (parent?)
# moodle/user:editprofile - edit profile (normally used in CONTEXT_USERID and CONTEXT_SYSTEM)

===Module-level Capabilities===
The capabilities are cached into a database table when a module is installed or updated. Whenever the capability definitions are updated, the module version number should be bumped up so that the database table can be updated.

The naming convention for capabilities that are specific to modules and blocks is 'mod/mod_name:capability'. The part before the colon is the full path to the module in the Moodle code. The module capabilities are defined in mod/mod_name/db/access.php.

#Assignment
##mod/assignment:view- reading the assignment description
##mod/assignment:submit - turn assignment in
##mod/assignment:grade - grading, viewing of list of submitted assignments
#Chat
##mod/chat:chat - allows a user to participate in this chat
##mod/chat:readlog - allows a user to read past chat session logs
##mod/chat:deletelog - allows a user to delete past chat logs
#Choice
##mod/choice:choose - make a choice
##mod/choice:readresponses - read all responses
##mod/choice:deleteresponses - deletes all responses
##mod/choice:downloadresponses - download responses
#Database
##mod/data:viewentry - reads other people's entry
##mod/data:writeentry - add / edit and delete (own) entries
##mod/data:managetemplates - add, delete, edit fields and templates
##mod/data:manageentries - edit/delete all entries
##mod/data:comment - comment
##mod/data:managecomments - edit/delete all comments
##mod/data:rate - rate an entry
##mod/data:viewrating
##mod/data:approve - approves an entry
##mod/data:uploadentries - batch upload of entries
#Exercise
##mod/exercise:assess
#Forum
##mod/forum:viewdiscussion
##mod/forum:viewdiscussionsfromallgroups
##mod/forum:viewhiddentimedposts
##mod/forum:startdiscussion
##mod/forum:replypost
##mod/forum:viewrating
##mod/forum:viewanyrating
##mod/forum:rate
##mod/forum:createattachment
##mod/forum:deleteownpost
##mod/forum:deleteanypost
##mod/forum:splitdiscussions
##mod/forum:movediscussions
##mod/forum:editanypost
##mod/forum:viewqandawithoutposting
##mod/forum:viewsubscribers
##mod/forum:managesubscriptions
##mod/forum:throttlingapplies
#Glossary
##mod/glossary:write - add entries
##mod/glossary:manageentries - add, edit, delete entries
##mod/glossary:managecategories - create, delete, edit categories
##mod/glossary:comment - comment on an entry
##mod/glossary:managecomments - edit, delete comments
##mod/glossary:import - import glossaries
##mod/glossary:export - export glossaries
##mod/glossary:approve - approve glossaries
##mod/glossary:rate - rates glossary
##mod/glossary:viewrating - view ratings
#Hotpot
##mod/hotpot:attempt - attempt a hotpot
##mod/hotpot:viewreport - review and view reports
##mod/hotpot:grade - (grade? and) regrade
##mod/hotpot:deleteattempt - deletes attempts
#Label
##none
#Lams
##mod/lams:participate - original student
##mod/lams:manage - original teacher
#Lesson
##mod/lesson:edit - add and edit pages
##mod/lesson:manage - view student attempts
#Quiz
##mod/quiz:grade - comment, override grade, manual grade
##mod/quiz:preview - previews the quiz
##mod/quiz:viewreports - view quiz result reports
##mod/quiz:manage - add/delete/move (up or down) questions for a quiz
##mod/quiz:attempt - attempt the quiz--[[User:Tim Hunt|Tim Hunt]]
#Resource
#Scorm
##mod/scorm:viewgrades
#Survey
##mod/survey:download - downloads survery result
##mod/survey:participate - participate/ do survey
##mod/survey:readresponses - read all user's responese
#Wiki
##mod/wiki:participate - original student, meaning depends of type and course setting
##mod/wiki:manage - original teacher, manages assigned group; moodle/site:accessallgroups is needed to manage all groups
##(Waiting on new wiki)
#Workshop
##mod/workshop:participate - original student, allows user to submit and assess
##mod/workshop:manage - original teacher, user can manage others
##(Waiting on new Workshop)

===Enrolment-level Capabilities===

The naming convention for capabilities that are specific to enrolment is 'enrol/enrol_name:capability'. The enrolment capabilities are defined in enrol/enrol_name/db/access.php.

#Authorize.net Payment Gateway
##enrol/authorize:managepayments - manage user payments, capture, void, refund, delete etc.

===Blocks===
#activity_modules
##None
#admin
#admin_2
#admin_bookmarks
#blog_menu
#blog_tags
#calendar_month
#calendar_upcoming
#course_list
#course_summary
#glossary_random
#html
#loancalc
#login
#messages
#news_items
#online_users
#participants
#quiz_results
#recent_activity
#rss_client
##block/rss_client:createprivatefeeds
##block/rss_client:createsharedfeeds
##block/rss_client:manageownfeeds
##block/rss_client:manageanyfeeds
#search
#search_forums
#section_links
#site_main_menu
#social_activities

===Questions===
I am adding question categories here because they seem to have been forgotten in the whole scheme of things since having been removed from the quiz module itself. I've made a suggestion on how these could be handled in [http://www.moodle.org/bugs/bug.php?op=show&bugid=6118&pos= bug 6118].

See [http://moodle.org/mod/forum/discuss.php?d=51143 this forum thread] for a discussion about the current problems wth publishing question categories.[[User:Tim Hunt|Tim Hunt]] 18:50, 8 August 2006 (WST)

==Programming Interface==

Although the Roles system may look complicated at first glance, implementing it in Moodle code is fairly simple.

* You need to define each capability once, so that Moodle can upgrade existing roles to take advantage of it. You do this in an access.php inside the db folder of any module (eg see mod/forum/db/access.php). The array contains entries like this (note the descriptions for the legacy roles which provides forward compatibility):
'mod/forum:viewforum' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'legacy' => array(
'guest' => CAP_PREVENT,
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'coursecreator' => CAP_ALLOW,
'admin' => CAP_ALLOW
)
),
* To load/change these capabilities you need to bump the module version. There's no need to provide changes or differences as Moodle will scan the whole array and sort it out.
* On each page you need to find the context the user is working in, using the get_context_instance() function. For example, in the forum module:

$context = get_context_instance(CONTEXT_MODULE, $cm->id);
* Then, whenever you want to check that the current user has rights to do something, call has_capability() like this:
if (!has_capability('mod/forum:viewforum', $context)) {
print_error('nopermissiontoviewforum');
}
* If you just want to assert a capability and then finish with an error message if it's not met (as we did above), then a shorter way it to use require_capability() like this:

require_capability('mod/forum:viewforum', $context);

* Note that there are extra parameters you can specify to get a custom error message, otherwise users get an automated "No permissions" message that lists the permission they were missing.

As a result of the new Roles System, all calls to isadmin(), iscoursecreator, isteacheredit(), isteacher(), isstudent(), and isguest() will have to be replaced with calls to has_capability() or require_capability(). However, these functions will be retained for some backward compatibility with old code, using the legacy capabilities to try and work out what to do.

==Metacourses==

The behaviour of metacourses in Moodle 1.7 changed slightly, in that where it used to just synch students from child courses to the parent course, it will now synch ALL roles. Teachers etc of the child courses will have the same role in the meta course. Technically metacourse synchronises all role assignments in CONTEXT_COURSE with its child courses; the only exception are users with moodle/course:managemetacourse capability, these users are synchronized only upwards, they are not unenrolled from metacourse when unenroling from child course or when removing the child from metacourse.

In order to import/enrol other courses into metacoure you need to have moodle/course:managemetacourse capability. You can add manually only participants with moodle/course:managemetacourse, all other participants are automatically synced with child courses - if you try to manually enrol user without this capability error is displayed. Similar error is shown also when you try to manually unenrol participant from meta course while still being enrolled in child course.

Sample setup:
* metacourse manager has been assigned role with moodle/course:managemetacourse capability in system or course category context
* students are enrolled in several child courses
* teachers are enrolled in separate child course(s)

==Problem areas we are working on ==

===Student view===

The "Student view" button has been removed completely.

If there is time and a secure way can be found, it will be replaced by a menu to let the user assume a temporary role in the context of that course.

===Teacher forum===

Teacher forums were always a curious exception to normal forums, as they were not part of a course as such, and were not backed up.

We're taking the opportunity to rectify this. The upgrade converts teacher forums with content to normal forums in section 0 of the course, and ensures that only teachers can access them. If the teacher forum had not been used in the course then it's not converted and will just dissappear.

===Enrolment plugins===

====Process of logging in====

# load_user_capability() is called to load all the capabilities
# check_enrolment_plugins() is called at the top of load_user_capability() to check all the enrolment plugins.
# For each active plugin:
##Check for setup_enrolments($user) and run it. This function will do all the processing needed to assign or unassign roles from the current user.
# load_user_capability() continues and loads up all the roles
# load_defaultuser_role() is called to add default site permissions (all users)

====Process of checking access to a course====

require_login($course->id) is called by the script and has logic like this:

# Is the user a guest at site level?
## Yes: Does the course allow guests?
### Yes: return true (and further capabilities are checked by the script)
### No: send the user to course/enrol.php for enrolment
## No: continue below

# Does the user have moodle/course:view in that (course) context?
## Yes: then they can enter (and further capabilities are checked by the script)
## No: is guest access allowed on the course?
### Yes: assign temporary guest role to that user for that context (in session cache).
### No: send the user to course/enrol.php for enrolment.

====Process of enrolling====

(more soon)

==Scenario brainstorming==

This section is for brainstorming some example roles that we would like to support. Note some of these *may* not be possible in 1.7.

===Student===
Obviously.

===Site Designers===
Is there a role for people involved in how the site looks but not full administrators? Thinking here of online control of themes rather than FTP theme uploading. But in either case they caneditlogos, caneditcss, candeditlevelatwhichthemeapplies.

===Educational Authority Adviser===
Someone who would want to browse the site and may be asked to comment or contribute to particular discussions or developments in school. Access for this role would be controlled by the school in the case of school level moodles but may be different if there were to be a Local Authority wide Moodle.

===Educational Inspector===
Someone who will visit the site to verify the school's self review that comments on home school relationships, extending the classroom etc. They may want to see summaries of usage and reports from surveys garnering parent and pupil views.

===Second Marker / Moderator===
A teacher within ths site that has access to assignments and quizzes from another teacher's course for second marking purposes. This may need additional functionality adding to the assignment module so that two sets of grades/feedback can be given to one set of assignments.

===Peer observer of teaching===
Many institutions encourage peer observation of teaching, to encourage reflection on practice. In online environments this will be similar to moderation or inspection. The peer observer would need to be able to experience the course "as a student", but also to be able to view summaries of usage, transcripts of interactions (forums/surveys/polls etc), grades assigned (e.g. in assignments).

===External Examiner===
Has all the rights of inspectors, but would also need to be able to review assignments and feedback, view forums, glossaries etc. However, would not want to post, feedback onto the site at all.

===Parent===
A parent will have one or more children in one or more institutions which could be using one or more moodle instances or a mixture of Learning Platforms. A parent's role will vary depending on the age of their children and whether they are contributing as a parent or a school supporter.

In Early Years (EY=3+4 yr olds) and Key Stage 1 (KS1=5+6 yr olds) they may play/learn on an activity or write for the child. Parents often interpret homework tasks and read to their children perhaps filling in a joint reading diary. In Key Stage 2 (KS2=7-11 yr olds) parents would be more monitoring but may join in as well.

In Key stages 3 (KS3=12-14 yr olds) and 4 (KS4=15+16 yr olds) this changes to more of a monitoring/awareness role where a parent would expect to have a summary report of attendance, attainment and general achievement on a weekly/monthly/termly or annual basis. Parents will often be asked to sign and write back comments about this review report.

In all Key Stages there is a great need for parents to receive communication from the school which they can confirm they have received by signing a form. In some cases this may also involve making choices from a list. It may also involve payment for a trip or disco being returned so there could be the possibility of electronic payments. Also in all Key Satges there may be a home-school agreement which may be signed up to. Could this form part of a site policy system that incorporates a tickable list of activities the parent agrees to the child using (blogs/wikis/forums etc.)?

Parent's evenings often involve complex booking systems that attempt to get parent's and teachers together. Easy for EY/KS1/KS2 very difficult for KS3/KS4. Wow would this help if it was built into the Learning Platform.

In some cases there needs to be confidential communication between the parent and the teacher without the child being party to this. It may involve teaching and learning but could also involve a behaviour or medical issue. Often this may be done via a sealed letter or face to face.

The latest incarnation of OfSTED with the Self Review Framework (SEF) there is a greater emphasis on schools gathering parent voice via surveys and discussion. There is a clear match here with parents have access to parental votes, questionnaires and discussions and for schools to be able to publish news, results and reports back to parents.

In the UK the LP framework and agenda as being pushed by the DfES via Becta emphasises that within the mandatory groups and roles functionality the parent role is likely to be required to meet the LP Framework procurement standard.

Again in the UK, parents have their own independent right of access to a child's educational records. Obviously, children's records must not be made available to other parties, including the parents of other children in the same class. Thus it would be necessary to associate parent accounts with their own child's accounts in such a way that they could, if so desired, have read access to their child's grades, answers and contributions, but generally not those of other children - this may be problematic in the case of wiki activities or forum posts.

There is some concern that children's forum contributions etc may be constrained if their parents are able to read all that they write; this may be particularly problematic in areas such as Personal, Social and Health Education (PSHE), where some schools may choose to use obfuscated usernames.

===Manager===
''Please add text here...''

===Weekly Seminar Leader===
''In a university seminar, typically 8-15 students in their 3rd/4th year, each student is responsible for leading one topic in a study series. I ask each student to research 5-10 resources, then give a powerpoint presentation to the other students. This is followed by an in-class discussion and then online homework. The homework involves some fun quiz questions and then some reflective journal questions. I ask each seminar leader to prepare the quiz questions and journal questions as well as their presentation. To do that, I would like to assign activity-making/authoring roles to the student--either for a short period, or for duration of the whole course. Thus "Allow Quiz Authoring Role" or "Allow Assignment Authoring Role" at the course level or, if possible, even the Topic level (in a topic or week format course) would be important.''

===Mentor/Mentee===
''Please add text here...''

===Community-Designed Rating Criteria===
''The gradebook tends to be the domain of the teacher. What if community/peer ratings/marks could also be entered there? What if peer assessment criteria could be designed by the students, not just the teacher?''

===Visitor===

This would be a role whereby one could allow a visitor to visit one's classroom. This might be a colleague interested in seeing your course, or a journalist who might be writing an article about one's site. They should not be able to see the names of any students anywhere (eg recent activity, forum posts) for privacy reasons. They should be able to try out things like quizzes, and lessons but no grades would be recorded (like in teacher preview mode). They would not be able to participate in choices and forums but could view them. It would be read only in a way like former-student role below but without access to a particular student's records that former student role would grant.

===Guest Speaker===

This role would be similar to the Visitor role above, but would allow seeing student names, and also allow both reading and posting to a specific forum or forums. We often have "guest speakers" who read and respond to student forum posts. Right now we have to add them as students, which isn't ideal.

===Former Student===
This role would be of particular use for courses with rolling enrollments. This role would be one where a student had completed all of the requirements of a course (ie assignments, quizzes etc.) but wished to have continued access to the course material for review or consultation. The key factor is that one would give access to the completed student to the notes he read, his work and the teacher's comments on it, but he would not be allowed to do anything that would take up the teacher's time. In other words, a sort-of read-only access to the course. How forums, which might contain pertinent information and would continue to grow, would be handled is a question. Perhaps the student would be shown only what was in the forums at the time he completed the course. He would not be allowed to see any new posts or add any himself. Same thing for database and glossary entries. In other words, a snapshot of the course at the time his regular enrollment ended. He shouldn't be able to see the names or profiles of any newly enrolled students for privacy reasons-hence the restrictions on forum access. One issue that would have to be dealt with would be changes to existing modules-such as resources. Does the student get access to the module as it was or as it is? We have no versioning of resources in Moodle so this would be a problem. What about a teacher changing a quiz question so that the answer is different? What would a former student see?

===Alumnus=== An ALUMNUS should be able to search for all other ALUMNI of the school, interact with them and be enrolled in a seperate course - which is like a META course with all the content of his learning and interaction - as well as capabilities to be a part of this ALUMNI only course. All the teachers of courses during school years should automatically be a part of the ALUMNI course .. which means when an ALUMNUS is enrolled in a course, the original teachers of all his courses get enrolled ? --[[User:Anil Sharma|Anil Sharma]] 20:54, 15 July 2006 (WST)

===Librarian===

Reference Librarians have an active role in most of the courses taught at some schools such as Earlham College (with Bibliographic Instruction). The Librarian role within Moodle could encompass default read access to all courses (unless prohibited by course teacher) and read access to all components of the course unless access is barred (again by teacher). The Librarians would also perhaps have a block called perhaps Reference Services or Reference Desk with write access where they could deposit resources. Also this block might have a chat applet whereby enrolled students could chat to the Reference Librarian on duty about their bibliographic research needs.

In schools there is often a book review system. This may be covered by the lending system database but may not in which case a librarian may neeed to have a course area they can create a database template to handle the reviews in which case they may have a normal teacher style role? Off topic but course an integration with common schools database systems would be great.

===Teacher===

Teachers should have read access to other Teacher's courses unless explictly prohibited. They should be able to set parts of their own course to be totally private (perhaps even to admin?). Just as each activity can currently be set to have group access, each activity could have a permissions field. Teachers could set default permissions for all activities on their course (eg they might disallow Librarian access for example) and then change the access permission for an individual activity.

I think that what is needed is a simple heirarchy of permissions and levels of granularity.

I would take issue with "teachers should have read access to other teacher's courses unless explicitly prohibited." This is a violation of the students' privacy as how they perform and what they do in one class isn't the business of another teacher. Moreover, in the real world a teacher wouldn't suddenly go sit in on a colleague's class without asking permission first. I would not have appreciated such an invasion of privacy as either a teacher or a student. It could be an option, but shouldn't be default.--[[User:N Hansen|N Hansen]] 19:54, 12 June 2006 (WST)

===Community Education Tutors/Trainers===
Teachers may be community adult education trainers making use of a school moodle so must only have access to their courses unless given access elsewhere. They would not necessarily get the default teacher privileges.

===Secretary/Student Worker===

We often have faculty who want their departmental secretary or student worker to scan and upload files and perhaps create resources. Currently they have to be given teacher access to the course. This is dangerous from a FERPA standpoint since they could easily get access to grades.

===Teaching Assistant===

Our Faculty frequently have undergraduate students acting as Teaching Assistants. These students need to be able to add resources, create assignments, and possibly grade assignments. However, due to FERPA they cannot have access to other students' overall grade information. I think the requirements here are slightly different than those of Secretary/Student Worker

===Student - FERPA rights===

A student that has asserted their FERPA rights to non-disclosure. Typically includes not publishing their name
in any public place. Could include this student only being seen with an "alias" within course spaces. Is this an attribute rather
than a role?

===Help Desk===

Help desk agents that have read access for the purposes of trouble shooting. Some care in placing this role within a hierarchy
of inheritance is needed, full access will be problematic with FERPA.

===Admin - Catgory based===

Basically a person in between full Admin and Creator that has the permissions of an Admin but only with respect to courses and students. Currently a Creator has permissions site-wide which does not always meet the requirements of a given organisation (e.g. Department A may not be happy that a person from Department B can create/modify courses within Department A's area). The ability to designate a Creator within a specific category would allow areas to be set up for a faculty/department/organisation and allow the Admin for that area to create/delete courses, upload users, add site-wide entries to the calendar etc.

===Process Roles===

organising the learning process for a group you wish to have the choice to place students in differnt roles: examples of this are:
* Give a student the role of forum-moderator with edit and chunk-rights
* Give students different roles & rights in a Webquest design (and change these roles next week
* Give students different resources, depending of their roles in a rolegame/simulation
* Give a student the rights to create the section content of next week (and only that week..)

==Things to finish for 1.7 Beta==
'''18 Sept 2006'''

#Remove core references to user_student, user_teacher, user_admin, user_coursecreator tables. [Yu]
#Address function: isteacher, isadmin, isstudent [Yu]
#Remove "view" capabilities from all modules unless required [Vy]
#Remove all old references from remaining Blocks [Vy]
#Metacourses [Skodak]
#Add risks to GUI[Skodak]
#Enrolment plugins [Martin and Alastair]
#[[Stats_roles_1.7|Statistics]] [Penny]
#Fix Loginas
#Add category-level assigns [Yu]
#[[Backup_roles_1.7|Backups]] [Eloy?]

===Proposal for interface enhancement===
Martin asked some questions, here are my answers. The sketches below are not worked out proposals. Their task is to visualize the idea. The exact colours and functionality may be defined after possible agreement about the proposals. The Green, orange and red columns support the meaning of the options from "allow" to "prohibit" (If you may want to see larger images please click onto the image or the "Enlarge" icon below the image.)

The list of possible settings is very long and '' "... the problem is not to overwhelm people with information" ''.

[[Image:01_moodle_define_roles_structured.png|thumb=01_moodle_define_roles_structured_pre.png]]

1) One proposal is to use colour to structure the sections and the columns. Picture 1 shows that the user can keep a much better overview when the list is divided into meaningful different coloured columns and clear sections.
 

[[Image:02_moodle_define_roles_collapsed.png|thumb=02_moodle_define_roles_collapsed_pre.png]]

2) A second proposal is to reduce the amount of information the user is shown at the same time. The YUI interface library offers great support to show/hide sections of the page by clicking on specific elements.

For example click on an icon beside the sub heading "Course categories" and show/hide all table rows with the CLASS "course-category".
 

[[Image:03_moodle_define_roles_tooltip.png|thumb=03_moodle_define_roles_tooltip_pre.png]]

3) '' "The main problem is the last column for risk ... we were thinking of putting little icons in there ..." ''
Icons are good when they tell the user more about possible actions/meanings then the letters. I am not sure if this is the case here. For both - icons or letters - the YUI tool-tip function would be able to give the user valuable information about the meaning.
 

==See also==

*[[Hardening new Roles system]]
*[[Roles and modules]]
*Using Moodle course:
**[http://moodle.org/mod/forum/view.php?f=941 Roles and Capabilities forum]
**Key discussions at Using Moodle forums:
***[http://moodle.org/mod/forum/discuss.php?d=38788 Roles and Permissions architecture]
***[http://moodle.org/mod/forum/discuss.php?d=56302#256313 An example of admin roles as set in the database]

[[Category:Roles]]
[[Category:Roles]]

[[fr:Developpement:Roles]]