MoodleDocs - User contributions [en]

Logging 2

2014-08-18T21:48:18Z

Raymor: /* Benefits of the new logging system */

{{Infobox Project
|name = Logging stage 2
|state = Completed
|tracker = MDL-37658
|discussion = https://moodle.org/mod/forum/discuss.php?d=235318
|assignee = moodle.com BACKEND team
}}

= Benefits of the new logging system =
A few benefits of the new logging system are:
* it allows capture of richer information from Moodle about actions;
* it provides control over how much information is logged;
* it abstracts log writing and reading so logging can be scaled;
* it lets you write/read logs to/from any external system through the use of logstore plugins;
* it allows control over how much logging history is kept; and
* it supports research, reporting and analytics.

== Why is Logging an important topic? ==

Logging is fundamental to research, reporting and analytics. Logging allows informed, evidence based decisions to be made.

It is important that changes to Moodle are based on measured data. We need to be able to:
* prove there is a problem and
* prove that a given change is an improvement.

Logging data can be used by different Moodle users.
* Better data allows researchers to study what happens in online teaching.
* Better data gives admins more feedback on how to run their site - both technically and in relation to processes. (Please note this change is not about profiling).
* Better data gives teachers better feedback to improve their teaching processes.
* Better data gives students better feedback to improve their learning.

We can't predict all forms of analysis that might happen in future.
* The logging system needs to be flexible in order to accommodate applications by these different users.
* The logging API needs to be constructed in a way that is possible to improve in future.

== Problems with the old logging approach ==

The old logging infrastructure had a number of issues that were resolved by this project.
* Logging was added ad-hoc by developers and had spotty coverage.
* Some logged actions did not contain important information needed later.
* There were performance and scalability problems, such as:
** log tables were joined in many popular queries and were slow;
** logged events were stored in a single Moodle database table, which was not scalable;
** it was not possible to configure levels of logging ; and
** it was not possible to disable logging completely.

= Logging =

The new [[Event 2|Events API]] introduced in Moodle 2.6 provides a notification mechanism and single collection point for actions within Moodle. The Events system also defines information about events that can be extended with additional information and functionality by core code and plugins, as needed.

In order to capture events a logging API was specified, consisting of a number of plugin types.

To transition from the old logging system to the new, work was required in a number of areas.

* In places where we previously added information to 'the' log table, we must instead generate a new event.
* The standard Moodle distribution now includes three simple logging storage plugins that will store events in new format (to an internal or external database).
* The original logging code and DB tables are available for full backwards compatibility for users of customised reports. It is possible to enable logging to the old {log} table if required.
* All standard reports have been upgraded to use the new logging system and use a logging retrieval plugin to access log information.
* Custom report plugins (add-ons) will be able to query the {log} table, but should ideally shift to the new logging system over time, so that sites are not forced to continue double logging.

== Old log usage analysis ==

See [[Logging_usage|this analysis]] to see log usage in Moodle 2.5 core code.

== Example scenario ==

'''Writing to the log'''

# A student submits an assignment.
# An event is triggered by the Assignment module.
# The log manager plugin observes the event and determines if it is log-worthy depending on some admin settings.
# The log manager sends the event to all enabled log storage subplugins implementing \tool_log\log\writer. Storage plugins may decide to filter out some events based on their admin settings.
# The log store plugin(s) stores the event data optionally including extra information such as remote IP or original logged-in-as user id.

'''Reading from the log'''

# A teacher opens an activity report.
# The activity report queries available log readers by using the current log manager (implementing \core\log\manager).
# If there is more than one log reader (implementing \core\log\sql_select_reader) available they can select the source of data for the report.
# The report requests events from the log reader and displays them.

== From event to report ==

