MoodleDocs - User contributions [en]

Useful things a teacher can do with roles

2008-10-13T10:01:01Z

Quen: /* Requirements: New role created by an administrator */

==Default role settings==

* Give students [[Forum moderator role|forum moderator rights]]
* Enable students to grade assignment submissions
* Give students the rights to approve database entries (or glossary entries)
* Allow students to clean up saved chat sessions

In each of the above cases, students are assigned the role of non-editing teacher in the module context (via the "Locally assigned roles" tab in the editing activity page).

==Requirement: Teachers allowed to override permissions==

* Create an [[Forum permissions|archive forum]] (or archive database, glossary or wiki)
* Enable students to [[Forum permissions|rate forum posts]]
* Allow students to [[Unenrolment|unenrol themselves from a course]]
* [[Block permissions|Hide a block]] from guests

By default, only administrators are able to override permissions. Instructions on enabling teachers to override permissions can be found in [[Override permissions]].

==Requirement: New role created by an administrator==

* Give students [[Quiz user with unlimited time role|unlimited time to complete quizzes]]
* Enable students to [[Question creator role|create questions]]
* Assign a student the [[Calendar editor role|role of calendar editor]]
* Provide temporary read-only access to naughty students

[[Category:Roles]]

OU blog

2008-09-30T13:38:27Z

Quen: New page: {{stub}} This contributed code module is an alternative blog system for Moodle. It can be used in place of, or in addition to, the standard Moodle blog system. ==Features== * Provides us...

{{stub}}
This contributed code module is an alternative blog system for Moodle. It can be used in place of, or in addition to, the standard Moodle blog system.

==Features==

