MoodleDocs - User contributions [en]

Logging 2

2013-07-10T00:58:56Z

Gallegre: logging of long events (moved)

{{Work in progress}}
{{Infobox Project
|name = Logging stage 2
|state = In very early specification
|tracker = MDL-37658
|discussion =
|assignee = moodle.com DEV team
}}

= Mandate =

To rewrite the logging API in Moodle to:
* Capture richer information from plugins/core about actions.
* Cover “all” of Moodle.
* Provide control over how much is logged.
* Improve efficiency by separating writing and reading so it can scale.
* Allow simpler control over how much logging history is kept.
* Support research, reporting and analytics.
* Support personal timelines.

= Why is Logging an important topic? =

Logging is fundamental to research, reporting and analytics.

* Not much of new Moodle development is based on measured data. We need to
** Prove there is a problem
** Prove that a given change is an improvement.
*Data comes from logging
*Better data would allow researchers to study what happens in online teaching.
*Better data would give admins more feedback on how to run their site (both technically and process)
*Better data would give teachers better feedback to improve their teaching process.
*Better data would give students better feedback to improve the learning process.
*We can't predict all the analysis that might happen in future.

= Examples of possible developments that would require better logs =

Here are some random ideas, please add more!

* Timely notifications of critical events (defined by users), eg more than five people posted in the same forum within an hour.
* "Red circle" notification badge counter icons everywhere in Moodle highlighting things that need attention for each user.
* Colour heatmaps overlaid on course page showing recent usage patterns on a course
* Visualisation of live activity across a whole site (for admins)
* Live engagement analytics that take every little action into account
* Identification of students at risk based on complete history

= Existing Problems =

* Logging is added adhoc by developers, has spotty coverage. No admin logging!
* Some logged actions do not contain necessary information.
* Performance and scalability problem.
** Log tables are joined in many popular queries and are slow.
** All logs go to database and it's not scalable.
** It is not possible to configure level of logging
** Large number of database writes even when carrying out ‘read-only’ requests.
* No archiving, so have to delete old logs.
* Deletion is wholesale, no control.
* No synchronization with server logs to help debugging performance issues
* No storage of traces when there are problems, so we can debug Moodle issues

= Existing log usage analysis =

See [[Logging_usage]]

= Places where we need more logs =
* Errors and warnings
** People report errors, but cannot duplicate it.
** Logging history with stack trace would be very useful
** Also dump session variables and all other data that can be useful for debugging
* Admin activities
* Micro activities in a page (more than one per load)
* AJAX calls (eg on course page)
* Should be careful about logging confidential information (e.g. do not log any POST data)
* Shouldn’t delete logs when course is deleted
* All events should all be logged
** Add more events (they are cheap and very useful)
** Need more standardisation of event data for all triggered events
** Add a catch-all handler that pushes events to the logging system
* --> Action logging improvements META - MDL-28443
* Logging of long events (such as ldap synchronization) should have
** one unique identifier per event (like for example postfix mail server) to help admin monitor the cron processes
** at least 2 log entries (begining and end) for each event, possibly more

= Logging Proposal =

This section is deliberately not called "Logging API" because Moodle does not provide any logging API. All plugins that perform logging and analyse logs to display reports can do it as they wish.

* In places where we previously added information to 'the' log we must generate the new event.
* The standard Moodle distribution will include simple DB logging plugin storing the data in new format. There will also be an section (optional) legacy logging plugin that will store data in the old format in {log} table. All standard reports will be upgraded to use the new logging system that will use a logging retrieval plugin to access log information. Custom report plugins will be able to query the {log} table, but should ideally shift to the new logging system over time, so that organisations are not forced to continue double logging.

== Example scenario ==

# Student submits an assignment.
# Event is triggered by assignment module.
# The logging handler (plugin) observes the event and determines if it is log-worthy.
# The logging handler decides which plugin(s) will store the log.
# Logging storage plugin(s) stores the information about the submission (on disc, in DB or wherever).
# Teacher requests report of student submissions.
# Report requests user submission counts from the logging access API (plugin).
# The logging API decides which logging retrieval plugin can supply the submission counts and requests it.
# The chosen logging retrieval plugin responds to the logging API with submission count.
# The logging API returns the counts.
# Report receives counts and displays count.

== From event to report ==

There are four steps of how event is converted into report:

# Handling of events and filtering what needs to be logged.
# Storing the events data in the log storage (DB, filesystem, etc.).
# Retrieving the data from log storage - each plugin implements some methods to query and extract logs back to Moodle.
# Displaying the data in the report.

One plugin can cover one or several steps. It is also possible to create a report that has built-in logging and listens to events (all 4 steps). Also external logging systems do not need to care about steps 3 and 4 at all.

Moodle standard distribution provides a suggestion on logging-report chain that can be followed by 3rd party plugins and may be not.

[[Image:logging_plugins_relation.png|frame|center|Logging plugins relation]]