There are four steps of how event is captured, logged and potentially presented in a report. These steps are summarised in [[#Figure1|Figure 1]] below and can be described as follows.

# Handling of events and filtering what needs to be logged. See interface \core\log\manager below.
# Storing the event data in the log storage (DB, filesystem, etc.). See interface \tool_log\log\writer below.
# Retrieving the data from log storage - each plugin implements some methods to query and extract logs back to Moodle. See interfaces \core\log\reader and \core\log\sql_reader below.
# Displaying the data in the report.

One plugin may cover multiple steps. For example we expect that most of log writer plugins will also implement log reader. It is also possible to create a report that has built-in event handling, log writing and reading and report presentation (all four steps). Also external logging systems may not wish to allow log data they capture to be read back into Moodle, handling such data instead through an external system, so they may not implement steps 3 and 4.

<div id="Figure1" style="text-align:center">
[[File:logging_plugins_relation.png]]
'''Figure 1. Logging plugins relationship diagram'''</div>

The [[#Figure2|Figure 2]] below shows how the requests are made between user actions, plugins and core when:

* configuring logging (which log writer plugins are enabled);
* an event occurs;
* a report is configured (selecting log store) and
* a report is viewed.

<div id="Figure2" style="text-align:center">
[[Image:logging_sequence.png|logging_sequence.png]]
'''Figure 2. Logging plugins sequence diagram'''</div>

== Public API ==

This section describes all interfaces that need to be implemented by log manager and each log storage class.

=== Reading API ===
* '''function \get_log_manager()''' - returns the current log manager if configured or some dummy instance otherwise, it uses the signleton pattern.
* '''interface \core\log\manager''' - log manager interface, in standard distribution implemented by \tool_log\log\manager and \core\log\dummy_manager
** public function get_readers($interface = null) returns the active storages implementing reader interface, returns array(classname => storage instance, ...)
* '''interface \core\log\reader''' - general event reader
** public function get_name() - returns name of the log storage, this will be used when selection data source in reports.
** public function get_description() - some help for admins.
** public function is_logging() - is latest data available?
* '''interface \core\log\sql_select_reader''' extends \core\log\reader - general log storage that supports sql selects (or emulates them)
** public function get_events_select($selectwhere, array $params, $order, $limitfrom, $limitnum) - returns event object instances matching given parameters.
** public function get_events_select_count($selectwhere, array $params) - returns number of events that would be returned from get_events() with the same parameters.
*** $selectwhere is supposed to be a limited sql predicate.
*** The set of operators allowed in $selectwhere are :- =, <>, >, >=, <, <=
*** The set of keywords allowed in $selectwhere are :- IN, BETWEEN, LIKE, IS NULL, IS NOT NULL
*** Logical operators OR, AND
*** NOT operator
*** ( and ) brackets
*** ? and :named parameter placeholders
*** Use of anything besides the mentioned keywords/operators is strictly forbidden.
* '''interface \core\log\sql_internal_reader''' extends \core\log\reader - log storage that can expose data as read-only database view or table.
** public function get_internal_log_table_name() - returns database table or view; structure is described in phpdocs, it will include all columns defined by log_sql

Most reports are expected to use only the reading API. Please note that all non-sql readers need to somehow translate the $selectwhere SQL query syntax.

When reports are searching for log readers, they use the get_log_manager()->get_readers($interface = null) where $interface is the name of reader interface that the report supports.
If there are multiple readers returned by the log manager, then the report is responsible for letting the user choose which storage to create the report on.

=== Writing API ===
* '''interface \tool_log\log\store''' - must be implemented by each store subplugin.
** public function __construct(\tool_log\log\manager $manager) - no parameters, configuration is taken from admin settings.
** public function dispose() - called when reading/writing finished.
* '''interface \tool_log\log\writer''' extends \tool_log\log\store - interface indicating the log store may be used for writing.
** public function write(\core\event\base $event) - called from event observer defined in log manager.

The writing API is defined in tool_log plugin, the log stores are defined as new subplugin of this plugin.

Each log store plugin will be responsible for filtering of events, it may use standardised admin settings and filtering or decide to implement custom filtering.

== Standard logging plugins ==

Standard Moodle distribution will include four plugins.

=== Logging management plugin (tool_log) ===

Defines:

class \tool_log\log\manager implements \core\log\manager;

The log manager is responsible for step 1 from [[#Figure1|Figure 1]] above. It allows admins to configure which log store subplugin is enabled and in which order they appear. The log store plugins are implemented as tool_log subplugins with class "store" in their namespace (\logstore_xxxx\log\store).

The log manager registers a '*' event observer, this observer is external - it means that events are received only when database transactions are not in progress.

=== Standard log storage plugin (logstore_standard) ===

Defines:

class \logstore_standard\log\store implements \core\log\sql_internal_reader, \tool_log\log\writer;

The name logstore_standard does not seem to be optimal - ''logstore_db'' is not allowed because it collides with standard /db/ subdirectory in plugins and ''logstore_database'' should be probably reserved for external database logging (to prevent any confusion).

This log storage plugin is responsible for steps 2 and 3 from [[#Figure1|Figure 1]] above. It is the primary replacement for the former {log} table. The performance will be similar to former log table, but for smaller sites, this simple default will suffice.

Each plugin decides how much data is kept, when it is deleted, etc.

==== Storage settings ====

Each storage plugin with a writer interface is responsible for backlisting or filtering of events. Some of the examples of filtering that can done is as follows.
* Include guests actions (default ''Yes'')
* Include log levels (default ''empty''), accepts constants from [[Event_2#Level_property]]
* Include by CRUD (default ''empty''), accepts C, R, U, and D
* Include by component (default ''empty'')
* Include by event name (default ''empty'')

=== External database log storage plugin (logstore_database) ===

Defines:

class \logstore_database\log\store implements \core\log\sql_select_reader, \tool_log\log\writer;

This log storage plugin is responsible for step 2 only from [[#Figure1|Figure 1]] above. There will be no interface to read from it provided with Moodle core.

=== Legacy log table reader (logstore_legacy) ===

Defines:

class \logstore_legacy\log\store implements \core\log\sql_select_reader, \tool_log\log\store;

This plugin will not conduct any log writing; it will translate existing {log} table data into the new event format and transforms new SQL selects to match the legacy table format. This serves as an emulation layer that allows new reports to access historical data stored in mdl_log table. Users will have to select this datasource manually if they want to see historical data that is not present in new log tables.

In new reports the legacy data will be presented using a special legacy event class that can not be triggered: \logstore_legacy\event\legacy

== Performance ==

Compared to older Moodle versions, the new system will need to deal with higher number of log entries. This has been improved by buffering log entry writes together with new bulk insert operations in the DML layer. Helper traits were introduced \tool_log\helper\buffered_writer to help stores easily buffer the events.

Running new and old event logging at the same time with result in twice the number of DB inserts. It is therefore recommended to disable the old logging as soon as possible.

In [https://tracker.moodle.org/browse/MDL-42894 MDL-42894], a logging API comparison was done and it's results were promising.
{| class="nicetable"
|-
! Enabled Stores
! dbwrites
! dbreads
! Time used
! Session size
! Memory
! Server load
|-
| Legacy + Standard store
| Little increase
| Same
| Same
| Same
| Same
| Increased
|-
| Only Standard store
| Decrease
| Same
| Same
| Same
| Same
| Increased
|-
| Only Legacy store
| Same
| Same
| Same
| Same
| Same
| Decrease
|-
| Neither Legacy nor Standard store
| Decrease
| Same
| Same
| Same
| Same
| Decrease
|}
FYI: Serverload is showing worse in most cases, but as this was done on my local machine with all interference, I am ignoring this for now.
--[[User:Rajesh Taneja|Rajesh Taneja]] ([[User talk:Rajesh Taneja|talk]]) 16:19, 14 February 2014 (WST)

== Screenshots ==
=== Log management page ===
[[File:event-observer.png |frame|center| Log management page]]

=== Log store settings pages ===
[[File:event-observer-2.png |frame|center| settings page for a the standard log setup]]
[[File:external-log-settings.png |frame|center| settings page for an external log: Database setup]]
[[File:external-filter-logs.png |frame|center| settings page for an external log: Filtering]]

== Overarching considerations ==

We can't actually predict all use cases, so we must think generically and plan for worst cases. Here are some overarching principles that will be followed in the implementation of the new logging system.

* Things that don't need to use logs should not use logs. (Recent activity, etc)
* Logging calls should be as cheap as possible.
* The Events API will be the central communication mechanism, allowing lots of potential information gathering tools to exist in future.
* Use plug-ins to determine where to put logs permanently (NoSQL, SAS, file...). Initially, the 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, which allows controls cotrol of log size, speed, etc..
* The functionality of the pre-existing function add_to_log() should be retained for backward compatibility, but allowing admins to disable it.

= Reports =

[[Logging usage#Reports]] describes current reports.

= Migration to new logging API =

== Follow-up Projects ==

* Converting completion to use events - MDL-42897
* Developing a ''Timeline'' page/block so each user to see a stream of activity that is relevant to them individually - MDL-42898

== Related ==

'''Here are some ideas of how new even data and observers can be put to use.''' Please note that the log storage API is not optimised for these tasks.
* Timely notifications of critical events (defined by users), for example more than five people posted in the same forum within an hour.
* "Red circle" notification badge counter icons everywhere in Moodle highlighting things that a user needs to pay attention attention to, such as ???.
* Colour heatmaps overlaid on course pages showing recent usage patterns of the course.
* Visualisation of live activity across a whole site (for admins) (is that logging or event handling?)
* Live engagement analytics reporting ??? that take specific actions into account, such as ???.
* Identification of students at risk based on their involvement in the course (or lack of it).

'''Logging of exceptions, errors and debugging'''

* Logging of Errors and warnings is not part of this specification, it meeds to be handled via a completely separate mechanism.
** People report errors that cannot be duplicated. Logging errors with a stack trace, session variables and other relevant data could be useful for debugging.
* Standard logs may theoretically produce errors and exceptions that need to be logged somewhere else.
* There is no synchronization with server logs to help debugging performance issues. (This will not be addressed by new logging API.)
* There is no logging of error information to help debug Moodle issues. (This will not be addressed by new logging API.)

'''Performance logging and profiling'''

We need to measure the performance of logging system and store the information somewhere.

'''Other'''

* There is no mechanism for archiving, so old logs are deleted and lost.
* Log deletion is indiscriminate, with no control of what log information is deleted or retained.

== Places where we need more logs ==

The principle work of this project is to replace the existing logging API. Once the new system is in place, the coverage of logging around Moodle can be improved.

Suggestions for places in Moodle where logging is needed should be reported as Tracker issues and linked to the Epic MDL-28443 "Action logging improvements". Feel free to echo significant areas here.

* Activities on site, course and activity administration pages.
* Micro activities in a page (more than one per load), such as ???.
* AJAX calls (eg on course page), such as ???.
* Logging of long events (such as an LDAP synchronisation) should have:
** one unique identifier per event (like for example postfix mail server) to help admin monitor the cron processes and
** at least 2 log entries (begining and end) for each event, possibly more.
* Should be careful about logging confidential information. Anonymous events can be used to controll privacy.
* Shouldn’t delete logs when course is deleted. There is no API to delete logs, each log storage controls the rotation or deleting of old data individually.

=See also=

* [[Event 2]]
* [[Migrating logging calls in plugins]]
* [[Migrating reports accessing logs]]

Other 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/
* [http://www.adlnet.gov/tla/lrs/ A Learning Record Store (LRS)] is a system that stores the tracking statements communicated through the [https://github.com/adlnet/xAPI-Spec Experience API (xAPI)]

Policy - Retroactive effects of completion settings

2014-07-07T19:01:11Z

Raymor: /* Summary */

== Summary ==

The question was:

Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

This question was decided by by Martin Dougiamas on Tue Mar 25 per tracker issue MDL-39624. Dougiamas decided:

''Completion of an activity is final and not affected by future settings changes (unless you manually reset it and are warned loudly and students are informed).
''

Documentation of the reasoning, pro and con, is below as it was posted prior to the decision being made.

-----

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. This would not be ideal, but it separating them may be better than the alternatives. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2014-07-07T18:58:07Z

Raymor: /* Summary */

== Summary ==

The question was:

Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

This question was decided by by Martin Dougiamas on Tue Mar 25 per tracker issue MDL-39624

[[Completion of an activity is final and not affected by future settings changes (unless you manually reset it and are warned loudly and students are informed).]]

Documentation of the reasoning, pro and con, is below as it was posted prior to the decision being made.

-----

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. This would not be ideal, but it separating them may be better than the alternatives. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Plugin validation

2014-04-17T15:08:39Z

Raymor: Fixed linked to policy on advertising

Before a plugin can be made available via the [http://moodle.org/plugins/ Moodle Plugins directory] it has to pass both an automatic and a manual validation process. The automatic checks are repeated for each new version of the plugin that is added, however the [http://moodle.org/mod/forum/discuss.php?d=192083#p837517 manual checks are only done for the initial release]. The aim is to complete manual checks within three working days of first submission, but sometimes based on timing and/or allocation of resources, it can take longer than that, so please be patient.

==The process==
Plugin submission --> Waiting for approval --> Approved.
* Waiting for approval --> Needs more work --> Waiting for approval
** Click 'Schedule this plugin for re-approval' under 'Admin block' > '{your plugin}' > 'Schedule this plugin for re-approval' when ready to go back into the approval queue.

Note: Plugin approvers are always get notified on all plugins that aren't approved. Feel free to leave us messages in the plugin comments during this phase.

==Automatic validation==

===General rules for all plugin types===
* Plugin name with [[Frankenstyle]] prefix must be unique in moodle.org/plugins. If there is another plugin with the same name you must either add new versions to this plugin (if it is yours) or rename your plugin if the names are accidentally the same. First in first served.
* The plugin must be uploaded as a single zip file
* The zip file must contain a single subfolder, named after your plugin (although the validator can also automatically rename subfolders generated by repos such as GitHub, which appear in the form 'username-moodle-pluginname-branchname')
* The subfolder must be laid out in such a way that the uploaded file could be unzipped directly into the top-level folder for that plugin type (e.g. an activity plugin called 'myplugin' should install correctly when unzipped in the Moodle /mod folder, creating a subfolder /mod/myplugin with all the standard files within it).
* The subfolder must contain a file called [[version.php]]. It should describe properties like 'version', 'requires', 'cron', 'component', 'maturity', 'release' and 'dependencies' . See exceptions below.
* Language file must be present in lang/en/FULLNAME.php (for Moodle 2.0+) or lang/en_utf8/FULLNAME.php (for Moodle 1.9). FULLNAME is the plugin name with frankenstyle prefix. See exceptions below.
* Language file must declare either $string['modulename'] (for activity modules) or $string['filtername'] (for Filters) or $string['pluginname'] (for all other plugin types). See exceptions below.
* The names of all database tables should start with the full 'frankenstyle' plugin name. For example block_myblock, or auth_paypal. See exceptions below.
* (Recommended) the subfolder should contain a file called README.txt (the validator can automatically rename other extensions to .txt) with details about the current release of the plugin.

Note: If you prefer using a readme.md file, please create a [http://en.wikipedia.org/wiki/Symbolic_link symbolic link] from it to a README.txt file. This way users without any markdown reader can easily doubleclick to open and read the README.txt with their default text editor. See [http://en.wikipedia.org/wiki/NTFS_symbolic_link#Syntax mklink command for Windows] or [http://en.wikipedia.org/wiki/Symbolic_link#POSIX_and_Unix-like_operating_systems ln command for Unix-like systems].

===Exceptions===
* [[version.php]] is required for Moodle 2.5 and onwards. It isn't strictly required (but it is always recommended) for older moodle versions for the following plugin types:
** Themes for Moodle 2.0 to 2.4
** Course formats for Moodle 2.0 to 2.4
** Blocks for Moodle 1.9
** Auth for Moodle 1.9
* language file is not required for plugins for Moodle 1.9 that are not activity modules
* $string['pluginname'] is not required for plugins for Moodle 1.9 that are not activity modules
* Question types for Moodle versions <= 2.1 instead of $string['pluginname'] should declare $string[NAME] (where NAME is the name of the plugin without frankenstyle prefix). Starting from 2.2 this was fixed and $string['pluginname'] shall be used.
* database tables are allowed to skip mod_ prefix for activity modules
* database tables are allowed to have question_ prefix instead of qtype_ for Question types. This is for historical reasons, all newly developed plugins are encouraged to have qtype_ prefix.

===Additional checks for activity modules===
* $module->version defined in version.php
* $module->requires defined in version.php
* file lib.php exists
* file lib.php contains “function xxxx_add_instance”
* file lib.php contains “function xxxx_update_instance”
* file view.php exists
* file index.php exists
* db/install.xml exists
* db/upgrade.php exists
* db/access.php exists

===Checks for particular plugin types===
* Themes: file config.php exists
* Blocks: file block_xxxx.php exists
* Auth: file auth.php exists
* Course formats: file format.php exists

==The Other category in the plugins directory==

If your plugin does not yet meet all the different standards, you are encouraged to add it to the [https://moodle.org/plugins/browse.php?list=category&id=38 Moodle Plugins Directory Other category]. Plugins in this category will be excluded from any automated processes such as installations or updates. Then when the plugin is improved to meet the standards, it can be moved to an another category in the plugins directory.

==Manual checks==
Before the plugin is publicly viewable a trusted reviewer will look through the code to make sure it is a valid plugin. Currently, these checks are completed by [https://moodle.org/user/view.php?id=1146834&course=5 Aparup Banerjee] (who is also part of the Sites team) and [http://moodle.org/user/view.php?id=51473&course=5 Anthony Borrow] (on a volunteer basis), so please bear with us if this sometimes takes a little longer than you expect. These checks include:
* The plugin installs cleanly
* It does not contain any obviously harmful code
* It is not a spam entry (This is somewhat along the lines of the [https://docs.moodle.org/24/en/Policy_on_Advertising policy on advertising] too)
* It is not a duplicate of an already uploaded plugin
* It mentions GPL license (if not a boilerplate atop every file then somewhere in the downloadable zip). (or be [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| completely GPL compatible])
** On what the copyright should be, refer to https://moodle.org/mod/forum/discuss.php?d=213610#p1117434
* It has documentation and referenced URLs in basic english.
* It does not lead to unrelated sites which can simply be linked to in content nor have unnecessarily repeated links.
* Links that facilitate sharing (source control, issue tracker, documentation, discussion) are in the 'Useful links' section where possible.
* Conventions are followed where possible. ( eg: https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code)
* Table config_plugin (not config) is used to store settings particular to a plugin.

Comments made during the review can usually be removed prior to approval if requested.

===Recommended URLs===
We usually request for the following data to be entered along with the plugin entry in order to facilitate easier sharing of information and feedback. So, in order of recommendation, they are :
# [https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code| Code repository], this could be any publicly accessible code repository. The suggested naming convention of the repository is [https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code| moodle-{plugintype}_{pluginname}].
#*Moodle development [https://docs.moodle.org/dev/Process#Develop_the_code_using_Git| uses git] almost 100% of the time as such lots of developers choose to have git repositories for their plugins too. There are popular public repositories, noteably github.com has some support on plugins directory for uploading of versions via a github repository plugin.
# Issue/Bug tracker. This is to enable users and other a quick link to easily report issues they encounter with your plugin.
#*You can choose to have a new component created in [https://tracker.moodle.org/browse/CONTRIB/| Tracker]. You can also choose to have it elsewhere as long as it is publicly accessible. (See [https://moodle.org/mod/forum/discuss.php?d=213419&mode=3| related discussion])
# Documentation. This could be at docs.moodle.org or anywhere publicly accessible.
# Website. This could be to demo, further describe or simply to link to one relevant page.

===Other recommendations===
* Long and short descriptions are populated to allow for easy search/indexing of your plugin.

==Frequently asked questions==
===Q: My code contains several components, why can't I distribute it as a single package?===
A: Moodle's architecture supposes that plugins are installed independently. However you can contact [https://moodle.org/user/view.php?id=1146834&course=5 Aparup] or [http://moodle.org/user/view.php?id=51473&course=5 Anthony] and ask for your plugins to be made into a set.

For versions from Moodle 2.2 onwards you can specify that one plugin depends on another in your [[version.php]] file.

===Q: I don't know which Moodle plugin type I should use. Can I just make a 'local' plugin and get it done?===

A: Most of the time there will be an applicable plugin type that will fit your add-on plugin. Using an appropriate plugin type allows you to use the relevant [[API]] and provide users with a common user interface throughout Moodle. This minimises work for you. The plugin will also be more easily understood by administrators and more people will use it.

We have seen that quite often a local plugin could actually have been an [[Admin tools|admin tool]] plugin, so consider if that is applicable in your case.

Here is the full [https://docs.moodle.org/dev/Plugins list of plugins] to choose from. If you think there is a need for a new plugin type, we're happy to consider API improvements.

For more information about [[Local plugins]], see [https://moodle.org/mod/forum/discuss.php?d=224231 this clarification].

===Q: I've a plugin to share that requires closed (or non-GPL compatible) source software. Can i share this in the plugins directory? ===

A: Yes you can but there are several things you must do to share this properly. Paraphrasing Martin, this is OK to be approved IF (and only if):

1) We give users FULL information on the dependency and what they need to do, in the description of the plugin.
2) We make it explicit that the required code is closed source and that we cannot vouch for it. The risks are all theirs to judge from wherever they obtain the software.

You can use the 'Potential privacy issues' field when editing the plugin to help describe this clearly.

Note: Your plugin must still satisfy other validations, such as not breaking moodle (without the required non-GPL software).

===Q: How to help with language support to any plugin in the plugins directory?===
A: Read this post for the procedure - http://lang.moodle.org/mod/forum/discuss.php?d=2485

==See also==

* [[Plugin documentation]] for information on providing documentation for your plugin right here in docs.moodle.org
* [[Plugin reviews]] for information on how to volunteer to write plugin reviews
* Continuous integration with [https://docs.moodle.org/dev/Travis#Moodle_plugins Travis-ci].

[[Category:Plugins]]

Policy - Retroactive effects of completion settings

2014-03-25T13:49:25Z

Raymor: /* Summary */

== Summary ==

The question was:

Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

This question was decided by by Martin Dougiamas on Tue Mar 25 per tracker issue MDL-37993

[[Completion of an activity is final and not affected by future settings changes (unless you manually reset it and are warned loudly and students are informed).]]

Documentation of the reasoning, pro and con, is below as it was posted prior to the decision being made.

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. This would not be ideal, but it separating them may be better than the alternatives. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2014-03-25T13:21:13Z

Raymor: /* Summary */

== Summary ==

The question was:

Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

This question was decided by by Martin Dougiamas on Tue Mar 25 per tracker issue MDL-37993
https://tracker.moodle.org/browse/MDL-37993

[[Completion of an activity is final and not affected by future settings changes (unless you manually reset it and are warned loudly and students are informed).]]

Documentation of the reasoning, pro and con, is below as it was posted prior to the decision being made.

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. This would not be ideal, but it separating them may be better than the alternatives. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2014-03-25T13:20:26Z

Raymor: /* Summary */

== Summary ==

The question was
Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

This question was decided by by Martin Dougiamas on Tue Mar 25 per tracker issue MDL-37993
https://tracker.moodle.org/browse/MDL-37993

Completion of an activity is final and not affected by future settings changes (unless you manually reset it and are warned loudly and students are informed).

Documentation of the reasoning, pro and con, is below as it was posted prior to the decision being made.

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. This would not be ideal, but it separating them may be better than the alternatives. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2013-05-21T16:21:55Z

Raymor: /* Example */

== Summary ==

There is an open policy question:
Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. This would not be ideal, but it separating them may be better than the alternatives. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2013-05-14T13:08:11Z

Raymor: /* Example */

== Summary ==

There is an open policy question:
Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

[In other words, the new criteria would apply only to currently active students, and removing a post indicates activity. - Ray Morris]

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2013-05-13T18:58:15Z

Raymor: /* Summary */ removed extraneous / redundant word "might"

== Summary ==

There is an open policy question:
Should past activity completions be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== Can changes for these two reasons be separated? (Not really.) ==

(sam marshall)

It will be technically difficult to separate the 'changing based on what a student has done' from 'changing settings'. I think we will need to make the behaviour consistent so that either of two rules applies:

OPTION B: Once a 'completed' or 'completed-passed' completion status is obtained, it should not change unless a teacher manually resets it.

OR (as supposedly true at present)

OPTION A: All completion statuses should change if the conditions or data changes.

(Note that I left completed-failed undefined because we want to let people retry things so it can't be 100% consistent this way...)

In other words I don't think we should attempt to treat 'changes in data' and 'changes in settings' as distinct situations that can be handled differently, as the page above might imply.

=== Example ===

Here's why I think it is impossible to treat the two cases (changes to actual data/user input vs changes to settings) as separate in general. Imagine that we are trying to do so (update 'completed' to 'not completed' for data changes, but not for setting changes). Consider this sequence:

1. In a forum, 3 posts are required for completion.

2. Student A makes 4 posts and is marked complete. Student B makes 3 posts and is marked complete.

3. Somebody changes the settings so that 5 posts are now required. (This is a settings change, so completion states aren't updated.)

4. Somebody deletes one of Student A's posts so that they now only have 3 posts. (This is a data change, so completion state is updated.)

In this situation, there has been a change to the data, so if we are treating those as separate then it is correct to potentially mark the student as not complete. But we do not store the historical values of all the setting, so we have to consider this according to current data; i.e. every time somebody gets a post deleted the system needs to check if they still have more than 5, and student A does not. As a result, student A would be marked 'not complete'.

This would be unfair because both students A and B have made 3 valid posts but B is still marked complete and A is not. (Note: In the current system, both A and B would have been marked incomplete at stage 3. In Option B, both A and B would remain complete; a student C who only made their posts after step 3 would have a disadvantage, but at least that's more easily understood i.e. when teachers change the settings they know they are making it harder for people from now on.)

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2013-05-10T16:30:24Z

Raymor: /* Summary */

== Summary ==

There is an open policy question:
Should past activity completions might be retroactively affected by changes to settings?
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2013-05-10T16:23:32Z

Raymor:

== Summary ==

There is an open policy question as to how past activity completions might be affected by changes to settings, whether or not certain changes should be retroactive.
That is, after a student completes an activity and it's marked as "completed-passed", "completed-failed", etc., might it later become "incomplete"?

As one example, a student might complete a Quiz, with a passing grade. The quiz is marked as completed-passed, which opens up a Certificate. The student prints the certificate and files it with regulators.
Six months later, the teacher decides that from now on the passing grade should be higher. The teacher changes the "grade to pass" setting. Should the student who completed and passed six months prior now
be marked as "failed", and their certificate revoked?

Two major categories of actions were mentioned, and two types of "intentions", or use-case scenarios, with different policies appearing reasonable depending on the type of
action and use-case or intention of the user. Actions can be a) changes to what a student has done , such as submitting or deleting an assignment or b) settings/requirements adjustments by the teacher.
Settings changes may be the result of two types of intentions - a decision that the new requirements should be different from the old, or a correction to an incorrect setting.

== Changes to what a student has done ==

Sam Marshall gave two examples suggesting that when there is a change to what a student has done, that could change the fact that something the student completed something.
<blockquote>
Example 1: If you just use 'on grade' completion, if a student does something and gets a grade, it will be marked complete. If the teacher then deletes their grade from gradebook, it will be marked incomplete again.

Example 2: In forum, if you set it to be complete after making 3 posts, and the student makes 3 posts, it will be marked complete. But if the teacher then deletes one of the posts, it will be marked incomplete again.

It could be argued that things should not be automatically 'un-completed' in this way (there are cases when both the above examples definitely seem appropriate, but it might be OK if the teacher had to manually un-complete them as well)
</blockquote>

No reasoning was posted with an opposing view on what should happen when changes are made to ''what a student has done''.

== Changes to settings ==

There are different opinions in regards to changes to settings, such as the grade required to pass. If a student completes an activity, such as passing a test, and some time later the "grade to pass" is changed, should their "completed-passed" be changed to "completed-failed", or should the changes apply "from now on"?

Per Ekström wrote:

<blockquote>
I would say, no.

As a student, you're given a deal; "Get a score of X or higher and you pass." If the bar is raised, and it's applied retroactively, then you are basicly breaking your end of the bargain. A pass is a pass no matter what, even if a teacher afterwards raise to 80%. ...

The most important thing with a grading system is that it's predictable and perceived fair. Retroactivity makes it everything but. Therefore I do not recommend it.
</blockquote>

Where Ekström uses the word "deal", common law uses the word "contract", and "breaking your end of the bargain" could be called "fraud".

Another example supporting this view was posted:
<blockquote>
Working as a private investigator without passing the required classes and staying up with continuing education is a crime. If I took the class and later the teacher changed the requirements and the system retroactively failed me, that would expose me, the student, to criminal charges.
</blockquote>

A different view was expressed by Tim Hunt:
<blockquote>
As a teacher, you are only human. Sometimes you make mistakes. You accidentally create a quiz with a passing grade of 90% (or forget to set the passing grade so it defaults ot 0%?). Then some students attempt the quiz and point out the mistake to you, so then you correct it to 80% and expect Moodle to automatically fix the completion state for students who already got between 80 and 90%.
</blockquote>

It was suggested that if the teacher knows they made a mistake and are correcting it, they can also correct the results of that mistake - manually changing passes to fails or vice-versa.

That is the open question - ''if settings/requirements are changed'', should Moodle automatically, retroactively change prior completions based on the new settings?

== See Also ==

[https://moodle.org/mod/forum/discuss.php?d=226129 Forum discussion of the question]

[https://tracker.moodle.org/browse/MDL-37993 Tracker issue which initiated the discussion]

Policy - Retroactive effects of completion settings

2013-05-10T16:18:03Z

Raymor: Created page with "== Summary == There is an open policy question as to how past activity completions might be affected by changes to settings, whether or not certain changes should be retroactiv..."

Activity completion API

2013-05-10T15:07:26Z

Raymor: /* See Also */ - removed "of of"

{{Moodle_2.0}}

Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

If you make no changes to a module whatsoever, it can only support 'manual' completion (where the user ticks a box).

== Feature support ==

To support the completion system, your module must include a ''modulename''<tt>_supports</tt> function in its <tt>lib.php</tt>. Here is an example:

/**
* Indicates API features that the forum supports.
*
* @param string $feature
* @return mixed True if yes (some features may use other values)
*/
function forum_supports($feature) {
switch($feature) {
case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
case FEATURE_COMPLETION_HAS_RULES: return true;
default: return null;
}
}

The relevant features for completion are:

* '''FEATURE_COMPLETION_TRACKS_VIEWS''' - the module can support completion 'on view', meaning that an activity becomes marked complete as soon as a user clicks on it.

* '''FEATURE_GRADE_HAS_GRADE''' - the module provides (or may provide, depending on settings) a grade for students. When a module supports grades, it can support completion 'on grade', meaning that an activity becomes marked complete as soon as a user is assigned a grade.

* '''FEATURE_COMPLETION_HAS_RULES''' - the module has custom completion rules.

== Completion on view ==

Completion on view means that, if selected, an activity is marked complete as soon as the user views it. 'View' is usually defined as seeing the module's main page; if you click on the activity, and there isn't an error, you have probably viewed it. However it is up to each module precisely how they define 'view'.

=== How to implement ===

In your module's ''modulename''<tt>_supports</tt> function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity. In order for navigation to work as expected (i.e. so that the navigation block on the module's page takes account that you have viewed this activity, if there is another activity that depends on it) you should put this code before printing the page header.

$completion = new completion_info($course);
$completion->set_module_viewed($cm);

=== Performance issues ===

Calling this method has no significant performance cost if 'on view' completion is not enabled for the activity. If it is enabled, then the performance cost is kept low because the 'viewed' state is cached; it doesn't add a database query to every request.

== Completion on grade ==

Completion on grade means that, if selected, an activity is marked complete as soon as the user receives a grade from that activity.

=== How to implement ===

In your module's _supports function, return true for FEATURE_GRADE_HAS_GRADE. No other action is necessary.

=== Performance issues ===

When 'on grade' completion is enabled, there will be some additional database queries after a grade is assigned or changed. Unless your activity changes grades very frequently, this is unlikely to be an issue.

== Custom completion rules ==

Custom completion rules allow for module-specific conditions. For example, the forum has custom rules so that you can make it mark a user completed when they make a certain number of posts to the forum.

It is a lot harder to implement custom completion rules than it is to use the system-provided 'view' or 'grade' conditions, but the instructions below should help make it clear.

=== Implementation overview ===

To implement custom completion rules, you need to:

# Return true for FEATURE_COMPLETION_HAS_RULES in your module's _supports function.
# Add database fields to your module's main table to store the custom completion settings.
# Add backup and restore code to back up these fields.
# Add controls to your module's settings form so that users can select the custom rules, altering these database settings.
# Add a function that checks the value of these rules (if set).
# Add code so that whenever the value affecting a rule might change, you inform the completion system.

=== Database fields for completion settings ===

When you provide a custom completion rule for a module, that rule requires data to be stored with each module instance: whether the rule is enabled for that instance, and any options that apply to the rule.

Usually the best place to store this information is your module's main table because:

* The information in the relevant row of this table is likely to be available in most parts of your code, so code changes are minimised.
* You already read this row with most requests, so there is no need for additional database queries which would reduce performance.
* The main table is used for most other module options so it is a logical place for this information.

If you are adding a basic completion condition you probably only need to add one field. To add a field to an existing module, you need to change the install.xml and then the update.php in the same way as adding any other field.

==== Example ====

Throughout this section I am using the forum as an example. The forum provides three completion options but because they all behave the same way, I am only showing one of them.

The forum adds this field to store a completion option:

* '''completionposts''' - this may be 0 or an integer. If it's an integer, say 3, then the user needs to add 3 forum posts (either new discussions or replies) in order for the forum to count as 'completed'.

=== Backup and restore for completion fields ===

Modules do not need to back up the generic completion options, which are handled by the system, but they do need to back up any custom options. You should add backup and restore logic for the fields mentioned above.

Remember that your restore code should handle the case when these fields are not present, setting the fields to a suitable default value.

==== Example ====

The following code in <tt>backup_forum_stepslib.php</tt> lists the fields to back up:

$forum = new backup_nested_element('forum', array('id'), array(
'type', 'name', 'intro', 'introformat',
'assessed', 'assesstimestart', 'assesstimefinish', 'scale',
'maxbytes', 'maxattachments', 'forcesubscribe', 'trackingtype',
'rsstype', 'rssarticles', 'timemodified', 'warnafter',
'blockafter', 'blockperiod', 'completiondiscussions', 'completionreplies',
'completionposts'));

As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.

=== Form changes for completion settings ===

When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.

* Implement the <tt>add_completion_rules</tt> function which adds the form controls for your new rules.

* Implement the <tt>completion_rule_enabled</tt> function which is called during form validation to check whether one of your module's completion rules has been selected.

* Implement other form changes if necessary to set up the form with your data. If your data is in the form of simple text boxes or dropdowns then this is not necessary, but you might want to have a checkbox that enables the rule with a separate control to set its value. This needs form tweaks.

==== Example ====

The forum offers a checkbox with a text input box beside it. You tick the checkbox to enable the rule, then type in the desired number of posts.

First, the function that adds these controls:

function add_completion_rules() {
$mform =& $this->_form;

$group=array();
$group[] =& $mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts','forum'));
$group[] =& $mform->createElement('text', 'completionposts', ' ', array('size'=>3));
$mform->setType('completionposts',PARAM_INT);
$mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), array(' '), false);
$mform->setHelpButton('completionpostsgroup', array('completion', get_string('completionpostshelp', 'forum'), 'forum'));
$mform->disabledIf('completionposts','completionpostsenabled','notchecked');

return array('completionpostsgroup');
}

* The function creates a checkbox and a text input field, which is set to accept only numbers.
* These are grouped together so they appear on the same line, and we add a help button.
* The text input field is disabled if the checkbox isn't ticked.
* Note that this function must return the top-level element associated with the completion rule. (If there are multiple elements, you can return more than one.)
** This is used so that your controls become disabled if automatic completion is not selected.

Next, a function for checking whether the user selected this option:

function completion_rule_enabled($data) {
return (!empty($data['completionpostsenabled']) && $data['completionposts']!=0);
}

* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.
** This is used to give an error if the user selects automatic completion, but fails to select any conditions.

That's all the 'required' functions, but we need to add some extra code to support the checkbox behaviour. I overrode get_data so that if there is a value in the edit field, but the checkbox is not ticked, the value counts as zero (the rule will not be enabled).

function get_data() {
$data = parent::get_data();
if (!$data) {
return $data;
}
if (!empty($data->completionunlocked)) {
// Turn off completion settings if the checkboxes aren't ticked
$autocompletion = !empty($data->completion) && $data->completion==COMPLETION_TRACKING_AUTOMATIC;
if (empty($data->completionpostsenabled) || !$autocompletion) {
$data->completionposts = 0;
}
}
return $data;
}

You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <code>$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.

Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:

function data_preprocessing(&$default_values){
// [Existing code, not shown]

// Set up the completion checkboxes which aren't part of standard data.
// We also make the default value (if you turn on the checkbox) for those
// numbers to be 1, this will not apply unless checkbox is ticked.
$default_values['completionpostsenabled']=
!empty($default_values['completionposts']) ? 1 : 0;
if(empty($default_values['completionposts'])) {
$default_values['completionposts']=1;
}
}

Phew! That's the form done.

=== Completion state function ===

When you create completion conditions, you need to write a function ''module''<tt>_get_completion_state</tt> that checks the value of those conditions for a particular user.

The function receives as parameters <tt>$course</tt>, <tt>$cm</tt>, and <tt>$userid</tt> - all self-explanatory, I hope - and <tt>$type</tt>. This has two values:

* '''COMPLETION_AND''' - if multiple conditions are selected, the user must meet all of them.
* '''COMPLETION_OR''' (not currently used) - if multiple conditions are selected, any one of them is good enough to complete the activity.

Your function should return:

* '''true''' if your custom completion options are enabled and the user meets the conditions.
* '''false''' if your custom completion options are enabled but the user does not yet meet the conditions.
* <tt>$type</tt> (not false!) if none of your custom completion options are not enabled.

==== Example ====

Here's the function for forum (simplified to include only the one completion option):

/**
* Obtains the automatic completion state for this forum based on any conditions
* in forum settings.
*
* @param object $course Course
* @param object $cm Course-module
* @param int $userid User ID
* @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
* @return bool True if completed, false if not, $type if conditions not set.
*/
function forum_get_completion_state($course,$cm,$userid,$type) {
global $CFG,$DB;

// Get forum details
if(!($forum=$DB->get_record('forum',array('id'=>$cm->instance)))) {
throw new Exception("Can't find forum {$cm->instance}");
}

// If completion option is enabled, evaluate it and return true/false
if($forum->completionposts) {
return $forum->completionposts <= $DB->get_field_sql("
SELECT
COUNT(1)
FROM
{forum_posts} fp
INNER JOIN {forum_discussions} fd ON fp.discussion=fd.id
WHERE
fp.userid=:userid AND fd.forum=:forumid",
array('userid'=>$userid,'forumid'=>$forum->id));
} else {
// Completion option is not enabled so just return $type
return $type;
}
}

=== Notifying the completion system ===

Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.

* To ensure performance is not compromised, you should notify the system only when the completion state might actually have changed. Don't notify the system unless your custom completion rule is actually enabled.
* You need to pass in the 'possible result' of the change. This is used to significantly improve performance. There are three values:
** '''COMPLETION_COMPLETE''' - this change will either have no effect on the user's completion state, or it will make it complete. The change cannot make a user's state ''in''complete if it was complete previously. In the forum example, when you add a post, there is no way this can make the user's state incomplete, so this possible result applies.
** '''COMPLETION_INCOMPLETE''' - this change will either have no effect on the user's completion state, or it will make it incomplete. The change cannot make a user's state complete if it was incomplete previously. Deleting a forum post would fall into this category.
** '''COMPLETION_UNKNOWN''' - this change might have either effect. Using this option is much slower than the others, so try to avoid using it in anything that might happen frequently.
* If the user whose completion state would be updated is not the current user, then the optional <tt>$userid</tt> parameter must be included. For example, if a teacher deletes a student's forum post, then it is the student's completion state which may need updating, not the teacher's.

==== Example ====

Here's the code that runs when somebody makes a new forum post:

// Update completion state
$completion=new completion_info($course);
if($completion->is_enabled($cm) && $forum->completionposts) {
$completion->update_state($cm,COMPLETION_COMPLETE);
}

== See Also ==
[[Conditional activities|Activity completion and availability]] - Original Specification

[[Course completion]] - Original Specification

[[Policy - Retroactive effects of completion settings]]

[[Core APIs]]

=== User Docs ===
[https://docs.moodle.org/en/Category:Completion Completion Docs]

[https://docs.moodle.org/en/Activity_completion Activity Completion]

[https://docs.moodle.org/en/Course_completion Course Completion]

[[Category:Conditional activities]]

[[Category:API]]

Activity completion API

2013-04-18T14:10:02Z

Raymor: /* See Also */

{{Moodle_2.0}}

Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

If you make no changes to a module whatsoever, it can only support 'manual' completion (where the user ticks a box).

== Feature support ==

To support the completion system, your module must include a ''modulename''<tt>_supports</tt> function in its <tt>lib.php</tt>. Here is an example:

/**
* Indicates API features that the forum supports.
*
* @param string $feature
* @return mixed True if yes (some features may use other values)
*/
function forum_supports($feature) {
switch($feature) {
case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
case FEATURE_COMPLETION_HAS_RULES: return true;
default: return null;
}
}

The relevant features for completion are:

* '''FEATURE_COMPLETION_TRACKS_VIEWS''' - the module can support completion 'on view', meaning that an activity becomes marked complete as soon as a user clicks on it.

* '''FEATURE_GRADE_HAS_GRADE''' - the module provides (or may provide, depending on settings) a grade for students. When a module supports grades, it can support completion 'on grade', meaning that an activity becomes marked complete as soon as a user is assigned a grade.

* '''FEATURE_COMPLETION_HAS_RULES''' - the module has custom completion rules.

== Completion on view ==

Completion on view means that, if selected, an activity is marked complete as soon as the user views it. 'View' is usually defined as seeing the module's main page; if you click on the activity, and there isn't an error, you have probably viewed it. However it is up to each module precisely how they define 'view'.

=== How to implement ===

In your module's ''modulename''<tt>_supports</tt> function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity. In order for navigation to work as expected (i.e. so that the navigation block on the module's page takes account that you have viewed this activity, if there is another activity that depends on it) you should put this code before printing the page header.

$completion = new completion_info($course);
$completion->set_module_viewed($cm);

=== Performance issues ===

Calling this method has no significant performance cost if 'on view' completion is not enabled for the activity. If it is enabled, then the performance cost is kept low because the 'viewed' state is cached; it doesn't add a database query to every request.

== Completion on grade ==

Completion on grade means that, if selected, an activity is marked complete as soon as the user receives a grade from that activity.

=== How to implement ===

In your module's _supports function, return true for FEATURE_GRADE_HAS_GRADE. No other action is necessary.

=== Performance issues ===

When 'on grade' completion is enabled, there will be some additional database queries after a grade is assigned or changed. Unless your activity changes grades very frequently, this is unlikely to be an issue.

== Custom completion rules ==

Custom completion rules allow for module-specific conditions. For example, the forum has custom rules so that you can make it mark a user completed when they make a certain number of posts to the forum.

It is a lot harder to implement custom completion rules than it is to use the system-provided 'view' or 'grade' conditions, but the instructions below should help make it clear.

=== Implementation overview ===

To implement custom completion rules, you need to:

# Return true for FEATURE_COMPLETION_HAS_RULES in your module's _supports function.
# Add database fields to your module's main table to store the custom completion settings.
# Add backup and restore code to back up these fields.
# Add controls to your module's settings form so that users can select the custom rules, altering these database settings.
# Add a function that checks the value of these rules (if set).
# Add code so that whenever the value affecting a rule might change, you inform the completion system.

=== Database fields for completion settings ===

When you provide a custom completion rule for a module, that rule requires data to be stored with each module instance: whether the rule is enabled for that instance, and any options that apply to the rule.

Usually the best place to store this information is your module's main table because:

* The information in the relevant row of this table is likely to be available in most parts of your code, so code changes are minimised.
* You already read this row with most requests, so there is no need for additional database queries which would reduce performance.
* The main table is used for most other module options so it is a logical place for this information.

If you are adding a basic completion condition you probably only need to add one field. To add a field to an existing module, you need to change the install.xml and then the update.php in the same way as adding any other field.

==== Example ====

Throughout this section I am using the forum as an example. The forum provides three completion options but because they all behave the same way, I am only showing one of them.

The forum adds this field to store a completion option:

* '''completionposts''' - this may be 0 or an integer. If it's an integer, say 3, then the user needs to add 3 forum posts (either new discussions or replies) in order for the forum to count as 'completed'.

=== Backup and restore for completion fields ===

Modules do not need to back up the generic completion options, which are handled by the system, but they do need to back up any custom options. You should add backup and restore logic for the fields mentioned above.

Remember that your restore code should handle the case when these fields are not present, setting the fields to a suitable default value.

==== Example ====

The following code in <tt>backup_forum_stepslib.php</tt> lists the fields to back up:

$forum = new backup_nested_element('forum', array('id'), array(
'type', 'name', 'intro', 'introformat',
'assessed', 'assesstimestart', 'assesstimefinish', 'scale',
'maxbytes', 'maxattachments', 'forcesubscribe', 'trackingtype',
'rsstype', 'rssarticles', 'timemodified', 'warnafter',
'blockafter', 'blockperiod', 'completiondiscussions', 'completionreplies',
'completionposts'));

As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.

=== Form changes for completion settings ===

When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.

* Implement the <tt>add_completion_rules</tt> function which adds the form controls for your new rules.

* Implement the <tt>completion_rule_enabled</tt> function which is called during form validation to check whether one of your module's completion rules has been selected.

* Implement other form changes if necessary to set up the form with your data. If your data is in the form of simple text boxes or dropdowns then this is not necessary, but you might want to have a checkbox that enables the rule with a separate control to set its value. This needs form tweaks.

==== Example ====

The forum offers a checkbox with a text input box beside it. You tick the checkbox to enable the rule, then type in the desired number of posts.

First, the function that adds these controls:

function add_completion_rules() {
$mform =& $this->_form;

$group=array();
$group[] =& $mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts','forum'));
$group[] =& $mform->createElement('text', 'completionposts', ' ', array('size'=>3));
$mform->setType('completionposts',PARAM_INT);
$mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), array(' '), false);
$mform->setHelpButton('completionpostsgroup', array('completion', get_string('completionpostshelp', 'forum'), 'forum'));
$mform->disabledIf('completionposts','completionpostsenabled','notchecked');

return array('completionpostsgroup');
}

* The function creates a checkbox and a text input field, which is set to accept only numbers.
* These are grouped together so they appear on the same line, and we add a help button.
* The text input field is disabled if the checkbox isn't ticked.
* Note that this function must return the top-level element associated with the completion rule. (If there are multiple elements, you can return more than one.)
** This is used so that your controls become disabled if automatic completion is not selected.

Next, a function for checking whether the user selected this option:

function completion_rule_enabled($data) {
return (!empty($data['completionpostsenabled']) && $data['completionposts']!=0);
}

* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.
** This is used to give an error if the user selects automatic completion, but fails to select any conditions.

That's all the 'required' functions, but we need to add some extra code to support the checkbox behaviour. I overrode get_data so that if there is a value in the edit field, but the checkbox is not ticked, the value counts as zero (the rule will not be enabled).

function get_data() {
$data = parent::get_data();
if (!$data) {
return $data;
}
if (!empty($data->completionunlocked)) {
// Turn off completion settings if the checkboxes aren't ticked
$autocompletion = !empty($data->completion) && $data->completion==COMPLETION_TRACKING_AUTOMATIC;
if (empty($data->completionpostsenabled) || !$autocompletion) {
$data->completionposts = 0;
}
}
return $data;
}

You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <code>$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.

Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:

function data_preprocessing(&$default_values){
// [Existing code, not shown]

// Set up the completion checkboxes which aren't part of standard data.
// We also make the default value (if you turn on the checkbox) for those
// numbers to be 1, this will not apply unless checkbox is ticked.
$default_values['completionpostsenabled']=
!empty($default_values['completionposts']) ? 1 : 0;
if(empty($default_values['completionposts'])) {
$default_values['completionposts']=1;
}
}

Phew! That's the form done.

=== Completion state function ===

When you create completion conditions, you need to write a function ''module''<tt>_get_completion_state</tt> that checks the value of those conditions for a particular user.

The function receives as parameters <tt>$course</tt>, <tt>$cm</tt>, and <tt>$userid</tt> - all self-explanatory, I hope - and <tt>$type</tt>. This has two values:

* '''COMPLETION_AND''' - if multiple conditions are selected, the user must meet all of them.
* '''COMPLETION_OR''' (not currently used) - if multiple conditions are selected, any one of them is good enough to complete the activity.

Your function should return:

* '''true''' if your custom completion options are enabled and the user meets the conditions.
* '''false''' if your custom completion options are enabled but the user does not yet meet the conditions.
* <tt>$type</tt> (not false!) if none of your custom completion options are not enabled.

==== Example ====

Here's the function for forum (simplified to include only the one completion option):

/**
* Obtains the automatic completion state for this forum based on any conditions
* in forum settings.
*
* @param object $course Course
* @param object $cm Course-module
* @param int $userid User ID
* @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
* @return bool True if completed, false if not, $type if conditions not set.
*/
function forum_get_completion_state($course,$cm,$userid,$type) {
global $CFG,$DB;

// Get forum details
if(!($forum=$DB->get_record('forum',array('id'=>$cm->instance)))) {
throw new Exception("Can't find forum {$cm->instance}");
}

// If completion option is enabled, evaluate it and return true/false
if($forum->completionposts) {
return $forum->completionposts <= $DB->get_field_sql("
SELECT
COUNT(1)
FROM
{forum_posts} fp
INNER JOIN {forum_discussions} fd ON fp.discussion=fd.id
WHERE
fp.userid=:userid AND fd.forum=:forumid",
array('userid'=>$userid,'forumid'=>$forum->id));
} else {
// Completion option is not enabled so just return $type
return $type;
}
}

=== Notifying the completion system ===

Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.

* To ensure performance is not compromised, you should notify the system only when the completion state might actually have changed. Don't notify the system unless your custom completion rule is actually enabled.
* You need to pass in the 'possible result' of the change. This is used to significantly improve performance. There are three values:
** '''COMPLETION_COMPLETE''' - this change will either have no effect on the user's completion state, or it will make it complete. The change cannot make a user's state ''in''complete if it was complete previously. In the forum example, when you add a post, there is no way this can make the user's state incomplete, so this possible result applies.
** '''COMPLETION_INCOMPLETE''' - this change will either have no effect on the user's completion state, or it will make it incomplete. The change cannot make a user's state complete if it was incomplete previously. Deleting a forum post would fall into this category.
** '''COMPLETION_UNKNOWN''' - this change might have either effect. Using this option is much slower than the others, so try to avoid using it in anything that might happen frequently.
* If the user whose completion state would be updated is not the current user, then the optional <tt>$userid</tt> parameter must be included. For example, if a teacher deletes a student's forum post, then it is the student's completion state which may need updating, not the teacher's.

==== Example ====

Here's the code that runs when somebody makes a new forum post:

// Update completion state
$completion=new completion_info($course);
if($completion->is_enabled($cm) && $forum->completionposts) {
$completion->update_state($cm,COMPLETION_COMPLETE);
}

== See Also ==
[[Conditional activities|Activity completion and availability]] - Original Specification

[[Course completion]] - Original Specification

[[Policy_Retroactive effects of of completion settings]]

[[Core APIs]]

=== User Docs ===
[https://docs.moodle.org/en/Category:Completion Completion Docs]

[https://docs.moodle.org/en/Activity_completion Activity Completion]

[https://docs.moodle.org/en/Course_completion Course Completion]

[[Category:Conditional activities]]

[[Category:API]]

Activity completion API

2013-04-18T14:08:29Z

Raymor:

{{Moodle_2.0}}

Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

If you make no changes to a module whatsoever, it can only support 'manual' completion (where the user ticks a box).

== Feature support ==

To support the completion system, your module must include a ''modulename''<tt>_supports</tt> function in its <tt>lib.php</tt>. Here is an example:

/**
* Indicates API features that the forum supports.
*
* @param string $feature
* @return mixed True if yes (some features may use other values)
*/
function forum_supports($feature) {
switch($feature) {
case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
case FEATURE_COMPLETION_HAS_RULES: return true;
default: return null;
}
}

The relevant features for completion are:

* '''FEATURE_COMPLETION_TRACKS_VIEWS''' - the module can support completion 'on view', meaning that an activity becomes marked complete as soon as a user clicks on it.

* '''FEATURE_GRADE_HAS_GRADE''' - the module provides (or may provide, depending on settings) a grade for students. When a module supports grades, it can support completion 'on grade', meaning that an activity becomes marked complete as soon as a user is assigned a grade.

* '''FEATURE_COMPLETION_HAS_RULES''' - the module has custom completion rules.

== Completion on view ==

Completion on view means that, if selected, an activity is marked complete as soon as the user views it. 'View' is usually defined as seeing the module's main page; if you click on the activity, and there isn't an error, you have probably viewed it. However it is up to each module precisely how they define 'view'.

=== How to implement ===

In your module's ''modulename''<tt>_supports</tt> function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity. In order for navigation to work as expected (i.e. so that the navigation block on the module's page takes account that you have viewed this activity, if there is another activity that depends on it) you should put this code before printing the page header.

$completion = new completion_info($course);
$completion->set_module_viewed($cm);

=== Performance issues ===

Calling this method has no significant performance cost if 'on view' completion is not enabled for the activity. If it is enabled, then the performance cost is kept low because the 'viewed' state is cached; it doesn't add a database query to every request.

== Completion on grade ==

Completion on grade means that, if selected, an activity is marked complete as soon as the user receives a grade from that activity.

=== How to implement ===

In your module's _supports function, return true for FEATURE_GRADE_HAS_GRADE. No other action is necessary.

=== Performance issues ===

When 'on grade' completion is enabled, there will be some additional database queries after a grade is assigned or changed. Unless your activity changes grades very frequently, this is unlikely to be an issue.

== Custom completion rules ==

Custom completion rules allow for module-specific conditions. For example, the forum has custom rules so that you can make it mark a user completed when they make a certain number of posts to the forum.

It is a lot harder to implement custom completion rules than it is to use the system-provided 'view' or 'grade' conditions, but the instructions below should help make it clear.

=== Implementation overview ===

To implement custom completion rules, you need to:

# Return true for FEATURE_COMPLETION_HAS_RULES in your module's _supports function.
# Add database fields to your module's main table to store the custom completion settings.
# Add backup and restore code to back up these fields.
# Add controls to your module's settings form so that users can select the custom rules, altering these database settings.
# Add a function that checks the value of these rules (if set).
# Add code so that whenever the value affecting a rule might change, you inform the completion system.

=== Database fields for completion settings ===

When you provide a custom completion rule for a module, that rule requires data to be stored with each module instance: whether the rule is enabled for that instance, and any options that apply to the rule.

Usually the best place to store this information is your module's main table because:

* The information in the relevant row of this table is likely to be available in most parts of your code, so code changes are minimised.
* You already read this row with most requests, so there is no need for additional database queries which would reduce performance.
* The main table is used for most other module options so it is a logical place for this information.

If you are adding a basic completion condition you probably only need to add one field. To add a field to an existing module, you need to change the install.xml and then the update.php in the same way as adding any other field.

==== Example ====

Throughout this section I am using the forum as an example. The forum provides three completion options but because they all behave the same way, I am only showing one of them.

The forum adds this field to store a completion option:

* '''completionposts''' - this may be 0 or an integer. If it's an integer, say 3, then the user needs to add 3 forum posts (either new discussions or replies) in order for the forum to count as 'completed'.

=== Backup and restore for completion fields ===

Modules do not need to back up the generic completion options, which are handled by the system, but they do need to back up any custom options. You should add backup and restore logic for the fields mentioned above.

Remember that your restore code should handle the case when these fields are not present, setting the fields to a suitable default value.

==== Example ====

The following code in <tt>backup_forum_stepslib.php</tt> lists the fields to back up:

$forum = new backup_nested_element('forum', array('id'), array(
'type', 'name', 'intro', 'introformat',
'assessed', 'assesstimestart', 'assesstimefinish', 'scale',
'maxbytes', 'maxattachments', 'forcesubscribe', 'trackingtype',
'rsstype', 'rssarticles', 'timemodified', 'warnafter',
'blockafter', 'blockperiod', 'completiondiscussions', 'completionreplies',
'completionposts'));

As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.

=== Form changes for completion settings ===

When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.

* Implement the <tt>add_completion_rules</tt> function which adds the form controls for your new rules.

* Implement the <tt>completion_rule_enabled</tt> function which is called during form validation to check whether one of your module's completion rules has been selected.

* Implement other form changes if necessary to set up the form with your data. If your data is in the form of simple text boxes or dropdowns then this is not necessary, but you might want to have a checkbox that enables the rule with a separate control to set its value. This needs form tweaks.

==== Example ====

The forum offers a checkbox with a text input box beside it. You tick the checkbox to enable the rule, then type in the desired number of posts.

First, the function that adds these controls:

function add_completion_rules() {
$mform =& $this->_form;

$group=array();
$group[] =& $mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts','forum'));
$group[] =& $mform->createElement('text', 'completionposts', ' ', array('size'=>3));
$mform->setType('completionposts',PARAM_INT);
$mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), array(' '), false);
$mform->setHelpButton('completionpostsgroup', array('completion', get_string('completionpostshelp', 'forum'), 'forum'));
$mform->disabledIf('completionposts','completionpostsenabled','notchecked');

return array('completionpostsgroup');
}

* The function creates a checkbox and a text input field, which is set to accept only numbers.
* These are grouped together so they appear on the same line, and we add a help button.
* The text input field is disabled if the checkbox isn't ticked.
* Note that this function must return the top-level element associated with the completion rule. (If there are multiple elements, you can return more than one.)
** This is used so that your controls become disabled if automatic completion is not selected.

Next, a function for checking whether the user selected this option:

function completion_rule_enabled($data) {
return (!empty($data['completionpostsenabled']) && $data['completionposts']!=0);
}

* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.
** This is used to give an error if the user selects automatic completion, but fails to select any conditions.

That's all the 'required' functions, but we need to add some extra code to support the checkbox behaviour. I overrode get_data so that if there is a value in the edit field, but the checkbox is not ticked, the value counts as zero (the rule will not be enabled).

function get_data() {
$data = parent::get_data();
if (!$data) {
return $data;
}
if (!empty($data->completionunlocked)) {
// Turn off completion settings if the checkboxes aren't ticked
$autocompletion = !empty($data->completion) && $data->completion==COMPLETION_TRACKING_AUTOMATIC;
if (empty($data->completionpostsenabled) || !$autocompletion) {
$data->completionposts = 0;
}
}
return $data;
}

You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <code>$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.

Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:

function data_preprocessing(&$default_values){
// [Existing code, not shown]

// Set up the completion checkboxes which aren't part of standard data.
// We also make the default value (if you turn on the checkbox) for those
// numbers to be 1, this will not apply unless checkbox is ticked.
$default_values['completionpostsenabled']=
!empty($default_values['completionposts']) ? 1 : 0;
if(empty($default_values['completionposts'])) {
$default_values['completionposts']=1;
}
}

Phew! That's the form done.

=== Completion state function ===

When you create completion conditions, you need to write a function ''module''<tt>_get_completion_state</tt> that checks the value of those conditions for a particular user.

The function receives as parameters <tt>$course</tt>, <tt>$cm</tt>, and <tt>$userid</tt> - all self-explanatory, I hope - and <tt>$type</tt>. This has two values:

* '''COMPLETION_AND''' - if multiple conditions are selected, the user must meet all of them.
* '''COMPLETION_OR''' (not currently used) - if multiple conditions are selected, any one of them is good enough to complete the activity.

Your function should return:

* '''true''' if your custom completion options are enabled and the user meets the conditions.
* '''false''' if your custom completion options are enabled but the user does not yet meet the conditions.
* <tt>$type</tt> (not false!) if none of your custom completion options are not enabled.

==== Example ====

Here's the function for forum (simplified to include only the one completion option):

/**
* Obtains the automatic completion state for this forum based on any conditions
* in forum settings.
*
* @param object $course Course
* @param object $cm Course-module
* @param int $userid User ID
* @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
* @return bool True if completed, false if not, $type if conditions not set.
*/
function forum_get_completion_state($course,$cm,$userid,$type) {
global $CFG,$DB;

// Get forum details
if(!($forum=$DB->get_record('forum',array('id'=>$cm->instance)))) {
throw new Exception("Can't find forum {$cm->instance}");
}

// If completion option is enabled, evaluate it and return true/false
if($forum->completionposts) {
return $forum->completionposts <= $DB->get_field_sql("
SELECT
COUNT(1)
FROM
{forum_posts} fp
INNER JOIN {forum_discussions} fd ON fp.discussion=fd.id
WHERE
fp.userid=:userid AND fd.forum=:forumid",
array('userid'=>$userid,'forumid'=>$forum->id));
} else {
// Completion option is not enabled so just return $type
return $type;
}
}

=== Notifying the completion system ===

Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.

* To ensure performance is not compromised, you should notify the system only when the completion state might actually have changed. Don't notify the system unless your custom completion rule is actually enabled.
* You need to pass in the 'possible result' of the change. This is used to significantly improve performance. There are three values:
** '''COMPLETION_COMPLETE''' - this change will either have no effect on the user's completion state, or it will make it complete. The change cannot make a user's state ''in''complete if it was complete previously. In the forum example, when you add a post, there is no way this can make the user's state incomplete, so this possible result applies.
** '''COMPLETION_INCOMPLETE''' - this change will either have no effect on the user's completion state, or it will make it incomplete. The change cannot make a user's state complete if it was incomplete previously. Deleting a forum post would fall into this category.
** '''COMPLETION_UNKNOWN''' - this change might have either effect. Using this option is much slower than the others, so try to avoid using it in anything that might happen frequently.
* If the user whose completion state would be updated is not the current user, then the optional <tt>$userid</tt> parameter must be included. For example, if a teacher deletes a student's forum post, then it is the student's completion state which may need updating, not the teacher's.

==== Example ====

Here's the code that runs when somebody makes a new forum post:

// Update completion state
$completion=new completion_info($course);
if($completion->is_enabled($cm) && $forum->completionposts) {
$completion->update_state($cm,COMPLETION_COMPLETE);
}

== See Also ==
[[Conditional activities|Activity completion and availability]] - Original Specification

[[Course completion]] - Original Specification

[[Policy|Retroactive effects of of completion settings]]

[[Core APIs]]

=== User Docs ===
[https://docs.moodle.org/en/Category:Completion Completion Docs]

[https://docs.moodle.org/en/Activity_completion Activity Completion]

[https://docs.moodle.org/en/Course_completion Course Completion]

[[Category:Conditional activities]]

[[Category:API]]

Moodle architecture

2013-04-18T14:05:21Z

Raymor: /* Activity and course completion */

The aim of this document is to quickly give an overview of how the Moodle works at a technical level. Hopefully this will be helpful to Administrators and Developers. However, to actually do Moodle development you will have to study the code in much more detail than is provided here. See the [[Developer_documentation|developer documentation]].

==What is Moodle?==

Moodle is a Learning Management System, Course Management System, or Virtual Learning Environment, depending on which term you prefer. Its goal is to give teachers and students the tools they need to teach and learn. Moodle comes from a background of [[:en:Pedagogy|Social Constructionist pedagogy]], however, it can be used to support any style of teaching and learning.

There are other types of software systems that are important for educational institutions, for example ePortfolios, Student Information Systems and Content repositories. Generally, Moodle does not try to re-invent these areas of functionality. Instead, tries to be the best LMS possible, and then interoperate gracefully with other systems that provide the other areas of functionality. It is, however, perfectly possible to use Moodle as a stand-alone system, without integrating it with anything else.

Moodle is a web application written in PHP. Moodle is open source. Copyright is owned by individual contributors, not assigned to a single entity, although the company Moodle Pty Ltd in Perth Australia, owned by Moodle's founder Martin Dougiamas, manages the project.

==Overview of a Moodle installation==

A Moodle installation comprises the Moodle code executing in a PHP-capable web server; a database managed by MySQL, PostgreSQL, Microsoft SQL Server, or Oracle; and a file store for uploaded and generated files (the moodledata folder).

All three parts can run on a single server; or they can be separated with many load-balanced web-servers, a database cluster, and a file-server; or anywhere between those extremes.

Moodle is designed to be simple to install on any server that meets these basic requirements. Moodle self-installs once the code has been copied to the web server and a blank database created (see [[:en:Installing Moodle]]). Similarly, Moodle can always self-upgrade from one version to the next (see [[:en:Upgrading]]).

==Moodle as a modular system==

Like many successful open source systems, Moodle is structured as an application core, surrounded by numerous plugins to provide specific functionality. Moodle is designed to be highly extensible and customizable without modifying the core libraries, as doing so would create problems when upgrading Moodle to a newer version. So when customizing or extending your own Moodle install, always do so through the plugin architecture.

Plugins in Moodle are of specific types. That is, an authentication plugin and an activity module will communicate with Moodle core using different APIs, tailored to the type of functionality the plugin provides. Functionality common to all plugins (installation, upgrade, permissions, configuration, ...) are, however, handled consistently across all plugin types.

The standard Moodle distribution includes Moodle core and a number of plugins of each type, so that a new Moodle installation can immediately be used to start teaching and learning. After installation a Moodle site can be adapted for a particular purpose by changing the default configuration option, and by installing and removing plugins. Most plugins that have been shared publicly are listed in the [http://moodle.org/plugins/index.php Moodle Plugins Directory].

Physically, a Moodle plugin is just a folder of PHP scripts (and CSS, JavaScript, etc. if necessary). Moodle core communicates with the plugin by looking for particular entry points, often defined in the file <tt>lib.php</tt> within the plugin.

==An overview of Moodle core==

''Apologies, this section is not complete yet. If you have the knowledge and time, please add to it.--[[User:Tim Hunt|Tim Hunt]] 18:28, 8 December 2010 (UTC)''

Moodle core provides all the infrastructure necessary to build an LMS. It implements the key concepts that all the different plugins will need to work with. These include

===Courses and activities===

A Moodle course is a sequence of activities and resources grouped into sections. Courses themselves are organised into a hierarchical set of categories within a Moodle site.

===Users===

Users, profile, my moodle ...

===Groups and cohorts===

===Enrolments and access control===

Contexts, roles, capabilities, and permissions, ...

===Activity and course completion===

The activity completion system allows activities such as Quizzes, SCORM modules, etc. to be marked complete when specified conditions are met.
For more information, see [[Activity_completion_API]]

===Navigation, settings and configuration===

===Forms library===

===JavaScript library===

Moodle has adopted the [http://developer.yahoo.com/yui/3/ Yahoo User Interface library]. There is also a nice system for loading the additional JavaScript files required by each page.

===Installation and upgrade===

===Logs and statistics===

==The most important plugin types==

===Activities and resources===

Activities and resources are the most basic individual components that make up a course and are the main tools for teaching and learning. Some examples of resources are: pages, links and IMS content packages. Examples of activities include: forums, wikis, quizzes, and assignments.

Activities are by far the largest type of plugin in terms of amount of code. A forum or wiki system could be a software project in its own right. Both activities and resources are installed in the <tt>mod</tt> folder.

===Blocks===

Blocks are small bits of interface functionality that can be added to (normally the sides of) pages. Many blocks provide additional views of data stored and modified elsewhere. Blocks live in the <tt>blocks</tt> folder.

===Themes===

The overall visual style of a Moodle site, a particular course, or all courses in a category, can be changed by selecting a different theme at these different levels. Themes are the standard way of making aesthetic changes to your Moodle application, decoupling presentation from content and functionality.

Themes live in the <tt>theme</tt> folder, and published themes are listed in the [http://moodle.org/mod/data/view.php?id=6552 Themes database].

===Language packs===

Moodle is internationalised. That is, you can get language packs for many different languages. Language packs are normally downloaded and installed via the Moodle administration screens, but they can also be downloaded manually from [http://download.moodle.org/langpack/ Moodle.org: language packs].

Administrators can also manually change any of the standard user interface strings if the terms used in the installed language pack are not appropriate.

===Course formats===

control how the structure of the course, a sequence of activities grouped into sections, is presented to the users. Course formats live in the <tt>course/format</tt> folder.

===Authentication plugins===

control how users log in. Moodle can manage usernames and passwords itself, or use those stored in LDAP or another database. Alternatively, Moodle can use a number of single-sign-on schemes. Authentication plugins live in the <tt>auth</tt> folder.

===Enrolment plugins===

control which users are enrolled in which courses. Again this can be by synchronising with another system, perhaps a student information system, or it can be tracked internally by Moodle. Enrolment plugins live in the <tt>enrol</tt> folder. (Moodle was created by an Australian, so enrol is the correct spelling ;-).)

===Repository plugins===

Ways for users to get content (files) into Moodle, either by uploading from their hard drive, or by getting the file from another location on the Internet, perhaps Drop Box, Google Docs, or Flickr. Repository plugins live in the <tt>repository</tt> folder.

===Others===

There are [[Developer_documentation#Make_a_new_plugin|many more types of plugins]] (more than 30 at the last count). These include text filters, question types, gradebook reports, admin reports, course reports, plagiarism detection services and web service protocols.

For a definitive, up-to-date list, look at the value returned by the <tt>get_plugin_types()</tt> function, which is defined in <tt>lib/moodlelib.php</tt>.

==How Moodle code is organised==

Moodle mostly follows a [http://martinfowler.com/eaaCatalog/transactionScript.html transaction script] approach. That is, suppose you are looking a Forum. The URL will be <tt>.../mod/forum/view.php?id=1234</tt>. and <tt>mod/forum/view.php</tt> the PHP script that generates that page. One could argue that transaction script is not an appropriate pattern for an application as complex as Moodle. However, it is a very natural architecture for a PHP application, and Moodle is an aggregate of many different plugins, rather than a single complex application.

Behind that basic transaction script approach, a lot of the core functionality has be refactored out into libraries (mostly in the <tt>lib</tt> folder). This provides elements of a [http://martinfowler.com/eaaCatalog/domainModel.html domain model]. The Moodle project started before PHP could handle object-oriented code, however, so don't expect an object-oriented domain model except in some of the more recent parts of the Moodle code.

There are two layers used to separate presentation from the business logic. The outer layer is the theme (see above) which controls the more visual aspects of the Moodle interface. Then there are renderer classes which generate the HTML to be output from the data supplied by the transaction scripts and the domain model. Unfortunately, neither PHP, nor the Moodle architecture, enforces a clear separation of the UI layer. It is possible for sloppy developers to make a mess, and this has happened in the past. The code in the standard Moodle distribution is gradually being cleaned up.

==The Moodle database==

The Moodle database comprises many tables (more than 250) because the whole database is an aggregate of the core tables and the tables belonging to each plugin. Fortunately, this large structure is understandable, because the tables for one particular plugin typically only link to each other and a few core tables. See [[Database_schema_introduction|Database schema introduction]] for more information.

The Moodle database structure is defined in <tt>install.xml</tt> files inside the <tt>db</tt> folder in each plugin. For example <tt>mod/forum/db/install.xml</tt> contains the database definition for the forum module. <tt>lib/db/install.xml</tt> defines the tables used by Moodle core. The <tt>install.xml</tt> files contain comments that should explain the purpose of each table and column. These comments can be turned into human-readable documentation by going to Site administration -> Development -> XMLDB editor in your Moodle installation, and clicking on the [Doc] link.

==See also==

* [[:en:Administrator documentation]]
* [[Developer_documentation|Developer documentation]]
* [[Database_schema_introduction|Database schema introduction]]
* [http://moodle.org/mod/data/view.php?id=6009 Modules and plugins] and [http://moodle.org/mod/data/view.php?id=6552 themes] databases
* [http://moodle.org/mod/forum/discuss.php?d=64465 Forum thread with a vigorous argument about whether an architecture document is a good idea, which eventually lead to this page being rewritten]
* [http://www.aosabook.org/en/moodle.html The chapter of The Architecture of Open Source Applications about Moodle]

[[Category:Coding guidelines]]