* Provides user blogs (similar to Moodle ones; everyone has their own blog) and course blogs (add an instance of the module to a course, and students in the course can all contribute to a shared blog).
* Full support for comments. Comments can be turned off for a particular blog or post, but otherwise people can leave comments in both user and course blogs. In order to avoid spam, you currently have to be a logged-in user in order to leave comments, even if the post itself is open to the public.
* Access control levels: private (user only), course members, logged-in users, or worldwide.
* Group support for course blogs (so you can have per-group blogs).
* Blog-specific tags. Tags are not connected to the Moodle tag system but apply only within the blog. You click on a tag to see all posts in the current blog with that tag.
* User cosmetic options - change the name of your blog (from My Name's Blog to whatever you like) and add a description.
* Standard Moodle 1.9 role/permission support (eg if you want to make it so students can't post to course blogs, etc).
* Post and comment management. You can edit or delete posts and delete comments, but deleted or previous text remains available to administrator users. (This is necessary in various circumstances.)
* RSS and Atom feeds.
* Automatically integrates with the OU search system (if that is installed) to provide fulltext search of blog posts.

There is no connection between this system and standard Moodle blog; installing this system doesn't do anything to your existing Moodle blogs. If you want to move over to this system entirely, you would use the Moodle admin option that lets you disable its internal blog feature, to avoid confusion. (There is no way at present to transfer actual content from Moodle blog to oublog.)

==Requirements==

* Requires PHP 5.
* Tested with Postgres 8.1 and MySQL 5. (Should work on other Moodle-supported databases.)
* Tested on current Moodle 1.9.2+ from CVS. (Probably works on any Moodle 1.9 though.)

No complex installation is necessary, just drop the oublog folder into your Moodle mod folder and visit the admin notifications page to install.

OU blog was specified by the Open University which funded the work. The actual development was done by Matt Clarkson of Catalyst, and further bugfixes and minor changes were then added by me (sam marshall) at the OU.

==Development status==

This blog is in active use at the Open University. We continue to maintain and develop it and plan to do public releases aligned with our internal release cycle.

There are no major developments planned at present.

==See also==
*[http://moodle.org/mod/data/view.php?d=13&rid=1820 OU blog] is a Modules and plugins database page for downloads and more information.
*Discussions: please create or find a discussion topic in the [http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]

[[Category:Contributed code]]

Development:Installing and upgrading plugin database tables

2008-08-29T12:45:56Z

Quen: /* The files you need for the second release */

==Introduction==

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visite the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:
;version.php : This records the version of the plugin code
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin. This is normally stored in the mdl_config table, in a row with name something like ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

==The files you need for the first release==

;version.php
$plugin->version = 2008080100;
$plugin->requires = XXXXXXXXXX; // Copy the current value from the top-level version.php file.
;db/install.xml
:This file, which you should [[Development:XMLDB_defining_an_XML_structure#The_XMLDB_editor|create with the XMLDB editor]], should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = XXXXXXXXXX; // Copy the current value from the top-level version.php file.
;db/install.xml : This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
$result = true;

/// Add a new column newcol to the mdl_question_myqtype
if ($result && $oldversion < 2008080200) {
// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.php exist.

if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from
upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
which says what is currently installed
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}

else if ($CFG->qtype_myqtype_version does not exist) {
Create the tables from the definitions in install.xml
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works. That is the best way to really understand what is happening.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no ''plugintype''_''pluginname''_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the ''plugintype''_''pluginname''_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==See also==

* [[Development:XMLDB_Documentation|XMLDB_Documentation]]
* [[Development:Coding|Coding guidelines]]
* [[Development:DDL functions|DDL functions]]
* [[Development:XMLDB defining an XML structure|install.xml file documentation]]

[[Category:XMLDB]]
[[Category:Installation]]

OU wiki

2008-08-28T12:43:21Z

Quen: /* Development status */

{{stub}}
This contributed code module is a simple, easy to use, but reasonably full-featured alternative to standard Moodle wiki.

==Features==

* Relies on HTML editor; does not use wiki markup except for links
* Can live alongside the existing wiki - does not make any attempt to convert content
* Includes integrated comments on pages or headings
* Supports most features of the old wiki
**Except for wiki markup (as above), attachments, and a few admin features
**If you want a search facility for the wiki, you must also install the ousearch block.

==Links==
*This contributed code's [http://moodle.org/mod/data/view.php?d=13&rid=1015 Modules and plugins database page] for downloads and more information.
*Discussions: please create or find a discussion topic [http://moodle.org/mod/forum/view.php?id=44 The Contributed Code forum]
* Also the [http://moodle.org/mod/forum/view.php?f=366 Wiki forum] has some discussion about OU wiki features

==Development status==

This wiki is in active use at the Open University. We continue to maintain and develop it and plan to do public releases aligned with our internal release cycle.

There are no major developments planned at present, but a number of minor enhancements should trickle in gradually. (Next planned features: way to easily revert to old page version, way for admins to hide page versions permanently.)

[[Category: Administrator]]
[[Category:Contributed code]]

Shared activities course format

2008-08-28T12:41:10Z

Quen: /* Development status */

{{stub}}
This contributed code module is a course format system that allows any Moodle user (for example, students) to create their own shared activities which they can invite a list of other people to join. When they invite people, those people receive an email with a link to the activity.

==Features==
This system could be useful if users meet on a course and want to arrange social events between themselves, or to stay in touch after the course ends.
* Supports [[Forum module]]s
* Supports installed [[OU wiki]]s

==Links==
*This contributed code's [PASTE http//: LINK HERE Modules and plugins database page] for downloads and more information.
*Discussions: please create or find a discussion topic [http://moodle.org/mod/forum/view.php?id=44 The Contributed Code forum]

==Development status==

This code is currently in use at the Open University, but we don't have any plans to develop it further at present (except adding support for oublog when that is released). We're also not aware of any major problems.

Please contact sam marshall if you find serious bugs. The public version may 'lag behind' our internal one, and we may need prodding to update it for bugfixes.

[[Category: Administrator]]
[[Category:Contributed code]]

Resource pages

2008-08-26T09:16:42Z

Quen:

{{stub}}
This contributed code module shows a list of links, files, or text snippets on a single page. This requires 2 patches and does not work with MySQL, only with Postgres databases.

==Features==

* Make items appear/disappear on set dates.
* Include sections and subsections within a page.
* Include links from RSS feed within page.

==Links==
*This contributed code's [http://moodle.org/mod/data/view.php?d=13&rid=1012 Modules and plugins database page] for downloads and more information.
*Discussions: please create or find a discussion topic [http://moodle.org/mod/forum/view.php?id=44 the contributed code's forum]

==Development status==

We (Open University) have not been updating the plugin code in line with our own local changes. If anyone actually uses it, you might want to request that we do so. Because this module is not very 'Moodle-like', is difficult to install, and requires a database which most people for some reason do not use, we don't anticipate that many other people will actually use it. (Please don't ask us for this update unless you have actually installed it, got it working, and wish to use it, as it will take us some work.)

We are hopeful that there will be a significant update released for Moodle 2.0 which removes the requirement to apply code patches, and works on all databases, so that everyone can easily install it if they want.

[[Category: Administrator]]
[[Category:Contributed code]]

Study calendar course format

2008-08-26T09:11:37Z

Quen:

{{stub}}
This contributed code give a course format that has tick boxes next to each item so the student can check them off.

==Features==
This is an enhanced version of the weekly course format. Key features:

* You can combine, rename, and generally configure weeks. (E.g. group together 2 weeks, call it 'Easter break'; or group together 6 weeks, call it 'Block 2'.)
* Integrates Moodle calendar events into the main display.
* Students can use checkboxes to mark their progress by ticking activities and events.

==Links==
*This contributed code's [http://moodle.org/mod/data/view.php?d=13&rid=1014 Modules and plugins database page] for downloads and more information.
*Discussions: please create or find a discussion topic [http://moodle.org/mod/forum/view.php?id=44 the contributed code's forum]

==Development status==

The current version is the final release for Moodle 1.x. If you find any serious bugs that need fixing, please get in touch with the developer (see contact details inside file); otherwise we are not expecting to make any changes.

For Moodle 2.0 we will release a new version of this course format (renamed 'study planner') which integrates with Moodle 2.0 features. (An extended version of the checkbox feature is included in core Moodle 2 and available for all course formats, so we needed to change our course format to take account of this.)

[[Category: Administrator]]
[[Category:Contributed code]]

Development:Conditional activities

2008-08-01T09:39:17Z

Quen: /* Available conditions */

{{Moodle_2.0}}

= Documentation =

[[Development:Conditional activities_Adding module support]]

= Design document =

(This is a design document by sam marshall from the Open University. It is based on earlier discussion in this wiki, and then detailed discussion with moodle.com staff who contributed improvements and corrections.)

See MDL-15497 for tasks and tracking.

sam marshall, 21 May 2008; updated as of 26 June 2008. Exported to MediaWiki format using OpenOffice.org 3.0 beta (i.e. this page doesn't perfectly represent the word-processor version) and manually tweaked a bit to fix it where it was obviously wrong.

== Introduction ==
This design document describes in some detail a proposed method to add support for ‘conditional activities’ to Moodle. It is based on a [https://docs.moodle.org/en/Development:Conditional_activities discussion on the Moodle wiki], conversations with Moodle.com staff, and only the teeniest pinch of OU requirements. 

This is divided into two related, but separate, chunks of work.

=== Completion tracking ===
Make the system store whether or not an activity has been ‘completed’.

This may be according to an activity-specific definition of completion, or because the student has ticked a box saying they’ve finished it.

When tracked automatically, completion could vary from formal requirements such as ‘scoring 90% on this quiz’ to informal requirements intended to ensure participation such as ‘post at least 3 times on this forum’.

It should be possible for teachers to access progress information for their students, so that they can see if anyone is falling behind.

=== Conditional availability ===
Allow or prevent access to an activity depending on various conditions.

These conditions may include the completion of other activities; in the case of graded activities, also whether the grade was pass/fail, or a specific amount. It also may include date.

=== Development process ===
I will do this work here. It is possible that time constraints might mean I only do the first part (completion tracking).

Development will be against Moodle 1.9, because we need it here at the OU, but it will never actually be committed into Moodle 1.9. The code will instead be ported to Moodle 2.0, which will require various changes (particularly in the area of database access).

Code will be PHP5. We will primarily test against Postgres here but intend using standard Moodle database API and only simple SQL where needed, so database compatibility is unlikely to be a problem.

In some cases the OU have versions of these features. I will be coding automatic upgrade from the previous versions. This will not be included in the core Moodle 2.0 version.

== Completion tracking ==
=== Completion options ===
The completion system can be enabled or disabled at site, course, and activity level.

* At site level, the new admin variable $CFG->enablecompletion (defaults to 1?).
* At course level, a new mdl_course field enablecompletion (defaults to 1).
* At activity level, a new mdl_course_modules field completion with values 0 = none, 1 = manual (student decides when they’ve completed something), 2 = automatic. Defaults to 1 but may be set by module e.g. a quiz module could default to automatic, label could set it to 0 so you don’t get checkboxes beside each label, etc.

This table illustrates the effect of these options. (‘enablecompletion’ is abbreviated to ‘ec’.)

{| class="prettytable"
| '''Location'''
| '''Feature'''
| '''Appears if'''

|-
| Admin settings
| On-off toggle for $CFG->ec
| –

|-
| Course settings
| On-off toggle for course ec
| $CFG->ec

|-
| Activity settings
| Off/manual/automatic option for course-module completion
| $CFG->ec && course ec

|-
| Course view
| Completion display/controls against activity
| $CFG->ec && course ec && completion

|-
| Admin block
| Link to progress report
| $CFG->ec && course ec && user has permission

|}
=== Completion states and conditions ===
Completion state is stored per-user for every activity. There are four states:

* <nowiki>Not completed [default – not stored in database]</nowiki>
* Completed (pass/fail unspecified)
* Completed, passed
* Completed, failed

The final two states only apply when completion is based on a specific grade result. These are used only in some situations. Here are the rules:

* Grade visible, ‘grade to pass’ set: ‘completed, passed’ and ‘completed, failed’ states will be used.
* ‘Grade to pass’ not set ''or''grade is hidden ''or''grade is hidden-until (regardless of until date): only the standard ‘not completed’, ‘completed’ states are used.

This is a ‘push’ system – the state is not computed live but is saved and that value used. When completion for the activity is set to manual, students can toggle this value between not completed and completed. When it is set to automatic, the system adjusts the value in certain cases.

==== Standard conditions ====
There are two standard conditions which do not require (much) module-specific behaviour.

* Graded – module has assigned grade for student.
** If there are multiple grades for this activity, you can select which one is used to determine completion. (We will not implement this selection in the user interface for the first release. It will always use the first grade.)
** This condition is implemented by a hook in gradebook that runs at the point where a grade is set.
* Viewed – student has viewed module.
** For this to be supported, the module must call a function completion_set_module_viewed($cm) when it thinks that the user has ‘viewed’ the activity. It also needs to indicate that it supports it via ''module''_supports(FEATURE_COMPLETION_TRACKS_VIEWS).

==== Custom conditions ====
Modules can support arbitrary custom conditions (with their own form components to configure these, and their own data storage to track them).

Example conditions might be:

* Forum
** User has made N posts.
** User has made N replies.
** Other people have posted N replies to discussions created by this user. (''This an example of a more complex possibility, not necessarily something that would be a good idea.'')
* Wiki
** User has edited N different pages.
** User has edited pages N times.
* Choice
** User has voted.

It is up to the module to determine when a condition has been met and update the user’s completion.

As part of this project I plan to create some custom conditions for one or a few modules (probably just forum), and implement view tracking for a wider range of modules.

==== Combining conditions ====
If an activity has both the standard grade condition, and module conditions, these are currently combined via Boolean AND. Modules that support multiple conditions should usually also AND them as this will make life simpler for developer and users; however this is up to the module, as it creates its own form fields and data items.

In the future we may (or may not!) provide the ability to choose boolean OR instead. Some of the API functions contain a parameter that indicates how results should be combined. At present this is always set to AND.

=== Expected date ===
An activity can optionally have an expected completion date. This date currently has no effect and is not shown to students, but it appears to teachers when viewing progress. It's intended so that teachers can see when students are having problems and maybe offer assistance.

In future it might be possible to export this data – e.g. the list of students who are 'late' – to external systemss.

=== Database ===
(''Prefix is shown as _. Constants are defined for all values here.'')

* _course
** +Field enablecompletion, unsigned int (1) default 0 not null.1 = enable completion options for activities (if enabled at site level). This is the user-interface default that applies to new courses when completion is enabled for the site.0 = disable and hide options. This is the database default that will apply to existing courses.
* _course_modules
** +Field completion, unsigned int (1) default 0 not null.0 = No progress tracking for this activity.1 = Manual completion tracking.2 = Automatic completion tracking.
** +Field completiongradeitemnumber, unsigned int(10) default 0.NULL = Grade information not used for completion.0,1,… = Use first/second/Nth grade item supplied by this activity.
** +Field completionview, unsigned int (1) default 0 not null.0 = View not required for completion.1 = View required for completion.
** +Field completionexpected, unsigned int (10) default 0 not null.0 = No particular date expected for completion<nowiki>* = time (seconds since epoch) by which activity is expected to be completed. </nowiki>
* New table _course_modules_completion which stores completion state for a user on each activity.
** id.
** coursemoduleid<nowiki> [index].</nowiki>
** userid<nowiki> [index]</nowiki>.
** completionstate, unsigned int(1) not null.(The absence of a row in the table counts the same as 0 here.)0 = not completed.1 = completed.2 = completed, passed.3 = completed, failed.
** viewed, unsigned int(1)null = not tracked0 = not viewed1 = viewedOnly stored if the activity is tracking viewed state.
** timemodified, unsigned int (10) not null.Last date the state changed, in seconds since epoch.

=== Capabilities ===
* moodle/course:viewprogress<nowiki> [default Teacher, Editing Teacher, Course Creator]</nowiki>Users with this permission can view progress of students on the course. If the course is set to visible groups mode, or the user also has accessallgroups, then they can see all groups. Otherwise they can only see groups they belong to.

=== Admin ===
A new admin setting progresstrackedroles stores a list of the roles that are considered relevant when displaying progress. (Other roles can still use the completion system, but won’t be shown on the progress screen.) This setting is editable via standard admin screens.

=== API ===
These functions will be included in a completionlib.php.

* completion_is_enabled($course=null,$cm=null)Returns true if completion is enabled. With no parameters, returns the site value; when course is specified, checks course as well.If course-module is specified, the return value is the same as the value of completion from course_modules.
* completion_update_state($course,$cm, $possibleresult=COMPLETION_UNKNOWN,$userid=0)Called to update completion state on the activity $cm for the given or current user. This obtains grade/viewable information if necessary and then asks the module whether the activity has been completed.It is called whenever a grade is updated on an activity that uses grades for completion and, by modules, whenever a module-specific piece of data that might affect completion has changed.
* $possibleresult is included for performance reasons to avoid recalculating completion when not necessary. Set to COMPLETION_COMPLETE or COMPLETION_NOTCOMPLETE, it indicates that the change which necessitated calling this function can only result in that type of state. For example, if there is a condition that the user must make 5 forum posts, we would call this function in response to any new post. But if the state is already ‘complete’, there is no point going through counting posts, checking grades, etc. This hint allows the code to skip further work if the user’s state is already the target. Once retrieved we will cache the state in session so that frequently, no database queries are required.
* For performance reasons, modules should still only call this function when necessary. The forum should not call this function whenever a new post is made, unless the completion option for counting posts is actually turned on for that forum.
* When a module is set to manual completion, this function is used to directly toggle completion. The completion value is set to $possibleresult.
* completion_set_module_viewed($course,$cm,$userid=0)Called when a module is viewed. If view-based completion is enabled (in $cm) then it sets the 'viewed' flag and calls update_completion_state.
* completion_count_user_data($cm)Called to determine whether any users have already completed an activity (if so, returns the number). This is used by the module settings form to determine whether completion settings should be 'locked'.
* completion_delete_all_state($course,$cm)Called at the point where course-module entries are deleted. Deletes all completion state data for that course-module.
* completion_reset_all_state($course,$cm)Deletes existing completion state for all users in this activity, then recalculates it by calling update_completion_state a lot for (i) all state-tracked users (those with progresstrackedroles roles in this activity’s context), (ii) all users who have stored completion state for this activity.Needs to be called if completion conditions change.
* completion_get_data($course,$cm,$wholecourse=false,$userid=0)Obtains completion data for a particular user related to a given activity. User defaults to current user.The $wholecourse parameter is a hint that, if it isn't already available, the system should retrieve into cache the completion data for all course activities now (so that future requests for other activities can be satisfied from cache).
* completion_get_activities($course)Gets course-module objects for all activities on a course that have completion turned on. (''Used by the progress report.'')
* completion_get_progress_all($course,$sortfirstname=false,$groupid=0)Obtains progress of all users in a course (or group) across all activities in that course for which completion tracking is enabled. (''Used by the progress report.'')
* completion_inform_grade_changed($course,$cm,&$item,&$grade,$deleted)Called to notify the completion system when a user's grade changes. Does nothing (quickly) if completion is not enabled for the item; if completion is enabled and depends on grade, calls completion_update_state. (''Provided only for use by the gradebook.'')

=== Module changes ===
There is no requirement for any module changes to support the completion system. Existing modules continue to work.

If no changes are made to a module, then manual completion (where the user ticks the box themselves) is supported for activities of that type, and automatic completion is not offered as an option in the activity settings screen.

Progressively more changes are required when implementing more detailed completion support for a module.

==== View support ====
To support the 'complete when viewed' feature, a module must do the following:

* Implement ''module''_supports() as follows:function ''module''_supports($feature) { switch($feature) { case FEATURE_COMPLETION_TRACKS_VIEWS: return true; default: return false; }}
* Add calls to completion_set_module_viewed whenever the module considers that it has been 'viewed'.
** It is up to the module to determine what this means. However most modules might put this call in view.php, near print_footer once it is clear that no errors occurred.
** This function does not take a significant time to run if view-based completion is not enabled, so you don't need to put the call inside an if.

==== Grade support ====
If a module provides grades, making ''module''_supports() return true for FEATURE_GRADE_HAS_GRADES will make these accessible to the completion system.

==== Custom completion ====
Supporting module-specific custom completion conditions requires extra work:

* Decide how to store the settings for these extra conditions (probably in your module's main table). Change your database tables to allow this.
* Add FEATURE_COMPLETION_HAS_RULES to your ''module''_supports().
* Add the extra controls to your mod_form.php.
** Override the method completion_add_rules() so that it adds extra form elements for your controls (the method is called at the right point so that they are added in the 'completion' box), and returns a list of the form elements (this is used to enable/disable them appropriately).
** Override the function completion_rule_enabled($data) so that it returns true if the supplied data means that at least one of the module's completion conditions is turned on. This is used to prevent the user from choosing 'automatic' completion if they don't also enable at least one condition.
** You may need to modify other functions such as definition_after_data() and get_data to set up your form controls appropriately based on the data from the database, or vice versa.
* In your lib.php, implement the new function ''module''_get_completion_state($course,$cm,$userid,$logic).
** If the specified module instance has completion requirements, this should return true (if they have been met) or false (if they haven't). The system will later combine this value with possible other completion requirements (view or grades).
** $logic is either COMPLETION_AND or COMPLETION_OR, indicating which type of Boolean logic should be used when there are multiple conditions.
** If completion conditions are not enabled for this particular instance, the function should return $logic (not false).
* In your module code, when something changes which might affect completion, call completion_update_state

=== Example of system operation ===
Assume that the forum offers an option to check completion based on the number of posts (complete when you’ve made N posts).

Every time a user makes a new post:

* Forum checks if completion tracking based on the number of posts is enabled (this would probably be an option in $forum). If not, it does nothing (''stop'').
* Forum calls completion_update_state($cm,COMPLETION_COMPLETE).
* System looks up the user’s current completion state for $cm. If the current state is already COMPLETION_COMPLETE (or COMPLETE_PASS or COMPLETE_FAIL) then it returns with no further action (''stop'').
* If grade-based completion is enabled, system obtains grade and checks it. If viewed-completion is enabled, system checks whether the module has been viewed.
* If the forum has its own completion rules, then the system calls forum_get_completion_state().
* The forum checks its own rules, including the number of posts and anything else that’s enabled. It returns true if these rules are met and false if they’re not.
* Combining this data, the system decides whether to update the completion state. If an update is needed, it makes the change in the database.

=== Activity UI (course page) ===
The user interface for students on the course view page needs to allow for displaying progress to students and, where completion is set to manual, allowing students to tick their own progress boxes.

I have based this suggested interface on experience here at the OU. The interface will be implemented via changes to print_section and course view.php.

* Completion displays alongside each activity for which completion is enabled, to the right of the section. (This conveniently separates it from the functional information at the left, and means that all the progress markers line up with each other.)
* Automatic completion displays as a tick or cross icon, by default coloured green and red (accessible colours will be chosen), or some kind of faint outline if something isn’t completed yet. The cross icon is used if completion state is 1.
* Manual completion displays using two more icons (‘manual tick’ and ‘manual blank’). Possible icons would be the same tick with a heavy dotted box around it, and an empty dotted box. The title of the icon is an interface clue to the user e.g. ‘Click to mark this activity completed’.When AJAX is not enabled, the manual icons link to a URL that toggles the completion value then redirects straight back to the course page.When AJAX is enabled, the manual icons use YUI to adjust the completion value without reloading the page. In this case some kind of animation – for example, the word ‘Saved’ appearing next to the icon for a second before fading away – will be used to indicate to users that their change has taken effect.
* If completion is not enabled for an activity (or for the course, site, etc) then the print_section display is the same as at present.
* When editing is turned on, completion information always displays as ticked regardless of the user’s actual completion setting. This makes it easy to see that completion is enabled for that activity.

I will get a graphic designer to look at the icons to use. To reiterate, there are six icons:

* automatic completion, not completed yet (above, not actually shown on its own, but would be a faint grey dotted box)
* automatic completion, completed (above, slightly grey tick, with faint grey dotted surround)
* automatic completion, pass (not shown, e.g. could be a green tick)
* automatic completion, fail (not shown, e.g. could be a red cross)
* manual completion, not completed (heavy black dotted outline)
* manual completion, completed (heavy black dotted outline with black tick)

It may need some work to make the manual ones look clickable and the automatic ones look not clickable, but not irrelevant either. For example we might have to resort to crappy 3D button-style shading on the manual ones. This is what I've done (badly) in the initial version of the icons which I have made.

=== Configuration UI (activity settings page) ===
Each activity’s completion settings can be configured on the standard activity settings page. These settings only appear if completion is enabled for the course and site.

The interface will be implemented via a change to the standard_coursemodule_elements function and a new optional form member function completion_add_rules(), as mentioned above, which is called (from within standard_coursemodule_elements) to add the activity-specific form elements.

We also need to determine whether the activity supports grades. This will be determined via the new ''module_''supports() function. (Note that there are existing functions for finding out whether a module ''instance'' has a grade, but not for finding out whether a module supports grades if it hasn't been created yet.)

((TODO: Diagram needs redoing))

* A dropdown allows choice of the three completion options – none, manual, automatic. (All three are shown in the diagrams below.) If the module does not support its own completion conditions, and does not support grades, then the ‘automatic’ option will not appear.
* A ‘view’ checkbox only appears if the module supports view tracking. If completion is not set to automatic, it will be greyed out. It allows you to mark something complete as soon as the user goes there once.
* A 'require grade' checkbox only appears if the module supports grades. If completion is not set to automatic, it will be greyed out.
** At this point we could have a dropdown selector to choose which grade item to use if there is more than one. However, at least for the first release, I am not providing a user interface for that feature.
* Module-specific settings, if any, are included. These are also greyed out if completion is not set to automatic. The module can add any number of settings. It is responsible for storing the data from these as part of its normal form processing.
* <nowiki>An expected completion date (default disabled) is given. This can be enabled for manual or automatic completion. It has no practical effect but displays on the progress screen. The intention is that those who design a course can set these dates at key points in the course. During the course, teachers can look at the progress report and use the dates as a guideline to check whether students are falling behind. [At a later date it might be possible to do other things with this data, such as export a list of 'late' students to an external system.]</nowiki>
* If anybody already has stored completion state for this activity, completion settings will be locked: they appear, but read-only. A button allows you to unlock the settings (making those fields editable again); after you do that and save the form, existing completion data is wiped and recalculated against the new conditions. A warning by the button explains that changing completion conditions after students complete things is not a good idea.

=== Progress tracking UI ===
Teachers wishing to track student progress can do so via the admin block. The existing course reports page will include a link to view student progress if the user has viewprogress capability.

The resulting page shows a summary of progress either for a particular group, or for all students in the course, according to the normal rules for group selection. It may include a standard group dropdown too.

# Progress is shown in a table. Students (everyone with a role in progresstrackedroles<nowiki>) are displayed down the left of the table and for activities that have completion enabled, the activity names [with expected completion dates, if set] are displayed across the top. Students can be sorted by first name or last name. The student names link to profiles and activity names link to the activities.</nowiki>
# The cells in this grid show progress indicators using the same icons as used on the course view page, although these icons are not clickable in the report. For each cell, the title, which you can see by hovering over it, indicates the state of the cell and the time modified (‘Completed 12/9/08 13:47’) as well as the student's name and the activity name (in case you are scrolling around a table that doesn't fit on-screen).
# A link at the bottom allows this table to be downloaded in CSV format. The downloaded version contains the same data, using two columns (‘state’ and ‘date’) for each activity.

=== Performance ===
==== Course view ====
When completion is enabled for a course, the course view page needs to obtain completion information. This will be cached in session and retrieved efficiently (hopefully 1 query) the first time.

==== Module pages ====
There is no performance impact when using modules that do not support completion, or where completion is disabled.

When you take an action that potentially involves completion (e.g. if you make a forum post to a forum that has enabled automatic completion when you reach N posts) the same completion state cache is used to read the current state of the data, so this should need no queries (you probably already saw the front page).

If your action could potentially change that completion state (e.g. you have not already completed the activity and you just made an additional forum post) there will be an additional cost at that time, depending on the activity – in this case, the forum will do a query to find out how many posts you've made. Because these actions occur relatively rarely, this should not cause a serious problem. (Once you have completed the activity, making another post will not incur the performance penalty.)

View-related completion tracking, the part most potentially problematic, will behave similarly: the first time you view something that has a 'viewed' requirement, it will make extra queries as it marks it viewed (or, if you viewed it in a previous session, loads up that information). After that the information will be cached in your session.

=== Backup and restore ===
* When users are included in backup, course backup will include the contents of the _course_modules_completion table.
* Course and course-modules backup will be modified to include the new fields in those tables.

= Conditional availability =
== Conditional options ==
There is no specific option to enable this part of the feature (?). The parts which depend on the completion system are enabled using the completion flag.

== Available conditions ==
You can place conditions on any activity. Conditions are always combined with Boolean AND, i.e. all conditions must be met before the activity becomes available. Unlike completion, conditions are not module-dependent. There are two types of condition:

# Conditional on date. You can have both of these conditions if required.
#* On or after date – activity becomes available on given date.
#* Before date – activity becomes unavailable on given date.
# Conditional on other activities. You can have as many of these conditions as desired.
#* Activity must be completed – any kind of completion will do.
#* Activity must be completed and passed – completion must have been graded and displayed with a pass mark (tick icon).
#* Activity must be graded at least/at most ''N''.

== Database ==
* _course_modules
** New field availablefrom, unsigned int (10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch</nowiki>) after which activity becomes available.
** New field availableuntil, unsigned int(10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch) after which activity becomes unavailable.</nowiki>
** New field showavailability, unsigned int (1) not null default 0.0 = Activity does not appear at all if conditions are not met.1 = If conditions are not met, activity appears but greyed out (‘hidden’ style) with no link and a short explanation of when it will be available.
* New table _course_modules_avail(able?) which stores any per-module conditions.
** id.
** coursemoduleid<nowiki> [index]</nowiki>.ID of the module that is being restricted.
** cmsourceid.ID of module that the restriction is based on.
** requiredcompletion, unsigned int(1) not null default 0.0 = no required completion.1 = required completed.2 = required completed and passed.3 = required completed and failed.
** gradesign, varchar(2).NULL = no required grade.<nowiki>‘<’, ‘<=</nowiki>’, ‘>’, ‘>=’ = requirement for grade.
** requiredgrade, number(10,5 decimals).Grade boundary used together with the above sign. May be null.

== API ==
Two new functions:

* availability_is_available($cm)Returns true if the module is available to students (it is visible, plus availability conditions, if any, are met). Does not include course access conditions, which it assumes have already been checked.This is a slot-in replacement where code checks for $cm->visible at key points such as in require_login.
* availability_get_display_details($cm)Obtains information about the activity’s availability which is required in order to display (or not display) a link to the activity. Returns an object with the following fields:->available – If true, activity is available; users should be allowed to access it / get links to it.->show – If true, activity should be displayed (even to users who do not have viewhiddenactivities)->info – Informational string. Blank if the activity is available.

Other changes:

* For performance reasons we need to cache the conditions in _course_modules_available. Best option is to use existing get_fast_modinfo infrastructure. This should not be hard. The above two functions will use this cache.

== Configuration UI (activity settings page) ==
The configuration UI will be implemented as part of standard_coursemodule_elements in the module forms. The existing ‘visible to students’ option (not changed in database/code) is moved within this UI.

This UI will appear even if completion is not enabled, but the parts related to completion will not show. So if completion is not enabled you will still be able to set available dates if you like, and the interface will remain consistent. The diagram below shows, first, the version that appears with completion not enabled, and then the one you get with completion enabled.

((There should be a diagram here, not sure it will show in the wiki version))

[[Image:]]

* The actual ‘available from’ options should include time as well as date. ‘Available from’ should default to midnight tomorrow; ‘Available until’ should default to 23:59 today. (I got bored laying out combo boxes.)
* ‘Information display’ controls whether informational text is displayed to students when an activity is not available. (See below.) The default is not to show information.
* The list of other activities which might have conditions includes only those other activities on the course which either have completion information, or a grade. Anything which doesn’t have completion information or a grade is omitted.
* Only one condition is permitted per other activity. This isn’t a restriction of the back-end, it just makes the UI simpler.
* The condition type dropdown by each activity is adjusted dynamically to include only options that are valid for that activity:
** ‘Completed’ appears only if completion is enabled for the activity.
** ‘Completed with pass’ and ‘Completed with fail’ (which I missed off the diagram by accident) appear only if completion is enabled for the activity, and set to a grade item, and the grade item contains a pass mark.
** The grade conditions appear only if the activity has a grade item.
* The grade box is a text-entry field. Users type in the floating-point number version of the required grade.

== Activity UI (course page) ==
(This will be accomplished via code changes to print_section. Logic is basically the same as for the current visible flag.)

For available activities, the display obviously does not change. Unavailable activities will be displayed as follows:

* If the current user has viewhiddenactivities:
** The activity displays using the CSS style for hidden activities.
** The informational message as to why the activity isn’t available is displayed (even if showinfo is not set).
* If the current user does not have viewhiddenactivities:
** If showavailability is not set, or if the activity is actually hidden (visibility 0), the activity does not display at all.
** If showavailability is set and the activity isn’t hidden but is unavailable for some other reason, the name of the activity displays using the CSS style for hidden activities, but does not include an actual link to the activity. The informational message as to why the activity isn’t available is displayed.

Here are some examples of hidden activities with informational text:Assignment resources Available from 6 Oct 2008Assignment resources Available when Unit 1 Test grade is > 90Assignment resources Available when Tutor group forum is marked complete (+ other requirements)When there are multiple conditions, only one is shown. Date is considered first; the order after that is arbitrary.

Behaviour is the same when editing is turned on except that the ‘availability’ string moves to the line below so as not to clash with all those icons.

== Performance ==
This adds a single quick database query to the course view page for courses which have enabled conditional activities / completion.

All other information is cached in modinfo<nowiki>, so does not have a performance penalty, save one problematic issue: the feature that allows arbitrary grade information to be considered. If you use pass/fail information, that’s fine, it’s there already in the completion data. But if you use a specific grade [and for example it could be different values for different activities] then the actual grade for the item needs to be retrieved on course view.</nowiki>

I don’t believe this will pose a massive performance issue as it only applies when modules are used as source for this kind of information. We should review this once it’s developed and, if necessary, optimise performance then. There are various caching approaches we could use.

== Module delete ==
If you try to delete a module, it will check to see if that module is referenced by any other module as a condition. If that’s the case, you will not be allowed to delete it. An error message will include a link to the module edit page for the other module (so you can go there and delete the condition if you like).

== Backup and restore ==
* The new _course_modules_available table will be backed up and restored.
** Partial restore needs to be handled. If your backup includes module A but not module B, and module A had a condition on B, then that condition will not be restored.
* Backup will also be modified to include the fields added to _course_modules.
* If you restore a course with a startdateoffset, it will offset the dates from the new _course_modules date fields.

= Module supported features =
As part of the completion system, I needed a way for modules to indicate support of certain features, so I propose a generic one which I have implemented:

* A module API function ''module''_supports($feature) which returns false if the feature is not available, and true (or an object with more information, if needed for specific features) if it is.
* A standard API function module_supports($modulename,$feature) which works as follows:
** If the $modulename_supports_feature function exists, it calls that function and returns the result.
** Otherwise it returns false – or, if features are added that correspond to ‘legacy’ ones that we can find out another way (e.g. by looking to see if a function exists) then this can be done.
* A set of FEATURE_''xx'' constants. For this code, the following are necessary:
** FEATURE_GRADE_HAS_GRADE
** FEATURE_COMPLETION_TRACKS_VIEWS
** FEATURE_COMPLETION_HAS_RULES
* Other feature constants could be added as desired, e.g. FEATURE_CRON, etc. My initial implementation will include only the 'new' ones needed for this work.

Note that this implementation would not be appropriate if modules were changed to be fully object-oriented. However I don't expect that to happen in Moodle 2 so this is probably OK.

Development:Conditional activities Adding module support

2008-07-31T11:03:17Z

Quen: /* Backup and restore for completion fields */

{{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 (for example, near the <tt>print_footer()</tt> call in <tt>view.php</tt>):

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

I added the following code to forum <tt>backuplib.php</tt> after a list of similar lines:

fwrite ($bf,full_tag("COMPLETIONPOSTS",4,false,$forum->completionposts));

And the following to <tt>restorelib.php</tt>:

$forum->completionposts = isset($info['MOD']['#']['COMPLETIONPOSTS']['0']['#'])?backup_todb($info['MOD']['#']['COMPLETIONPOSTS']['0']['#']):0;

(This code followed the existing style set by other lines. I don't necessarily recommend this exact pattern.)

=== 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 false;
}
// 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;
}

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

Development:Conditional activities Adding module support

2008-07-31T11:02:13Z

Quen: /* Database fields for completion settings */

{{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 (for example, near the <tt>print_footer()</tt> call in <tt>view.php</tt>):

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

==== Example ====

I added the following code to forum <tt>backuplib.php</tt> after a list of similar lines:

fwrite ($bf,full_tag("COMPLETIONPOSTS",4,false,$forum->completionposts));

And the following to <tt>restorelib.php</tt>:

$forum->completionposts = isset($info['MOD']['#']['COMPLETIONPOSTS']['0']['#'])?backup_todb($info['MOD']['#']['COMPLETIONPOSTS']['0']['#']):0;

=== 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 false;
}
// 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;
}

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

Development:Conditional activities Adding module support

2008-07-31T10:59:48Z

Quen: /* Implementation overview */

{{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 (for example, near the <tt>print_footer()</tt> call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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

Development:Conditional activities Adding module support

2008-07-30T15:28:17Z

Quen: /* Notifying the completion system */

{{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 (for example, near the <tt>print_footer()</tt> call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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

Development:Conditional activities Adding module support

2008-07-30T12:23:03Z

Quen: /* Example */

{{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 (for example, near the <tt>print_footer()</tt> call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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.

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

Development:Conditional activities Adding module support

2008-07-30T12:21:21Z

Quen: /* How to implement */

{{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 (for example, near the <tt>print_footer()</tt> call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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.

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

Development:Conditional activities Adding module support

2008-07-30T12:20:15Z

Quen: /* Feature support */

{{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 _supports function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity (for example, near the print_footer() call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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.

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

Development:Conditional activities Adding module support

2008-07-30T12:19:38Z

Quen: /* Notifying the completion system */

{{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 <tt>modulename_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 _supports function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity (for example, near the print_footer() call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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.

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

Development:Conditional activities Adding module support

2008-07-30T12:19:27Z

Quen: /* Notifying the completion system */

{{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 <tt>modulename_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 _supports function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity (for example, near the print_footer() call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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.

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

Development:Conditional activities Adding module support

2008-07-30T12:07:20Z

Quen: /* Example */

{{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 <tt>modulename_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 _supports function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity (for example, near the print_footer() call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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

Development:Conditional activities Adding module support

2008-07-30T12:06:54Z

Quen: /* Completion value function */

{{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 <tt>modulename_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 _supports function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity (for example, near the print_footer() call in <tt>view.php</tt>):

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

=== 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 false;
}
// 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;
}

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

Development:Conditional activities Adding module support

2008-07-30T11:55:41Z

Quen: /* Example */

Development:Conditional activities Adding module support

2008-07-30T11:55:07Z

Quen: /* Custom completion rules */

Development:Conditional activities Adding module support

2008-07-30T11:53:51Z

Quen: /* Example */

Development:Conditional activities Adding module support

2008-07-30T11:52:12Z

Quen: /* Example */

Development:Conditional activities Adding module support

2008-07-30T11:51:58Z

Quen: /* Form changes for completion settings */

Development:Conditional activities Adding module support

2008-07-30T11:37:33Z

Quen: /* Database fields for completion settings */

Development:Conditional activities Adding module support

2008-07-30T11:29:30Z

Quen: /* Custom completion rules */

Development:Conditional activities Adding module support

2008-07-30T11:15:21Z

Quen:

Development:Conditional activities Adding module support

2008-07-30T10:59:10Z

Quen: New page: {{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 what...

Development:Conditional activities

2008-07-30T10:57:04Z

Quen:

{{Moodle_2.0}}

= Documentation =

[[Development:Conditional activities_Adding module support]]

= Design document =

(This is a design document by sam marshall from the Open University. It is based on earlier discussion in this wiki, and then detailed discussion with moodle.com staff who contributed improvements and corrections.)

See MDL-15497 for tasks and tracking.

sam marshall, 21 May 2008; updated as of 26 June 2008. Exported to MediaWiki format using OpenOffice.org 3.0 beta (i.e. this page doesn't perfectly represent the word-processor version) and manually tweaked a bit to fix it where it was obviously wrong.

== Introduction ==
This design document describes in some detail a proposed method to add support for ‘conditional activities’ to Moodle. It is based on a [https://docs.moodle.org/en/Development:Conditional_activities discussion on the Moodle wiki], conversations with Moodle.com staff, and only the teeniest pinch of OU requirements. 

This is divided into two related, but separate, chunks of work.

=== Completion tracking ===
Make the system store whether or not an activity has been ‘completed’.

This may be according to an activity-specific definition of completion, or because the student has ticked a box saying they’ve finished it.

When tracked automatically, completion could vary from formal requirements such as ‘scoring 90% on this quiz’ to informal requirements intended to ensure participation such as ‘post at least 3 times on this forum’.

It should be possible for teachers to access progress information for their students, so that they can see if anyone is falling behind.

=== Conditional availability ===
Allow or prevent access to an activity depending on various conditions.

These conditions may include the completion of other activities; in the case of graded activities, also whether the grade was pass/fail, or a specific amount. It also may include date.

=== Development process ===
I will do this work here. It is possible that time constraints might mean I only do the first part (completion tracking).

Development will be against Moodle 1.9, because we need it here at the OU, but it will never actually be committed into Moodle 1.9. The code will instead be ported to Moodle 2.0, which will require various changes (particularly in the area of database access).

Code will be PHP5. We will primarily test against Postgres here but intend using standard Moodle database API and only simple SQL where needed, so database compatibility is unlikely to be a problem.

In some cases the OU have versions of these features. I will be coding automatic upgrade from the previous versions. This will not be included in the core Moodle 2.0 version.

== Completion tracking ==
=== Completion options ===
The completion system can be enabled or disabled at site, course, and activity level.

* At site level, the new admin variable $CFG->enablecompletion (defaults to 1?).
* At course level, a new mdl_course field enablecompletion (defaults to 1).
* At activity level, a new mdl_course_modules field completion with values 0 = none, 1 = manual (student decides when they’ve completed something), 2 = automatic. Defaults to 1 but may be set by module e.g. a quiz module could default to automatic, label could set it to 0 so you don’t get checkboxes beside each label, etc.

This table illustrates the effect of these options. (‘enablecompletion’ is abbreviated to ‘ec’.)

{| class="prettytable"
| '''Location'''
| '''Feature'''
| '''Appears if'''

|-
| Admin settings
| On-off toggle for $CFG->ec
| –

|-
| Course settings
| On-off toggle for course ec
| $CFG->ec

|-
| Activity settings
| Off/manual/automatic option for course-module completion
| $CFG->ec && course ec

|-
| Course view
| Completion display/controls against activity
| $CFG->ec && course ec && completion

|-
| Admin block
| Link to progress report
| $CFG->ec && course ec && user has permission

|}
=== Completion states and conditions ===
Completion state is stored per-user for every activity. There are four states:

* <nowiki>Not completed [default – not stored in database]</nowiki>
* Completed (pass/fail unspecified)
* Completed, passed
* Completed, failed

The final two states only apply when completion is based on a specific grade result. These are used only in some situations. Here are the rules:

* Grade visible, ‘grade to pass’ set: ‘completed, passed’ and ‘completed, failed’ states will be used.
* ‘Grade to pass’ not set ''or''grade is hidden ''or''grade is hidden-until (regardless of until date): only the standard ‘not completed’, ‘completed’ states are used.

This is a ‘push’ system – the state is not computed live but is saved and that value used. When completion for the activity is set to manual, students can toggle this value between not completed and completed. When it is set to automatic, the system adjusts the value in certain cases.

==== Standard conditions ====
There are two standard conditions which do not require (much) module-specific behaviour.

* Graded – module has assigned grade for student.
** If there are multiple grades for this activity, you can select which one is used to determine completion. (We will not implement this selection in the user interface for the first release. It will always use the first grade.)
** This condition is implemented by a hook in gradebook that runs at the point where a grade is set.
* Viewed – student has viewed module.
** For this to be supported, the module must call a function completion_set_module_viewed($cm) when it thinks that the user has ‘viewed’ the activity. It also needs to indicate that it supports it via ''module''_supports(FEATURE_COMPLETION_TRACKS_VIEWS).

==== Custom conditions ====
Modules can support arbitrary custom conditions (with their own form components to configure these, and their own data storage to track them).

Example conditions might be:

* Forum
** User has made N posts.
** User has made N replies.
** Other people have posted N replies to discussions created by this user. (''This an example of a more complex possibility, not necessarily something that would be a good idea.'')
* Wiki
** User has edited N different pages.
** User has edited pages N times.
* Choice
** User has voted.

It is up to the module to determine when a condition has been met and update the user’s completion.

As part of this project I plan to create some custom conditions for one or a few modules (probably just forum), and implement view tracking for a wider range of modules.

==== Combining conditions ====
If an activity has both the standard grade condition, and module conditions, these are currently combined via Boolean AND. Modules that support multiple conditions should usually also AND them as this will make life simpler for developer and users; however this is up to the module, as it creates its own form fields and data items.

In the future we may (or may not!) provide the ability to choose boolean OR instead. Some of the API functions contain a parameter that indicates how results should be combined. At present this is always set to AND.

=== Expected date ===
An activity can optionally have an expected completion date. This date currently has no effect and is not shown to students, but it appears to teachers when viewing progress. It's intended so that teachers can see when students are having problems and maybe offer assistance.

In future it might be possible to export this data – e.g. the list of students who are 'late' – to external systemss.

=== Database ===
(''Prefix is shown as _. Constants are defined for all values here.'')

* _course
** +Field enablecompletion, unsigned int (1) default 0 not null.1 = enable completion options for activities (if enabled at site level). This is the user-interface default that applies to new courses when completion is enabled for the site.0 = disable and hide options. This is the database default that will apply to existing courses.
* _course_modules
** +Field completion, unsigned int (1) default 0 not null.0 = No progress tracking for this activity.1 = Manual completion tracking.2 = Automatic completion tracking.
** +Field completiongradeitemnumber, unsigned int(10) default 0.NULL = Grade information not used for completion.0,1,… = Use first/second/Nth grade item supplied by this activity.
** +Field completionview, unsigned int (1) default 0 not null.0 = View not required for completion.1 = View required for completion.
** +Field completionexpected, unsigned int (10) default 0 not null.0 = No particular date expected for completion<nowiki>* = time (seconds since epoch) by which activity is expected to be completed. </nowiki>
* New table _course_modules_completion which stores completion state for a user on each activity.
** id.
** coursemoduleid<nowiki> [index].</nowiki>
** userid<nowiki> [index]</nowiki>.
** completionstate, unsigned int(1) not null.(The absence of a row in the table counts the same as 0 here.)0 = not completed.1 = completed.2 = completed, passed.3 = completed, failed.
** viewed, unsigned int(1)null = not tracked0 = not viewed1 = viewedOnly stored if the activity is tracking viewed state.
** timemodified, unsigned int (10) not null.Last date the state changed, in seconds since epoch.

=== Capabilities ===
* moodle/course:viewprogress<nowiki> [default Teacher, Editing Teacher, Course Creator]</nowiki>Users with this permission can view progress of students on the course. If the course is set to visible groups mode, or the user also has accessallgroups, then they can see all groups. Otherwise they can only see groups they belong to.

=== Admin ===
A new admin setting progresstrackedroles stores a list of the roles that are considered relevant when displaying progress. (Other roles can still use the completion system, but won’t be shown on the progress screen.) This setting is editable via standard admin screens.

=== API ===
These functions will be included in a completionlib.php.

* completion_is_enabled($course=null,$cm=null)Returns true if completion is enabled. With no parameters, returns the site value; when course is specified, checks course as well.If course-module is specified, the return value is the same as the value of completion from course_modules.
* completion_update_state($course,$cm, $possibleresult=COMPLETION_UNKNOWN,$userid=0)Called to update completion state on the activity $cm for the given or current user. This obtains grade/viewable information if necessary and then asks the module whether the activity has been completed.It is called whenever a grade is updated on an activity that uses grades for completion and, by modules, whenever a module-specific piece of data that might affect completion has changed.
* $possibleresult is included for performance reasons to avoid recalculating completion when not necessary. Set to COMPLETION_COMPLETE or COMPLETION_NOTCOMPLETE, it indicates that the change which necessitated calling this function can only result in that type of state. For example, if there is a condition that the user must make 5 forum posts, we would call this function in response to any new post. But if the state is already ‘complete’, there is no point going through counting posts, checking grades, etc. This hint allows the code to skip further work if the user’s state is already the target. Once retrieved we will cache the state in session so that frequently, no database queries are required.
* For performance reasons, modules should still only call this function when necessary. The forum should not call this function whenever a new post is made, unless the completion option for counting posts is actually turned on for that forum.
* When a module is set to manual completion, this function is used to directly toggle completion. The completion value is set to $possibleresult.
* completion_set_module_viewed($course,$cm,$userid=0)Called when a module is viewed. If view-based completion is enabled (in $cm) then it sets the 'viewed' flag and calls update_completion_state.
* completion_count_user_data($cm)Called to determine whether any users have already completed an activity (if so, returns the number). This is used by the module settings form to determine whether completion settings should be 'locked'.
* completion_delete_all_state($course,$cm)Called at the point where course-module entries are deleted. Deletes all completion state data for that course-module.
* completion_reset_all_state($course,$cm)Deletes existing completion state for all users in this activity, then recalculates it by calling update_completion_state a lot for (i) all state-tracked users (those with progresstrackedroles roles in this activity’s context), (ii) all users who have stored completion state for this activity.Needs to be called if completion conditions change.
* completion_get_data($course,$cm,$wholecourse=false,$userid=0)Obtains completion data for a particular user related to a given activity. User defaults to current user.The $wholecourse parameter is a hint that, if it isn't already available, the system should retrieve into cache the completion data for all course activities now (so that future requests for other activities can be satisfied from cache).
* completion_get_activities($course)Gets course-module objects for all activities on a course that have completion turned on. (''Used by the progress report.'')
* completion_get_progress_all($course,$sortfirstname=false,$groupid=0)Obtains progress of all users in a course (or group) across all activities in that course for which completion tracking is enabled. (''Used by the progress report.'')
* completion_inform_grade_changed($course,$cm,&$item,&$grade,$deleted)Called to notify the completion system when a user's grade changes. Does nothing (quickly) if completion is not enabled for the item; if completion is enabled and depends on grade, calls completion_update_state. (''Provided only for use by the gradebook.'')

=== Module changes ===
There is no requirement for any module changes to support the completion system. Existing modules continue to work.

If no changes are made to a module, then manual completion (where the user ticks the box themselves) is supported for activities of that type, and automatic completion is not offered as an option in the activity settings screen.

Progressively more changes are required when implementing more detailed completion support for a module.

==== View support ====
To support the 'complete when viewed' feature, a module must do the following:

* Implement ''module''_supports() as follows:function ''module''_supports($feature) { switch($feature) { case FEATURE_COMPLETION_TRACKS_VIEWS: return true; default: return false; }}
* Add calls to completion_set_module_viewed whenever the module considers that it has been 'viewed'.
** It is up to the module to determine what this means. However most modules might put this call in view.php, near print_footer once it is clear that no errors occurred.
** This function does not take a significant time to run if view-based completion is not enabled, so you don't need to put the call inside an if.

==== Grade support ====
If a module provides grades, making ''module''_supports() return true for FEATURE_GRADE_HAS_GRADES will make these accessible to the completion system.

==== Custom completion ====
Supporting module-specific custom completion conditions requires extra work:

* Decide how to store the settings for these extra conditions (probably in your module's main table). Change your database tables to allow this.
* Add FEATURE_COMPLETION_HAS_RULES to your ''module''_supports().
* Add the extra controls to your mod_form.php.
** Override the method completion_add_rules() so that it adds extra form elements for your controls (the method is called at the right point so that they are added in the 'completion' box), and returns a list of the form elements (this is used to enable/disable them appropriately).
** Override the function completion_rule_enabled($data) so that it returns true if the supplied data means that at least one of the module's completion conditions is turned on. This is used to prevent the user from choosing 'automatic' completion if they don't also enable at least one condition.
** You may need to modify other functions such as definition_after_data() and get_data to set up your form controls appropriately based on the data from the database, or vice versa.
* In your lib.php, implement the new function ''module''_get_completion_state($course,$cm,$userid,$logic).
** If the specified module instance has completion requirements, this should return true (if they have been met) or false (if they haven't). The system will later combine this value with possible other completion requirements (view or grades).
** $logic is either COMPLETION_AND or COMPLETION_OR, indicating which type of Boolean logic should be used when there are multiple conditions.
** If completion conditions are not enabled for this particular instance, the function should return $logic (not false).
* In your module code, when something changes which might affect completion, call completion_update_state

=== Example of system operation ===
Assume that the forum offers an option to check completion based on the number of posts (complete when you’ve made N posts).

Every time a user makes a new post:

* Forum checks if completion tracking based on the number of posts is enabled (this would probably be an option in $forum). If not, it does nothing (''stop'').
* Forum calls completion_update_state($cm,COMPLETION_COMPLETE).
* System looks up the user’s current completion state for $cm. If the current state is already COMPLETION_COMPLETE (or COMPLETE_PASS or COMPLETE_FAIL) then it returns with no further action (''stop'').
* If grade-based completion is enabled, system obtains grade and checks it. If viewed-completion is enabled, system checks whether the module has been viewed.
* If the forum has its own completion rules, then the system calls forum_get_completion_state().
* The forum checks its own rules, including the number of posts and anything else that’s enabled. It returns true if these rules are met and false if they’re not.
* Combining this data, the system decides whether to update the completion state. If an update is needed, it makes the change in the database.

=== Activity UI (course page) ===
The user interface for students on the course view page needs to allow for displaying progress to students and, where completion is set to manual, allowing students to tick their own progress boxes.

I have based this suggested interface on experience here at the OU. The interface will be implemented via changes to print_section and course view.php.

* Completion displays alongside each activity for which completion is enabled, to the right of the section. (This conveniently separates it from the functional information at the left, and means that all the progress markers line up with each other.)
* Automatic completion displays as a tick or cross icon, by default coloured green and red (accessible colours will be chosen), or some kind of faint outline if something isn’t completed yet. The cross icon is used if completion state is 1.
* Manual completion displays using two more icons (‘manual tick’ and ‘manual blank’). Possible icons would be the same tick with a heavy dotted box around it, and an empty dotted box. The title of the icon is an interface clue to the user e.g. ‘Click to mark this activity completed’.When AJAX is not enabled, the manual icons link to a URL that toggles the completion value then redirects straight back to the course page.When AJAX is enabled, the manual icons use YUI to adjust the completion value without reloading the page. In this case some kind of animation – for example, the word ‘Saved’ appearing next to the icon for a second before fading away – will be used to indicate to users that their change has taken effect.
* If completion is not enabled for an activity (or for the course, site, etc) then the print_section display is the same as at present.
* When editing is turned on, completion information always displays as ticked regardless of the user’s actual completion setting. This makes it easy to see that completion is enabled for that activity.

I will get a graphic designer to look at the icons to use. To reiterate, there are six icons:

* automatic completion, not completed yet (above, not actually shown on its own, but would be a faint grey dotted box)
* automatic completion, completed (above, slightly grey tick, with faint grey dotted surround)
* automatic completion, pass (not shown, e.g. could be a green tick)
* automatic completion, fail (not shown, e.g. could be a red cross)
* manual completion, not completed (heavy black dotted outline)
* manual completion, completed (heavy black dotted outline with black tick)

It may need some work to make the manual ones look clickable and the automatic ones look not clickable, but not irrelevant either. For example we might have to resort to crappy 3D button-style shading on the manual ones. This is what I've done (badly) in the initial version of the icons which I have made.

=== Configuration UI (activity settings page) ===
Each activity’s completion settings can be configured on the standard activity settings page. These settings only appear if completion is enabled for the course and site.

The interface will be implemented via a change to the standard_coursemodule_elements function and a new optional form member function completion_add_rules(), as mentioned above, which is called (from within standard_coursemodule_elements) to add the activity-specific form elements.

We also need to determine whether the activity supports grades. This will be determined via the new ''module_''supports() function. (Note that there are existing functions for finding out whether a module ''instance'' has a grade, but not for finding out whether a module supports grades if it hasn't been created yet.)

((TODO: Diagram needs redoing))

* A dropdown allows choice of the three completion options – none, manual, automatic. (All three are shown in the diagrams below.) If the module does not support its own completion conditions, and does not support grades, then the ‘automatic’ option will not appear.
* A ‘view’ checkbox only appears if the module supports view tracking. If completion is not set to automatic, it will be greyed out. It allows you to mark something complete as soon as the user goes there once.
* A 'require grade' checkbox only appears if the module supports grades. If completion is not set to automatic, it will be greyed out.
** At this point we could have a dropdown selector to choose which grade item to use if there is more than one. However, at least for the first release, I am not providing a user interface for that feature.
* Module-specific settings, if any, are included. These are also greyed out if completion is not set to automatic. The module can add any number of settings. It is responsible for storing the data from these as part of its normal form processing.
* <nowiki>An expected completion date (default disabled) is given. This can be enabled for manual or automatic completion. It has no practical effect but displays on the progress screen. The intention is that those who design a course can set these dates at key points in the course. During the course, teachers can look at the progress report and use the dates as a guideline to check whether students are falling behind. [At a later date it might be possible to do other things with this data, such as export a list of 'late' students to an external system.]</nowiki>
* If anybody already has stored completion state for this activity, completion settings will be locked: they appear, but read-only. A button allows you to unlock the settings (making those fields editable again); after you do that and save the form, existing completion data is wiped and recalculated against the new conditions. A warning by the button explains that changing completion conditions after students complete things is not a good idea.

=== Progress tracking UI ===
Teachers wishing to track student progress can do so via the admin block. The existing course reports page will include a link to view student progress if the user has viewprogress capability.

The resulting page shows a summary of progress either for a particular group, or for all students in the course, according to the normal rules for group selection. It may include a standard group dropdown too.

# Progress is shown in a table. Students (everyone with a role in progresstrackedroles<nowiki>) are displayed down the left of the table and for activities that have completion enabled, the activity names [with expected completion dates, if set] are displayed across the top. Students can be sorted by first name or last name. The student names link to profiles and activity names link to the activities.</nowiki>
# The cells in this grid show progress indicators using the same icons as used on the course view page, although these icons are not clickable in the report. For each cell, the title, which you can see by hovering over it, indicates the state of the cell and the time modified (‘Completed 12/9/08 13:47’) as well as the student's name and the activity name (in case you are scrolling around a table that doesn't fit on-screen).
# A link at the bottom allows this table to be downloaded in CSV format. The downloaded version contains the same data, using two columns (‘state’ and ‘date’) for each activity.

=== Performance ===
==== Course view ====
When completion is enabled for a course, the course view page needs to obtain completion information. This will be cached in session and retrieved efficiently (hopefully 1 query) the first time.

==== Module pages ====
There is no performance impact when using modules that do not support completion, or where completion is disabled.

When you take an action that potentially involves completion (e.g. if you make a forum post to a forum that has enabled automatic completion when you reach N posts) the same completion state cache is used to read the current state of the data, so this should need no queries (you probably already saw the front page).

If your action could potentially change that completion state (e.g. you have not already completed the activity and you just made an additional forum post) there will be an additional cost at that time, depending on the activity – in this case, the forum will do a query to find out how many posts you've made. Because these actions occur relatively rarely, this should not cause a serious problem. (Once you have completed the activity, making another post will not incur the performance penalty.)

View-related completion tracking, the part most potentially problematic, will behave similarly: the first time you view something that has a 'viewed' requirement, it will make extra queries as it marks it viewed (or, if you viewed it in a previous session, loads up that information). After that the information will be cached in your session.

=== Backup and restore ===
* When users are included in backup, course backup will include the contents of the _course_modules_completion table.
* Course and course-modules backup will be modified to include the new fields in those tables.

= Conditional availability =
== Conditional options ==
There is no specific option to enable this part of the feature (?). The parts which depend on the completion system are enabled using the completion flag.

== Available conditions ==
You can place conditions on any activity. Conditions are always combined with Boolean AND, i.e. all conditions must be met before the activity becomes available. Unlike completion, conditions are not module-dependent. There are two types of condition:

# Conditional on date. You can have both of these conditions if required.

#
#* On or after date – activity becomes available on given date.
#* Before date – activity becomes unavailable on given date.

# Conditional on other activities. You can have as many of these conditions as desired.

#
#* Activity must be completed – any kind of completion will do.
#* Activity must be completed and passed – completion must have been graded and displayed with a pass mark (tick icon).
#* Activity must be graded at least/at most ''N''.

== Database ==
* _course_modules
** New field availablefrom, unsigned int (10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch</nowiki>) after which activity becomes available.
** New field availableuntil, unsigned int(10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch) after which activity becomes unavailable.</nowiki>
** New field showavailability, unsigned int (1) not null default 0.0 = Activity does not appear at all if conditions are not met.1 = If conditions are not met, activity appears but greyed out (‘hidden’ style) with no link and a short explanation of when it will be available.
* New table _course_modules_avail(able?) which stores any per-module conditions.
** id.
** coursemoduleid<nowiki> [index]</nowiki>.ID of the module that is being restricted.
** cmsourceid.ID of module that the restriction is based on.
** requiredcompletion, unsigned int(1) not null default 0.0 = no required completion.1 = required completed.2 = required completed and passed.3 = required completed and failed.
** gradesign, varchar(2).NULL = no required grade.<nowiki>‘<’, ‘<=</nowiki>’, ‘>’, ‘>=’ = requirement for grade.
** requiredgrade, number(10,5 decimals).Grade boundary used together with the above sign. May be null.

== API ==
Two new functions:

* availability_is_available($cm)Returns true if the module is available to students (it is visible, plus availability conditions, if any, are met). Does not include course access conditions, which it assumes have already been checked.This is a slot-in replacement where code checks for $cm->visible at key points such as in require_login.
* availability_get_display_details($cm)Obtains information about the activity’s availability which is required in order to display (or not display) a link to the activity. Returns an object with the following fields:->available – If true, activity is available; users should be allowed to access it / get links to it.->show – If true, activity should be displayed (even to users who do not have viewhiddenactivities)->info – Informational string. Blank if the activity is available.

Other changes:

* For performance reasons we need to cache the conditions in _course_modules_available. Best option is to use existing get_fast_modinfo infrastructure. This should not be hard. The above two functions will use this cache.

== Configuration UI (activity settings page) ==
The configuration UI will be implemented as part of standard_coursemodule_elements in the module forms. The existing ‘visible to students’ option (not changed in database/code) is moved within this UI.

This UI will appear even if completion is not enabled, but the parts related to completion will not show. So if completion is not enabled you will still be able to set available dates if you like, and the interface will remain consistent. The diagram below shows, first, the version that appears with completion not enabled, and then the one you get with completion enabled.

((There should be a diagram here, not sure it will show in the wiki version))

[[Image:]]

* The actual ‘available from’ options should include time as well as date. ‘Available from’ should default to midnight tomorrow; ‘Available until’ should default to 23:59 today. (I got bored laying out combo boxes.)
* ‘Information display’ controls whether informational text is displayed to students when an activity is not available. (See below.) The default is not to show information.
* The list of other activities which might have conditions includes only those other activities on the course which either have completion information, or a grade. Anything which doesn’t have completion information or a grade is omitted.
* Only one condition is permitted per other activity. This isn’t a restriction of the back-end, it just makes the UI simpler.
* The condition type dropdown by each activity is adjusted dynamically to include only options that are valid for that activity:
** ‘Completed’ appears only if completion is enabled for the activity.
** ‘Completed with pass’ and ‘Completed with fail’ (which I missed off the diagram by accident) appear only if completion is enabled for the activity, and set to a grade item, and the grade item contains a pass mark.
** The grade conditions appear only if the activity has a grade item.
* The grade box is a text-entry field. Users type in the floating-point number version of the required grade.

== Activity UI (course page) ==
(This will be accomplished via code changes to print_section. Logic is basically the same as for the current visible flag.)

For available activities, the display obviously does not change. Unavailable activities will be displayed as follows:

* If the current user has viewhiddenactivities:
** The activity displays using the CSS style for hidden activities.
** The informational message as to why the activity isn’t available is displayed (even if showinfo is not set).
* If the current user does not have viewhiddenactivities:
** If showavailability is not set, or if the activity is actually hidden (visibility 0), the activity does not display at all.
** If showavailability is set and the activity isn’t hidden but is unavailable for some other reason, the name of the activity displays using the CSS style for hidden activities, but does not include an actual link to the activity. The informational message as to why the activity isn’t available is displayed.

Here are some examples of hidden activities with informational text:Assignment resources Available from 6 Oct 2008Assignment resources Available when Unit 1 Test grade is > 90Assignment resources Available when Tutor group forum is marked complete (+ other requirements)When there are multiple conditions, only one is shown. Date is considered first; the order after that is arbitrary.

Behaviour is the same when editing is turned on except that the ‘availability’ string moves to the line below so as not to clash with all those icons.

== Performance ==
This adds a single quick database query to the course view page for courses which have enabled conditional activities / completion.

All other information is cached in modinfo<nowiki>, so does not have a performance penalty, save one problematic issue: the feature that allows arbitrary grade information to be considered. If you use pass/fail information, that’s fine, it’s there already in the completion data. But if you use a specific grade [and for example it could be different values for different activities] then the actual grade for the item needs to be retrieved on course view.</nowiki>

I don’t believe this will pose a massive performance issue as it only applies when modules are used as source for this kind of information. We should review this once it’s developed and, if necessary, optimise performance then. There are various caching approaches we could use.

== Module delete ==
If you try to delete a module, it will check to see if that module is referenced by any other module as a condition. If that’s the case, you will not be allowed to delete it. An error message will include a link to the module edit page for the other module (so you can go there and delete the condition if you like).

== Backup and restore ==
* The new _course_modules_available table will be backed up and restored.
** Partial restore needs to be handled. If your backup includes module A but not module B, and module A had a condition on B, then that condition will not be restored.
* Backup will also be modified to include the fields added to _course_modules.
* If you restore a course with a startdateoffset, it will offset the dates from the new _course_modules date fields.

= Module supported features =
As part of the completion system, I needed a way for modules to indicate support of certain features, so I propose a generic one which I have implemented:

* A module API function ''module''_supports($feature) which returns false if the feature is not available, and true (or an object with more information, if needed for specific features) if it is.
* A standard API function module_supports($modulename,$feature) which works as follows:
** If the $modulename_supports_feature function exists, it calls that function and returns the result.
** Otherwise it returns false – or, if features are added that correspond to ‘legacy’ ones that we can find out another way (e.g. by looking to see if a function exists) then this can be done.
* A set of FEATURE_''xx'' constants. For this code, the following are necessary:
** FEATURE_GRADE_HAS_GRADE
** FEATURE_COMPLETION_TRACKS_VIEWS
** FEATURE_COMPLETION_HAS_RULES
* Other feature constants could be added as desired, e.g. FEATURE_CRON, etc. My initial implementation will include only the 'new' ones needed for this work.

Note that this implementation would not be appropriate if modules were changed to be fully object-oriented. However I don't expect that to happen in Moodle 2 so this is probably OK.

Development:Conditional activities

2008-06-26T16:37:45Z

Quen:

(This is a design document by sam marshall from the Open University. It is based on earlier discussion in this wiki, and then detailed discussion with moodle.com staff who contributed improvements and corrections.)

= Conditional activities =
sam marshall, 21 May 2008; updated as of 26 June 2008. Exported to MediaWiki format using OpenOffice.org 3.0 beta (i.e. this page doesn't perfectly represent the word-processor version) and manually tweaked a bit to fix it where it was obviously wrong.

== Introduction ==
This design document describes in some detail a proposed method to add support for ‘conditional activities’ to Moodle. It is based on a [https://docs.moodle.org/en/Development:Conditional_activities discussion on the Moodle wiki], conversations with Moodle.com staff, and only the teeniest pinch of OU requirements. 

This is divided into two related, but separate, chunks of work.

=== Completion tracking ===
Make the system store whether or not an activity has been ‘completed’.

This may be according to an activity-specific definition of completion, or because the student has ticked a box saying they’ve finished it.

When tracked automatically, completion could vary from formal requirements such as ‘scoring 90% on this quiz’ to informal requirements intended to ensure participation such as ‘post at least 3 times on this forum’.

It should be possible for teachers to access progress information for their students, so that they can see if anyone is falling behind.

=== Conditional availability ===
Allow or prevent access to an activity depending on various conditions.

These conditions may include the completion of other activities; in the case of graded activities, also whether the grade was pass/fail, or a specific amount. It also may include date.

=== Development process ===
I will do this work here. It is possible that time constraints might mean I only do the first part (completion tracking).

Development will be against Moodle 1.9, because we need it here at the OU, but it will never actually be committed into Moodle 1.9. The code will instead be ported to Moodle 2.0, which will require various changes (particularly in the area of database access).

Code will be PHP5. We will primarily test against Postgres here but intend using standard Moodle database API and only simple SQL where needed, so database compatibility is unlikely to be a problem.

In some cases the OU have versions of these features. I will be coding automatic upgrade from the previous versions. This will not be included in the core Moodle 2.0 version.

== Completion tracking ==
=== Completion options ===
The completion system can be enabled or disabled at site, course, and activity level.

* At site level, the new admin variable $CFG->enablecompletion (defaults to 1?).
* At course level, a new mdl_course field enablecompletion (defaults to 1).
* At activity level, a new mdl_course_modules field completion with values 0 = none, 1 = manual (student decides when they’ve completed something), 2 = automatic. Defaults to 1 but may be set by module e.g. a quiz module could default to automatic, label could set it to 0 so you don’t get checkboxes beside each label, etc.

This table illustrates the effect of these options. (‘enablecompletion’ is abbreviated to ‘ec’.)

{| class="prettytable"
| '''Location'''
| '''Feature'''
| '''Appears if'''

|-
| Admin settings
| On-off toggle for $CFG->ec
| –

|-
| Course settings
| On-off toggle for course ec
| $CFG->ec

|-
| Activity settings
| Off/manual/automatic option for course-module completion
| $CFG->ec && course ec

|-
| Course view
| Completion display/controls against activity
| $CFG->ec && course ec && completion

|-
| Admin block
| Link to progress report
| $CFG->ec && course ec && user has permission

|}
=== Completion states and conditions ===
Completion state is stored per-user for every activity. There are four states:

* <nowiki>Not completed [default – not stored in database]</nowiki>
* Completed (pass/fail unspecified)
* Completed, passed
* Completed, failed

The final two states only apply when completion is based on a specific grade result. These are used only in some situations. Here are the rules:

* Grade visible, ‘grade to pass’ set: ‘completed, passed’ and ‘completed, failed’ states will be used.
* ‘Grade to pass’ not set ''or''grade is hidden ''or''grade is hidden-until (regardless of until date): only the standard ‘not completed’, ‘completed’ states are used.

This is a ‘push’ system – the state is not computed live but is saved and that value used. When completion for the activity is set to manual, students can toggle this value between not completed and completed. When it is set to automatic, the system adjusts the value in certain cases.

==== Standard conditions ====
There are two standard conditions which do not require (much) module-specific behaviour.

* Graded – module has assigned grade for student.
** If there are multiple grades for this activity, you can select which one is used to determine completion. (We will not implement this selection in the user interface for the first release. It will always use the first grade.)
** This condition is implemented by a hook in gradebook that runs at the point where a grade is set.
* Viewed – student has viewed module.
** For this to be supported, the module must call a function completion_set_module_viewed($cm) when it thinks that the user has ‘viewed’ the activity. It also needs to indicate that it supports it via ''module''_supports(FEATURE_COMPLETION_TRACKS_VIEWS).

==== Custom conditions ====
Modules can support arbitrary custom conditions (with their own form components to configure these, and their own data storage to track them).

Example conditions might be:

* Forum
** User has made N posts.
** User has made N replies.
** Other people have posted N replies to discussions created by this user. (''This an example of a more complex possibility, not necessarily something that would be a good idea.'')
* Wiki
** User has edited N different pages.
** User has edited pages N times.
* Choice
** User has voted.

It is up to the module to determine when a condition has been met and update the user’s completion.

As part of this project I plan to create some custom conditions for one or a few modules (probably just forum), and implement view tracking for a wider range of modules.

==== Combining conditions ====
If an activity has both the standard grade condition, and module conditions, these are currently combined via Boolean AND. Modules that support multiple conditions should usually also AND them as this will make life simpler for developer and users; however this is up to the module, as it creates its own form fields and data items.

In the future we may (or may not!) provide the ability to choose boolean OR instead. Some of the API functions contain a parameter that indicates how results should be combined. At present this is always set to AND.

=== Expected date ===
An activity can optionally have an expected completion date. This date currently has no effect and is not shown to students, but it appears to teachers when viewing progress. It's intended so that teachers can see when students are having problems and maybe offer assistance.

In future it might be possible to export this data – e.g. the list of students who are 'late' – to external systemss.

=== Database ===
(''Prefix is shown as _. Constants are defined for all values here.'')

* _course
** +Field enablecompletion, unsigned int (1) default 0 not null.1 = enable completion options for activities (if enabled at site level). This is the user-interface default that applies to new courses when completion is enabled for the site.0 = disable and hide options. This is the database default that will apply to existing courses.
* _course_modules
** +Field completion, unsigned int (1) default 0 not null.0 = No progress tracking for this activity.1 = Manual completion tracking.2 = Automatic completion tracking.
** +Field completiongradeitemnumber, unsigned int(10) default 0.NULL = Grade information not used for completion.0,1,… = Use first/second/Nth grade item supplied by this activity.
** +Field completionview, unsigned int (1) default 0 not null.0 = View not required for completion.1 = View required for completion.
** +Field completionexpected, unsigned int (10) default 0 not null.0 = No particular date expected for completion<nowiki>* = time (seconds since epoch) by which activity is expected to be completed. </nowiki>
* New table _course_modules_completion which stores completion state for a user on each activity.
** id.
** coursemoduleid<nowiki> [index].</nowiki>
** userid<nowiki> [index]</nowiki>.
** completionstate, unsigned int(1) not null.(The absence of a row in the table counts the same as 0 here.)0 = not completed.1 = completed.2 = completed, passed.3 = completed, failed.
** viewed, unsigned int(1)null = not tracked0 = not viewed1 = viewedOnly stored if the activity is tracking viewed state.
** timemodified, unsigned int (10) not null.Last date the state changed, in seconds since epoch.

=== Capabilities ===
* moodle/course:viewprogress<nowiki> [default Teacher, Editing Teacher, Course Creator]</nowiki>Users with this permission can view progress of students on the course. If the course is set to visible groups mode, or the user also has accessallgroups, then they can see all groups. Otherwise they can only see groups they belong to.

=== Admin ===
A new admin setting progresstrackedroles stores a list of the roles that are considered relevant when displaying progress. (Other roles can still use the completion system, but won’t be shown on the progress screen.) This setting is editable via standard admin screens.

=== API ===
These functions will be included in a completionlib.php.

* completion_is_enabled($course=null,$cm=null)Returns true if completion is enabled. With no parameters, returns the site value; when course is specified, checks course as well.If course-module is specified, the return value is the same as the value of completion from course_modules.
* completion_update_state($course,$cm, $possibleresult=COMPLETION_UNKNOWN,$userid=0)Called to update completion state on the activity $cm for the given or current user. This obtains grade/viewable information if necessary and then asks the module whether the activity has been completed.It is called whenever a grade is updated on an activity that uses grades for completion and, by modules, whenever a module-specific piece of data that might affect completion has changed.
* $possibleresult is included for performance reasons to avoid recalculating completion when not necessary. Set to COMPLETION_COMPLETE or COMPLETION_NOTCOMPLETE, it indicates that the change which necessitated calling this function can only result in that type of state. For example, if there is a condition that the user must make 5 forum posts, we would call this function in response to any new post. But if the state is already ‘complete’, there is no point going through counting posts, checking grades, etc. This hint allows the code to skip further work if the user’s state is already the target. Once retrieved we will cache the state in session so that frequently, no database queries are required.
* For performance reasons, modules should still only call this function when necessary. The forum should not call this function whenever a new post is made, unless the completion option for counting posts is actually turned on for that forum.
* When a module is set to manual completion, this function is used to directly toggle completion. The completion value is set to $possibleresult.
* completion_set_module_viewed($course,$cm,$userid=0)Called when a module is viewed. If view-based completion is enabled (in $cm) then it sets the 'viewed' flag and calls update_completion_state.
* completion_count_user_data($cm)Called to determine whether any users have already completed an activity (if so, returns the number). This is used by the module settings form to determine whether completion settings should be 'locked'.
* completion_delete_all_state($course,$cm)Called at the point where course-module entries are deleted. Deletes all completion state data for that course-module.
* completion_reset_all_state($course,$cm)Deletes existing completion state for all users in this activity, then recalculates it by calling update_completion_state a lot for (i) all state-tracked users (those with progresstrackedroles roles in this activity’s context), (ii) all users who have stored completion state for this activity.Needs to be called if completion conditions change.
* completion_get_data($course,$cm,$wholecourse=false,$userid=0)Obtains completion data for a particular user related to a given activity. User defaults to current user.The $wholecourse parameter is a hint that, if it isn't already available, the system should retrieve into cache the completion data for all course activities now (so that future requests for other activities can be satisfied from cache).
* completion_get_activities($course)Gets course-module objects for all activities on a course that have completion turned on. (''Used by the progress report.'')
* completion_get_progress_all($course,$sortfirstname=false,$groupid=0)Obtains progress of all users in a course (or group) across all activities in that course for which completion tracking is enabled. (''Used by the progress report.'')
* completion_inform_grade_changed($course,$cm,&$item,&$grade,$deleted)Called to notify the completion system when a user's grade changes. Does nothing (quickly) if completion is not enabled for the item; if completion is enabled and depends on grade, calls completion_update_state. (''Provided only for use by the gradebook.'')

=== Module changes ===
There is no requirement for any module changes to support the completion system. Existing modules continue to work.

If no changes are made to a module, then manual completion (where the user ticks the box themselves) is supported for activities of that type, and automatic completion is not offered as an option in the activity settings screen.

Progressively more changes are required when implementing more detailed completion support for a module.

==== View support ====
To support the 'complete when viewed' feature, a module must do the following:

* Implement ''module''_supports() as follows:function ''module''_supports($feature) { switch($feature) { case FEATURE_COMPLETION_TRACKS_VIEWS: return true; default: return false; }}
* Add calls to completion_set_module_viewed whenever the module considers that it has been 'viewed'.
** It is up to the module to determine what this means. However most modules might put this call in view.php, near print_footer once it is clear that no errors occurred.
** This function does not take a significant time to run if view-based completion is not enabled, so you don't need to put the call inside an if.

==== Grade support ====
If a module provides grades, making ''module''_supports() return true for FEATURE_GRADE_HAS_GRADES will make these accessible to the completion system.

==== Custom completion ====
Supporting module-specific custom completion conditions requires extra work:

* Decide how to store the settings for these extra conditions (probably in your module's main table). Change your database tables to allow this.
* Add FEATURE_COMPLETION_HAS_RULES to your ''module''_supports().
* Add the extra controls to your mod_form.php.
** Override the method completion_add_rules() so that it adds extra form elements for your controls (the method is called at the right point so that they are added in the 'completion' box), and returns a list of the form elements (this is used to enable/disable them appropriately).
** Override the function completion_rule_enabled($data) so that it returns true if the supplied data means that at least one of the module's completion conditions is turned on. This is used to prevent the user from choosing 'automatic' completion if they don't also enable at least one condition.
** You may need to modify other functions such as definition_after_data() and get_data to set up your form controls appropriately based on the data from the database, or vice versa.
* In your lib.php, implement the new function ''module''_get_completion_state($course,$cm,$userid,$logic).
** If the specified module instance has completion requirements, this should return true (if they have been met) or false (if they haven't). The system will later combine this value with possible other completion requirements (view or grades).
** $logic is either COMPLETION_AND or COMPLETION_OR, indicating which type of Boolean logic should be used when there are multiple conditions.
** If completion conditions are not enabled for this particular instance, the function should return $logic (not false).
* In your module code, when something changes which might affect completion, call completion_update_state

=== Example of system operation ===
Assume that the forum offers an option to check completion based on the number of posts (complete when you’ve made N posts).

Every time a user makes a new post:

* Forum checks if completion tracking based on the number of posts is enabled (this would probably be an option in $forum). If not, it does nothing (''stop'').
* Forum calls completion_update_state($cm,COMPLETION_COMPLETE).
* System looks up the user’s current completion state for $cm. If the current state is already COMPLETION_COMPLETE (or COMPLETE_PASS or COMPLETE_FAIL) then it returns with no further action (''stop'').
* If grade-based completion is enabled, system obtains grade and checks it. If viewed-completion is enabled, system checks whether the module has been viewed.
* If the forum has its own completion rules, then the system calls forum_get_completion_state().
* The forum checks its own rules, including the number of posts and anything else that’s enabled. It returns true if these rules are met and false if they’re not.
* Combining this data, the system decides whether to update the completion state. If an update is needed, it makes the change in the database.

=== Activity UI (course page) ===
The user interface for students on the course view page needs to allow for displaying progress to students and, where completion is set to manual, allowing students to tick their own progress boxes.

I have based this suggested interface on experience here at the OU. The interface will be implemented via changes to print_section and course view.php.

* Completion displays alongside each activity for which completion is enabled, to the right of the section. (This conveniently separates it from the functional information at the left, and means that all the progress markers line up with each other.)
* Automatic completion displays as a tick or cross icon, by default coloured green and red (accessible colours will be chosen), or some kind of faint outline if something isn’t completed yet. The cross icon is used if completion state is 1.
* Manual completion displays using two more icons (‘manual tick’ and ‘manual blank’). Possible icons would be the same tick with a heavy dotted box around it, and an empty dotted box. The title of the icon is an interface clue to the user e.g. ‘Click to mark this activity completed’.When AJAX is not enabled, the manual icons link to a URL that toggles the completion value then redirects straight back to the course page.When AJAX is enabled, the manual icons use YUI to adjust the completion value without reloading the page. In this case some kind of animation – for example, the word ‘Saved’ appearing next to the icon for a second before fading away – will be used to indicate to users that their change has taken effect.
* If completion is not enabled for an activity (or for the course, site, etc) then the print_section display is the same as at present.
* When editing is turned on, completion information always displays as ticked regardless of the user’s actual completion setting. This makes it easy to see that completion is enabled for that activity.

I will get a graphic designer to look at the icons to use. To reiterate, there are six icons:

* automatic completion, not completed yet (above, not actually shown on its own, but would be a faint grey dotted box)
* automatic completion, completed (above, slightly grey tick, with faint grey dotted surround)
* automatic completion, pass (not shown, e.g. could be a green tick)
* automatic completion, fail (not shown, e.g. could be a red cross)
* manual completion, not completed (heavy black dotted outline)
* manual completion, completed (heavy black dotted outline with black tick)

It may need some work to make the manual ones look clickable and the automatic ones look not clickable, but not irrelevant either. For example we might have to resort to crappy 3D button-style shading on the manual ones. This is what I've done (badly) in the initial version of the icons which I have made.

=== Configuration UI (activity settings page) ===
Each activity’s completion settings can be configured on the standard activity settings page. These settings only appear if completion is enabled for the course and site.

The interface will be implemented via a change to the standard_coursemodule_elements function and a new optional form member function completion_add_rules(), as mentioned above, which is called (from within standard_coursemodule_elements) to add the activity-specific form elements.

We also need to determine whether the activity supports grades. This will be determined via the new ''module_''supports() function. (Note that there are existing functions for finding out whether a module ''instance'' has a grade, but not for finding out whether a module supports grades if it hasn't been created yet.)

((TODO: Diagram needs redoing))

* A dropdown allows choice of the three completion options – none, manual, automatic. (All three are shown in the diagrams below.) If the module does not support its own completion conditions, and does not support grades, then the ‘automatic’ option will not appear.
* A ‘view’ checkbox only appears if the module supports view tracking. If completion is not set to automatic, it will be greyed out. It allows you to mark something complete as soon as the user goes there once.
* A 'require grade' checkbox only appears if the module supports grades. If completion is not set to automatic, it will be greyed out.
** At this point we could have a dropdown selector to choose which grade item to use if there is more than one. However, at least for the first release, I am not providing a user interface for that feature.
* Module-specific settings, if any, are included. These are also greyed out if completion is not set to automatic. The module can add any number of settings. It is responsible for storing the data from these as part of its normal form processing.
* <nowiki>An expected completion date (default disabled) is given. This can be enabled for manual or automatic completion. It has no practical effect but displays on the progress screen. The intention is that those who design a course can set these dates at key points in the course. During the course, teachers can look at the progress report and use the dates as a guideline to check whether students are falling behind. [At a later date it might be possible to do other things with this data, such as export a list of 'late' students to an external system.]</nowiki>
* If anybody already has stored completion state for this activity, completion settings will be locked: they appear, but read-only. A button allows you to unlock the settings (making those fields editable again); after you do that and save the form, existing completion data is wiped and recalculated against the new conditions. A warning by the button explains that changing completion conditions after students complete things is not a good idea.

=== Progress tracking UI ===
Teachers wishing to track student progress can do so via the admin block. The existing course reports page will include a link to view student progress if the user has viewprogress capability.

The resulting page shows a summary of progress either for a particular group, or for all students in the course, according to the normal rules for group selection. It may include a standard group dropdown too.

# Progress is shown in a table. Students (everyone with a role in progresstrackedroles<nowiki>) are displayed down the left of the table and for activities that have completion enabled, the activity names [with expected completion dates, if set] are displayed across the top. Students can be sorted by first name or last name. The student names link to profiles and activity names link to the activities.</nowiki>
# The cells in this grid show progress indicators using the same icons as used on the course view page, although these icons are not clickable in the report. For each cell, the title, which you can see by hovering over it, indicates the state of the cell and the time modified (‘Completed 12/9/08 13:47’) as well as the student's name and the activity name (in case you are scrolling around a table that doesn't fit on-screen).
# A link at the bottom allows this table to be downloaded in CSV format. The downloaded version contains the same data, using two columns (‘state’ and ‘date’) for each activity.

=== Performance ===
==== Course view ====
When completion is enabled for a course, the course view page needs to obtain completion information. This will be cached in session and retrieved efficiently (hopefully 1 query) the first time.

==== Module pages ====
There is no performance impact when using modules that do not support completion, or where completion is disabled.

When you take an action that potentially involves completion (e.g. if you make a forum post to a forum that has enabled automatic completion when you reach N posts) the same completion state cache is used to read the current state of the data, so this should need no queries (you probably already saw the front page).

If your action could potentially change that completion state (e.g. you have not already completed the activity and you just made an additional forum post) there will be an additional cost at that time, depending on the activity – in this case, the forum will do a query to find out how many posts you've made. Because these actions occur relatively rarely, this should not cause a serious problem. (Once you have completed the activity, making another post will not incur the performance penalty.)

View-related completion tracking, the part most potentially problematic, will behave similarly: the first time you view something that has a 'viewed' requirement, it will make extra queries as it marks it viewed (or, if you viewed it in a previous session, loads up that information). After that the information will be cached in your session.

=== Backup and restore ===
* When users are included in backup, course backup will include the contents of the _course_modules_completion table.
* Course and course-modules backup will be modified to include the new fields in those tables.

= Conditional availability =
== Conditional options ==
There is no specific option to enable this part of the feature (?). The parts which depend on the completion system are enabled using the completion flag.

== Available conditions ==
You can place conditions on any activity. Conditions are always combined with Boolean AND, i.e. all conditions must be met before the activity becomes available. Unlike completion, conditions are not module-dependent. There are two types of condition:

# Conditional on date. You can have both of these conditions if required.

#
#* On or after date – activity becomes available on given date.
#* Before date – activity becomes unavailable on given date.

# Conditional on other activities. You can have as many of these conditions as desired.

#
#* Activity must be completed – any kind of completion will do.
#* Activity must be completed and passed – completion must have been graded and displayed with a pass mark (tick icon).
#* Activity must be graded at least/at most ''N''.

== Database ==
* _course_modules
** New field availablefrom, unsigned int (10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch</nowiki>) after which activity becomes available.
** New field availableuntil, unsigned int(10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch) after which activity becomes unavailable.</nowiki>
** New field showavailability, unsigned int (1) not null default 0.0 = Activity does not appear at all if conditions are not met.1 = If conditions are not met, activity appears but greyed out (‘hidden’ style) with no link and a short explanation of when it will be available.
* New table _course_modules_avail(able?) which stores any per-module conditions.
** id.
** coursemoduleid<nowiki> [index]</nowiki>.ID of the module that is being restricted.
** cmsourceid.ID of module that the restriction is based on.
** requiredcompletion, unsigned int(1) not null default 0.0 = no required completion.1 = required completed.2 = required completed and passed.3 = required completed and failed.
** gradesign, varchar(2).NULL = no required grade.<nowiki>‘<’, ‘<=</nowiki>’, ‘>’, ‘>=’ = requirement for grade.
** requiredgrade, number(10,5 decimals).Grade boundary used together with the above sign. May be null.

== API ==
Two new functions:

* availability_is_available($cm)Returns true if the module is available to students (it is visible, plus availability conditions, if any, are met). Does not include course access conditions, which it assumes have already been checked.This is a slot-in replacement where code checks for $cm->visible at key points such as in require_login.
* availability_get_display_details($cm)Obtains information about the activity’s availability which is required in order to display (or not display) a link to the activity. Returns an object with the following fields:->available – If true, activity is available; users should be allowed to access it / get links to it.->show – If true, activity should be displayed (even to users who do not have viewhiddenactivities)->info – Informational string. Blank if the activity is available.

Other changes:

* For performance reasons we need to cache the conditions in _course_modules_available. Best option is to use existing get_fast_modinfo infrastructure. This should not be hard. The above two functions will use this cache.

== Configuration UI (activity settings page) ==
The configuration UI will be implemented as part of standard_coursemodule_elements in the module forms. The existing ‘visible to students’ option (not changed in database/code) is moved within this UI.

This UI will appear even if completion is not enabled, but the parts related to completion will not show. So if completion is not enabled you will still be able to set available dates if you like, and the interface will remain consistent. The diagram below shows, first, the version that appears with completion not enabled, and then the one you get with completion enabled.

((There should be a diagram here, not sure it will show in the wiki version))

[[Image:]]

* The actual ‘available from’ options should include time as well as date. ‘Available from’ should default to midnight tomorrow; ‘Available until’ should default to 23:59 today. (I got bored laying out combo boxes.)
* ‘Information display’ controls whether informational text is displayed to students when an activity is not available. (See below.) The default is not to show information.
* The list of other activities which might have conditions includes only those other activities on the course which either have completion information, or a grade. Anything which doesn’t have completion information or a grade is omitted.
* Only one condition is permitted per other activity. This isn’t a restriction of the back-end, it just makes the UI simpler.
* The condition type dropdown by each activity is adjusted dynamically to include only options that are valid for that activity:
** ‘Completed’ appears only if completion is enabled for the activity.
** ‘Completed with pass’ and ‘Completed with fail’ (which I missed off the diagram by accident) appear only if completion is enabled for the activity, and set to a grade item, and the grade item contains a pass mark.
** The grade conditions appear only if the activity has a grade item.
* The grade box is a text-entry field. Users type in the floating-point number version of the required grade.

== Activity UI (course page) ==
(This will be accomplished via code changes to print_section. Logic is basically the same as for the current visible flag.)

For available activities, the display obviously does not change. Unavailable activities will be displayed as follows:

* If the current user has viewhiddenactivities:
** The activity displays using the CSS style for hidden activities.
** The informational message as to why the activity isn’t available is displayed (even if showinfo is not set).
* If the current user does not have viewhiddenactivities:
** If showavailability is not set, or if the activity is actually hidden (visibility 0), the activity does not display at all.
** If showavailability is set and the activity isn’t hidden but is unavailable for some other reason, the name of the activity displays using the CSS style for hidden activities, but does not include an actual link to the activity. The informational message as to why the activity isn’t available is displayed.

Here are some examples of hidden activities with informational text:Assignment resources Available from 6 Oct 2008Assignment resources Available when Unit 1 Test grade is > 90Assignment resources Available when Tutor group forum is marked complete (+ other requirements)When there are multiple conditions, only one is shown. Date is considered first; the order after that is arbitrary.

Behaviour is the same when editing is turned on except that the ‘availability’ string moves to the line below so as not to clash with all those icons.

== Performance ==
This adds a single quick database query to the course view page for courses which have enabled conditional activities / completion.

All other information is cached in modinfo<nowiki>, so does not have a performance penalty, save one problematic issue: the feature that allows arbitrary grade information to be considered. If you use pass/fail information, that’s fine, it’s there already in the completion data. But if you use a specific grade [and for example it could be different values for different activities] then the actual grade for the item needs to be retrieved on course view.</nowiki>

I don’t believe this will pose a massive performance issue as it only applies when modules are used as source for this kind of information. We should review this once it’s developed and, if necessary, optimise performance then. There are various caching approaches we could use.

== Module delete ==
If you try to delete a module, it will check to see if that module is referenced by any other module as a condition. If that’s the case, you will not be allowed to delete it. An error message will include a link to the module edit page for the other module (so you can go there and delete the condition if you like).

== Backup and restore ==
* The new _course_modules_available table will be backed up and restored.
** Partial restore needs to be handled. If your backup includes module A but not module B, and module A had a condition on B, then that condition will not be restored.
* Backup will also be modified to include the fields added to _course_modules.
* If you restore a course with a startdateoffset, it will offset the dates from the new _course_modules date fields.

= Module supported features =
As part of the completion system, I needed a way for modules to indicate support of certain features, so I propose a generic one which I have implemented:

* A module API function ''module''_supports($feature) which returns false if the feature is not available, and true (or an object with more information, if needed for specific features) if it is.
* A standard API function module_supports($modulename,$feature) which works as follows:
** If the $modulename_supports_feature function exists, it calls that function and returns the result.
** Otherwise it returns false – or, if features are added that correspond to ‘legacy’ ones that we can find out another way (e.g. by looking to see if a function exists) then this can be done.
* A set of FEATURE_''xx'' constants. For this code, the following are necessary:
** FEATURE_GRADE_HAS_GRADE
** FEATURE_COMPLETION_TRACKS_VIEWS
** FEATURE_COMPLETION_HAS_RULES
* Other feature constants could be added as desired, e.g. FEATURE_CRON, etc. My initial implementation will include only the 'new' ones needed for this work.

Note that this implementation would not be appropriate if modules were changed to be fully object-oriented. However I don't expect that to happen in Moodle 2 so this is probably OK.

Development:Git Migration

2008-06-24T10:30:03Z

Quen: /* The way to go for developers who want it now */

= Proposal to move Moodle development from CVS to Git =

There have been discussions to abandon CVS as the main version tracking system, to move to a distributed system instead. Many developers have expressed their interest for [http://git.or.cz Git]. A [http://moodle.org/mod/forum/discuss.php?d=99763 discussion] is taking place in moodle.org forums about a possible move to Git and contains a lot of information.

Some other systems have also been mentioned, such as [http://www.selenic.com/mercurial/wiki/ Mercurial].

= Git and human usage =

* A lot of people need an easy interface to the revision system. Most of them are currently using TortoiseCVS (a lot of translators, it seems). There is no tool (as of late June 2008) for Git that is equivalent in ease of use to TortoiseCVS, though [http://digilander.libero.it/mcostalba/ qgit] (said to be running flawlessly on Windows) and [http://cola.tuxfamily.org/ git-cola] are improving. In the meantime, people could use a CVS gateway, which would need to work both ways (read & write), to give people time to change over once proper tools become available.
* Developers using Eclipse, NetBeans, and most other major IDEs need to wait for plugins. There is a [http://wiki.eclipse.org/EGit/Proposal proposal], which is aiming to provide a pure-Java implementation along with an Eclipse plugin and should lead to support at least in the Java-based IDEs, but this is still not ready for prime time (June 2008).
* [http://vim.sourceforge.net/scripts/script.php?script_id=90 VCSCommand] plugin for Vim now supports Git.
* Some users are using CVS mirrors to deploy (and update) their site. Can't break this. A read-only CVS gateway could be a good working solution to this.

= Git and server-side tool integration =

* Web interface to the repository: Git provides a web interface. Alternatively, Trac now provides a [http://trac-hacks.org/wiki/GitPlugin GitPlugin] that could be used.
* Bug tracking: see [http://forums.atlassian.com/thread.jspa?threadID=24671&tstart=0] and [http://jira.atlassian.com/browse/FE-337] (support still uncomplete, on June 24 2008). Martín Langhoff says: "[http://moodle.org/mod/forum/discuss.php?d=99763#p441057 looks like there is a mercurial plugin we can quickly grab and, ahem, repurpose...]". We could also use a CVS gateway, though there could be problems with this workaround, as "[http://moodle.org/mod/forum/discuss.php?d=99763#p440831 the rev numbers don't line up]".
* The module managing [http://moodle.org/cvs moodle.org/cvs] would need to be rewritten to use Git. The user-access control would need to be managed [http://moodle.org/mod/forum/discuss.php?d=99763#p441030 using the pre-received hook].
* Need to see if cvsspam (for the cvs-commits list) would still work
* Moving cvs.moodle.org to git.moodle.org? Or keep both?

= The way to go for developers who want it now =

It's possible to use Git right now, to track
* Follow instructions on the "[[Tracking Moodle CVS with git]]" page
* Use git-cvsexportcommit to commit to Moodle CVS
* Wait until the next refresh (5h30 am, New Zealand time) to get the patch back into your local Git repository

= Other interesting links =

* [http://garrys-brain.blogspot.com/2008/04/git-for-windows-msysgit.html Garry Bodsworth] says some good of the MinGW port of Git (for Windows)
* Installation reports - Git growth amongst DSCMs: [http://tinyurl.com/4uemg2 http://tinyurl.com/4uemg2]
* Usage reports - With a longer timeframe, and counting CVS/SVN: [http://tinyurl.com/4hu2cn http://tinyurl.com/4hu2cn]
* Get a free personal public git repo with some cool tools: [http://github.com/ http://github.com/]
* Free screencasts by Scott Chacon on using Git: [http://gitcasts.com/ http://gitcasts.com/]
* [http://pragprog.com/titles/tsgit/pragmatic-version-control-using-git Pragmatic Version Control using Git] will come out on November 1st, 2008.

[[Category:Developer]]
[[Category:Developer tools]]

Development:Git Migration

2008-06-24T10:28:36Z

Quen: /* Git and human usage */

= Proposal to move Moodle development from CVS to Git =

There have been discussions to abandon CVS as the main version tracking system, to move to a distributed system instead. Many developers have expressed their interest for [http://git.or.cz Git]. A [http://moodle.org/mod/forum/discuss.php?d=99763 discussion] is taking place in moodle.org forums about a possible move to Git and contains a lot of information.

Some other systems have also been mentioned, such as [http://www.selenic.com/mercurial/wiki/ Mercurial].

= Git and human usage =

* A lot of people need an easy interface to the revision system. Most of them are currently using TortoiseCVS (a lot of translators, it seems). There is no tool (as of late June 2008) for Git that is equivalent in ease of use to TortoiseCVS, though [http://digilander.libero.it/mcostalba/ qgit] (said to be running flawlessly on Windows) and [http://cola.tuxfamily.org/ git-cola] are improving. In the meantime, people could use a CVS gateway, which would need to work both ways (read & write), to give people time to change over once proper tools become available.
* Developers using Eclipse, NetBeans, and most other major IDEs need to wait for plugins. There is a [http://wiki.eclipse.org/EGit/Proposal proposal], which is aiming to provide a pure-Java implementation along with an Eclipse plugin and should lead to support at least in the Java-based IDEs, but this is still not ready for prime time (June 2008).
* [http://vim.sourceforge.net/scripts/script.php?script_id=90 VCSCommand] plugin for Vim now supports Git.
* Some users are using CVS mirrors to deploy (and update) their site. Can't break this. A read-only CVS gateway could be a good working solution to this.

= Git and server-side tool integration =

* Web interface to the repository: Git provides a web interface. Alternatively, Trac now provides a [http://trac-hacks.org/wiki/GitPlugin GitPlugin] that could be used.
* Bug tracking: see [http://forums.atlassian.com/thread.jspa?threadID=24671&tstart=0] and [http://jira.atlassian.com/browse/FE-337] (support still uncomplete, on June 24 2008). Martín Langhoff says: "[http://moodle.org/mod/forum/discuss.php?d=99763#p441057 looks like there is a mercurial plugin we can quickly grab and, ahem, repurpose...]". We could also use a CVS gateway, though there could be problems with this workaround, as "[http://moodle.org/mod/forum/discuss.php?d=99763#p440831 the rev numbers don't line up]".
* The module managing [http://moodle.org/cvs moodle.org/cvs] would need to be rewritten to use Git. The user-access control would need to be managed [http://moodle.org/mod/forum/discuss.php?d=99763#p441030 using the pre-received hook].
* Need to see if cvsspam (for the cvs-commits list) would still work
* Moving cvs.moodle.org to git.moodle.org? Or keep both?

= The way to go for developers who want it now =

It's possible to use Git right now, to track
* Follow instructions on the "[Tracking Moodle CVS with git]" page
* Use git-cvsexportcommit to commit to Moodle CVS
* Wait until the next refresh (5h30 am, New Zealand time) to get the patch back into your local Git repository

= Other interesting links =

* [http://garrys-brain.blogspot.com/2008/04/git-for-windows-msysgit.html Garry Bodsworth] says some good of the MinGW port of Git (for Windows)
* Installation reports - Git growth amongst DSCMs: [http://tinyurl.com/4uemg2 http://tinyurl.com/4uemg2]
* Usage reports - With a longer timeframe, and counting CVS/SVN: [http://tinyurl.com/4hu2cn http://tinyurl.com/4hu2cn]
* Get a free personal public git repo with some cool tools: [http://github.com/ http://github.com/]
* Free screencasts by Scott Chacon on using Git: [http://gitcasts.com/ http://gitcasts.com/]
* [http://pragprog.com/titles/tsgit/pragmatic-version-control-using-git Pragmatic Version Control using Git] will come out on November 1st, 2008.

[[Category:Developer]]
[[Category:Developer tools]]

Development:DB layer 2.0 migration docs

2008-06-06T13:03:01Z

Quen: /* The golden changes */

{{Work in progress}}{{Template:Development:dmllib 2.0}}__NOTOC__

== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[Development:XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

== XMLDB changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the XMLDB Editor (Admin->Misc->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.

=== The changes ===

* No changes are required in install.xml files at all (that's good news!).
* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
* All XMLDBTable instances in your upgrade code must be replaced by xmldb_table (parameters are the same, no change with them required)
* All XMLDBField instances in your upgrade code must be replaced by xmldb_field (no change in parameters)
* All XMLDBIndex instances in your upgrade code must be replaced by xmldb_index (no change in parameters)
* All XMLDBKey instances in your upgrade code must be replaced by xmldb_key (no change in parameters)
* All the addFieldInfo() methods must be replaced by add_field() (no change in parameters)
* All the addIndexInfo() methods must be replaced by add_index() (no change in parameters)
* All the addKeyInfo() methods must be replaced by add_key() (no change in parameters)
* All the setAttributes() methods must be replaced by set_attributes() (no change in parameters)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
table_exists ==> $dbman->table_exists
field_exists ==> $dbman->field_exists
index_exists ==> $dbman->index_exists
find_index_name ==> $dbman->find_index_name
find_check_constraint_name ==> $dbman->find_check_constraint_name
check_constraint_exists ==> $dbman->check_constraint_exists
find_sequence_name ==> $dbman->find_sequence_name
create_table ==> $dbman->create_table
drop_table ==> $dbman->drop_table
rename_table ==> $dbman->rename_table
add_field ==> $dbman->add_field
drop_field ==> $dbman->drop field
rename_field ==> $dbman->rename_field
change_field_type ==> $dbman->change_field_type
change_field_precision => $dbman->change_field_precision
change_field_unsigned ==> $dbman->change_field_unsigned
change_field_notnull ==> $dbman->change_field_notnull
change_field_enum ==> $dbman->change_field_enum
change_field_default ==> $dbman->change_field_default
add_key ==> $dbman->add_key
drop_key ==> $dbman->drop_key
add_index ==> $dbman->add_index
drop_index ==> $dbman->drop_index

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into two sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere).

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

*Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
Example:
// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);

'''Careful: for some functions, the $params array is not the second function parameter. For example, set_field:'''
// Old syntax
set_field('user', 'firstname', 'Eloy', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Eloy', array('id' => 1));

*All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
Example:
// Old syntax:
$user = get_record("user", "firstname", "Eloy", "lastname", "Lafuente");

// New syntax:
global $DB;
$conditions = array("firstname" => "Eloy", "lastname" => "Lafuente");
$user = $DB->get_record("user", $conditions);
**Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
global $DB;
$user = $DB->get_record("user", array("firstname" => "Eloy", "lastname" => "Lafuente") );

*rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
Example:
// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
....
}
$rs->close();

*All uses of addslashes() must be removed. They are no longer needed
*Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

Example:
// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";

*When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
**Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
**Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array.

Examples:
// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Eloy' AND lastname = 'Lafuente'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Eloy', 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Eloy', 'lastname' => 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);

*Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

Example:
// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);

=== The iron changes ===

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

Development talk:DB layer 2.0 migration docs

2008-06-06T11:24:15Z

Quen: /* random things */

* The developer reading this article MUST read XMLDB Documentation (at least Introduction + three first Developing section pages) otherwise he's going to ask plenty of questions :) It could be very good that the first line of this article be: "In order to understand this article you need to know how works the database abstraction layer in Moodle (previous to 2.0)".

* API link is broken (=> http://php.moodle.org/ "Server not found")

* We know that some changes need to be done on 2.0. But on what?
All these examples concerns the glossary module. It would be good to indicate it first. When I read it first, I didn't really know what was going to be explained in XMLDB changes. In fact all this section is about "Updating your upgrade.php file for Moodle 2.0". Conclusion: we really need a clear first sentence for the all "XMLDB changes" section. So we know what we are going to read. Once I knew what is about, all was very clear.

* If we don't make any change on DDL code we shouldn't make it as a section/block. The DDL section should be a note. If you remove this section don't forget to update: "Changes below are grouped into 3 main blocks" => "Changes below are grouped into 2 main blocks"

* DML section:
this is about to change all DML code, in all Moodle files? I think it miss an introduction line as well.

* Maybe you should use more the word: YOU should do that, YOU do this, YOU ... The developer will feel more guided.

Note: I wrote this comment on first read.

Note 2: I'm new as dev in Moodle, and I've just discover all the power of Moodle XMLDB reading. All the current XMLDB looks awesome, I don't even talk about the coming 2.0 :)

[[User:jerome mouneyrac|jerome mouneyrac]] 22:22, 22 May 2008 (CDT)

== random things ==

1 I added a marker re add_index or somesuch, is it really renamed add_key or is that just a copy/paste error? If it is correct, needs changing to emphasise that the function has really changed.

2 The section with nothing in it (DDL) should probably be removed :)

3 'Golden' and 'iron' makes no sense at all to me, nor did the explanation. Could we rename these in some way?

4 The example using named params should probably be changed to use better names for the params eg fn, ln - if you're using 'param1' and 'param2' you should use use the ordered one.

5 Some of the examples are unnecessarily wordy - for example, why put the array into a variable then call the function? It only has two elements, you can do it in the same line no problem.
:Wordiness in code samples is perfectly OK, Sam, but you're free to be more terse in your implementations ;) [[User:Nicolas Connault|Nicolas Connault]] 06:59, 3 June 2008 (CDT)
::Yes, but my point is that it makes it look bad for people who are having to change. It's like, OMG! this was one line before and now it's four! wtf I have to define a separate array every time I scratch my backside! why are you making my life a misery, you unfeeling b****rds!!! That kind of thing. :) I don't think it makes it easier to understand to show use of a mostly-unnecessary separate variable. [[User:sam marshall|sam marshall]] 06:24, 6 June 2008 (CDT)

6 Wow this new system is a fantastic improvement (except for the new IN function which is kind of nasty)

[[User:sam marshall|sam marshall]] 04:32, 3 June 2008 (CDT)

Development talk:DB layer 2.0 migration docs

2008-06-03T09:33:41Z

Quen: /* random things */

* The developer reading this article MUST read XMLDB Documentation (at least Introduction + three first Developing section pages) otherwise he's going to ask plenty of questions :) It could be very good that the first line of this article be: "In order to understand this article you need to know how works the database abstraction layer in Moodle (previous to 2.0)".

* API link is broken (=> http://php.moodle.org/ "Server not found")

* We know that some changes need to be done on 2.0. But on what?
All these examples concerns the glossary module. It would be good to indicate it first. When I read it first, I didn't really know what was going to be explained in XMLDB changes. In fact all this section is about "Updating your upgrade.php file for Moodle 2.0". Conclusion: we really need a clear first sentence for the all "XMLDB changes" section. So we know what we are going to read. Once I knew what is about, all was very clear.

* If we don't make any change on DDL code we shouldn't make it as a section/block. The DDL section should be a note. If you remove this section don't forget to update: "Changes below are grouped into 3 main blocks" => "Changes below are grouped into 2 main blocks"

* DML section:
this is about to change all DML code, in all Moodle files? I think it miss an introduction line as well.

* Maybe you should use more the word: YOU should do that, YOU do this, YOU ... The developer will feel more guided.

Note: I wrote this comment on first read.

Note 2: I'm new as dev in Moodle, and I've just discover all the power of Moodle XMLDB reading. All the current XMLDB looks awesome, I don't even talk about the coming 2.0 :)

[[User:jerome mouneyrac|jerome mouneyrac]] 22:22, 22 May 2008 (CDT)

== random things ==

1 I added a marker re add_index or somesuch, is it really renamed add_key or is that just a copy/paste error? If it is correct, needs changing to emphasise that the function has really changed.

2 The section with nothing in it (DDL) should probably be removed :)

3 'Golden' and 'iron' makes no sense at all to me, nor did the explanation. Could we rename these in some way?

4 The example using named params should probably be changed to use better names for the params eg fn, ln - if you're using 'param1' and 'param2' you should use use the ordered one.

5 Some of the examples are unnecessarily wordy - for example, why put the array into a variable then call the function? It only has two elements, you can do it in the same line no problem.

6 Wow this new system is a fantastic improvement (except for the new IN function which is kind of nasty)

[[User:sam marshall|sam marshall]] 04:32, 3 June 2008 (CDT)

Development talk:DB layer 2.0 migration docs

2008-06-03T09:32:04Z

Quen: random things

* The developer reading this article MUST read XMLDB Documentation (at least Introduction + three first Developing section pages) otherwise he's going to ask plenty of questions :) It could be very good that the first line of this article be: "In order to understand this article you need to know how works the database abstraction layer in Moodle (previous to 2.0)".

* API link is broken (=> http://php.moodle.org/ "Server not found")

* We know that some changes need to be done on 2.0. But on what?
All these examples concerns the glossary module. It would be good to indicate it first. When I read it first, I didn't really know what was going to be explained in XMLDB changes. In fact all this section is about "Updating your upgrade.php file for Moodle 2.0". Conclusion: we really need a clear first sentence for the all "XMLDB changes" section. So we know what we are going to read. Once I knew what is about, all was very clear.

* If we don't make any change on DDL code we shouldn't make it as a section/block. The DDL section should be a note. If you remove this section don't forget to update: "Changes below are grouped into 3 main blocks" => "Changes below are grouped into 2 main blocks"

* DML section:
this is about to change all DML code, in all Moodle files? I think it miss an introduction line as well.

* Maybe you should use more the word: YOU should do that, YOU do this, YOU ... The developer will feel more guided.

Note: I wrote this comment on first read.

Note 2: I'm new as dev in Moodle, and I've just discover all the power of Moodle XMLDB reading. All the current XMLDB looks awesome, I don't even talk about the coming 2.0 :)

[[User:jerome mouneyrac|jerome mouneyrac]] 22:22, 22 May 2008 (CDT)

== random things ==

1 I added a marker re add_index or somesuch, is it really renamed add_key or is that just a copy/paste error? If it is correct, needs changing to emphasise that the function has really changed.

2 The section with nothing in it (DDL) should probably be removed :)

3 'Golden' and 'iron' makes no sense at all to me, nor did the explanation. Could we rename these in some way?

4 The example using named params should probably be changed to use better names for the params eg fn, ln - if you're using 'param1' and 'param2' you should use use the ordered one.

5 Wow this new system is a fantastic improvement (except for the new IN syntax which is horrid)

[[User:sam marshall|sam marshall]] 04:32, 3 June 2008 (CDT)

Development:DB layer 2.0 migration docs

2008-06-03T09:22:50Z

Quen: /* The changes */

{{Work in progress}}{{Template:Development:dmllib 2.0}}__NOTOC__
This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 3 main blocks ([[Development:XMLDB_Documentation|xmldb]], [[wikipedia:Data_Definition_Language|ddl]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end knowing not only what to change but how and why those changes are required.

Also, it's recommended to read the whole [[Development:XMLDB_Documentation|XMLDB]], [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation and [http://php.moodle.org APIs] before start with the migration. That will allow you to have some initial knowledge about the new architecture.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too much complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, pleas report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, for sure that will help a lot of developers. Thanks!

== XMLDB changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the XMLDB Editor (Admin->Misc->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look to some code in core modules, blocks... whatever you need. They are a good reference.

=== The changes ===

* No changes required in install.xml files at all (that's good news!).
* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
* All XMLDBTable instances in your upgrade code must be replaced by xmldb_table (parameters are the same, no change with them required)
* All XMLDBField instances in your upgrade code must be replaced by xmldb_field (no change in parameters)
* All XMLDBIndex instances in your upgrade code must be replaced by xmldb_index (no change in parameters)
* All XMLDBKey instances in your upgrade code must be replaced by xmldb_key (no change in parameters)
* All the addFieldInfo() methods must be replaced by add_field() (no change in parameters)
* All the addIndexInfo() methods must be replaced by add_key() (no change in parameters) [[User:sam marshall|sam marshall]] I'm guessing this is supposed to be add_index()? Or are indexes the same as keys now?
* All the addKeyInfo() methods must be replaced by add_key() (no change in parameters)
* All the setAttributes() methods must be replaced by set_attributes() (no change in parameters)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
table_exists ==> $dbman->table_exists
field_exists ==> $dbman->field_exists
index_exists ==> $dbman->index_exists
find_index_name ==> $dbman->find_index_name
find_check_constraint_name ==> $dbman->find_check_constraint_name
check_constraint_exists ==> $dbman->check_constraint_exists
find_sequence_name ==> $dbman->find_sequence_name
create_table ==> $dbman->create_table
drop_table ==> $dbman->drop_table
rename_table ==> $dbman->rename_table
add_field ==> $dbman->add_field
drop_field ==> $dbman->drop field
rename_field ==> $dbman->rename_field
change_field_type ==> $dbman->change_field_type
change_field_precision => $dbman->change_field_precision
change_field_unsigned ==> $dbman->change_field_unsigned
change_field_notnull ==> $dbman->change_field_notnull
change_field_enum ==> $dbman->change_field_enum
change_field_default ==> $dbman->change_field_default
add_key ==> $dbman->add_key
drop_key ==> $dbman->drop_key
add_index ==> $dbman->add_index
drop_index ==> $dbman->drop_index

== DDL changes ==

You are really lucky! If you've performed all the changes above, then all your DDL code has been upgraded successfully! Congrats!

== DML changes ==

=== Some comments ===

* This is, with difference, the complexer part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into two sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere).

=== The golden changes ===
*Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
Example:
// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);

*All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
Example:
// Old syntax:
$user = get_record("user", "firstname", "Eloy", "lastname", "Lafuente");

// New syntax:
global $DB;
$conditions = array("firstname" => "Eloy", "lastname" => "Lafuente");
$user = $DB->get_record("user", $conditions);

*rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
Example:
// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
....
}
$rs->close();

*All uses of addslashes() must be removed. They are no longer needed
*Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

Example:
// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";

*When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
**Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
**Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array.

Examples:
// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Eloy' AND lastname = 'Lafuente'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Eloy', 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('param1' => 'Eloy', 'param2' => 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :param1 AND lastname = :param2";
$user = $DB->get_record_sql($sql, $params);

*Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

Example:
// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);

=== The iron changes ===

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

Development:DB layer 2.0 migration docs

2008-06-03T09:22:34Z

Quen: /* The changes */

{{Work in progress}}{{Template:Development:dmllib 2.0}}__NOTOC__
This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 3 main blocks ([[Development:XMLDB_Documentation|xmldb]], [[wikipedia:Data_Definition_Language|ddl]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end knowing not only what to change but how and why those changes are required.

Also, it's recommended to read the whole [[Development:XMLDB_Documentation|XMLDB]], [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation and [http://php.moodle.org APIs] before start with the migration. That will allow you to have some initial knowledge about the new architecture.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too much complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, pleas report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, for sure that will help a lot of developers. Thanks!

== XMLDB changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the XMLDB Editor (Admin->Misc->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look to some code in core modules, blocks... whatever you need. They are a good reference.

=== The changes ===

* No changes required in install.xml files at all (that's good news!).
* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
* All XMLDBTable instances in your upgrade code must be replaced by xmldb_table (parameters are the same, no change with them required)
* All XMLDBField instances in your upgrade code must be replaced by xmldb_field (no change in parameters)
* All XMLDBIndex instances in your upgrade code must be replaced by xmldb_index (no change in parameters)
* All XMLDBKey instances in your upgrade code must be replaced by xmldb_key (no change in parameters)
* All the addFieldInfo() methods must be replaced by add_field() (no change in parameters)
* All the addIndexInfo() methods must be replaced by add_key() (no change in parameters) ~~ I'm guessing this is supposed to be add_index()? Or are indexes the same as keys now?
* All the addKeyInfo() methods must be replaced by add_key() (no change in parameters)
* All the setAttributes() methods must be replaced by set_attributes() (no change in parameters)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
table_exists ==> $dbman->table_exists
field_exists ==> $dbman->field_exists
index_exists ==> $dbman->index_exists
find_index_name ==> $dbman->find_index_name
find_check_constraint_name ==> $dbman->find_check_constraint_name
check_constraint_exists ==> $dbman->check_constraint_exists
find_sequence_name ==> $dbman->find_sequence_name
create_table ==> $dbman->create_table
drop_table ==> $dbman->drop_table
rename_table ==> $dbman->rename_table
add_field ==> $dbman->add_field
drop_field ==> $dbman->drop field
rename_field ==> $dbman->rename_field
change_field_type ==> $dbman->change_field_type
change_field_precision => $dbman->change_field_precision
change_field_unsigned ==> $dbman->change_field_unsigned
change_field_notnull ==> $dbman->change_field_notnull
change_field_enum ==> $dbman->change_field_enum
change_field_default ==> $dbman->change_field_default
add_key ==> $dbman->add_key
drop_key ==> $dbman->drop_key
add_index ==> $dbman->add_index
drop_index ==> $dbman->drop_index

== DDL changes ==

You are really lucky! If you've performed all the changes above, then all your DDL code has been upgraded successfully! Congrats!

== DML changes ==

=== Some comments ===

* This is, with difference, the complexer part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into two sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere).

=== The golden changes ===
*Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
Example:
// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);

*All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
Example:
// Old syntax:
$user = get_record("user", "firstname", "Eloy", "lastname", "Lafuente");

// New syntax:
global $DB;
$conditions = array("firstname" => "Eloy", "lastname" => "Lafuente");
$user = $DB->get_record("user", $conditions);

*rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
Example:
// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
....
}
$rs->close();

*All uses of addslashes() must be removed. They are no longer needed
*Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

Example:
// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";

*When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
**Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
**Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array.

Examples:
// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Eloy' AND lastname = 'Lafuente'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Eloy', 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('param1' => 'Eloy', 'param2' => 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :param1 AND lastname = :param2";
$user = $DB->get_record_sql($sql, $params);

*Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

Example:
// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);

=== The iron changes ===

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

Development:DB layer 2.0 migration docs

2008-06-03T09:20:52Z

Quen: /* Some comments */

{{Work in progress}}{{Template:Development:dmllib 2.0}}__NOTOC__
This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 3 main blocks ([[Development:XMLDB_Documentation|xmldb]], [[wikipedia:Data_Definition_Language|ddl]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end knowing not only what to change but how and why those changes are required.

Also, it's recommended to read the whole [[Development:XMLDB_Documentation|XMLDB]], [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation and [http://php.moodle.org APIs] before start with the migration. That will allow you to have some initial knowledge about the new architecture.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too much complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, pleas report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, for sure that will help a lot of developers. Thanks!

== XMLDB changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the XMLDB Editor (Admin->Misc->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look to some code in core modules, blocks... whatever you need. They are a good reference.

=== The changes ===

* No changes required in install.xml files at all (that's good news!).
* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
* All XMLDBTable instances in your upgrade code must be replaced by xmldb_table (parameters are the same, no change with them required)
* All XMLDBField instances in your upgrade code must be replaced by xmldb_field (no change in parameters)
* All XMLDBIndex instances in your upgrade code must be replaced by xmldb_index (no change in parameters)
* All XMLDBKey instances in your upgrade code must be replaced by xmldb_key (no change in parameters)
* All the addFieldInfo() methods must be replaced by add_field() (no change in parameters)
* All the addIndexInfo() methods must be replaced by add_key() (no change in parameters)
* All the addKeyInfo() methods must be replaced by add_key() (no change in parameters)
* All the setAttributes() methods must be replaced by set_attributes() (no change in parameters)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
table_exists ==> $dbman->table_exists
field_exists ==> $dbman->field_exists
index_exists ==> $dbman->index_exists
find_index_name ==> $dbman->find_index_name
find_check_constraint_name ==> $dbman->find_check_constraint_name
check_constraint_exists ==> $dbman->check_constraint_exists
find_sequence_name ==> $dbman->find_sequence_name
create_table ==> $dbman->create_table
drop_table ==> $dbman->drop_table
rename_table ==> $dbman->rename_table
add_field ==> $dbman->add_field
drop_field ==> $dbman->drop field
rename_field ==> $dbman->rename_field
change_field_type ==> $dbman->change_field_type
change_field_precision => $dbman->change_field_precision
change_field_unsigned ==> $dbman->change_field_unsigned
change_field_notnull ==> $dbman->change_field_notnull
change_field_enum ==> $dbman->change_field_enum
change_field_default ==> $dbman->change_field_default
add_key ==> $dbman->add_key
drop_key ==> $dbman->drop_key
add_index ==> $dbman->add_index
drop_index ==> $dbman->drop_index

== DDL changes ==

You are really lucky! If you've performed all the changes above, then all your DDL code has been upgraded successfully! Congrats!

== DML changes ==

=== Some comments ===

* This is, with difference, the complexer part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into two sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere).

=== The golden changes ===
*Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
Example:
// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);

*All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
Example:
// Old syntax:
$user = get_record("user", "firstname", "Eloy", "lastname", "Lafuente");

// New syntax:
global $DB;
$conditions = array("firstname" => "Eloy", "lastname" => "Lafuente");
$user = $DB->get_record("user", $conditions);

*rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
Example:
// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
....
}
$rs->close();

*All uses of addslashes() must be removed. They are no longer needed
*Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

Example:
// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";

*When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
**Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
**Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array.

Examples:
// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Eloy' AND lastname = 'Lafuente'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Eloy', 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('param1' => 'Eloy', 'param2' => 'Lafuente');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :param1 AND lastname = :param2";
$user = $DB->get_record_sql($sql, $params);

*Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

Example:
// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);

=== The iron changes ===

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

Development:Conditional activities

2008-04-17T15:57:10Z

Quen: /* sam's picture */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

[[User:sam marshall|sam marshall]] For us and no doubt other places, the 'activity completion' part of the system is still useful even if we are not using conditional activities for a course. We would then want a reporting interface so that tutors can see which tracked activities their students have/haven't completed. (And for course staff, obviously they would be able to see all students on the course in the same manner.)

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. Would be stored in course_modules_avail

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

[[User:sam marshall|sam marshall]] How is this defined? I think it probably needs a way to specify conditions for the course.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

[[User:sam marshall|sam marshall]] I think modulespecific is difficult to handle here because it probably needs to be set per module (i.e. typically in the module settings page and stored in the module's main table). Suggest moving to the _done table.

[[User:sam marshall|sam marshall]] Eloy suggested we should only store conditions in one place (as opposed to the A/B above) but I see the possible need for several e.g. a quiz, you want one activity that shows if you get > 80% and another one that shows only if you get <80%. However I think this could still be simplified - how about putting the 'grade' stuff ONLY in this 'avail' table (so your choice for avail is basically always 'require the activity to think it's done, however it likes' but then you can additionally require a grade as well). So done = completed regardless of grade or anything else, but avail could be conditional on grade.

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==sam's picture==

This diagram shows sam's idea of how it should look/work, which is not quite the same as the original description above. It definitely isn't intended to be final in any way as features might need to be removed (or added or changed) etc. - I just did a diagram to illustrate my thinking.

[[Image:conditional.png|Possible interface diagram]]

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T15:54:11Z

Quen:

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

[[User:sam marshall|sam marshall]] For us and no doubt other places, the 'activity completion' part of the system is still useful even if we are not using conditional activities for a course. We would then want a reporting interface so that tutors can see which tracked activities their students have/haven't completed. (And for course staff, obviously they would be able to see all students on the course in the same manner.)

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. Would be stored in course_modules_avail

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

[[User:sam marshall|sam marshall]] How is this defined? I think it probably needs a way to specify conditions for the course.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

[[User:sam marshall|sam marshall]] I think modulespecific is difficult to handle here because it probably needs to be set per module (i.e. typically in the module settings page and stored in the module's main table). Suggest moving to the _done table.

[[User:sam marshall|sam marshall]] Eloy suggested we should only store conditions in one place (as opposed to the A/B above) but I see the possible need for several e.g. a quiz, you want one activity that shows if you get > 80% and another one that shows only if you get <80%. However I think this could still be simplified - how about putting the 'grade' stuff ONLY in this 'avail' table (so your choice for avail is basically always 'require the activity to think it's done, however it likes' but then you can additionally require a grade as well). So done = completed regardless of grade or anything else, but avail could be conditional on grade.

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==sam's picture==

This diagram shows sam's idea of how it should look/work, which is not quite the same as the original description above. It definitely isn't intended to be final in any way as features might need to be removed (or added) etc.

[[Image:conditional.png|Possible interface diagram]]

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

File:conditional.png

2008-04-17T15:51:22Z

Quen: Diagram of possible interface for conditional activities options (very early draft)

Diagram of possible interface for conditional activities options (very early draft)

Development:Conditional activities

2008-04-17T12:11:34Z

Quen: /* course_modules_avail */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

[[User:sam marshall|sam marshall]] For us and no doubt other places, the 'activity completion' part of the system is still useful even if we are not using conditional activities for a course. We would then want a reporting interface so that tutors can see which tracked activities their students have/haven't completed. (And for course staff, obviously they would be able to see all students on the course in the same manner.)

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. Would be stored in course_modules_avail

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

[[User:sam marshall|sam marshall]] How is this defined? I think it probably needs a way to specify conditions for the course.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

[[User:sam marshall|sam marshall]] I think modulespecific is difficult to handle here because it probably needs to be set per module (i.e. typically in the module settings page and stored in the module's main table). Suggest moving to the _done table.

[[User:sam marshall|sam marshall]] Eloy suggested we should only store conditions in one place (as opposed to the A/B above) but I see the possible need for several e.g. a quiz, you want one activity that shows if you get > 80% and another one that shows only if you get <80%. However I think this could still be simplified - how about putting the 'grade' stuff ONLY in this 'avail' table (so your choice for avail is basically always 'require the activity to think it's done, however it likes' but then you can additionally require a grade as well). So done = completed regardless of grade or anything else, but avail could be conditional on grade.

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T12:06:37Z

Quen: /* course_completion */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

[[User:sam marshall|sam marshall]] For us and no doubt other places, the 'activity completion' part of the system is still useful even if we are not using conditional activities for a course. We would then want a reporting interface so that tutors can see which tracked activities their students have/haven't completed. (And for course staff, obviously they would be able to see all students on the course in the same manner.)

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. Would be stored in course_modules_avail

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

[[User:sam marshall|sam marshall]] How is this defined? I think it probably needs a way to specify conditions for the course.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T11:51:11Z

Quen: /* This activity will be available when ... */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

[[User:sam marshall|sam marshall]] For us and no doubt other places, the 'activity completion' part of the system is still useful even if we are not using conditional activities for a course. We would then want a reporting interface so that tutors can see which tracked activities their students have/haven't completed. (And for course staff, obviously they would be able to see all students on the course in the same manner.)

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. Would be stored in course_modules_avail

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T11:43:44Z

Quen: /* Objectives */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

[[User:sam marshall|sam marshall]] For us and no doubt other places, the 'activity completion' part of the system is still useful even if we are not using conditional activities for a course. We would then want a reporting interface so that tutors can see which tracked activities their students have/haven't completed. (And for course staff, obviously they would be able to see all students on the course in the same manner.)

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. This may complicate the design slightly as obviously date is not a per-other-activity option

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T10:02:15Z

Quen: /* This activity will be completed when ... */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. This may complicate the design slightly as obviously date is not a per-other-activity option

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T10:01:38Z

Quen: /* This activity will be available when ... */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. This may complicate the design slightly as obviously date is not a per-other-activity option

[[User:sam marshall|sam marshall]] Maybe consider also an option for whether the activity is visible before it is available, greyed out with a 'This activity will be available when...' note, or not displayed at all.

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

[[User:sam marshall|sam marshall]] Just wondering, how are you going to track 'viewed'? Modules don't store this in a sensible way, only in the log table.

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T10:00:32Z

Quen: /* Course page */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

[[User:sam marshall|sam marshall]] At the OU we use an option that controls who sees the checkbox. Remember course:participate? YES IT'S THAT AGAIN. Not that it is really really desperately needed or anything. Ahem. But anyhow, we have a specific permission for who the progress system applies to, and this is checked with doanything=false. You might need something similar.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. This may complicate the design slightly as obviously date is not a per-other-activity option

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

[[User:sam marshall|sam marshall]] Just wondering, how are you going to track 'viewed'? Modules don't store this in a sensible way, only in the log table.

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]

Development:Conditional activities

2008-04-17T09:59:20Z

Quen: /* Course page */

This is a developer's page for Moodle Version 2.0, describing an evolving specification. UNDER CONSTRUCTION!

Conditional activities allow the course editor to hide certain activities until conditions on other activities have been met.

For example, a student will not see Assignment B until they have scored 80% or higher on Quiz A.

==Objectives==

# We want to know when activities are finished (for each user independently)
# We want to have this calculated automatically, but also manually if required.
# We want other some activities to be hidden until other activities are done.
# We want to "chain" these things into learning paths.
# We want the course page to remain fast.
# We want conditional activities to be optional.

==Overview==

There are two main approaches to this. For the discussion below let's use A to mean a source activity, and B and C to mean two activities that are only available when A is done.

Approach 1: The one used by activity locking is to place the UI to choose the conditions in B, so that it specifies the passing grades etc that are needed for A so that B is unlocked. This has advantages in that B can specify a different passing grade that C (both on the same A).

Approach 2: This places the logic in A, so that it defines when it is "done" any way it likes and B can just say "I'm available when A is done". The advantages here are that A can define "done" in any way it likes, and the configuration can be more subtle if the module wants it.

The approach described below actually combines BOTH these approaches so it should please everyone and allow the maximum flexibility.

==Interfaces==

===Site settings===

Admins can turn Conditional Activities on/off for the whole site.

===Course settings===

Teachers can choose between three states for a course:
# Conditional Activities off
# Conditional Activities Manual
# Conditional Activities Auto

===Course page===

For teachers
* Each activity will have an icon indicating the status, and clicking on it takes you to the activity settings (see below). These are also available as a tab from the main activity pages.

For students
* Colour icons (checkboxes) in red/orange/green down the side of the course format indicate the status of each activity
* In manual mode, these can be clicked on to toggle the status as required (so that students can manually keep track of what they've done).
* In auto mode, these icons are fixed

[[User:sam marshall|sam marshall]] Be very careful with colours. You mustn't use colour as only way of displaying information (accessibility). I'd suggest something like: For manual mode, use straightforward checkbox as above; For auto mode, use an icon as described but make these look different as well as different colour (I'd suggest grey crosshatching for unavailable, white (hollow w/black outline) for available but not done, green tick inside box for done-pass, red cross inside box for done-fail) and of course include alt text

[[User:sam marshall|sam marshall]] 'Manual' and 'Auto' modes maybe needs rethinking. I think this should be actually be a choice of 'disable system' (why? well, anyway), 'enable system', and 'enable system plus student progress'. These are equiv to off, auto, and auto+manual. The reason for this is that if you specify conditions for something you always want it to be 'auto' obviously. But, anything you didn't specify conditions for, it could be 'manual' (i.e. you want students to track progress on some things that are not trackable automatically, e.g. 'go and read this web link' (a link) or 'go and read the book we sent you' (a label)

[[User:sam marshall|sam marshall]] If this approach is adopted (or anyway for standard manual), it needs a way to turn off progress support per-activity, this could be in course_modules or whatever. For example you don't want to include a 'progress' box on something like a generic course forum that is available for the life of the course, or a course resources page that's similar, or a page about how to contact student support. We do this because in editing mode, our checkboxes include a tiny little eye icon next to them so you can hide them where they aren't needed. Maybe also appropriate to set defaults i.e. labels default to not having progress.

===Activity settings===

When the teacher is editing the activity settings for each activity, they see two parts to the page:

====This activity will be available when ...====

The UI here is standard for all modules. (Settings are stored in the '''course_modules_avail''' table.) It shows all the other activities in the course, and beside each of them are menus to choose from:
* Grade >= X (<, <=, >= and >)
* Viewed
* Completed (as defined by that activity)

[[User:sam marshall|sam marshall]] Should also include date as a condition. This may complicate the design slightly as obviously date is not a per-other-activity option

====This activity will be completed when ...====

This UI shows optional settings for this activity to define when it thinks it is finished. (Settings are stored in '''course_modules_done''' table):
* Grade >= X (<, <=, >= and >)
* Viewed
* Something else (interface defined by module)

[[User:sam marshall|sam marshall]] Just wondering, how are you going to track 'viewed'? Modules don't store this in a sensible way, only in the log table.

==Tables==

===course_modules_completion===
This table records the status of each user completing each activity module. It represents current state and is used to make the display of course pages very fast. It is updated whenever grades or modules change etc.

* id
* courseid - just here for speed
* cmid - FK to course_modules
* userid
* status - hide / not done / in progress / done fail / done pass
* timemodified

===course_completion===
This table records when whole courses are completed.

* id
* userid
* courseid
* status

===course_modules_avail===
Records settings for availability
* id
* cmid - the activity that is defining the condition
* cmsourceid - the activity we are checking
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean
* modulespecific - boolean

===course_modules_done===
Records settings for whether something is done
* id
* cmid
* gradesign - <, >, <=, => etc
* gradecutoff
* views - boolean

==Process==

Coming soon

==Issues to think about==

* How do we cope with circular references?
* We should remove conditions when activities are deleted - how does that affect things downstream?

==See also==
*Take a look at the [http://moodle.org/mod/forum/view.php?f=678 Conditional activities forum] at [http://moodle.org http://moodle.org].
*[[Activity_Locking]], a MoodleDoc page with table and descriptions of different conditional activity modules
*[[Score Lock]] a MoodleDoc page for another conditional activity module for 1.6
*[http://moodle.org/mod/forum/discuss.php?d=35488 forum discussion about Stuart Mayor's Conditional Activities], including Moodle 1.6 version
*[http://moodle.org/mod/forum/discuss.php?d=36697 Conditional activities at CICEI], running demo included as student, teacher and designer.
*[[Adding/editing_a_lesson#Dependent_on]] MoodleDoc page . The lesson activity settings in V 1.6 has a specialized dependency setting. Entering the lesson can be made dependent on the % (lesson questions) correct, time spent or completion of one other specific lesson.

*Tracker reference(s) for conditional development _____________

[[Category:Developer|Conditional activities]]