[[Image:logging_sequence.png|frame|center|Logging plugins sequence diagram]]

== Standard logging plugins ==

Standard Moodle 2.6 distribution will include 3 plugins:

=== Event logging handling plugin (tool_eventobserver) ===

Responsible for step 1 from above. Has functions pluginname_register_log_instance() and pluginname_unregister_log_instance() that allow to add/remove log storage instance and also allows admin to configure what kind of events to store for each log instance.

=== Event logging DB storage plugin (tool_logdbstorage) ===

Responsible for step 2 from above. Has function pluginname_get_log_instances(). Allows admin to create storage instances and assign event handling plugin to fill each of them

=== Event logging driver plugin (tool_logdbdriver) ===

Responsible for step 3 from above. This plugin can only work with tool_logdbstorage. It provides functions to access data in log.

== Mockups ==
=== Log storage settings page===
[[File:dblogstoragemockup.png |frame|center| Log storage settings page]]
=== Log storage Instance configuration page===
[[File:dblogstorageinstancemockup.png |frame|center| Log storage instance configuration page]]
=== File log instance configuration page===
[[File:Filelogger.png |frame|center| File Log instance configuration page]]
=== Event observer initial configuration page ===
[[File:event-observer.png |frame|center| Event observer initial configuration page]]
=== Event observer individual logging device event management page ===
[[File:event-observer-2.png |frame|center| Event observer individual logging device event management page]]

== Summary ==

We can't actually predict all the use cases so we must think generically and plan for worst cases.

* Things that don't need to use logs should not use logs. (Recent activity, etc)
* Make logging calls as cheap as possible
* Use Events API for the originating calls to create lots of hooks for other things
* Use MUC-like plug-ins to determine where to put logs permanently (NoSQL, SAS, file...). Default will be to the current log table.
* Log everything we possibly can think of.
* Define log level settings (on each logging call) so different sites can choose what they want logged and so control size, speed etc
* add_to_log retained for backward compatibility, make it a wrapper for new logger function.
* provide hooks to expose logs everywhere. For example, each page should have a link that shows logs and stats for that page.

=See also=

* [[Event 2]]

Example logging systems:
* http://logstash.net/
* http://fluentd.org/
* http://logging.apache.org/log4php/

Examples of data-based learning technology development:
* http://onlinelibrary.wiley.com/doi/10.1111/j.1467-8535.2008.00928.x/abstract
* http://www.sciencedirect.com/science/article/pii/S0360131510000461 -> qtype_pmatch
* http://www.tandfonline.com/doi/abs/10.1080/02680513.2011.567754
* http://oro.open.ac.uk/24619/

Logging 2

2013-07-10T00:52:06Z

Gallegre: /* Examples of possible developments that would require better logs */ + long events begin/end

{{Work in progress}}
{{Infobox Project
|name = Logging stage 2
|state = In very early specification
|tracker = MDL-37658
|discussion =
|assignee = moodle.com DEV team
}}

= Mandate =

To rewrite the logging API in Moodle to:
* Capture richer information from plugins/core about actions.
* Cover “all” of Moodle.
* Provide control over how much is logged.
* Improve efficiency by separating writing and reading so it can scale.
* Allow simpler control over how much logging history is kept.
* Support research, reporting and analytics.
* Support personal timelines.

= Why is Logging an important topic? =

Logging is fundamental to research, reporting and analytics.

* Not much of new Moodle development is based on measured data. We need to
** Prove there is a problem
** Prove that a given change is an improvement.
*Data comes from logging
*Better data would allow researchers to study what happens in online teaching.
*Better data would give admins more feedback on how to run their site (both technically and process)
*Better data would give teachers better feedback to improve their teaching process.
*Better data would give students better feedback to improve the learning process.
*We can't predict all the analysis that might happen in future.

= Examples of possible developments that would require better logs =

Here are some random ideas, please add more!

* Timely notifications of critical events (defined by users), eg more than five people posted in the same forum within an hour.
* "Red circle" notification badge counter icons everywhere in Moodle highlighting things that need attention for each user.
* Colour heatmaps overlaid on course page showing recent usage patterns on a course
* Visualisation of live activity across a whole site (for admins)
* Live engagement analytics that take every little action into account
* Identification of students at risk based on complete history
* Logging of long events (such as sync with ldap) should have 1) one identifier per event and 2) at least 2 log entries (begining and end) for each event, possibly more

= Existing Problems =

* Logging is added adhoc by developers, has spotty coverage. No admin logging!
* Some logged actions do not contain necessary information.
* Performance and scalability problem.
** Log tables are joined in many popular queries and are slow.
** All logs go to database and it's not scalable.
** It is not possible to configure level of logging
** Large number of database writes even when carrying out ‘read-only’ requests.
* No archiving, so have to delete old logs.
* Deletion is wholesale, no control.
* No synchronization with server logs to help debugging performance issues
* No storage of traces when there are problems, so we can debug Moodle issues

= Existing log usage analysis =

See [[Logging_usage]]

= Places where we need more logs =
* Errors and warnings
** People report errors, but cannot duplicate it.
** Logging history with stack trace would be very useful
** Also dump session variables and all other data that can be useful for debugging
* Admin activities
* Micro activities in a page (more than one per load)
* AJAX calls (eg on course page)
* Should be careful about logging confidential information (e.g. do not log any POST data)
* Shouldn’t delete logs when course is deleted
* All events should all be logged
** Add more events (they are cheap and very useful)
** Need more standardisation of event data for all triggered events
** Add a catch-all handler that pushes events to the logging system
* --> Action logging improvements META - MDL-28443

= Logging Proposal =

This section is deliberately not called "Logging API" because Moodle does not provide any logging API. All plugins that perform logging and analyse logs to display reports can do it as they wish.

* In places where we previously added information to 'the' log we must generate the new event.
* The standard Moodle distribution will include simple DB logging plugin storing the data in new format. There will also be an section (optional) legacy logging plugin that will store data in the old format in {log} table. All standard reports will be upgraded to use the new logging system that will use a logging retrieval plugin to access log information. Custom report plugins will be able to query the {log} table, but should ideally shift to the new logging system over time, so that organisations are not forced to continue double logging.

== Example scenario ==

# Student submits an assignment.
# Event is triggered by assignment module.
# The logging handler (plugin) observes the event and determines if it is log-worthy.
# The logging handler decides which plugin(s) will store the log.
# Logging storage plugin(s) stores the information about the submission (on disc, in DB or wherever).
# Teacher requests report of student submissions.
# Report requests user submission counts from the logging access API (plugin).
# The logging API decides which logging retrieval plugin can supply the submission counts and requests it.
# The chosen logging retrieval plugin responds to the logging API with submission count.
# The logging API returns the counts.
# Report receives counts and displays count.

== From event to report ==

There are four steps of how event is converted into report:

# Handling of events and filtering what needs to be logged.
# Storing the events data in the log storage (DB, filesystem, etc.).
# Retrieving the data from log storage - each plugin implements some methods to query and extract logs back to Moodle.
# Displaying the data in the report.

One plugin can cover one or several steps. It is also possible to create a report that has built-in logging and listens to events (all 4 steps). Also external logging systems do not need to care about steps 3 and 4 at all.

Moodle standard distribution provides a suggestion on logging-report chain that can be followed by 3rd party plugins and may be not.

[[Image:logging_plugins_relation.png|frame|center|Logging plugins relation]]

[[Image:logging_sequence.png|frame|center|Logging plugins sequence diagram]]

== Standard logging plugins ==

Standard Moodle 2.6 distribution will include 3 plugins:

=== Event logging handling plugin (tool_eventobserver) ===

Responsible for step 1 from above. Has functions pluginname_register_log_instance() and pluginname_unregister_log_instance() that allow to add/remove log storage instance and also allows admin to configure what kind of events to store for each log instance.

=== Event logging DB storage plugin (tool_logdbstorage) ===

Responsible for step 2 from above. Has function pluginname_get_log_instances(). Allows admin to create storage instances and assign event handling plugin to fill each of them

=== Event logging driver plugin (tool_logdbdriver) ===

Responsible for step 3 from above. This plugin can only work with tool_logdbstorage. It provides functions to access data in log.

== Mockups ==
=== Log storage settings page===
[[File:dblogstoragemockup.png |frame|center| Log storage settings page]]
=== Log storage Instance configuration page===
[[File:dblogstorageinstancemockup.png |frame|center| Log storage instance configuration page]]
=== File log instance configuration page===
[[File:Filelogger.png |frame|center| File Log instance configuration page]]
=== Event observer initial configuration page ===
[[File:event-observer.png |frame|center| Event observer initial configuration page]]
=== Event observer individual logging device event management page ===
[[File:event-observer-2.png |frame|center| Event observer individual logging device event management page]]

== Summary ==

We can't actually predict all the use cases so we must think generically and plan for worst cases.

* Things that don't need to use logs should not use logs. (Recent activity, etc)
* Make logging calls as cheap as possible
* Use Events API for the originating calls to create lots of hooks for other things
* Use MUC-like plug-ins to determine where to put logs permanently (NoSQL, SAS, file...). Default will be to the current log table.
* Log everything we possibly can think of.
* Define log level settings (on each logging call) so different sites can choose what they want logged and so control size, speed etc
* add_to_log retained for backward compatibility, make it a wrapper for new logger function.
* provide hooks to expose logs everywhere. For example, each page should have a link that shows logs and stats for that page.

=See also=

* [[Event 2]]

Example logging systems:
* http://logstash.net/
* http://fluentd.org/
* http://logging.apache.org/log4php/

Examples of data-based learning technology development:
* http://onlinelibrary.wiley.com/doi/10.1111/j.1467-8535.2008.00928.x/abstract
* http://www.sciencedirect.com/science/article/pii/S0360131510000461 -> qtype_pmatch
* http://www.tandfonline.com/doi/abs/10.1080/02680513.2011.567754
* http://oro.open.ac.uk/24619/

User:Allegre Guillaume

2012-07-23T10:41:35Z

Gallegre:

Hello,

I use Moodle in a professional context : I am co-leader of [http://www.silecs.info SILECS],
a small free software IT service company based in Grenoble, France.
Our customers are mainly french universities.
We propose to them Moodle installation, customization and support.

For the documentation effort, I try to participate in the french documentation, by
updating obsolete translations and beginning new ones.

I also try to contribute to english documentation, mainly by completing existing pages, sharing my experiences.
My philosophy is "write the doc you'd like to have found".

[[fr:Utilisateur:Allegre Guillaume]]

Frankenstyle

2012-07-23T10:36:10Z

Gallegre: /* Usage */ + config_plugins

'Frankenstyle component names' refers to the naming convention that is used to uniquely identify a Moodle plugin based on the type of plugin and its name. They are used throughout the Moodle code (with a notable exception being the css class names in the themes).

Martin Dougiamas invented the word 'frankenstyle' to describe this naming system which was invented by Petr Skoda.

== Format ==

Frankenstyle component names have a prefix and then a folder name, separated by an underscore.

# The prefix is determined by the type of plugin. For example, the prefix for an activity module is '''mod'''.
# The name is the folder name of the plugin, always lower case. For example, the name for Quiz is '''quiz'''.

So the frankenstyle component name for the quiz module is '''mod_quiz'''.

== Plugin types ==

{| class="nicetable"
|-
! Plugin type
! Frankenstyle prefix
! Moodle path
|-
| [[Activity modules]]
| mod
| /mod
|-
| [[Admin reports]]
| report
| /admin/report
|-
| [[Admin tools]]
| tool
| /admin/tool
|-
| [[Assignment types]]
| assignment
| /mod/assignment/type
|-
| [[Authentication plugins]]
| auth
| /auth
|-
| [[Blocks]]
| block
| /blocks
|-
| Core subsystems
| core
| / (not a true plugin, see below for details)
|-
| [[Course formats]]
| format
| /course/format
|-
| [[Course reports]]
| coursereport
| /course/report
|-
| [[Database fields]]
| datafield
| /mod/data/field
|-
| [[Database presets]]
| datapreset
| /mod/data/preset
|-
| [[Editors]]
| editor
| /lib/editor
|-
| [[Enrolment plugins]]
| enrol
| /enrol
|-
| [[Filters]]
| filter
| /filter
|-
| [[Gradebook export]]
| gradeexport
| /grade/export
|-
| [[Gradebook import]]
| gradeimport
| /grade/import
|-
| [[Gradebook reports]]
| gradereport
| /grade/report
|-
| [[Grading methods]]
| gradingform
| /grade/grading/form
|-
| [[Local plugins]]
| local
| /local
|-
| [[Messaging consumers]]
| message
| /message/output
|-
| [[Mnet services]]
| mnetservice
| /mnet/service
|-
| [[Plagiarism plugins]]
| plagiarism
| /plagiarism
|-
| [[Portfolio plugins]]
| portfolio
| /portfolio
|-
| [[Question behaviours]]
| qbehaviour
| /question/behaviour
|-
| [[Question formats]]
| qformat
| /question/format
|-
| [[Question types]]
| qtype
| /question/type
|-
| [[Quiz reports]]
| quiz
| /mod/quiz/report
|-
| [[Repository plugins]]
| repository
| /repository
|-
| [[SCORM reports]]
| scormreport
| /mod/scorm/report
|-
| [[Themes]]
| theme
| /theme
|-
| [[User profile fields]]
| profilefield
| /user/profile/field
|-
| [[Webservice protocols]]
| webservice
| /webservice
|-
| [[Workshop allocation strategies]]
| workshopallocation
| /mod/workshop/allocation
|-
| [[Workshop evaluation plugins]]
| workshopeval
| /mod/workshop/eval
|-
| [[Workshop grading forms]]
| workshopform
| /mod/workshop/form
|}

To get a definitive list in your version of Moodle 2.x, use a small Moodle script with <tt>print_object(get_plugin_types());</tt>.

== Core subsystems ==

Subsystems in Moodle are not plugins themselves but can be referred to using '''core_xxx''' where xxx is the subsystem name as defined in get_core_subsystems().

You can see these being used in the @package parameter in phpdocs, or in the [[Web_services_Roadmap|webservice function names]].

{| class="nicetable"
|-
! Core subsystem
! Frankenstyle component name
|-
| Access
| core_access
|-
| Conditional availability
| core_condition
|-
| Comment
| core_comment
|-
| Completion
| core_completion
|-
| Course
| core_course
|-
| Enrol
| core_enrol
|-
| Files
| core_files
|-
| Forms
| core_form
|-
| Grade
| core_grade
|-
| Groups
| core_group
|-
| Messages
| core_message
|-
| Mnet
| core_mnet
|-
| My home page
| core_my
|-
| Notes
| core_notes
|-
| Ratings
| core_rating
|-
| Role
| core_role
|-
| RSS
| core_rss
|-
| Tag
| core_tag
|-
| User
| core_user
|-
| Web service
| core_webservice
|}

== Usage ==

Frankenstyle component names are used in:

=== Table names ===

All table names for a plugin must begin with its frankenstyle name (after the standard Moodle table prefix).

(The exception to this rule is Moodle activities which (for historical reasons) do not have mod_ in front of the plugin name)

Examples: mdl_'''local_coolreport''', mdl_'''local_coolreport'''_users

=== Plugin configuration table ===

In the '''config_plugins''' table, column '''plugin''', the frankenstyle name is used.

=== Capabilities ===

All capabilities for a plugin use the frankenstyle name, except with a / instead of a _.

Example: '''mod/quiz''':viewattempt

=== Language files===

The main language file for each plugin (with the notable exception of activity modules) is the frankenstyle component name.

Examples: /blocks/participants/lang/en/'''block_participants'''.php

=== Renderers ===

=== Other places (TODO) ===

* @package declarations in phpdocs, see [[Coding_style#PHPDoc]]
* [[Web_services_Roadmap|web service function names]]
* [http://moodle.org Moodle Plugins database]

Please add more as they come up.

==See also==

* [[Plugins]]
* [[Core APIs]]

[[Category:Plugins]]

Plugin types

2012-07-23T10:30:36Z

Gallegre: script for listing plugin types

The M in Moodle stands for modular. The easiest and most maintainable way to add new functionality to Moodle is by writing one of these types of plugin.
If none of the standardized types fits your needs, you can use the "local" type.

You can get the most recent list of types with the following script, or refer to the table below.
<?php
define('CLI_SCRIPT', true);
require('path/to/config.php'); // global moodle config file.
print_object(get_plugin_types());

{| class="nicetable"
|-
! Plugin type
! Component name
! Moodle path
! Description
! Moodle versions
|-
| [[Activity modules]]
| mod
| /mod
| Activity modules are the most important type of plugins. They provide activities in courses. For example: Forum, Quiz and Assignment.
| All
|-
| [[Admin reports]]
| report
| /admin/report
| Provides useful views of data in a Moodle site, for admins only.
| Up to 2.1 (for 2.2+ see [[Reports]])
|-
| [[Admin tools]]
| tool
| /admin/tool
| Provides utility scripts useful for admins to examine and modify a Moodle site
| 2.2+
|-
| [[Assignment types|Assignment 2.2 types]]
| assignment
| /mod/assignment/type
| Different forms of assignments to be graded by teachers
| 1.x - 2.2
|-
| Assignment 2.3 submissions
| assignsubmission
| /mod/assign/submission
| Different forms of assignment submissions
| 2.3+
|-
| Assignment 2.3 feedbacks
| assignfeedback
| /mod/assign/feedback
| Different forms of assignment feedbacks
| 2.3+
|-
| [[Authentication plugins]]
| auth
| /auth
| Allows connection to external sources of authentication
| 2.0
|-
| [[Blocks]]
| block
| /blocks
| Small information-displays or tools that can be moved around pages
| 2.0+
|-
| [[Course formats]]
| format
| /course/format
| Different ways of laying out the activities and blocks in a course
| 1.3+
|-
| [[Course reports]]
| coursereport
| /course/report
| Reports of activity within the course
| Up to 2.1 (for 2.2+ see [[Reports]])
|-
| [[Database fields]]
| datafield
| /mod/data/field
| Different types of data that may be added to databases
| 1.6+
|-
| [[Database presets]]
| datapreset
| /mod/data/preset
| Pre-defined templates for databases
| 1.6+
|-
| [[Editors]]
| editor
| /lib/editor
| Alternative text editors for editing content
| 2.0+
|-
| [[Enrolment plugins]]
| enrol
| /enrol
| Ways to control who is enrolled in courses
| 2.0+
|-
| [[Filters]]
| filter
| /filter
| Automatically convert, highlight, and transmogrify text posted into Moodle.
| 1.4+
|-
| [[Gradebook export]]
| gradeexport
| /grade/export
| Export grades in various formats
| 1.9+
|-
| [[Gradebook import]]
| gradeimport
| /grade/import
| Import grades in various formats
| 1.9+
|-
| [[Gradebook reports]]
| gradereport
| /grade/report
| Display/edit grades in various layouts and reports
| 1.9+
|-
| [[Grading methods]]
| gradingform
| /grade/grading/form
| Interfaces for actually performing grading in activity modules (eg Rubrics).
| 2.2+
|-
| [[Local plugins]]
| local
| /local
| Generic plugins for local customisations
| 2.0+
|-
| [[Messaging consumers]]
| message
| /message/output
| Send messages to users via different methods (email, sms, jabber, etc)
| 2.0+
|-
| [[Plagiarism plugins]]
| plagiarism
| /plagiarism
| Define external services to process submitted files and content
| 2.0+
|-
| [[Portfolio plugins]]
| portfolio
| /portfolio
| Connect external portfolio services as destinations for users to store Moodle content
| 1.9+
|-
| [[Question behaviours]]
| qbehaviour
| /question/behaviour
| Control how student interact with questions during an attempt
| 2.1+
|-
| [[Question formats]]
| qformat
| /question/format
| Import and export question definitions to/from the question bank
| 1.6+
|-
| [[Question types]]
| qtype
| /question/type
| Different types of question (e.g. multiple-choice, drag-and-drop) that can be used in quizzes and other activities
| 1.6+
|-
| [[Quiz access rules]]
| quizaccess
| /mod/quiz/accessrule
| Add conditions to when or where quizzes can be attempted, for example only from some IP addresses, or student must enter a password first
| 2.2+
|-
| [[Quiz reports]]
| quiz
| /mod/quiz/report
| Display and analyse the results of quizzes, or just plug miscellaneous behaviour into the quiz module
| 1.1+
|-
| [[Reports]]
| report
| /report
| Provides useful views of data in a Moodle site for admins and teachers
| 2.2+
|-
| [[Repository plugins]]
| repository
| /repository
| Connect to external sources of files to use in Moodle
| 2.0+
|-
| [[SCORM reports]]
| scormreport
| /mod/scorm/report
| Analysis of SCORM attempts
| 2.2+
|-
| [[Themes]]
| theme
| /theme
| Change the look of Moodle by changing the the HTML and the CSS. See also [[Themes 1.9]].
| 2.0+
|-
| [[User profile fields]]
| profilefield
| /user/profile/field
| Add new types of data to user profiles
| 1.9+
|-
| [[Webservice protocols]]
| webservice
| /webservice
| Define new protocols for web service communication (such as SOAP, XML-RPC, JSON, REST ...)
| 2.0+
|-
| [[Workshop allocation methods]]
| workshopallocation
| /mod/workshop/allocation
| Define ways how submissions are assigned for assessment in the [[Workshop]] module
| 2.0+
|-
| [[Workshop evaluation methods]]
| workshopeval
| /mod/workshop/eval
| Implement the calculation of the grade for assessment (grading grade) in the [[Workshop]] module
| 2.0+
|-
| [[Workshop grading strategies]]
| workshopform
| /mod/workshop/form
| Define the type of the grading form and implement the calculation of the grade for submission in the [[Workshop]] module
| 2.0+
|}

==See also==
* [[Guidelines_for_contributed_code|Guidelines for contributing code]]
* [[Core APIs]]
* [[Frankenstyle]]
* [http://moodle.org/plugins Moodle Plugins database] - lists all the modules that people have contributed

[[Category:Coding guidelines|Plugins]]
[[Category:Plugins]]

Course reports

2012-07-20T18:50:30Z

Gallegre: Removed obsolete or incorrect documentation about mod.php

Course reports

2012-07-20T18:48:17Z

Gallegre: added correct documentation for menu entries

A course report plugin is just another folder inside course/report/. It follows standard plugin practice and may have lang, db etc. sub-folders if these are required. A version.php file must be included.

In order to add a menu entry for your plugin, you must define a function named ''FOOBAR_report_extend_navigation'' in your ''lib.php'' file, where FOOBAR is your plugin name.
For example, for a module named ''synopsis'' (coursereport_synopsis in standardized form), the code will be :

function synopsis_report_extend_navigation($reportnav, $course, $context) {
$url = new moodle_url('/course/report/synopsis/index.php', array('id' => $course->id));
$reportnav->add(get_string('Synopsis', 'coursereport_synopsis'), $url);
}

A mod.php file must be included. This is responsible for creating the HTML fragment that will appear on the course report page as one of the report options. This can be anything. Typically, it will simply generate a link to another page in the report folder (usually index.php) that produces the report. It may, like the logs report generate a form to be completed.

[[Category:Plugins]]

User:Allegre Guillaume

2008-05-22T14:14:24Z

Gallegre: first english version

Hello,

I use Moodle in a professional context : I am co-leader of [http://www.silecs.info SILECS],
a small free software IT service company based in Grenoble, France.
We propose to our customers Moodle installation, customization and support.

For the documentation effort, I try to participate in the french documentation, by
updating obsolete translations and beginning new ones.
I also have already added small details to the english documentation.

[https://docs.moodle.org/fr/index.php?title=Utilisateur:Allegre_Guillaume French version of my homepage]

Talk:Repository API

2008-03-05T23:04:17Z

Gallegre: /* Editing Repository Files / Version Control ? */

(Ideas will be deleted from the comments section as they are resolved or merged into the main spec)

===Missing concept of trusted files===
Files are not created equal, some of them are to be trusted, some can not be trusted at all. Web browsers trust everything received from the server, files from server may access cookie information and thus scripting technologies may allow them to do anything user can do. We do have to trust our teachers because they are supposed to create the learning content, but we definitely can not trust all students.

Imagine if students were allowed to upload arbitrary files to server, like html file loaded with javascript and the server would happily serve them to all Moodle users. Our solution is to use html cleaning filters for submitted texts and force downloads of student uploaded files. To do this we must know if we trust the files or not. Unfortunately the forced downloads of student uploaded files and cleaning of html texts does not solve all problems, because bugs in browsers and especially browser plug-ins may sometimes be used to work around our protections.

The best solution would be to use separate web addresses for trusted and not trusted files (two wwwroots in config.php), not all sites may afford two different addresses but we should be imo prepared for this. [[User:Skodak|Skodak]] 16:42, 28 February 2008 (CST)

Great idea, yes. In fact couldn't all the files be served via $CFG->fileroot all the time?
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

userid field could be used for this, but separate flag might be better in order to allow teachers to upload untrusted files (teacher uploads assignment submission for the student).

===Relative file links===
Flash, Java and SCORM require relative links and directory hierarchy in general - we must support it. Some SCORM packages load hundreds of files per page which means the file serving must be very fast with minimum of db access.

Reading the proposal above it seems the API is about serving of isolated files referenced by repository ids. HTML requires to use relative or absolute locators with file names, we can not use repository ids directly in relative links. In case of scorm we have absolute path to base of SCORM package of given activity and SCORM files use relative links inside the package.
Solution could be to store relative paths directly in filename field ex:directory1/directory2/filename.ext.

Yes I agree, we definitely need to support (virtual) directories and slasharguments.
We could just match the file argument to a path in the db. Perhaps add the fileid
to the argument path as a primary key: fileid/directory1/directory2/filename.ext
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Virtual directories and files===
Sometimes the content of files is generated on the fly (csv exports, etc.), there are many special files spread through codebase doing nearly the same, it should be imho possible to use the same file API for these.

Another virtual example is assignment submissions and webdav. I would like to see an option to browse the assignment submissions as directory structure, the top directory would be a list of names of users, inside html files with online assignment and uploaded files. This would allow us to implement simple zip&go or webdav based offline grading solutions. The problem here is that the content of this virtual submissions directly needs to be created on the fly based on user references, the proposed repository structure can not be used for this.

Very interesting idea! [[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Backup/restore relinking===
We are supporting relinking inside courses only. Till now it was easy to guess if absolute link will work after restore on another server.
There are several types of files:
*course files - relinked during restore, works on any server if from the same course
*module files - not relinked, urls are not permanent, link can not be copypasted (assignments, forum attachments, rss files, etc.)
*user files - not relinked, links work only on original server (blog attachments, personal files, etc.)

I think all this will be simplified in the proposed system because everything is
represented using the same system: a file with an ACL (backup can quickly
determine all the files in one course, probably using one SQL query).
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Access needed for both file and its instances===
We need two types of access control - first who can create instances (link files), second who can access the instance (download the file).

For the first don't we already have those capabilities? (like mod/forum:createattachment,
moodle/course:managefiles) but they probably could use rationalising. We'll need new
ones per repository, too, of course.
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Cache lifetime===
There should be a way to specify cache filetime for each instance of file. For example 0 for uploaded assignments, 1 day for resource file. It might be better to allow modules to decide about this, at present it is hardcoded in file.php.

Great idea. [[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

== Hierarchy in tables ? ==

It's possible that I don't undertand a key piece of the concept, but I wonder why there is no reference to any "parent id" in the file or file_instance table ?
In other words, how the hierarchical structure is supposed to be "imported" from repository to Moodle ?
If the hierarchy is reserved to the course context, and not to the repository context, it seems difficult to allow students to access
to a complete directory, for example.

On the other hand, maybe it's only a question for the "local" repository type, and not to the "generic" repository API ?
[[User:Allegre Guillaume|Allegre Guillaume]] 16:43, 5 March 2008 (CST)

== Editing Repository Files / Version Control ? ==

How do you imagine to handle the "editing file" problem ?
I can see several solutions :
# the simplest way : write access to a file really allows to edit (re-upload) the file, each instance being modified
# the "cheap copy" way : optionally, the modification is applied only to new file_instances (or those for which the teacher forces to). Here you have to handle two (then maybe more) revisions of this file.
This triggers the file revisions (or version control) question.

A related question is about versionned files :
should it depend only upon the repository layer (for example, a plugin could implement a SVN "repository") ?
Or should Moodle be aware of the file "revision number" ?
[[User:Allegre Guillaume|Allegre Guillaume]] 17:00, 5 March 2008 (CST)

Talk:Repository API

2008-03-05T23:00:50Z

Gallegre: Editing Repository Files / Version Control ?

(Ideas will be deleted from the comments section as they are resolved or merged into the main spec)

===Missing concept of trusted files===
Files are not created equal, some of them are to be trusted, some can not be trusted at all. Web browsers trust everything received from the server, files from server may access cookie information and thus scripting technologies may allow them to do anything user can do. We do have to trust our teachers because they are supposed to create the learning content, but we definitely can not trust all students.

Imagine if students were allowed to upload arbitrary files to server, like html file loaded with javascript and the server would happily serve them to all Moodle users. Our solution is to use html cleaning filters for submitted texts and force downloads of student uploaded files. To do this we must know if we trust the files or not. Unfortunately the forced downloads of student uploaded files and cleaning of html texts does not solve all problems, because bugs in browsers and especially browser plug-ins may sometimes be used to work around our protections.

The best solution would be to use separate web addresses for trusted and not trusted files (two wwwroots in config.php), not all sites may afford two different addresses but we should be imo prepared for this. [[User:Skodak|Skodak]] 16:42, 28 February 2008 (CST)

Great idea, yes. In fact couldn't all the files be served via $CFG->fileroot all the time?
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

userid field could be used for this, but separate flag might be better in order to allow teachers to upload untrusted files (teacher uploads assignment submission for the student).

===Relative file links===
Flash, Java and SCORM require relative links and directory hierarchy in general - we must support it. Some SCORM packages load hundreds of files per page which means the file serving must be very fast with minimum of db access.

Reading the proposal above it seems the API is about serving of isolated files referenced by repository ids. HTML requires to use relative or absolute locators with file names, we can not use repository ids directly in relative links. In case of scorm we have absolute path to base of SCORM package of given activity and SCORM files use relative links inside the package.
Solution could be to store relative paths directly in filename field ex:directory1/directory2/filename.ext.

Yes I agree, we definitely need to support (virtual) directories and slasharguments.
We could just match the file argument to a path in the db. Perhaps add the fileid
to the argument path as a primary key: fileid/directory1/directory2/filename.ext
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Virtual directories and files===
Sometimes the content of files is generated on the fly (csv exports, etc.), there are many special files spread through codebase doing nearly the same, it should be imho possible to use the same file API for these.

Another virtual example is assignment submissions and webdav. I would like to see an option to browse the assignment submissions as directory structure, the top directory would be a list of names of users, inside html files with online assignment and uploaded files. This would allow us to implement simple zip&go or webdav based offline grading solutions. The problem here is that the content of this virtual submissions directly needs to be created on the fly based on user references, the proposed repository structure can not be used for this.

Very interesting idea! [[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Backup/restore relinking===
We are supporting relinking inside courses only. Till now it was easy to guess if absolute link will work after restore on another server.
There are several types of files:
*course files - relinked during restore, works on any server if from the same course
*module files - not relinked, urls are not permanent, link can not be copypasted (assignments, forum attachments, rss files, etc.)
*user files - not relinked, links work only on original server (blog attachments, personal files, etc.)

I think all this will be simplified in the proposed system because everything is
represented using the same system: a file with an ACL (backup can quickly
determine all the files in one course, probably using one SQL query).
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Access needed for both file and its instances===
We need two types of access control - first who can create instances (link files), second who can access the instance (download the file).

For the first don't we already have those capabilities? (like mod/forum:createattachment,
moodle/course:managefiles) but they probably could use rationalising. We'll need new
ones per repository, too, of course.
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Cache lifetime===
There should be a way to specify cache filetime for each instance of file. For example 0 for uploaded assignments, 1 day for resource file. It might be better to allow modules to decide about this, at present it is hardcoded in file.php.

Great idea. [[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

== Hierarchy in tables ? ==

It's possible that I don't undertand a key piece of the concept, but I wonder why there is no reference to any "parent id" in the file or file_instance table ?
In other words, how the hierarchical structure is supposed to be "imported" from repository to Moodle ?
If the hierarchy is reserved to the course context, and not to the repository context, it seems difficult to allow students to access
to a complete directory, for example.

On the other hand, maybe it's only a question for the "local" repository type, and not to the "generic" repository API ?
[[User:Allegre Guillaume|Allegre Guillaume]] 16:43, 5 March 2008 (CST)

== Editing Repository Files / Version Control ? ==

How do you imagine to handle the "editing file" problem ?
I can see several solutions :
# the simplest way : write access to a file really allows to edit (re-upload) the file, each instance being modified
# the "cheap copy" way : optionally, the modification is applied only to new file_instances (or those for which the teacher forces to).
This triggers the file revisions (or version control) question.

A related question is about versionned files :
should it depend only upon the repository layer (for example, a plugin could implement a SVN "repository") ?
Or should Moodle be aware of the file "revision number" ?
[[User:Allegre Guillaume|Allegre Guillaume]] 17:00, 5 March 2008 (CST)

Talk:Repository API

2008-03-05T22:43:01Z

Gallegre: Hierarchy in tables ?