https://docs.moodle.org/dev/api.php?action=feedcontributions&feedformat=atom&user=Markn
MoodleDocs - User contributions [en]
2026-04-26T07:27:26Z
User contributions
MediaWiki 1.43.5
https://docs.moodle.org/dev/index.php?title=Graderule_API&diff=60521
Graderule API
2021-07-29T11:53:51Z
<p>Markn: </p>
<hr />
<div>{{Infobox Project<br />
|name = Graderule<br />
|state = In development<br />
|tracker = MDL-60155<br />
|discussion =<br />
|assignee = Mark Nelson<br />
}}<br />
{{Moodle 4.0}}<br />
== Introduction ==<br />
<br />
A grade rule plugin is a plugin that allows you to manipulate users final grades in the gradebook based on business rules.<br />
<br />
=== History ===<br />
<br />
This work was borne primarily as a way for Monash University to be able to implement hurdles functionality. A hurdle in their nomenclature being a grade item (or activity) that a student has to pass in order to pass the entire course. Having conditional calculations were only about half the solution as they required for a specific maximum mark and grade letter if a student failed a hurdle.<br />
<br />
== Anatomy of a Grade Rule Plugin ==</div>
Markn
https://docs.moodle.org/dev/index.php?title=Graderule_API&diff=60520
Graderule API
2021-07-29T11:53:09Z
<p>Markn: Created page with "{{Infobox Project |name = Graderule |state = In development |tracker = MDL-60155 |discussion = |assignee = Marcus Boon }} {{Moodle 3.9}} == Introduction == A grade rule plugi..."</p>
<hr />
<div>{{Infobox Project<br />
|name = Graderule<br />
|state = In development<br />
|tracker = MDL-60155<br />
|discussion =<br />
|assignee = Marcus Boon<br />
}}<br />
{{Moodle 3.9}}<br />
== Introduction ==<br />
<br />
A grade rule plugin is a plugin that allows you to manipulate users final grades in the gradebook based on business rules.<br />
<br />
=== History ===<br />
<br />
This work was borne primarily as a way for Monash University to be able to implement hurdles functionality. A hurdle in their nomenclature being a grade item (or activity) that a student has to pass in order to pass the entire course. Having conditional calculations were only about half the solution as they required for a specific maximum mark and grade letter if a student failed a hurdle.<br />
<br />
== Anatomy of a Grade Rule Plugin ==</div>
Markn
https://docs.moodle.org/dev/index.php?title=Tag_API&diff=53023
Tag API
2017-10-13T03:57:11Z
<p>Markn: /* Deleting and clearing tags */</p>
<hr />
<div>{{Moodle 3.1}}<br />
<br />
==Tag API overview==<br />
<br />
The Tag API allows you to assign labels to information in Moodle. This makes finding this information easier and also facilitates the grouping of similar information. The Tag API allows you to create, modify, delete and search tags in the Moodle system. The main tag related functions can be found in the tag/classes/tag.php file. For a through overview of all of the functions available for working with Tags please see methods in core_tag_tag, core_tag_collection and core_tag_area classes, however the following examples should give you a general understanding of how to get started with tags.<br />
<br />
This page describes API in Moodle 3.1 and above, for earlier versions see [[Tag API before 3.1]]<br />
<br />
==Tag API usage==<br />
<br />
When user tags something a '''tag instance''' is created in the database linking the item to the actual '''tag'''. If tag did not exist before it is created automatically. Do not confuse these two entities - deleting the tag instance does not normally delete tag, however deleting tag deletes all tag instances associated with it. <br />
<br />
Developers define '''tag areas''' the areas that can be tagged, examples are:<br />
* blog posts<br />
* courses<br />
* users (tags represent user interests)<br />
* activity modules<br />
* questions<br />
* wiki pages<br />
<br />
Each tag area is identified by two attributes - component and itemtype. ''Itemtype must be a name of a table in the database.'' Component is the core component or plugin responsible for the tagging. This way the same DB table (for example 'user' or 'course') may be independently tagged by several components. Administrator or manager is able to manage the tag areas, collections and tags inside them on the [https://docs.moodle.org/en/Managing_tags Managing tags] page. Users are able to search tags and view all items tagged with them that they have access to.<br />
<br />
===Defining a tag area===<br />
<br />
First, developer must define the tag areas in the file '''db/tag.php'''. This will usually look like:<br />
<code php><br />
$tagareas = array(<br />
array(<br />
'itemtype' => 'wiki_pages', // This must be a name of the database table (without prefix).<br />
'component' => 'mod_wiki', // This can be omitted for plugins since it can only be full frankenstyle name of the plugin.<br />
'callback' => 'mod_wiki_get_tagged_pages',<br />
'callbackfile' => '/mod/wiki/locallib.php',<br />
),<br />
);<br />
</code><br />
You will also need to add language string, for the example above it will be '''$string['tagarea_wiki_pages'] = 'Wiki pages';'''<br />
<br />
There are more options such as specifying the default value for "Standard tags", having a fixed collection or excluding from search. They can be found in comments in [[https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]]<br />
<br />
After making changes to db/tag.php plugin developer must bump the plugin version in '''version.php''' and run upgrade script. This usually applies to any changes in the db/ folder.<br />
<br />
===Adding tags element to the editing form===<br />
<br />
After tag area is defined it should appear on "Manage tags" page. Now it is time to allow users to add/change tags when editing the item. Here is an example from Wiki module:<br />
<br />
1. Add a 'tags' form element to the editing form:<br />
<code php><br />
$mform->addElement('tags', 'tags', get_string('tags'), array('itemtype' => 'wiki_pages', 'component' => 'mod_wiki'));<br />
</code><br />
<br />
This element will automatically check if the tag area is disabled by the manager and will not display anything in this case. However if you want to add a header you need to check if tag area is enabled add this:<br />
<code php><br />
if (core_tag_tag::is_enabled('mod_wiki', 'wiki_pages')) {<br />
$mform->addElement('header', 'tagshdr', get_string('tags', 'tag'));<br />
}<br />
</code><br />
<br />
2. Save the form data<br />
<code php><br />
if ($data = $form->get_data()) {<br />
// Do some other processing here, if this is a new page (item) you need to insert it in the DB and obtain id.<br />
// $pageid = $data->id;<br />
core_tag_tag::set_item_tags('mod_wiki', 'wiki_pages', $pageid, $modulecontext, $data->tags);<br />
}<br />
</code><br />
It is important to specify the correct context in this function. Note that $data->tags will always be returned by the form, even if the area is disabled, however core_tag_tag::set_item_tags() will not change or reset tags if the tag area is disabled.<br />
<br />
3. Populate the form with existing tags before calling $form->set_data($data):<br />
<code php><br />
$data = $DB->get_record('wiki_pages', array('id' => $this->page->id)); // Well, it's more complicated than that of course....<br />
$data->tags = core_tag_tag::get_item_tags_array('mod_wiki', 'wiki_pages', $this->page->id);<br />
$form->set_data($data);<br />
</code><br />
<br />
Always test the code with tag area enabled and disabled.<br />
<br />
===Displaying tags next to the item===<br />
<br />
Example of displaying of the tags are user interests on the user profile page. User can see the list of interests, each of them is a link that leads to the page that shows all items tagged with this tag.<br />
<br />
Here is the code used by Wiki module to display tags the page is tagged with:<br />
<br />
<code php><br />
echo $OUTPUT->tag_list(core_tag_tag::get_item_tags('mod_wiki', 'wiki_pages', $page->id), null, 'wiki-tags');<br />
</code><br />
<br />
===Deleting and clearing tags===<br />
<br />
Cron will automatically remove tag instances that point to non existing items, however it is a good habit to delete tags when the record is deleted.<br />
<br />
'''Please note:''' If you have created a course activity that uses tags you should also remember to delete the tags during a course reset by adding code to the reset course callbacks. First you want to add a checkbox that a user can check if they wish to delete the tags, then code that handles the case when the checkbox has been checked. Example -<br />
<br />
<code php><br />
/**<br />
* The elements to add the course reset form.<br />
*<br />
* @param moodleform $mform<br />
*/<br />
function book_reset_course_form_definition(&$mform) {<br />
$mform->addElement('header', 'bookheader', get_string('modulenameplural', 'book'));<br />
$mform->addElement('checkbox', 'reset_book_tags', get_string('removeallbooktags', 'book'));<br />
}<br />
<br />
/**<br />
* This function is used by the reset_course_userdata function in moodlelib.<br />
* @param $data the data submitted from the reset course.<br />
* @return array status array<br />
*/<br />
function book_reset_userdata($data) {<br />
global $DB;<br />
<br />
$status = [];<br />
<br />
if (!empty($data->reset_book_tags)) {<br />
// Loop through the books and remove the tags from the chapters.<br />
if ($books = $DB->get_records('book', array('course' => $data->courseid))) {<br />
foreach ($books as $book) {<br />
if (!$cm = get_coursemodule_from_instance('book', $book->id)) {<br />
continue;<br />
}<br />
<br />
$context = context_module::instance($cm->id);<br />
core_tag_tag::delete_instances('mod_book', null, $context->id);<br />
}<br />
}<br />
<br />
$status[] = [<br />
'component' => get_string('modulenameplural', 'book'),<br />
'item' => get_string('tagsdeleted', 'book'),<br />
'error' => false<br />
];<br />
}<br />
<br />
return $status;<br />
}<br />
</code><br />
<br />
The functions used to delete the tags are -<br />
<code php><br />
core_tag_tag::remove_all_item_tags($component, $itemtype, $itemid, $tiuserid = 0) // Removes all tag instances associated with an item.<br />
core_tag_tag::delete_instances($component, $itemtype = null, $contextid = null) // Removes tag instances in bulk. Here $component is mandatory in this method, either itemtype or contextid or neither or both can be specified.<br />
</code><br />
<br />
===Backup and restore===<br />
<br />
When you tag contents inside the course the plugin has to hook into backup and restore and process necessary tags. This is especially important for the contents inside activity modules, such as wiki pages or forum posts. Questions in the course question bank also backup and restore their tags.<br />
<br />
You can choose to backup and restore tags for each item individually (as it is done in mod_wiki) OR backup all tags in the context at once (as it is done in mod_glossary or mod_forum). Second option is preferable for performance reasons. Make sure to take into account $userinfo (whether user information is backed up / restored), for example wiki pages is not user information but glossary entries are, tags on them follow the same rule.<br />
<br />
This is an example from Glossary module that can be found in '''backup_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
$tags = new backup_nested_element('entriestags');<br />
$tag = new backup_nested_element('tag', array('id'), array('itemid', 'rawname'));<br />
// ...<br />
$glossary->add_child($tags); // Note that parent node is the glossary, not glossary entry, however the individual entries are tagged.<br />
$tags->add_child($tag);<br />
// ...<br />
if ($userinfo && core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) {<br />
$tag->set_source_sql('SELECT t.id, ti.itemid, t.rawname<br />
FROM {tag} t<br />
JOIN {tag_instance} ti ON ti.tagid = t.id<br />
WHERE ti.itemtype = ?<br />
AND ti.component = ?<br />
AND ti.contextid = ?', array(<br />
backup_helper::is_sqlparam('glossary_entries'),<br />
backup_helper::is_sqlparam('mod_glossary'),<br />
backup::VAR_CONTEXTID));<br />
}<br />
// ...<br />
}<br />
</code><br />
<br />
And this in the '''restore_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
if ($userinfo) {<br />
$paths[] = new restore_path_element('glossary_entry_tag', '/activity/glossary/entriestags/tag');<br />
}<br />
// ...<br />
}<br />
<br />
protected function process_glossary_entry_tag($data) {<br />
$data = (object)$data;<br />
<br />
if (!core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) { // Tags disabled on this site, nothing to process.<br />
return;<br />
}<br />
<br />
$tag = $data->rawname;<br />
if (!$itemid = $this->get_mappingid('glossary_entry', $data->itemid)) {<br />
// Orphaned tag, we could not find the glossary entry for it - ignore.<br />
return;<br />
}<br />
<br />
$context = context_module::instance($this->task->get_moduleid());<br />
core_tag_tag::add_item_tag('mod_glossary', 'glossary_entries', $itemid, $context, $tag);<br />
}<br />
</code><br />
<br />
===Search callback===<br />
<br />
This is the most difficult part of Tag API. When user searches for the items tagged with a specific tag only the items user has access to must be returned. Running access check on all items can be very costly. Class '''core_tag_index_builder''' can help with retrieving and caching records, especially inside the courses or activity modules.<br />
<br />
<code php><br />
function mod_wiki_get_tagged_pages($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {<br />
// Find items.<br />
// Please refer to existing callbacks in core for examples.<br />
<br />
// ...<br />
<br />
// Use core_tag_index_builder to build and filter the list of items. <br />
// Notice how we search for 6 items when we need to display 5 - this way we will know that we need to display a link to the next page.<br />
$builder = new core_tag_index_builder('mod_wiki', 'wiki_pages', $query, $params, $page * $perpage, $perpage + 1);<br />
<br />
// ...<br />
<br />
$items = $builder->get_items();<br />
if (count($items) > $perpage) {<br />
$totalpages = $page + 2; // We don't need exact page count, just indicate that the next page exists.<br />
array_pop($items);<br />
}<br />
<br />
// Build the display contents.<br />
if ($items) {<br />
$tagfeed = new core_tag\output\tagfeed();<br />
foreach ($items as $item) {<br />
$tagfeed->add(...);<br />
}<br />
<br />
$content = $OUTPUT->render_from_template('core_tag/tagfeed', $tagfeed->export_for_template($OUTPUT));<br />
<br />
return new core_tag\output\tagindex($tag, 'mod_wiki', 'wiki_pages', $content,<br />
$exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);<br />
}<br />
}<br />
</code><br />
<br />
===User-specific tags===<br />
<br />
It is possible that each tagged item can be tagged by each user independently. Before Moodle 3.0 this was how courses were tagged however from 3.0 tagging courses became more standard. The functionality remains in the API (argument $tiuser to the tagging functions). In this case both tag list and tag cloud will display all tag instances added by all users but each user will be able to edit only their own.<br />
<br />
If developer chooses to implement it in the plugin, they need to also implement the UI when admin or other privileged user can remove or edit the instances of another user. Otherwise if teacher has tagged the course and later resigned there will be no way to change their tags. Also such tag instances need special treatment during backup and restore - they are now considered "user data" and user id mapping should be performed.<br />
<br />
===Advanced usages===<br />
<br />
Custom plugins may go beyond the standard tags handling and use them without mixing with regular course/user/wiki/blogs tags, hide them from the "Tag search" page and "Tags" block but instead have their own interface to search/categorise using tags. This can be achieved by defining tag collection, make it not searchable and specify a custom URL to link to when the tag is actually displayed. This all can be defined in db/tag.php, see the comments in [https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]<br />
<br />
* '''tag_area::get_collection($component, $itemtype)''' - will return you the collection that your tag area is in<br />
* '''tag_collection::get_tag_cloud()''' - will return all tags in the collection. There are no API methods to get the tags used in the tag area - this is actually the purpose of tag collections.<br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[Tag API before 3.1]]<br />
* [https://docs.moodle.org/en/Managing_tags Managing tags]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Tag_API&diff=53005
Tag API
2017-10-12T11:13:24Z
<p>Markn: /* Deleting and clearing tags */</p>
<hr />
<div>{{Moodle 3.1}}<br />
<br />
==Tag API overview==<br />
<br />
The Tag API allows you to assign labels to information in Moodle. This makes finding this information easier and also facilitates the grouping of similar information. The Tag API allows you to create, modify, delete and search tags in the Moodle system. The main tag related functions can be found in the tag/classes/tag.php file. For a through overview of all of the functions available for working with Tags please see methods in core_tag_tag, core_tag_collection and core_tag_area classes, however the following examples should give you a general understanding of how to get started with tags.<br />
<br />
This page describes API in Moodle 3.1 and above, for earlier versions see [[Tag API before 3.1]]<br />
<br />
==Tag API usage==<br />
<br />
When user tags something a '''tag instance''' is created in the database linking the item to the actual '''tag'''. If tag did not exist before it is created automatically. Do not confuse these two entities - deleting the tag instance does not normally delete tag, however deleting tag deletes all tag instances associated with it. <br />
<br />
Developers define '''tag areas''' the areas that can be tagged, examples are:<br />
* blog posts<br />
* courses<br />
* users (tags represent user interests)<br />
* activity modules<br />
* questions<br />
* wiki pages<br />
<br />
Each tag area is identified by two attributes - component and itemtype. ''Itemtype must be a name of a table in the database.'' Component is the core component or plugin responsible for the tagging. This way the same DB table (for example 'user' or 'course') may be independently tagged by several components. Administrator or manager is able to manage the tag areas, collections and tags inside them on the [https://docs.moodle.org/en/Managing_tags Managing tags] page. Users are able to search tags and view all items tagged with them that they have access to.<br />
<br />
===Defining a tag area===<br />
<br />
First, developer must define the tag areas in the file '''db/tag.php'''. This will usually look like:<br />
<code php><br />
$tagareas = array(<br />
array(<br />
'itemtype' => 'wiki_pages', // This must be a name of the database table (without prefix).<br />
'component' => 'mod_wiki', // This can be omitted for plugins since it can only be full frankenstyle name of the plugin.<br />
'callback' => 'mod_wiki_get_tagged_pages',<br />
'callbackfile' => '/mod/wiki/locallib.php',<br />
),<br />
);<br />
</code><br />
You will also need to add language string, for the example above it will be '''$string['tagarea_wiki_pages'] = 'Wiki pages';'''<br />
<br />
There are more options such as specifying the default value for "Standard tags", having a fixed collection or excluding from search. They can be found in comments in [[https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]]<br />
<br />
After making changes to db/tag.php plugin developer must bump the plugin version in '''version.php''' and run upgrade script. This usually applies to any changes in the db/ folder.<br />
<br />
===Adding tags element to the editing form===<br />
<br />
After tag area is defined it should appear on "Manage tags" page. Now it is time to allow users to add/change tags when editing the item. Here is an example from Wiki module:<br />
<br />
1. Add a 'tags' form element to the editing form:<br />
<code php><br />
$mform->addElement('tags', 'tags', get_string('tags'), array('itemtype' => 'wiki_pages', 'component' => 'mod_wiki'));<br />
</code><br />
<br />
This element will automatically check if the tag area is disabled by the manager and will not display anything in this case. However if you want to add a header you need to check if tag area is enabled add this:<br />
<code php><br />
if (core_tag_tag::is_enabled('mod_wiki', 'wiki_pages')) {<br />
$mform->addElement('header', 'tagshdr', get_string('tags', 'tag'));<br />
}<br />
</code><br />
<br />
2. Save the form data<br />
<code php><br />
if ($data = $form->get_data()) {<br />
// Do some other processing here, if this is a new page (item) you need to insert it in the DB and obtain id.<br />
// $pageid = $data->id;<br />
core_tag_tag::set_item_tags('mod_wiki', 'wiki_pages', $pageid, $modulecontext, $data->tags);<br />
}<br />
</code><br />
It is important to specify the correct context in this function. Note that $data->tags will always be returned by the form, even if the area is disabled, however core_tag_tag::set_item_tags() will not change or reset tags if the tag area is disabled.<br />
<br />
3. Populate the form with existing tags before calling $form->set_data($data):<br />
<code php><br />
$data = $DB->get_record('wiki_pages', array('id' => $this->page->id)); // Well, it's more complicated than that of course....<br />
$data->tags = core_tag_tag::get_item_tags_array('mod_wiki', 'wiki_pages', $this->page->id);<br />
$form->set_data($data);<br />
</code><br />
<br />
Always test the code with tag area enabled and disabled.<br />
<br />
===Displaying tags next to the item===<br />
<br />
Example of displaying of the tags are user interests on the user profile page. User can see the list of interests, each of them is a link that leads to the page that shows all items tagged with this tag.<br />
<br />
Here is the code used by Wiki module to display tags the page is tagged with:<br />
<br />
<code php><br />
echo $OUTPUT->tag_list(core_tag_tag::get_item_tags('mod_wiki', 'wiki_pages', $page->id), null, 'wiki-tags');<br />
</code><br />
<br />
===Deleting and clearing tags===<br />
<br />
Cron will automatically remove tag instances that point to non existing items, however it is a good habit to delete tags when the record is deleted.<br />
<br />
'''Please note:''' If you have created a course activity that uses tags you should also remember to delete the tags during a course reset by adding code to the reset course callbacks. First you want to add a checkbox that a user can check if they wish to delete the tags, then code that handles the case when the checkbox has been checked. Example -<br />
<br />
<code php><br />
/**<br />
* The elements to add the course reset form.<br />
*<br />
* @param moodleform $mform<br />
*/<br />
function book_reset_course_form_definition(&$mform) {<br />
$mform->addElement('header', 'bookheader', get_string('modulenameplural', 'book'));<br />
$mform->addElement('checkbox', 'reset_book_tags', get_string('removeallbooktags', 'book'));<br />
}<br />
<br />
/**<br />
* This function is used by the reset_course_userdata function in moodlelib.<br />
* @param $data the data submitted from the reset course.<br />
* @return array status array<br />
*/<br />
function book_reset_userdata($data) {<br />
global $DB;<br />
<br />
$status = [];<br />
<br />
if (!empty($data->reset_book_tags)) {<br />
// Loop through the books and remove the tags from the chapters.<br />
if ($books = $DB->get_records('book', array('course' => $data->courseid))) {<br />
foreach ($books as $book) {<br />
if (!$cm = get_coursemodule_from_instance('book', $book->id)) {<br />
continue;<br />
}<br />
<br />
$context = context_module::instance($cm->id);<br />
core_tag_tag::delete_instances('mod_book', null, $context->id);<br />
}<br />
}<br />
<br />
$status[] = [<br />
'component' => get_string('modulenameplural', 'book'),<br />
'item' => get_string('tagsdeleted', 'book'),<br />
'error' => false<br />
];<br />
}<br />
<br />
return $status;<br />
}<br />
</code><br />
<br />
* '''core_tag_tag::remove_all_item_tags($component, $itemtype, $itemid, $tiuserid = 0)''' - removes all tag instances associated with an item.<br />
* '''core_tag_tag::delete_instances($component, $itemtype = null, $contextid = null)''' - deletes tag instances in bulk. Here $component is mandatory in this method, either itemtype or contextid or neither or both can be specified.<br />
<br />
===Backup and restore===<br />
<br />
When you tag contents inside the course the plugin has to hook into backup and restore and process necessary tags. This is especially important for the contents inside activity modules, such as wiki pages or forum posts. Questions in the course question bank also backup and restore their tags.<br />
<br />
You can choose to backup and restore tags for each item individually (as it is done in mod_wiki) OR backup all tags in the context at once (as it is done in mod_glossary or mod_forum). Second option is preferable for performance reasons. Make sure to take into account $userinfo (whether user information is backed up / restored), for example wiki pages is not user information but glossary entries are, tags on them follow the same rule.<br />
<br />
This is an example from Glossary module that can be found in '''backup_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
$tags = new backup_nested_element('entriestags');<br />
$tag = new backup_nested_element('tag', array('id'), array('itemid', 'rawname'));<br />
// ...<br />
$glossary->add_child($tags); // Note that parent node is the glossary, not glossary entry, however the individual entries are tagged.<br />
$tags->add_child($tag);<br />
// ...<br />
if ($userinfo && core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) {<br />
$tag->set_source_sql('SELECT t.id, ti.itemid, t.rawname<br />
FROM {tag} t<br />
JOIN {tag_instance} ti ON ti.tagid = t.id<br />
WHERE ti.itemtype = ?<br />
AND ti.component = ?<br />
AND ti.contextid = ?', array(<br />
backup_helper::is_sqlparam('glossary_entries'),<br />
backup_helper::is_sqlparam('mod_glossary'),<br />
backup::VAR_CONTEXTID));<br />
}<br />
// ...<br />
}<br />
</code><br />
<br />
And this in the '''restore_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
if ($userinfo) {<br />
$paths[] = new restore_path_element('glossary_entry_tag', '/activity/glossary/entriestags/tag');<br />
}<br />
// ...<br />
}<br />
<br />
protected function process_glossary_entry_tag($data) {<br />
$data = (object)$data;<br />
<br />
if (!core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) { // Tags disabled on this site, nothing to process.<br />
return;<br />
}<br />
<br />
$tag = $data->rawname;<br />
if (!$itemid = $this->get_mappingid('glossary_entry', $data->itemid)) {<br />
// Orphaned tag, we could not find the glossary entry for it - ignore.<br />
return;<br />
}<br />
<br />
$context = context_module::instance($this->task->get_moduleid());<br />
core_tag_tag::add_item_tag('mod_glossary', 'glossary_entries', $itemid, $context, $tag);<br />
}<br />
</code><br />
<br />
===Search callback===<br />
<br />
This is the most difficult part of Tag API. When user searches for the items tagged with a specific tag only the items user has access to must be returned. Running access check on all items can be very costly. Class '''core_tag_index_builder''' can help with retrieving and caching records, especially inside the courses or activity modules.<br />
<br />
<code php><br />
function mod_wiki_get_tagged_pages($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {<br />
// Find items.<br />
// Please refer to existing callbacks in core for examples.<br />
<br />
// ...<br />
<br />
// Use core_tag_index_builder to build and filter the list of items. <br />
// Notice how we search for 6 items when we need to display 5 - this way we will know that we need to display a link to the next page.<br />
$builder = new core_tag_index_builder('mod_wiki', 'wiki_pages', $query, $params, $page * $perpage, $perpage + 1);<br />
<br />
// ...<br />
<br />
$items = $builder->get_items();<br />
if (count($items) > $perpage) {<br />
$totalpages = $page + 2; // We don't need exact page count, just indicate that the next page exists.<br />
array_pop($items);<br />
}<br />
<br />
// Build the display contents.<br />
if ($items) {<br />
$tagfeed = new core_tag\output\tagfeed();<br />
foreach ($items as $item) {<br />
$tagfeed->add(...);<br />
}<br />
<br />
$content = $OUTPUT->render_from_template('core_tag/tagfeed', $tagfeed->export_for_template($OUTPUT));<br />
<br />
return new core_tag\output\tagindex($tag, 'mod_wiki', 'wiki_pages', $content,<br />
$exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);<br />
}<br />
}<br />
</code><br />
<br />
===User-specific tags===<br />
<br />
It is possible that each tagged item can be tagged by each user independently. Before Moodle 3.0 this was how courses were tagged however from 3.0 tagging courses became more standard. The functionality remains in the API (argument $tiuser to the tagging functions). In this case both tag list and tag cloud will display all tag instances added by all users but each user will be able to edit only their own.<br />
<br />
If developer chooses to implement it in the plugin, they need to also implement the UI when admin or other privileged user can remove or edit the instances of another user. Otherwise if teacher has tagged the course and later resigned there will be no way to change their tags. Also such tag instances need special treatment during backup and restore - they are now considered "user data" and user id mapping should be performed.<br />
<br />
===Advanced usages===<br />
<br />
Custom plugins may go beyond the standard tags handling and use them without mixing with regular course/user/wiki/blogs tags, hide them from the "Tag search" page and "Tags" block but instead have their own interface to search/categorise using tags. This can be achieved by defining tag collection, make it not searchable and specify a custom URL to link to when the tag is actually displayed. This all can be defined in db/tag.php, see the comments in [https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]<br />
<br />
* '''tag_area::get_collection($component, $itemtype)''' - will return you the collection that your tag area is in<br />
* '''tag_collection::get_tag_cloud()''' - will return all tags in the collection. There are no API methods to get the tags used in the tag area - this is actually the purpose of tag collections.<br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[Tag API before 3.1]]<br />
* [https://docs.moodle.org/en/Managing_tags Managing tags]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Tag_API&diff=53004
Tag API
2017-10-12T10:39:06Z
<p>Markn: /* Deleting and clearing tags */</p>
<hr />
<div>{{Moodle 3.1}}<br />
<br />
==Tag API overview==<br />
<br />
The Tag API allows you to assign labels to information in Moodle. This makes finding this information easier and also facilitates the grouping of similar information. The Tag API allows you to create, modify, delete and search tags in the Moodle system. The main tag related functions can be found in the tag/classes/tag.php file. For a through overview of all of the functions available for working with Tags please see methods in core_tag_tag, core_tag_collection and core_tag_area classes, however the following examples should give you a general understanding of how to get started with tags.<br />
<br />
This page describes API in Moodle 3.1 and above, for earlier versions see [[Tag API before 3.1]]<br />
<br />
==Tag API usage==<br />
<br />
When user tags something a '''tag instance''' is created in the database linking the item to the actual '''tag'''. If tag did not exist before it is created automatically. Do not confuse these two entities - deleting the tag instance does not normally delete tag, however deleting tag deletes all tag instances associated with it. <br />
<br />
Developers define '''tag areas''' the areas that can be tagged, examples are:<br />
* blog posts<br />
* courses<br />
* users (tags represent user interests)<br />
* activity modules<br />
* questions<br />
* wiki pages<br />
<br />
Each tag area is identified by two attributes - component and itemtype. ''Itemtype must be a name of a table in the database.'' Component is the core component or plugin responsible for the tagging. This way the same DB table (for example 'user' or 'course') may be independently tagged by several components. Administrator or manager is able to manage the tag areas, collections and tags inside them on the [https://docs.moodle.org/en/Managing_tags Managing tags] page. Users are able to search tags and view all items tagged with them that they have access to.<br />
<br />
===Defining a tag area===<br />
<br />
First, developer must define the tag areas in the file '''db/tag.php'''. This will usually look like:<br />
<code php><br />
$tagareas = array(<br />
array(<br />
'itemtype' => 'wiki_pages', // This must be a name of the database table (without prefix).<br />
'component' => 'mod_wiki', // This can be omitted for plugins since it can only be full frankenstyle name of the plugin.<br />
'callback' => 'mod_wiki_get_tagged_pages',<br />
'callbackfile' => '/mod/wiki/locallib.php',<br />
),<br />
);<br />
</code><br />
You will also need to add language string, for the example above it will be '''$string['tagarea_wiki_pages'] = 'Wiki pages';'''<br />
<br />
There are more options such as specifying the default value for "Standard tags", having a fixed collection or excluding from search. They can be found in comments in [[https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]]<br />
<br />
After making changes to db/tag.php plugin developer must bump the plugin version in '''version.php''' and run upgrade script. This usually applies to any changes in the db/ folder.<br />
<br />
===Adding tags element to the editing form===<br />
<br />
After tag area is defined it should appear on "Manage tags" page. Now it is time to allow users to add/change tags when editing the item. Here is an example from Wiki module:<br />
<br />
1. Add a 'tags' form element to the editing form:<br />
<code php><br />
$mform->addElement('tags', 'tags', get_string('tags'), array('itemtype' => 'wiki_pages', 'component' => 'mod_wiki'));<br />
</code><br />
<br />
This element will automatically check if the tag area is disabled by the manager and will not display anything in this case. However if you want to add a header you need to check if tag area is enabled add this:<br />
<code php><br />
if (core_tag_tag::is_enabled('mod_wiki', 'wiki_pages')) {<br />
$mform->addElement('header', 'tagshdr', get_string('tags', 'tag'));<br />
}<br />
</code><br />
<br />
2. Save the form data<br />
<code php><br />
if ($data = $form->get_data()) {<br />
// Do some other processing here, if this is a new page (item) you need to insert it in the DB and obtain id.<br />
// $pageid = $data->id;<br />
core_tag_tag::set_item_tags('mod_wiki', 'wiki_pages', $pageid, $modulecontext, $data->tags);<br />
}<br />
</code><br />
It is important to specify the correct context in this function. Note that $data->tags will always be returned by the form, even if the area is disabled, however core_tag_tag::set_item_tags() will not change or reset tags if the tag area is disabled.<br />
<br />
3. Populate the form with existing tags before calling $form->set_data($data):<br />
<code php><br />
$data = $DB->get_record('wiki_pages', array('id' => $this->page->id)); // Well, it's more complicated than that of course....<br />
$data->tags = core_tag_tag::get_item_tags_array('mod_wiki', 'wiki_pages', $this->page->id);<br />
$form->set_data($data);<br />
</code><br />
<br />
Always test the code with tag area enabled and disabled.<br />
<br />
===Displaying tags next to the item===<br />
<br />
Example of displaying of the tags are user interests on the user profile page. User can see the list of interests, each of them is a link that leads to the page that shows all items tagged with this tag.<br />
<br />
Here is the code used by Wiki module to display tags the page is tagged with:<br />
<br />
<code php><br />
echo $OUTPUT->tag_list(core_tag_tag::get_item_tags('mod_wiki', 'wiki_pages', $page->id), null, 'wiki-tags');<br />
</code><br />
<br />
===Deleting and clearing tags===<br />
<br />
Cron will automatically remove tag instances that point to non existing items, however it is a good habit to delete tags when the record is deleted. '''Please note:''' You should clear tags when a course has been reset in the reset course callback:<br />
* '''core_tag_tag::remove_all_item_tags($component, $itemtype, $itemid, $tiuserid = 0)''' - removes all tag instances associated with an item<br />
* '''core_tag_tag::delete_instances($component, $itemtype = null, $contextid = null)''' - deletes tag instances in bulk. Here $component is mandatory in this method, either itemtype or contextid or neither or both can be specified.<br />
<br />
===Backup and restore===<br />
<br />
When you tag contents inside the course the plugin has to hook into backup and restore and process necessary tags. This is especially important for the contents inside activity modules, such as wiki pages or forum posts. Questions in the course question bank also backup and restore their tags.<br />
<br />
You can choose to backup and restore tags for each item individually (as it is done in mod_wiki) OR backup all tags in the context at once (as it is done in mod_glossary or mod_forum). Second option is preferable for performance reasons. Make sure to take into account $userinfo (whether user information is backed up / restored), for example wiki pages is not user information but glossary entries are, tags on them follow the same rule.<br />
<br />
This is an example from Glossary module that can be found in '''backup_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
$tags = new backup_nested_element('entriestags');<br />
$tag = new backup_nested_element('tag', array('id'), array('itemid', 'rawname'));<br />
// ...<br />
$glossary->add_child($tags); // Note that parent node is the glossary, not glossary entry, however the individual entries are tagged.<br />
$tags->add_child($tag);<br />
// ...<br />
if ($userinfo && core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) {<br />
$tag->set_source_sql('SELECT t.id, ti.itemid, t.rawname<br />
FROM {tag} t<br />
JOIN {tag_instance} ti ON ti.tagid = t.id<br />
WHERE ti.itemtype = ?<br />
AND ti.component = ?<br />
AND ti.contextid = ?', array(<br />
backup_helper::is_sqlparam('glossary_entries'),<br />
backup_helper::is_sqlparam('mod_glossary'),<br />
backup::VAR_CONTEXTID));<br />
}<br />
// ...<br />
}<br />
</code><br />
<br />
And this in the '''restore_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
if ($userinfo) {<br />
$paths[] = new restore_path_element('glossary_entry_tag', '/activity/glossary/entriestags/tag');<br />
}<br />
// ...<br />
}<br />
<br />
protected function process_glossary_entry_tag($data) {<br />
$data = (object)$data;<br />
<br />
if (!core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) { // Tags disabled on this site, nothing to process.<br />
return;<br />
}<br />
<br />
$tag = $data->rawname;<br />
if (!$itemid = $this->get_mappingid('glossary_entry', $data->itemid)) {<br />
// Orphaned tag, we could not find the glossary entry for it - ignore.<br />
return;<br />
}<br />
<br />
$context = context_module::instance($this->task->get_moduleid());<br />
core_tag_tag::add_item_tag('mod_glossary', 'glossary_entries', $itemid, $context, $tag);<br />
}<br />
</code><br />
<br />
===Search callback===<br />
<br />
This is the most difficult part of Tag API. When user searches for the items tagged with a specific tag only the items user has access to must be returned. Running access check on all items can be very costly. Class '''core_tag_index_builder''' can help with retrieving and caching records, especially inside the courses or activity modules.<br />
<br />
<code php><br />
function mod_wiki_get_tagged_pages($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {<br />
// Find items.<br />
// Please refer to existing callbacks in core for examples.<br />
<br />
// ...<br />
<br />
// Use core_tag_index_builder to build and filter the list of items. <br />
// Notice how we search for 6 items when we need to display 5 - this way we will know that we need to display a link to the next page.<br />
$builder = new core_tag_index_builder('mod_wiki', 'wiki_pages', $query, $params, $page * $perpage, $perpage + 1);<br />
<br />
// ...<br />
<br />
$items = $builder->get_items();<br />
if (count($items) > $perpage) {<br />
$totalpages = $page + 2; // We don't need exact page count, just indicate that the next page exists.<br />
array_pop($items);<br />
}<br />
<br />
// Build the display contents.<br />
if ($items) {<br />
$tagfeed = new core_tag\output\tagfeed();<br />
foreach ($items as $item) {<br />
$tagfeed->add(...);<br />
}<br />
<br />
$content = $OUTPUT->render_from_template('core_tag/tagfeed', $tagfeed->export_for_template($OUTPUT));<br />
<br />
return new core_tag\output\tagindex($tag, 'mod_wiki', 'wiki_pages', $content,<br />
$exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);<br />
}<br />
}<br />
</code><br />
<br />
===User-specific tags===<br />
<br />
It is possible that each tagged item can be tagged by each user independently. Before Moodle 3.0 this was how courses were tagged however from 3.0 tagging courses became more standard. The functionality remains in the API (argument $tiuser to the tagging functions). In this case both tag list and tag cloud will display all tag instances added by all users but each user will be able to edit only their own.<br />
<br />
If developer chooses to implement it in the plugin, they need to also implement the UI when admin or other privileged user can remove or edit the instances of another user. Otherwise if teacher has tagged the course and later resigned there will be no way to change their tags. Also such tag instances need special treatment during backup and restore - they are now considered "user data" and user id mapping should be performed.<br />
<br />
===Advanced usages===<br />
<br />
Custom plugins may go beyond the standard tags handling and use them without mixing with regular course/user/wiki/blogs tags, hide them from the "Tag search" page and "Tags" block but instead have their own interface to search/categorise using tags. This can be achieved by defining tag collection, make it not searchable and specify a custom URL to link to when the tag is actually displayed. This all can be defined in db/tag.php, see the comments in [https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]<br />
<br />
* '''tag_area::get_collection($component, $itemtype)''' - will return you the collection that your tag area is in<br />
* '''tag_collection::get_tag_cloud()''' - will return all tags in the collection. There are no API methods to get the tags used in the tag area - this is actually the purpose of tag collections.<br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[Tag API before 3.1]]<br />
* [https://docs.moodle.org/en/Managing_tags Managing tags]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Tag_API&diff=53003
Tag API
2017-10-12T10:37:52Z
<p>Markn: </p>
<hr />
<div>{{Moodle 3.1}}<br />
<br />
==Tag API overview==<br />
<br />
The Tag API allows you to assign labels to information in Moodle. This makes finding this information easier and also facilitates the grouping of similar information. The Tag API allows you to create, modify, delete and search tags in the Moodle system. The main tag related functions can be found in the tag/classes/tag.php file. For a through overview of all of the functions available for working with Tags please see methods in core_tag_tag, core_tag_collection and core_tag_area classes, however the following examples should give you a general understanding of how to get started with tags.<br />
<br />
This page describes API in Moodle 3.1 and above, for earlier versions see [[Tag API before 3.1]]<br />
<br />
==Tag API usage==<br />
<br />
When user tags something a '''tag instance''' is created in the database linking the item to the actual '''tag'''. If tag did not exist before it is created automatically. Do not confuse these two entities - deleting the tag instance does not normally delete tag, however deleting tag deletes all tag instances associated with it. <br />
<br />
Developers define '''tag areas''' the areas that can be tagged, examples are:<br />
* blog posts<br />
* courses<br />
* users (tags represent user interests)<br />
* activity modules<br />
* questions<br />
* wiki pages<br />
<br />
Each tag area is identified by two attributes - component and itemtype. ''Itemtype must be a name of a table in the database.'' Component is the core component or plugin responsible for the tagging. This way the same DB table (for example 'user' or 'course') may be independently tagged by several components. Administrator or manager is able to manage the tag areas, collections and tags inside them on the [https://docs.moodle.org/en/Managing_tags Managing tags] page. Users are able to search tags and view all items tagged with them that they have access to.<br />
<br />
===Defining a tag area===<br />
<br />
First, developer must define the tag areas in the file '''db/tag.php'''. This will usually look like:<br />
<code php><br />
$tagareas = array(<br />
array(<br />
'itemtype' => 'wiki_pages', // This must be a name of the database table (without prefix).<br />
'component' => 'mod_wiki', // This can be omitted for plugins since it can only be full frankenstyle name of the plugin.<br />
'callback' => 'mod_wiki_get_tagged_pages',<br />
'callbackfile' => '/mod/wiki/locallib.php',<br />
),<br />
);<br />
</code><br />
You will also need to add language string, for the example above it will be '''$string['tagarea_wiki_pages'] = 'Wiki pages';'''<br />
<br />
There are more options such as specifying the default value for "Standard tags", having a fixed collection or excluding from search. They can be found in comments in [[https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]]<br />
<br />
After making changes to db/tag.php plugin developer must bump the plugin version in '''version.php''' and run upgrade script. This usually applies to any changes in the db/ folder.<br />
<br />
===Adding tags element to the editing form===<br />
<br />
After tag area is defined it should appear on "Manage tags" page. Now it is time to allow users to add/change tags when editing the item. Here is an example from Wiki module:<br />
<br />
1. Add a 'tags' form element to the editing form:<br />
<code php><br />
$mform->addElement('tags', 'tags', get_string('tags'), array('itemtype' => 'wiki_pages', 'component' => 'mod_wiki'));<br />
</code><br />
<br />
This element will automatically check if the tag area is disabled by the manager and will not display anything in this case. However if you want to add a header you need to check if tag area is enabled add this:<br />
<code php><br />
if (core_tag_tag::is_enabled('mod_wiki', 'wiki_pages')) {<br />
$mform->addElement('header', 'tagshdr', get_string('tags', 'tag'));<br />
}<br />
</code><br />
<br />
2. Save the form data<br />
<code php><br />
if ($data = $form->get_data()) {<br />
// Do some other processing here, if this is a new page (item) you need to insert it in the DB and obtain id.<br />
// $pageid = $data->id;<br />
core_tag_tag::set_item_tags('mod_wiki', 'wiki_pages', $pageid, $modulecontext, $data->tags);<br />
}<br />
</code><br />
It is important to specify the correct context in this function. Note that $data->tags will always be returned by the form, even if the area is disabled, however core_tag_tag::set_item_tags() will not change or reset tags if the tag area is disabled.<br />
<br />
3. Populate the form with existing tags before calling $form->set_data($data):<br />
<code php><br />
$data = $DB->get_record('wiki_pages', array('id' => $this->page->id)); // Well, it's more complicated than that of course....<br />
$data->tags = core_tag_tag::get_item_tags_array('mod_wiki', 'wiki_pages', $this->page->id);<br />
$form->set_data($data);<br />
</code><br />
<br />
Always test the code with tag area enabled and disabled.<br />
<br />
===Displaying tags next to the item===<br />
<br />
Example of displaying of the tags are user interests on the user profile page. User can see the list of interests, each of them is a link that leads to the page that shows all items tagged with this tag.<br />
<br />
Here is the code used by Wiki module to display tags the page is tagged with:<br />
<br />
<code php><br />
echo $OUTPUT->tag_list(core_tag_tag::get_item_tags('mod_wiki', 'wiki_pages', $page->id), null, 'wiki-tags');<br />
</code><br />
<br />
===Deleting and clearing tags===<br />
<br />
Cron will automatically remove tag instances that point to non existing items, however it is a good habit to delete tags when the record is deleted. *Please note:* You should clear tags when a course has been reset in the reset course callback:<br />
* '''core_tag_tag::remove_all_item_tags($component, $itemtype, $itemid, $tiuserid = 0)''' - removes all tag instances associated with an item<br />
* '''core_tag_tag::delete_instances($component, $itemtype = null, $contextid = null)''' - deletes tag instances in bulk. Here $component is mandatory in this method, either itemtype or contextid or neither or both can be specified.<br />
<br />
===Backup and restore===<br />
<br />
When you tag contents inside the course the plugin has to hook into backup and restore and process necessary tags. This is especially important for the contents inside activity modules, such as wiki pages or forum posts. Questions in the course question bank also backup and restore their tags.<br />
<br />
You can choose to backup and restore tags for each item individually (as it is done in mod_wiki) OR backup all tags in the context at once (as it is done in mod_glossary or mod_forum). Second option is preferable for performance reasons. Make sure to take into account $userinfo (whether user information is backed up / restored), for example wiki pages is not user information but glossary entries are, tags on them follow the same rule.<br />
<br />
This is an example from Glossary module that can be found in '''backup_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
$tags = new backup_nested_element('entriestags');<br />
$tag = new backup_nested_element('tag', array('id'), array('itemid', 'rawname'));<br />
// ...<br />
$glossary->add_child($tags); // Note that parent node is the glossary, not glossary entry, however the individual entries are tagged.<br />
$tags->add_child($tag);<br />
// ...<br />
if ($userinfo && core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) {<br />
$tag->set_source_sql('SELECT t.id, ti.itemid, t.rawname<br />
FROM {tag} t<br />
JOIN {tag_instance} ti ON ti.tagid = t.id<br />
WHERE ti.itemtype = ?<br />
AND ti.component = ?<br />
AND ti.contextid = ?', array(<br />
backup_helper::is_sqlparam('glossary_entries'),<br />
backup_helper::is_sqlparam('mod_glossary'),<br />
backup::VAR_CONTEXTID));<br />
}<br />
// ...<br />
}<br />
</code><br />
<br />
And this in the '''restore_glossary_stepslib.php''':<br />
<br />
<code php><br />
protected function define_structure() {<br />
// ...<br />
if ($userinfo) {<br />
$paths[] = new restore_path_element('glossary_entry_tag', '/activity/glossary/entriestags/tag');<br />
}<br />
// ...<br />
}<br />
<br />
protected function process_glossary_entry_tag($data) {<br />
$data = (object)$data;<br />
<br />
if (!core_tag_tag::is_enabled('mod_glossary', 'glossary_entries')) { // Tags disabled on this site, nothing to process.<br />
return;<br />
}<br />
<br />
$tag = $data->rawname;<br />
if (!$itemid = $this->get_mappingid('glossary_entry', $data->itemid)) {<br />
// Orphaned tag, we could not find the glossary entry for it - ignore.<br />
return;<br />
}<br />
<br />
$context = context_module::instance($this->task->get_moduleid());<br />
core_tag_tag::add_item_tag('mod_glossary', 'glossary_entries', $itemid, $context, $tag);<br />
}<br />
</code><br />
<br />
===Search callback===<br />
<br />
This is the most difficult part of Tag API. When user searches for the items tagged with a specific tag only the items user has access to must be returned. Running access check on all items can be very costly. Class '''core_tag_index_builder''' can help with retrieving and caching records, especially inside the courses or activity modules.<br />
<br />
<code php><br />
function mod_wiki_get_tagged_pages($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {<br />
// Find items.<br />
// Please refer to existing callbacks in core for examples.<br />
<br />
// ...<br />
<br />
// Use core_tag_index_builder to build and filter the list of items. <br />
// Notice how we search for 6 items when we need to display 5 - this way we will know that we need to display a link to the next page.<br />
$builder = new core_tag_index_builder('mod_wiki', 'wiki_pages', $query, $params, $page * $perpage, $perpage + 1);<br />
<br />
// ...<br />
<br />
$items = $builder->get_items();<br />
if (count($items) > $perpage) {<br />
$totalpages = $page + 2; // We don't need exact page count, just indicate that the next page exists.<br />
array_pop($items);<br />
}<br />
<br />
// Build the display contents.<br />
if ($items) {<br />
$tagfeed = new core_tag\output\tagfeed();<br />
foreach ($items as $item) {<br />
$tagfeed->add(...);<br />
}<br />
<br />
$content = $OUTPUT->render_from_template('core_tag/tagfeed', $tagfeed->export_for_template($OUTPUT));<br />
<br />
return new core_tag\output\tagindex($tag, 'mod_wiki', 'wiki_pages', $content,<br />
$exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);<br />
}<br />
}<br />
</code><br />
<br />
===User-specific tags===<br />
<br />
It is possible that each tagged item can be tagged by each user independently. Before Moodle 3.0 this was how courses were tagged however from 3.0 tagging courses became more standard. The functionality remains in the API (argument $tiuser to the tagging functions). In this case both tag list and tag cloud will display all tag instances added by all users but each user will be able to edit only their own.<br />
<br />
If developer chooses to implement it in the plugin, they need to also implement the UI when admin or other privileged user can remove or edit the instances of another user. Otherwise if teacher has tagged the course and later resigned there will be no way to change their tags. Also such tag instances need special treatment during backup and restore - they are now considered "user data" and user id mapping should be performed.<br />
<br />
===Advanced usages===<br />
<br />
Custom plugins may go beyond the standard tags handling and use them without mixing with regular course/user/wiki/blogs tags, hide them from the "Tag search" page and "Tags" block but instead have their own interface to search/categorise using tags. This can be achieved by defining tag collection, make it not searchable and specify a custom URL to link to when the tag is actually displayed. This all can be defined in db/tag.php, see the comments in [https://github.com/moodle/moodle/blob/master/lib/db/tag.php lib/db/tag.php]<br />
<br />
* '''tag_area::get_collection($component, $itemtype)''' - will return you the collection that your tag area is in<br />
* '''tag_collection::get_tag_cloud()''' - will return all tags in the collection. There are no API methods to get the tags used in the tag area - this is actually the purpose of tag collections.<br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[Tag API before 3.1]]<br />
* [https://docs.moodle.org/en/Managing_tags Managing tags]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52555
Calendar API
2017-06-07T11:36:55Z
<p>Markn: /* calendar_get_legacy_events() */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Event priority==<br />
There might be cases that an activity event will have user and/or group overrides. Therefore we need a way to show only the relevant event on the user's calendar. This is where the 'priority' field comes in. <br />
<br />
The event priority is set to the following:<br />
* NULL for non-override events.<br />
<code php><br />
$event->priority = null;<br />
</code><br />
* 0 for user override events.<br />
<code php><br />
$event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;<br />
</code><br />
* A positive integer for group events.<br />
<br />
For integer and non-null event priorities, the lower the value, the higher the priority is. Meaning, user overrides always have a higher priority than group overrides. Group override priorities are currently being determined in two ways in core activities:<br />
# In the assignment module, the event priorities for group overrides are being determined from the 'sortorder' column in the 'assign_overrides' table.<br />
# In the lesson and quiz modules, the event priorities for group overrides are being calculated using the functions lesson_get_group_override_priorities($lessonid) and quiz_get_group_override_priorities($quizid).<br />
<br />
Should you ever decide to sort out group override priorities by implementing *_get_group_override_priorities(), the recommended return structure would be something like<br />
<code php><br />
[<br />
'youreventtype1' => $prioritiesforeventtype1, <br />
...<br />
]<br />
</code><br />
where '$prioritiesforeventtype1' is an associative array that has the timestamp of the group override event as key and the calculated priority as value. For more details, please see the implementation for the lesson module below:<br />
<code php><br />
/**<br />
* Calculates the priorities of timeopen and timeclose values for group overrides for a lesson.<br />
*<br />
* @param int $lessonid The lesson ID.<br />
* @return array|null Array of group override priorities for open and close times. Null if there are no group overrides.<br />
*/<br />
function lesson_get_group_override_priorities($lessonid) {<br />
global $DB;<br />
<br />
// Fetch group overrides.<br />
$where = 'lessonid = :lessonid AND groupid IS NOT NULL';<br />
$params = ['lessonid' => $lessonid];<br />
$overrides = $DB->get_records_select('lesson_overrides', $where, $params, '', 'id, groupid, available, deadline');<br />
if (!$overrides) {<br />
return null;<br />
}<br />
<br />
$grouptimeopen = [];<br />
$grouptimeclose = [];<br />
foreach ($overrides as $override) {<br />
if ($override->available !== null && !in_array($override->available, $grouptimeopen)) {<br />
$grouptimeopen[] = $override->available;<br />
}<br />
if ($override->deadline !== null && !in_array($override->deadline, $grouptimeclose)) {<br />
$grouptimeclose[] = $override->deadline;<br />
}<br />
}<br />
<br />
// Sort open times in ascending manner. The earlier open time gets higher priority.<br />
sort($grouptimeopen);<br />
// Set priorities.<br />
$opengrouppriorities = [];<br />
$openpriority = 1;<br />
foreach ($grouptimeopen as $timeopen) {<br />
$opengrouppriorities[$timeopen] = $openpriority++;<br />
}<br />
<br />
// Sort close times in descending manner. The later close time gets higher priority.<br />
rsort($grouptimeclose);<br />
// Set priorities.<br />
$closegrouppriorities = [];<br />
$closepriority = 1;<br />
foreach ($grouptimeclose as $timeclose) {<br />
$closegrouppriorities[$timeclose] = $closepriority++;<br />
}<br />
<br />
return [<br />
'open' => $opengrouppriorities,<br />
'close' => $closegrouppriorities<br />
];<br />
}<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br /><br />
The variables to pass to <code>create_instance()</code> are -<br />
<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code><br />
<br />
==Refreshing calendar events of activity modules==<br />
A new ad-hoc task 'refresh_mod_calendar_events_task' has been created. This task basically loops through all of the activity modules that implement the '*_refresh_events()' hook.<br />
<br />
Sample usage:<br />
<code php><br />
// Create the instance.<br />
$refreshtask = new refresh_mod_calendar_events_task();<br />
<br />
// Add custom data.<br />
$customdata = [<br />
'plugins' => ['assign', 'lesson', 'quiz'] // Optional. If not specified, it will refresh the events of all of the activity modules.<br />
];<br />
$refreshtask->set_custom_data($customdata);<br />
<br />
// Queue it.<br />
\core\task\manager::queue_adhoc_task($refreshtask);<br />
</code><br />
<br />
==calendar_get_legacy_events()==<br />
This functions accepts the same inputs as 'calendar_get_events()' but is now utilising the new Moodle Calendar API system. It respects overrides and will also add the action properties, whenever appropriate.<br />
<br />
==Changes to Behat==<br />
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage" where 'Course 1' is the fullname of the course.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52336
Calendar API
2017-05-10T05:04:24Z
<p>Markn: /* Changes to Behat */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br /><br />
The variables to pass to <code>create_instance()</code> are -<br />
<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code><br />
<br />
==Changes to Behat==<br />
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage" where 'Course 1' is the fullname of the course.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52335
Calendar API
2017-05-10T05:01:54Z
<p>Markn: /* Changes to Behat */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br /><br />
The variables to pass to <code>create_instance()</code> are -<br />
<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code><br />
<br />
==Changes to Behat==<br />
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage" where 'Course 1' is the name of the course.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Block_myoverview&diff=52334
Block myoverview
2017-05-10T04:58:14Z
<p>Markn: Redirected page to Calendar API#Action events</p>
<hr />
<div>#REDIRECT [[Calendar_API#Action_events]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52333
Calendar API
2017-05-10T04:54:57Z
<p>Markn: /* mod_xyz_core_calendar_provide_event_action() */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br /><br />
The variables to pass to <code>create_instance()</code> are -<br />
<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code><br />
<br />
==Changes to Behat==<br />
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage". ('Course 1' being the name of the course).</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52332
Calendar API
2017-05-10T04:53:58Z
<p>Markn: /* mod_xyz_core_calendar_provide_event_action() */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br /><br />
The variables to pass to <code php>create_instance()</code> are -<br />
<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code><br />
<br />
==Changes to Behat==<br />
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage". ('Course 1' being the name of the course).</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52331
Calendar API
2017-05-10T04:52:42Z
<p>Markn: </p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code><br />
<br />
==Changes to Behat==<br />
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage". ('Course 1' being the name of the course).</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52330
Calendar API
2017-05-10T04:08:46Z
<p>Markn: /* mod_xyz_core_calendar_provide_event_action() */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52329
Calendar API
2017-05-10T03:57:17Z
<p>Markn: /* mod_xyz_core_calendar_is_event_visible(calendar_event $event) */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible()====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Block_myoverview&diff=52328
Block myoverview
2017-05-10T03:47:53Z
<p>Markn: Created page with "Please see https://docs.moodle.org/dev/Calendar_API#Action_events."</p>
<hr />
<div>Please see https://docs.moodle.org/dev/Calendar_API#Action_events.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52317
Calendar API
2017-05-09T09:04:45Z
<p>Markn: /* Action events */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.<br />
<br />
Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.<br />
<br />
<code php><br />
$event->type = CALENDAR_EVENT_TYPE_ACTION;<br />
$event->timesort = $scorm->timeclose;<br />
</code><br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52316
Calendar API
2017-05-09T09:01:39Z
<p>Markn: /* Creating an event */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52315
Calendar API
2017-05-09T09:00:46Z
<p>Markn: /* Action events */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52314
Calendar API
2017-05-09T08:55:07Z
<p>Markn: /* mod_xyz_core_calendar_is_event_visible(calendar_event $event) */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
<code php><br />
/**<br />
* Is the event visible?<br />
*<br />
* This is used to determine global visibility of an event in all places throughout Moodle. For example,<br />
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and<br />
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.<br />
*<br />
* @param calendar_event $event<br />
* @return bool Returns true if the event is visible to the current user, false otherwise.<br />
*/<br />
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {<br />
global $CFG, $USER;<br />
<br />
require_once($CFG->dirroot . '/mod/assign/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];<br />
$context = context_module::instance($cm->id);<br />
<br />
$assign = new assign($context, $cm, null);<br />
<br />
if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {<br />
return $assign->can_grade();<br />
} else {<br />
return !$assign->can_grade() && $assign->can_view_submission($USER->id);<br />
}<br />
}<br />
</code><br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52313
Calendar API
2017-05-09T08:53:52Z
<p>Markn: /* mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count()====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.<br />
<br />
Eg.<br />
<br />
<code php><br />
/**<br />
* Callback function that determines whether an action event should be showing its item count<br />
* based on the event type and the item count.<br />
*<br />
* @param calendar_event $event The calendar event.<br />
* @param int $itemcount The item count associated with the action event.<br />
* @return bool<br />
*/<br />
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {<br />
// List of event types where the action event's item count should be shown.<br />
$eventtypesshowingitemcount = [<br />
ASSIGN_EVENT_TYPE_GRADINGDUE<br />
];<br />
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.<br />
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;<br />
}<br />
</code></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52312
Calendar API
2017-05-09T08:47:51Z
<p>Markn: /* mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory) */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
====mod_xyz_core_calendar_provide_event_action()====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()</code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52311
Calendar API
2017-05-09T08:45:55Z
<p>Markn: /* mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory) */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
====mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.<br />
<br />
Eg.<br />
<code php><br />
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,<br />
\core_calendar\action_factory $factory) {<br />
global $CFG;<br />
<br />
require_once($CFG->dirroot . '/mod/scorm/locallib.php');<br />
<br />
$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];<br />
<br />
if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {<br />
// The scorm has closed so the user can no longer submit anything.<br />
return null;<br />
}<br />
<br />
// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.<br />
$customdata = $cm->customdata ?: [];<br />
$customdata['id'] = $cm->instance;<br />
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);<br />
<br />
// Check that the SCORM activity is open.<br />
list($actionable, $warnings) = scorm_get_availability_status($scorm);<br />
<br />
return $factory->create_instance(<br />
get_string('enter', 'scorm'),<br />
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),<br />
1,<br />
$actionable<br />
);<br />
}<br />
</code><br />
<br />
The variables to pass to <code>create_instance()<code> are -<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52304
Calendar API
2017-05-09T08:29:02Z
<p>Markn: /* mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory) */</p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
====mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none (in which case the event will not be shown). This is used by the new block_myoverview plugin. If you do not implement this function then the events created by your plugin will never be shown on the block.<br />
<br />
Eg.<br />
return $factory->create_instance(<br />
$name,<br />
$url,<br />
$itemcount,<br />
$actionable<br />
);<br />
<br />
# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
# $url \moodle_url The URL the user visits in order to perform this action.<br />
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52301
Calendar API
2017-05-09T08:04:25Z
<p>Markn: </p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==Creating an event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
====mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none (in which case the event will not be shown). This is used by the new block_myoverview plugin. If you do not implement this function then the events created by your plugin will never be shown on the block.<br />
<br />
Eg.<br />
return $factory->create_instance(<br />
$name,<br />
$url,<br />
$itemcount,<br />
$actionable<br />
);<br />
<br />
$name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
$url \moodle_url The URL the user visits in order to perform this action.<br />
$itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
$actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52299
Calendar API
2017-05-09T07:14:29Z
<p>Markn: </p>
<hr />
<div>{{ Moodle 3.3 }}<br />
<br />
This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==The calendar_event class==<br />
<br />
The general functionality of the calendar_event() class is to create, update and delete events.<br />
<br />
==Creating a new event==<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
==Updating an event==<br />
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
==Deleting an event==<br />
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==Action events==<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
===The callbacks===<br />
<br />
====mod_xyz_core_calendar_is_event_visible(calendar_event $event)====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
====mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none (in which case the event will not be shown). This is used by the new block_myoverview plugin. If you do not implement this function then the events created by your plugin will never be shown on the block.<br />
<br />
Eg.<br />
return $factory->create_instance(<br />
$name,<br />
$url,<br />
$itemcount,<br />
$actionable<br />
);<br />
<br />
$name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
$url \moodle_url The URL the user visits in order to perform this action.<br />
$itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
$actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52129
Calendar API
2017-04-07T05:47:52Z
<p>Markn: /* Action events */</p>
<hr />
<div>This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of the calendar_event() class is to create, update and delete events.<br />
<br />
===Creating a new event===<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating an event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting an event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
===Action events===<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my overview sam student.png]]<br />
<br />
====The callbacks====<br />
<br />
=====mod_xyz_core_calendar_is_event_visible(calendar_event $event)=====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
=====mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)=====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none (in which case the event will not be shown). This is used by the new block_myoverview plugin. If you do not implement this function then the events created by your plugin will never be shown on the block.<br />
<br />
Eg.<br />
return $factory->create_instance(<br />
$name,<br />
$url,<br />
$itemcount,<br />
$actionable<br />
);<br />
<br />
$name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
$url \moodle_url The URL the user visits in order to perform this action.<br />
$itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
$actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
=====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)=====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=File:my_overview_sam_student.png&diff=52128
File:my overview sam student.png
2017-04-07T05:46:07Z
<p>Markn: </p>
<hr />
<div></div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52127
Calendar API
2017-04-07T05:45:46Z
<p>Markn: </p>
<hr />
<div>This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].<br />
<br />
The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.<br />
<br />
The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of the calendar_event() class is to create, update and delete events.<br />
<br />
===Creating a new event===<br />
Creating a new calendar event. <br />
<br />
<code php><br />
require_once($CFG->dirroot.'/calendar/lib.php');<br />
<br />
$event = new stdClass();<br />
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.<br />
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.<br />
$event->name = get_string('calendarstart', 'scorm', $scorm->name);<br />
$event->description = format_module_intro('scorm', $scorm, $cmid);<br />
$event->courseid = $scorm->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'scorm';<br />
$event->instance = $scorm->id;<br />
$event->timestart = $scorm->timeopen;<br />
$event->timesort = $scorm->timeopen;<br />
$event->visible = instance_is_visible('scorm', $scorm);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating an event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting an event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
===Action events===<br />
<br />
Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.<br />
<br />
[[File:my_overview_sam_student.png]]<br />
<br />
====The callbacks====<br />
<br />
=====mod_xyz_core_calendar_is_event_visible(calendar_event $event)=====<br />
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.<br />
<br />
=====mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)=====<br />
This function takes a calendar event and provides the action associated with it, or null if there is none (in which case the event will not be shown). This is used by the new block_myoverview plugin. If you do not implement this function then the events created by your plugin will never be shown on the block.<br />
<br />
Eg.<br />
return $factory->create_instance(<br />
$name,<br />
$url,<br />
$itemcount,<br />
$actionable<br />
);<br />
<br />
$name String The name of the event, eg. get_string('dosomething', 'mod_xyz').<br />
$url \moodle_url The URL the user visits in order to perform this action.<br />
$itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.<br />
$actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.<br />
<br />
=====mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)=====<br />
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API&diff=52121
Calendar API
2017-04-06T06:30:53Z
<p>Markn: Replaced content with "These are the new docs (written for 3.3) for the calendar API, for the older version please see [https://docs.moodle.org/dev/Calendar_API_old Calendar API]. The Calendar..."</p>
<hr />
<div>These are the new docs (written for 3.3) for the calendar API, for the older version please see [https://docs.moodle.org/dev/Calendar_API_old Calendar API].<br />
<br />
The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API_old&diff=52120
Calendar API old
2017-04-06T06:30:34Z
<p>Markn: </p>
<hr />
<div>These are the old docs for the calendar API, for the newer version please see [https://docs.moodle.org/dev/Calendar_API Calendar API].<br />
<br />
The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to create event for the hook.<br />
<code php><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to update the hook event.<br />
<code php><br />
calendar_event::update($data, $checkcapability = true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to delete event for the hook.<br />
<code php><br />
$calendar_event = new calendar_event($event_data);<br />
$calendar_event->delete($deleterepeated = false)<br />
</code><br />
<br />
===Event hook===<br />
The capability to use hook to perform specific action to calendar event. This requires setting up $CFG->calendar and include external calendar file in $CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php').<br />
<code php><br />
calendar_event_hook($action, array $args)<br />
</code><br />
<br />
==Functions==<br />
List of function for calendar and calendar_event.<br />
<br />
===Retrieve or print calendar's information===<br />
<code php><br />
calendar_get_default_courses()<br />
calendar_get_days()<br />
calendar_get_starting_weekday()<br />
calendar_day_representation($tstamp, $now = false, $usecommonwords = true)<br />
calendar_time_representation($time)<br />
calendar_wday_name($englishname)<br />
calendar_days_in_month($month, $year)<br />
calendar_get_link_href($linkbase, $d, $m, $y)<br />
calendar_get_mini($courses, $groups, $users, $cal_month = false, $cal_year = false)<br />
calendar_get_popup($is_today, $event_timestart, $popupcontent = '') <br />
calendar_add_month($month, $year)<br />
calendar_sub_month($month, $year)<br />
calendar_get_module_cached(&$coursecache, $modulename, $instance) <br />
calendar_get_course_cached(&$coursecache, $courseid)<br />
calendar_print_month_selector($name, $selected)<br />
</code><br />
<br />
===Control calendar display===<br />
<code php><br />
calendar_top_controls($type, $data)<br />
calendar_filter_controls(moodle_url $returnurl)<br />
calendar_preferences_button(stdClass $course)<br />
calendar_set_filters(array $courseeventsfrom, $ignorefilters = false)<br />
calendar_get_link_previous($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
calendar_get_link_next($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
</code><br />
<br />
===Retrieve calendar_event information===<br />
<code php><br />
calendar_get_allowed_types(&$allowed, $course = null)<br />
calendar_add_event_allowed($event) <br />
calendar_edit_event_allowed($event)<br />
calendar_user_can_add_event($course)<br />
calendar_show_event_type($type, $user = null)<br />
calendar_set_event_type_display($type, $display = null, $user = null)<br />
calendar_get_events($tstart, $tend, $users, $groups, $courses, $withduration = true, $ignorehidden = true)<br />
calendar_events_by_day($events, $month, $year, &$eventsbyday, &$durationbyday, &$typesbyday, &$courses) <br />
calendar_get_upcoming($courses, $groups, $users, $daysinfuture, $maxevents, $fromtime = 0)<br />
calendar_get_block_upcoming($events, $linkhref = NULL)<br />
calendar_format_event_time($event, $now, $linkparams = null, $usecommonwords = true, $showtime = 0)<br />
calendar_add_event_metadata($event)<br />
</code><br />
<br />
==Examples==<br />
The following are examples of using the basic calendar_event API in Moodle.<br />
<br />
===Example to create new event===<br />
Creating new calendar event for closing feedback date.<br />
<code php><br />
$event = new stdClass;<br />
$event->name = get_string('stop', 'feedback').' '.$feedback->name;<br />
$event->description = format_module_intro('feedback', $feedback, $feedback->coursemodule);<br />
$event->courseid = $feedback->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'feedback';<br />
$event->instance = $feedback->id;<br />
$event->eventtype = 'feedbackcloses'; // For activity module's events, this can be used to set the alternative text of the event icon. Set it to 'pluginname' unless you have a better string.<br />
$event->timestart = $feedback->timeclose;<br />
$event->visible = instance_is_visible('feedback', $feedback);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating existing calendar event===<br />
Simple example of updating exiting event through moodle form.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting existing calendar event===<br />
Simple example of deleting existing event from database.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[:en:Calendar|Calendar user docs]]<br />
* [[Calendar types]]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API_old&diff=52119
Calendar API old
2017-04-06T06:28:39Z
<p>Markn: </p>
<hr />
<div>These are the old docs for the calendar API, for the newer version please see <br />
<br />
The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to create event for the hook.<br />
<code php><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to update the hook event.<br />
<code php><br />
calendar_event::update($data, $checkcapability = true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to delete event for the hook.<br />
<code php><br />
$calendar_event = new calendar_event($event_data);<br />
$calendar_event->delete($deleterepeated = false)<br />
</code><br />
<br />
===Event hook===<br />
The capability to use hook to perform specific action to calendar event. This requires setting up $CFG->calendar and include external calendar file in $CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php').<br />
<code php><br />
calendar_event_hook($action, array $args)<br />
</code><br />
<br />
==Functions==<br />
List of function for calendar and calendar_event.<br />
<br />
===Retrieve or print calendar's information===<br />
<code php><br />
calendar_get_default_courses()<br />
calendar_get_days()<br />
calendar_get_starting_weekday()<br />
calendar_day_representation($tstamp, $now = false, $usecommonwords = true)<br />
calendar_time_representation($time)<br />
calendar_wday_name($englishname)<br />
calendar_days_in_month($month, $year)<br />
calendar_get_link_href($linkbase, $d, $m, $y)<br />
calendar_get_mini($courses, $groups, $users, $cal_month = false, $cal_year = false)<br />
calendar_get_popup($is_today, $event_timestart, $popupcontent = '') <br />
calendar_add_month($month, $year)<br />
calendar_sub_month($month, $year)<br />
calendar_get_module_cached(&$coursecache, $modulename, $instance) <br />
calendar_get_course_cached(&$coursecache, $courseid)<br />
calendar_print_month_selector($name, $selected)<br />
</code><br />
<br />
===Control calendar display===<br />
<code php><br />
calendar_top_controls($type, $data)<br />
calendar_filter_controls(moodle_url $returnurl)<br />
calendar_preferences_button(stdClass $course)<br />
calendar_set_filters(array $courseeventsfrom, $ignorefilters = false)<br />
calendar_get_link_previous($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
calendar_get_link_next($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
</code><br />
<br />
===Retrieve calendar_event information===<br />
<code php><br />
calendar_get_allowed_types(&$allowed, $course = null)<br />
calendar_add_event_allowed($event) <br />
calendar_edit_event_allowed($event)<br />
calendar_user_can_add_event($course)<br />
calendar_show_event_type($type, $user = null)<br />
calendar_set_event_type_display($type, $display = null, $user = null)<br />
calendar_get_events($tstart, $tend, $users, $groups, $courses, $withduration = true, $ignorehidden = true)<br />
calendar_events_by_day($events, $month, $year, &$eventsbyday, &$durationbyday, &$typesbyday, &$courses) <br />
calendar_get_upcoming($courses, $groups, $users, $daysinfuture, $maxevents, $fromtime = 0)<br />
calendar_get_block_upcoming($events, $linkhref = NULL)<br />
calendar_format_event_time($event, $now, $linkparams = null, $usecommonwords = true, $showtime = 0)<br />
calendar_add_event_metadata($event)<br />
</code><br />
<br />
==Examples==<br />
The following are examples of using the basic calendar_event API in Moodle.<br />
<br />
===Example to create new event===<br />
Creating new calendar event for closing feedback date.<br />
<code php><br />
$event = new stdClass;<br />
$event->name = get_string('stop', 'feedback').' '.$feedback->name;<br />
$event->description = format_module_intro('feedback', $feedback, $feedback->coursemodule);<br />
$event->courseid = $feedback->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'feedback';<br />
$event->instance = $feedback->id;<br />
$event->eventtype = 'feedbackcloses'; // For activity module's events, this can be used to set the alternative text of the event icon. Set it to 'pluginname' unless you have a better string.<br />
$event->timestart = $feedback->timeclose;<br />
$event->visible = instance_is_visible('feedback', $feedback);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating existing calendar event===<br />
Simple example of updating exiting event through moodle form.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting existing calendar event===<br />
Simple example of deleting existing event from database.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[:en:Calendar|Calendar user docs]]<br />
* [[Calendar types]]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Calendar_API_old&diff=52118
Calendar API old
2017-04-06T06:27:13Z
<p>Markn: Created page with "The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site. ==Overview== The Moodle Calendar collects..."</p>
<hr />
<div>The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to create event for the hook.<br />
<code php><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to update the hook event.<br />
<code php><br />
calendar_event::update($data, $checkcapability = true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to delete event for the hook.<br />
<code php><br />
$calendar_event = new calendar_event($event_data);<br />
$calendar_event->delete($deleterepeated = false)<br />
</code><br />
<br />
===Event hook===<br />
The capability to use hook to perform specific action to calendar event. This requires setting up $CFG->calendar and include external calendar file in $CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php').<br />
<code php><br />
calendar_event_hook($action, array $args)<br />
</code><br />
<br />
==Functions==<br />
List of function for calendar and calendar_event.<br />
<br />
===Retrieve or print calendar's information===<br />
<code php><br />
calendar_get_default_courses()<br />
calendar_get_days()<br />
calendar_get_starting_weekday()<br />
calendar_day_representation($tstamp, $now = false, $usecommonwords = true)<br />
calendar_time_representation($time)<br />
calendar_wday_name($englishname)<br />
calendar_days_in_month($month, $year)<br />
calendar_get_link_href($linkbase, $d, $m, $y)<br />
calendar_get_mini($courses, $groups, $users, $cal_month = false, $cal_year = false)<br />
calendar_get_popup($is_today, $event_timestart, $popupcontent = '') <br />
calendar_add_month($month, $year)<br />
calendar_sub_month($month, $year)<br />
calendar_get_module_cached(&$coursecache, $modulename, $instance) <br />
calendar_get_course_cached(&$coursecache, $courseid)<br />
calendar_print_month_selector($name, $selected)<br />
</code><br />
<br />
===Control calendar display===<br />
<code php><br />
calendar_top_controls($type, $data)<br />
calendar_filter_controls(moodle_url $returnurl)<br />
calendar_preferences_button(stdClass $course)<br />
calendar_set_filters(array $courseeventsfrom, $ignorefilters = false)<br />
calendar_get_link_previous($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
calendar_get_link_next($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
</code><br />
<br />
===Retrieve calendar_event information===<br />
<code php><br />
calendar_get_allowed_types(&$allowed, $course = null)<br />
calendar_add_event_allowed($event) <br />
calendar_edit_event_allowed($event)<br />
calendar_user_can_add_event($course)<br />
calendar_show_event_type($type, $user = null)<br />
calendar_set_event_type_display($type, $display = null, $user = null)<br />
calendar_get_events($tstart, $tend, $users, $groups, $courses, $withduration = true, $ignorehidden = true)<br />
calendar_events_by_day($events, $month, $year, &$eventsbyday, &$durationbyday, &$typesbyday, &$courses) <br />
calendar_get_upcoming($courses, $groups, $users, $daysinfuture, $maxevents, $fromtime = 0)<br />
calendar_get_block_upcoming($events, $linkhref = NULL)<br />
calendar_format_event_time($event, $now, $linkparams = null, $usecommonwords = true, $showtime = 0)<br />
calendar_add_event_metadata($event)<br />
</code><br />
<br />
==Examples==<br />
The following are examples of using the basic calendar_event API in Moodle.<br />
<br />
===Example to create new event===<br />
Creating new calendar event for closing feedback date.<br />
<code php><br />
$event = new stdClass;<br />
$event->name = get_string('stop', 'feedback').' '.$feedback->name;<br />
$event->description = format_module_intro('feedback', $feedback, $feedback->coursemodule);<br />
$event->courseid = $feedback->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'feedback';<br />
$event->instance = $feedback->id;<br />
$event->eventtype = 'feedbackcloses'; // For activity module's events, this can be used to set the alternative text of the event icon. Set it to 'pluginname' unless you have a better string.<br />
$event->timestart = $feedback->timeclose;<br />
$event->visible = instance_is_visible('feedback', $feedback);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating existing calendar event===<br />
Simple example of updating exiting event through moodle form.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting existing calendar event===<br />
Simple example of deleting existing event from database.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==See also==<br />
<br />
* [[Core APIs]]<br />
* [[:en:Calendar|Calendar user docs]]<br />
* [[Calendar types]]<br />
<br />
[[Category:API]]</div>
Markn
https://docs.moodle.org/dev/index.php?title=GSOC/2016&diff=51879
GSOC/2016
2017-02-14T04:08:23Z
<p>Markn: /* Atto image resize/crop/rotate */</p>
<hr />
<div>The outputs of the Moodle GSOC 2016 projects were summarised at [https://moodle.com/2016/10/12/moodle-continues-to-advance-open-source-project-through-googles-summer-of-code/ moodle.com blog post].<br />
<br />
For more details, see the [https://dev.moodle.org/course/view.php?id=23 GSOC 2016 course] at dev.moodle.org.<br />
<br />
The final projects were also presented at the [[Developer meeting September 2016]] - see [http://recordings.blindsidenetworks.com/moodlehq/c51f7a86bf8c2f31dba5c5a454a6fd349674f9c2-1473335743561/capture the meeting video archive].<br />
<br />
== Plugin skeleton generator ==<br />
<br />
The project’s aim was to make developing plugins a much easier task. A new tool was designed and implemented by the GSOC student. Based on coding techniques used by existing plugins, on the guides and specifications found in the Moodle developer documentation, as well as on the user’s input, the new tool generates skeleton code that can be used to build new Moodle plugins.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Moodle plugin accepted into the Moodle Plugins directory: https://moodle.org/plugins/tool_pluginskel<br />
* Documentation: [[:en:Plugin skeleton generator|Plugin skeleton generator docs page]]<br />
* Student: [https://moodle.org/user/view.php?id=2024009 Alexandru Elisei]<br />
* Mentor: [https://moodle.org/user/view.php?id=1601 David Mudrák]<br />
* Detailed project spec page: [[tool_pluginkenobi]]<br />
<br />
==Adding search to more Moodle components==<br />
<br />
Several key search areas like users or messages have been successfully integrated into Moodle's core expanding global search subsystem's functionality to cover all major search use cases. You can see the full list of issues in this [https://tracker.moodle.org/browse/MDL-55538 epic].<br />
<br />
* Project status: Successfully passed<br />
* Project output: Integrated into Moodle's core<br />
* Student: [https://moodle.org/user/view.php?id=2039167&course=5 Devang Gaur]<br />
* Mentor: [https://moodle.org/user/profile.php?id=122326 David Monllaó]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-55538 Moodle tracker issue]<br />
<br />
==Atto image resize/crop/rotate==<br />
With the current code users can resize, crop and rotate images in the atto text editor in the same way this can be achieved in Google docs.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Getting ready for integration review<br />
* Student: [https://moodle.org/user/view.php?id=1953983 Joey Andres]<br />
* Mentor: [https://moodle.org/user/profile.php?id=1057750 Mark Nelson]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-44239 Moodle tracker issue] and [https://tracker.moodle.org/browse/MDL-55633 Moodle tracker issue]<br />
<br />
==Add support to end-to-end testing in the Mobile app==<br />
<br />
The project's aim was to add more end to end tests to the Mobile application. Supun developed almost 30 new tests that were integrated into Moodle Mobile.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Almost 30 new tests integrated into Moodle Mobile<br />
* Student: [https://moodle.org/user/view.php?id=2065840&course=5 Supun Wanniarachchi]<br />
* Mentor: Juan Leyva<br />
* [https://github.com/Supun94/moodlemobile2/commits/gsoc-e2e Original branch with the new tests]<br />
* Related issues: MOBILE-1864 AND MOBILE-1179<br />
* [http://blog.supun.me/2016/08/19/gsoc-2016-final-protractor-test-implementation-documentation-moodle-mobile-app/ Detailed project documentation]<br />
<br />
==See Also==<br />
[http://www.moodleworld.com/moodle-announces-gsoc-participants-gsoc-summerofcode-moodle/ Moodle announces GSoC participants]</div>
Markn
https://docs.moodle.org/dev/index.php?title=GSOC/2016&diff=51878
GSOC/2016
2017-02-14T04:07:54Z
<p>Markn: /* Atto image resize/crop/rotate */</p>
<hr />
<div>The outputs of the Moodle GSOC 2016 projects were summarised at [https://moodle.com/2016/10/12/moodle-continues-to-advance-open-source-project-through-googles-summer-of-code/ moodle.com blog post].<br />
<br />
For more details, see the [https://dev.moodle.org/course/view.php?id=23 GSOC 2016 course] at dev.moodle.org.<br />
<br />
The final projects were also presented at the [[Developer meeting September 2016]] - see [http://recordings.blindsidenetworks.com/moodlehq/c51f7a86bf8c2f31dba5c5a454a6fd349674f9c2-1473335743561/capture the meeting video archive].<br />
<br />
== Plugin skeleton generator ==<br />
<br />
The project’s aim was to make developing plugins a much easier task. A new tool was designed and implemented by the GSOC student. Based on coding techniques used by existing plugins, on the guides and specifications found in the Moodle developer documentation, as well as on the user’s input, the new tool generates skeleton code that can be used to build new Moodle plugins.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Moodle plugin accepted into the Moodle Plugins directory: https://moodle.org/plugins/tool_pluginskel<br />
* Documentation: [[:en:Plugin skeleton generator|Plugin skeleton generator docs page]]<br />
* Student: [https://moodle.org/user/view.php?id=2024009 Alexandru Elisei]<br />
* Mentor: [https://moodle.org/user/view.php?id=1601 David Mudrák]<br />
* Detailed project spec page: [[tool_pluginkenobi]]<br />
<br />
==Adding search to more Moodle components==<br />
<br />
Several key search areas like users or messages have been successfully integrated into Moodle's core expanding global search subsystem's functionality to cover all major search use cases. You can see the full list of issues in this [https://tracker.moodle.org/browse/MDL-55538 epic].<br />
<br />
* Project status: Successfully passed<br />
* Project output: Integrated into Moodle's core<br />
* Student: [https://moodle.org/user/view.php?id=2039167&course=5 Devang Gaur]<br />
* Mentor: [https://moodle.org/user/profile.php?id=122326 David Monllaó]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-55538 Moodle tracker issue]<br />
<br />
==Atto image resize/crop/rotate==<br />
With the current code users can resize, crop and rotate images in the atto text edit in the same way this can be achieved in Google docs.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Getting ready for integration review<br />
* Student: [https://moodle.org/user/view.php?id=1953983 Joey Andres]<br />
* Mentor: [https://moodle.org/user/profile.php?id=1057750 Mark Nelson]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-44239 Moodle tracker issue] and [https://tracker.moodle.org/browse/MDL-55633 Moodle tracker issue]<br />
<br />
==Add support to end-to-end testing in the Mobile app==<br />
<br />
The project's aim was to add more end to end tests to the Mobile application. Supun developed almost 30 new tests that were integrated into Moodle Mobile.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Almost 30 new tests integrated into Moodle Mobile<br />
* Student: [https://moodle.org/user/view.php?id=2065840&course=5 Supun Wanniarachchi]<br />
* Mentor: Juan Leyva<br />
* [https://github.com/Supun94/moodlemobile2/commits/gsoc-e2e Original branch with the new tests]<br />
* Related issues: MOBILE-1864 AND MOBILE-1179<br />
* [http://blog.supun.me/2016/08/19/gsoc-2016-final-protractor-test-implementation-documentation-moodle-mobile-app/ Detailed project documentation]<br />
<br />
==See Also==<br />
[http://www.moodleworld.com/moodle-announces-gsoc-participants-gsoc-summerofcode-moodle/ Moodle announces GSoC participants]</div>
Markn
https://docs.moodle.org/dev/index.php?title=GSOC/2016&diff=51877
GSOC/2016
2017-02-14T04:07:20Z
<p>Markn: /* Atto image resize/crop/rotate */</p>
<hr />
<div>The outputs of the Moodle GSOC 2016 projects were summarised at [https://moodle.com/2016/10/12/moodle-continues-to-advance-open-source-project-through-googles-summer-of-code/ moodle.com blog post].<br />
<br />
For more details, see the [https://dev.moodle.org/course/view.php?id=23 GSOC 2016 course] at dev.moodle.org.<br />
<br />
The final projects were also presented at the [[Developer meeting September 2016]] - see [http://recordings.blindsidenetworks.com/moodlehq/c51f7a86bf8c2f31dba5c5a454a6fd349674f9c2-1473335743561/capture the meeting video archive].<br />
<br />
== Plugin skeleton generator ==<br />
<br />
The project’s aim was to make developing plugins a much easier task. A new tool was designed and implemented by the GSOC student. Based on coding techniques used by existing plugins, on the guides and specifications found in the Moodle developer documentation, as well as on the user’s input, the new tool generates skeleton code that can be used to build new Moodle plugins.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Moodle plugin accepted into the Moodle Plugins directory: https://moodle.org/plugins/tool_pluginskel<br />
* Documentation: [[:en:Plugin skeleton generator|Plugin skeleton generator docs page]]<br />
* Student: [https://moodle.org/user/view.php?id=2024009 Alexandru Elisei]<br />
* Mentor: [https://moodle.org/user/view.php?id=1601 David Mudrák]<br />
* Detailed project spec page: [[tool_pluginkenobi]]<br />
<br />
==Adding search to more Moodle components==<br />
<br />
Several key search areas like users or messages have been successfully integrated into Moodle's core expanding global search subsystem's functionality to cover all major search use cases. You can see the full list of issues in this [https://tracker.moodle.org/browse/MDL-55538 epic].<br />
<br />
* Project status: Successfully passed<br />
* Project output: Integrated into Moodle's core<br />
* Student: [https://moodle.org/user/view.php?id=2039167&course=5 Devang Gaur]<br />
* Mentor: [https://moodle.org/user/profile.php?id=122326 David Monllaó]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-55538 Moodle tracker issue]<br />
<br />
==Atto image resize/crop/rotate==<br />
With the current code users can resize, crop and rotate images in the atto text edit in the same way this can be achieved in Google docs.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Getting ready for integration review<br />
* Student: [https://moodle.org/user/view.php?id=1953983&course=5 Joey Andres]<br />
* Mentor: [https://moodle.org/user/profile.php?id=1057750 Mark Nelson]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-44239 Moodle tracker issue] and [https://tracker.moodle.org/browse/MDL-55633 Moodle tracker issue]<br />
<br />
==Add support to end-to-end testing in the Mobile app==<br />
<br />
The project's aim was to add more end to end tests to the Mobile application. Supun developed almost 30 new tests that were integrated into Moodle Mobile.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Almost 30 new tests integrated into Moodle Mobile<br />
* Student: [https://moodle.org/user/view.php?id=2065840&course=5 Supun Wanniarachchi]<br />
* Mentor: Juan Leyva<br />
* [https://github.com/Supun94/moodlemobile2/commits/gsoc-e2e Original branch with the new tests]<br />
* Related issues: MOBILE-1864 AND MOBILE-1179<br />
* [http://blog.supun.me/2016/08/19/gsoc-2016-final-protractor-test-implementation-documentation-moodle-mobile-app/ Detailed project documentation]<br />
<br />
==See Also==<br />
[http://www.moodleworld.com/moodle-announces-gsoc-participants-gsoc-summerofcode-moodle/ Moodle announces GSoC participants]</div>
Markn
https://docs.moodle.org/dev/index.php?title=GSOC/2016&diff=51876
GSOC/2016
2017-02-14T04:06:11Z
<p>Markn: /* Atto image resize/crop/rotate */</p>
<hr />
<div>The outputs of the Moodle GSOC 2016 projects were summarised at [https://moodle.com/2016/10/12/moodle-continues-to-advance-open-source-project-through-googles-summer-of-code/ moodle.com blog post].<br />
<br />
For more details, see the [https://dev.moodle.org/course/view.php?id=23 GSOC 2016 course] at dev.moodle.org.<br />
<br />
The final projects were also presented at the [[Developer meeting September 2016]] - see [http://recordings.blindsidenetworks.com/moodlehq/c51f7a86bf8c2f31dba5c5a454a6fd349674f9c2-1473335743561/capture the meeting video archive].<br />
<br />
== Plugin skeleton generator ==<br />
<br />
The project’s aim was to make developing plugins a much easier task. A new tool was designed and implemented by the GSOC student. Based on coding techniques used by existing plugins, on the guides and specifications found in the Moodle developer documentation, as well as on the user’s input, the new tool generates skeleton code that can be used to build new Moodle plugins.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Moodle plugin accepted into the Moodle Plugins directory: https://moodle.org/plugins/tool_pluginskel<br />
* Documentation: [[:en:Plugin skeleton generator|Plugin skeleton generator docs page]]<br />
* Student: [https://moodle.org/user/view.php?id=2024009 Alexandru Elisei]<br />
* Mentor: [https://moodle.org/user/view.php?id=1601 David Mudrák]<br />
* Detailed project spec page: [[tool_pluginkenobi]]<br />
<br />
==Adding search to more Moodle components==<br />
<br />
Several key search areas like users or messages have been successfully integrated into Moodle's core expanding global search subsystem's functionality to cover all major search use cases. You can see the full list of issues in this [https://tracker.moodle.org/browse/MDL-55538 epic].<br />
<br />
* Project status: Successfully passed<br />
* Project output: Integrated into Moodle's core<br />
* Student: [https://moodle.org/user/view.php?id=2039167&course=5 Devang Gaur]<br />
* Mentor: [https://moodle.org/user/profile.php?id=122326 David Monllaó]<br />
* Issues: [https://tracker.moodle.org/browse/MDL-55538 Moodle tracker issue]<br />
<br />
==Atto image resize/crop/rotate==<br />
With the current code users can resize, crop and rotate images in the atto text edit in the same way this can be achieved in Google docs.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Getting ready for integration review<br />
* Student: [https://moodle.org/user/view.php?id=1953983&course=5 Joey Andres]<br />
* Mentor: Mark Nelson<br />
* Issues: [https://tracker.moodle.org/browse/MDL-44239 Moodle tracker issue] and [https://tracker.moodle.org/browse/MDL-55633 Moodle tracker issue]<br />
<br />
==Add support to end-to-end testing in the Mobile app==<br />
<br />
The project's aim was to add more end to end tests to the Mobile application. Supun developed almost 30 new tests that were integrated into Moodle Mobile.<br />
<br />
* Project status: Successfully passed<br />
* Project output: Almost 30 new tests integrated into Moodle Mobile<br />
* Student: [https://moodle.org/user/view.php?id=2065840&course=5 Supun Wanniarachchi]<br />
* Mentor: Juan Leyva<br />
* [https://github.com/Supun94/moodlemobile2/commits/gsoc-e2e Original branch with the new tests]<br />
* Related issues: MOBILE-1864 AND MOBILE-1179<br />
* [http://blog.supun.me/2016/08/19/gsoc-2016-final-protractor-test-implementation-documentation-moodle-mobile-app/ Detailed project documentation]<br />
<br />
==See Also==<br />
[http://www.moodleworld.com/moodle-announces-gsoc-participants-gsoc-summerofcode-moodle/ Moodle announces GSoC participants]</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=51796
Projects for new developers
2017-01-30T08:02:25Z
<p>Markn: /* Potential projects */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Pusher integration for HTML5 push notifications ===<br />
Moodle supports message output plugins. By adding a plugin for pusher.com and a Javascript service worker to listen for push notifications, we can have realtime HTML5 notifications on all platforms.<br />
:'''Skills required''': Javascript (JQuery, AMD), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=1337843 Damyon Wiese]<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid.<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
===Clef | Two-Factor Authentication===<br />
Create [https://getclef.com Clef two factor authentication] plugin, so a user can log in using their mobile to reduce login time. This will improve security and reduce the login time for users.<br />
<br />
:'''Skills required:''' PHP, Javascript<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=1328988 Rajesh Taneja]<br />
<br />
=== Multi-step login screen ===<br />
Update the login screen to first ask for a username, and then the password as a two-step process.<br />
See the login process for Google<br />
<br />
:'''Skills required:''' PHP, JavaScript, Mustache<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=1779959 John Okely]<br />
<br />
<br />
=== 2FA - Two Factor Authentication ===<br />
Add support for Two-Factor Authentication. This would work well when combined with the Multi-step login screen.<br />
Factors requiring consideration include the Mobile app integrations.<br />
<br />
:'''Skills required:''' PHP, JavaScript, Mustache<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=268794 Andrew Nicols]<br />
<br />
=== CLI Helper for Moodle Developers ===<br />
Possibly an addendum to MDK, a set of scripts to help facilitate various common tasks. In particular:<br />
* creation of Persistent Objects including their Class files, the XMLDB code to create their tables, and the XMLDB upgrade scripts required to upgrade (including version bumps)<br />
<br />
:'''Skills required:''' PHP, Python?<br />
:'''Difficulty level''': Hard<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=268794 Andrew Nicols]<br />
<br />
=== Trait for Mock DB in unit tests ===<br />
In moodle we run every unit test using a real database. This is extremely slow with little benefit. Granted it does catch some cross-database compatibility issues, but we don't need it for every test. We should add a trait that test classes can use that will automatically set up mock $DB to save processing power and unnecessary waiting for DB.<br />
<br />
:'''Skills required:''' PHP, PHPUnit<br />
:'''Difficulty level''': Easy<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=268794 Andrew Nicols] or [https://moodle.org/user/profile.php?id=1779959 John Okely]<br />
<br />
=== Mock implementation of DML ===<br />
In moodle we run every unit test using a real database. This is extremely slow with little benefit. Granted it does catch some cross-database compatibility issues, but we don't need it for every test. It is possible to extend moodle_database and mock all the calls to use an in memory/mocked database. The easiest way to do this may be to use first make a Data Access Object implementation, and then use a mock DAO<br />
<br />
:'''Skills required:''' PHP, PHPUnit<br />
:'''Difficulty level''': Very Hard<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=1779959 John Okely]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn
https://docs.moodle.org/dev/index.php?title=My_course_overview_improvements&diff=51641
My course overview improvements
2016-12-19T04:46:25Z
<p>Markn: /* Course Completion Tracking */</p>
<hr />
<div>This page will detail the technical specification for the improvements to the My course overview block.<br />
<br />
{{Infobox Project<br />
|name = Improvements to my course overview block.<br />
|state = Starting<br />
|tracker = MDL-55611<br />
|discussion = https://tracker.moodle.org/browse/UX-8<br />
|assignee = HQ Projects Team<br />
}}<br />
<br />
== Summary ==<br />
<br />
The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.<br />
<br />
The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview). <br />
<br />
== Requirements ==<br />
<br />
=== Course Overview Block ===<br />
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.<br />
<br />
* Mustache templates:<br />
** General template for the block (wrapping template)<br />
*** Timeline view<br />
**** Sort by dates (wrapping template)<br />
***** Template for displaying single todo (rendered in list)<br />
**** Sort by courses (wrapping template)<br />
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)<br />
** Courses view<br />
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data<br />
*** As above, single template for a course<br />
* Javascript<br />
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)<br />
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Module for courses view that handles requesting the data and rendering the templates<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Use the new pie chart we add<br />
** User the todo api javascript module to interact with the server external API<br />
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)<br />
** Style Boost theme<br />
** Style bootstrap base theme (e.g. clean)<br />
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)<br />
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)<br />
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)<br />
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)<br />
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)<br />
<br />
=== Todo API ===<br />
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user. <br />
<br />
The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc. <br />
<br />
Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.<br />
<br />
Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.<br />
<br />
* Add a todo class (pretty please can we have an actual class rather than just stdClass)<br />
** Some properties of the class:<br />
*** unique id (context id, component, area and item id?)<br />
*** name - the name of the thing the todo relates to (e.g. activity name)<br />
*** url - the url of the thing the todo relates to (e.g. view.php of the module)<br />
*** user id - the id of the user this todo belong to<br />
*** course id - the course if that the todo relates to<br />
*** icon url - the icon for the todo (default to the module icon)<br />
*** start date (optional) - when the todo starts<br />
*** end date (optional) - when the todo must be actioned by<br />
*** item count - how many associated items there are (e.g. 4 unread posts)<br />
*** action name - display name of the todo (e.g. "submit assignment")<br />
*** action url - url of the todo action (e.g. link to the assignment submission page)<br />
*** action start date - a date after which the todo can be actioned (only display the action url after this date)<br />
*** action state - Has this been actioned? Eg, The assignment was submitted.<br />
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).<br />
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).<br />
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).<br />
** The API class would benefit from this.<br />
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.<br />
** It can also handle all of the caching<br />
** Support pagination as above<br />
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).<br />
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.<br />
* Add an external API class.<br />
** This class shouldn't contain any business logic (that all lives in the API class). <br />
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.<br />
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.<br />
* Add some renderables for the todo<br />
** The todos should probably just be renderable / template-able themselves<br />
** These will be used by the external API class.<br />
* Improve performance using caching (this will be trial and error with the performance testing)<br />
* Write unit tests for all new API functions and external API functions<br />
* Add a javascript module to interact with the Todo API (no bespoke ajax requests everywhere please)<br />
<br />
=== Chart.js ===<br />
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above<br />
<br />
=== Calendar Event API ===<br />
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.<br />
<br />
* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation<br />
* Add indexes to the event table if they are missing<br />
** display/order by date<br />
** course id<br />
** user id<br />
* Add functions to the calendar event API to retrieve groups of events for a given user(s)<br />
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code<br />
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set<br />
** API needs to support order by new date field<br />
** API needs to support limit and offset<br />
* Add unit tests for new API functions<br />
<br />
=== Calendar Block ===<br />
* Make sure all of the todos are showing up in the calendar for the user<br />
** Note: we *should* get this for free since we are simply creating calendar events<br />
* Make sure we are only displaying appropriate events (ie. if there is a user override then show that for the user, not multiple).<br />
<br />
=== Course Completion Tracking ===<br />
* Develop a way to track completion on for all courses<br />
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled<br />
* Add an API to query the completion status of a course that implements the agreed approach<br />
* Do we need to persist the course progress somewhere or can it be calculated at run time?<br />
** Assess performance of both options<br />
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate<br />
<br />
==== Notes ====<br />
There are different ways of calculating the completion percentage for a course and some will be more informative than others, depending on the type of usage of the course.<br />
<br />
Some possible options are:<br />
* The number of completed+visible activities / The number of visible activities<br />
* The number of completed activities / The number of activities<br />
* The current week / the number of weeks<br />
* The (current date - course start date) / (course end date - course start date) * Requires a course end date<br />
* The current course grade / the required course grade (don’t expose hidden grades)<br />
* The enrolment duration / the required enrolment duration<br />
<br />
Because each course completion criteria requires a different calculation, one possible method is:<br />
<br />
'''If course completion is enabled'''<br />
<br />
for each course completion criteria - get the current and total possible values for completion<br />
<br />
'''if all are required:''' <br />
<br />
normalise and sum/average the values<br />
<br />
'''if any is required'''<br />
<br />
calculate the highest percentage completion<br />
<br />
'''If only activity completion is enabled (and not course completion)''' <br />
<br />
calculate the completion percentage purely on the number of activities complete / the total number of activities. (Ignoring activities with no completion - should we ignore activities the current user cannot see via access restrictions?)<br />
<br />
'''If course completion is not enabled'''<br />
<br />
Try and calculation the completion based purely on the course start / end date<br />
<br />
'''To calculate the current and total values for each completion criteria:'''<br />
* Activity completion - number of activities complete / number of activities required to be completed<br />
* Completion of other courses - number of courses complete / number of courses required to be completed<br />
* Enrolment Date - the current date - course start date / the enrolled until date - course start date. If there is no course start date use the enrolment start date. Max of 1.<br />
* Enroled duration - the number of days enrolled / the number of days required to be enrolled. Max of 1.<br />
* Unenrollment. 0 if enrolled, 1 if unenrolled.<br />
* Course grade - current course grade / required course grade. Max of 1.<br />
* Manual self completion. 0 if not complete, 1 if complete<br />
* Manual completion by others. 0 if not complete, 1 if complete<br />
<br />
=== General Moodle stuff ===<br />
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block<br />
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events<br />
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit<br />
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)<br />
* Add an implementation of the callback interface thingo to each module that will be creating a todo <br />
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc<br />
** It will then create the appropriate todo from the calendar event and add all of the action stuff.<br />
<br />
=== General Testing ===<br />
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.<br />
<br />
=== Proof Of Concept Code ===<br />
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2<br />
<br />
Please review it and add any comments or what ever.<br />
<br />
== Questions for the UX team ==<br />
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?<br />
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?<br />
** Answer: It gets removed.<br />
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.<br />
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?<br />
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.<br />
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?<br />
* When an activity combines both a ''due date'' and an ''expected completed on'' date (e.g. assignment module with completion), what is the date of the task?<br />
* Are activities the only ones that generate calendar events (todos)?<br />
<br />
== Questions for the Integrators ==<br />
* What should we do with the existing block_course_overview block and the corresponding hooks in the activities (eg. xxx_print_overview())?<br />
# Leave the block and keep the hooks.<br />
## Have to maintain more code. This is not desirable as we have a new fancy block now.<br />
# Leave the block in the code and deprecate the hooks in the activities.<br />
## Will be odd having a block in core we know will display debugging messages. <br />
# Delete the block and don't put it in plugins DB and remove the hooks from the activities completely, no debugging messages or anything.<br />
## This will break for users who are relying on the code being there, or third party activities who have extensive code in their hook to display something fancy that no longer gets used.<br />
# We should move the block to the plugins DB and deprecate the hooks.<br />
## It is odd having a block in the plugins DB that when installed will display debugging messages.<br />
# We should ask Integrators.<br />
<br />
== Things for Damyon ==<br />
* Think of complex scenarios that the API will have to deal with. If it's too complex forget Damyon mentioned it.</div>
Markn
https://docs.moodle.org/dev/index.php?title=My_course_overview_improvements&diff=51574
My course overview improvements
2016-12-13T06:04:59Z
<p>Markn: </p>
<hr />
<div>This page will detail the technical specification for the improvements to the My course overview block.<br />
<br />
{{Infobox Project<br />
|name = Improvements to my course overview block.<br />
|state = Starting<br />
|tracker = MDL-55611<br />
|discussion = https://tracker.moodle.org/browse/UX-8<br />
|assignee = HQ Projects Team<br />
}}<br />
<br />
== Summary ==<br />
<br />
The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.<br />
<br />
The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview). <br />
<br />
== Requirements ==<br />
<br />
=== Course Overview Block ===<br />
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.<br />
<br />
* Mustache templates:<br />
** General template for the block (wrapping template)<br />
*** Timeline view<br />
**** Sort by dates (wrapping template)<br />
***** Template for displaying single todo (rendered in list)<br />
**** Sort by courses (wrapping template)<br />
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)<br />
** Courses view<br />
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data<br />
*** As above, single template for a course<br />
* Javascript<br />
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)<br />
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Module for courses view that handles requesting the data and rendering the templates<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Use the new pie chart we add<br />
** User the todo api javascript module to interact with the server external API<br />
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)<br />
** Style Boost theme<br />
** Style bootstrap base theme (e.g. clean)<br />
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)<br />
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)<br />
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)<br />
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)<br />
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)<br />
<br />
=== Todo API ===<br />
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user. <br />
<br />
The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc. <br />
<br />
Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.<br />
<br />
Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.<br />
<br />
* Add a todo class (pretty please can we have an actual class rather than just stdClass)<br />
** Some properties of the class:<br />
*** unique id (context id, component, area and item id?)<br />
*** name - the name of the thing the todo relates to (e.g. activity name)<br />
*** url - the url of the thing the todo relates to (e.g. view.php of the module)<br />
*** user id - the id of the user this todo belong to<br />
*** course id - the course if that the todo relates to<br />
*** icon url - the icon for the todo (default to the module icon)<br />
*** start date (optional) - when the todo starts<br />
*** end date (optional) - when the todo must be actioned by<br />
*** item count - how many associated items there are (e.g. 4 unread posts)<br />
*** action name - display name of the todo (e.g. "submit assignment")<br />
*** action url - url of the todo action (e.g. link to the assignment submission page)<br />
*** action start date - a date after which the todo can be actioned (only display the action url after this date)<br />
*** action state - Has this been actioned? Eg, The assignment was submitted.<br />
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).<br />
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).<br />
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).<br />
** The API class would benefit from this.<br />
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.<br />
** It can also handle all of the caching<br />
** Support pagination as above<br />
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).<br />
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.<br />
* Add an external API class.<br />
** This class shouldn't contain any business logic (that all lives in the API class). <br />
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.<br />
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.<br />
* Add some renderables for the todo<br />
** The todos should probably just be renderable / template-able themselves<br />
** These will be used by the external API class.<br />
* Improve performance using caching (this will be trial and error with the performance testing)<br />
* Write unit tests for all new API functions and external API functions<br />
* Add a javascript module to interact with the Todo API (no bespoke ajax requests everywhere please)<br />
<br />
=== Chart.js ===<br />
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above<br />
<br />
=== Calendar Event API ===<br />
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.<br />
<br />
* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation<br />
* Add indexes to the event table if they are missing<br />
** display/order by date<br />
** course id<br />
** user id<br />
* Add functions to the calendar event API to retrieve groups of events for a given user(s)<br />
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code<br />
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set<br />
** API needs to support order by new date field<br />
** API needs to support limit and offset<br />
* Add unit tests for new API functions<br />
<br />
=== Calendar Block ===<br />
* Make sure all of the todos are showing up in the calendar for the user<br />
** Note: we *should* get this for free since we are simply creating calendar events<br />
* Make sure we are only displaying appropriate events (ie. if there is a user override then show that for the user, not multiple).<br />
<br />
=== Course Completion Tracking ===<br />
* Develop a way to track completion on for all courses<br />
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled<br />
* Add an API to query the completion status of a course that implements the agreed approach<br />
* Do we need to persist the course progress somewhere or can it be calculated at run time?<br />
** Assess performance of both options<br />
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate<br />
<br />
=== General Moodle stuff ===<br />
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block<br />
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events<br />
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit<br />
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)<br />
* Add an implementation of the callback interface thingo to each module that will be creating a todo <br />
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc<br />
** It will then create the appropriate todo from the calendar event and add all of the action stuff.<br />
<br />
=== General Testing ===<br />
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.<br />
<br />
=== Proof Of Concept Code ===<br />
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2<br />
<br />
Please review it and add any comments or what ever.<br />
<br />
== Questions for the UX team ==<br />
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?<br />
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?<br />
** Answer: It gets removed.<br />
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.<br />
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?<br />
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.<br />
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?<br />
* When an activity combines both a ''due date'' and an ''expected completed on'' date (e.g. assignment module with completion), what is the date of the task?<br />
* Are activities the only ones that generate calendar events (todos)?<br />
<br />
== Questions for the Integrators ==<br />
* What should we do with the existing block_course_overview block and the corresponding hooks in the activities (eg. xxx_print_overview())?<br />
# Leave the block and keep the hooks.<br />
## Have to maintain more code. This is not desirable as we have a new fancy block now.<br />
# Leave the block in the code and deprecate the hooks in the activities.<br />
## Will be odd having a block in core we know will display debugging messages. <br />
# Delete the block and don't put it in plugins DB and remove the hooks from the activities completely, no debugging messages or anything.<br />
## This will break for users who are relying on the code being there, or third party activities who have extensive code in their hook to display something fancy that no longer gets used.<br />
# We should move the block to the plugins DB and deprecate the hooks.<br />
## It is odd having a block in the plugins DB that when installed will display debugging messages.<br />
# We should ask Integrators.<br />
<br />
== Things for Damyon ==<br />
* Think of complex scenarios that the API will have to deal with. If it's too complex forget Damyon mentioned it.</div>
Markn
https://docs.moodle.org/dev/index.php?title=My_course_overview_improvements&diff=51573
My course overview improvements
2016-12-13T05:44:47Z
<p>Markn: /* Questions for the Integrators */</p>
<hr />
<div>This page will detail the technical specification for the improvements to the My course overview block.<br />
<br />
{{Infobox Project<br />
|name = Improvements to my course overview block.<br />
|state = Starting<br />
|tracker = MDL-55611<br />
|discussion = https://tracker.moodle.org/browse/UX-8<br />
|assignee = HQ Projects Team<br />
}}<br />
<br />
== Summary ==<br />
<br />
The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.<br />
<br />
The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview). <br />
<br />
== Requirements ==<br />
<br />
=== Course Overview Block ===<br />
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.<br />
<br />
* Mustache templates:<br />
** General template for the block (wrapping template)<br />
*** Timeline view<br />
**** Sort by dates (wrapping template)<br />
***** Template for displaying single todo (rendered in list)<br />
**** Sort by courses (wrapping template)<br />
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)<br />
** Courses view<br />
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data<br />
*** As above, single template for a course<br />
* Javascript<br />
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)<br />
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Module for courses view that handles requesting the data and rendering the templates<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Use the new pie chart we add<br />
** User the todo api javascript module to interact with the server external API<br />
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)<br />
** Style Boost theme<br />
** Style bootstrap base theme (e.g. clean)<br />
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)<br />
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)<br />
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)<br />
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)<br />
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)<br />
<br />
=== Todo API ===<br />
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user. <br />
<br />
The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc. <br />
<br />
Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.<br />
<br />
Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.<br />
<br />
* Add a todo class (pretty please can we have an actual class rather than just stdClass)<br />
** Some properties of the class:<br />
*** unique id (context id, component, area and item id?)<br />
*** name - the name of the thing the todo relates to (e.g. activity name)<br />
*** url - the url of the thing the todo relates to (e.g. view.php of the module)<br />
*** user id - the id of the user this todo belong to<br />
*** course id - the course if that the todo relates to<br />
*** icon url - the icon for the todo (default to the module icon)<br />
*** start date (optional) - when the todo starts<br />
*** end date (optional) - when the todo must be actioned by<br />
*** item count - how many associated items there are (e.g. 4 unread posts)<br />
*** action name - display name of the todo (e.g. "submit assignment")<br />
*** action url - url of the todo action (e.g. link to the assignment submission page)<br />
*** action start date - a date after which the todo can be actioned (only display the action url after this date)<br />
*** action state - Has this been actioned? Eg, The assignment was submitted.<br />
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).<br />
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).<br />
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).<br />
** The API class would benefit from this.<br />
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.<br />
** It can also handle all of the caching<br />
** Support pagination as above<br />
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).<br />
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.<br />
* Add an external API class.<br />
** This class shouldn't contain any business logic (that all lives in the API class). <br />
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.<br />
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.<br />
* Add some renderables for the todo<br />
** The todos should probably just be renderable / template-able themselves<br />
** These will be used by the external API class.<br />
* Improve performance using caching (this will be trial and error with the performance testing)<br />
* Write unit tests for all new API functions and external API functions<br />
* Add a javascript module to interact with the Todo API (no bespoke ajax requests everywhere please)<br />
<br />
=== Chart.js ===<br />
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above<br />
<br />
=== Calendar Event API ===<br />
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.<br />
<br />
* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation<br />
* Add indexes to the event table if they are missing<br />
** display/order by date<br />
** course id<br />
** user id<br />
* Add functions to the calendar event API to retrieve groups of events for a given user(s)<br />
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code<br />
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set<br />
** API needs to support order by new date field<br />
** API needs to support limit and offset<br />
* Add unit tests for new API functions<br />
<br />
=== Calendar Block ===<br />
* Make sure all of the todos are showing up in the calendar for the user<br />
** Note: we *should* get this for free since we are simply creating calendar events<br />
<br />
=== Course Completion Tracking ===<br />
* Develop a way to track completion on for all courses<br />
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled<br />
* Add an API to query the completion status of a course that implements the agreed approach<br />
* Do we need to persist the course progress somewhere or can it be calculated at run time?<br />
** Assess performance of both options<br />
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate<br />
<br />
=== General Moodle stuff ===<br />
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block<br />
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events<br />
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit<br />
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)<br />
* Add an implementation of the callback interface thingo to each module that will be creating a todo <br />
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc<br />
** It will then create the appropriate todo from the calendar event and add all of the action stuff.<br />
<br />
=== General Testing ===<br />
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.<br />
<br />
=== Proof Of Concept Code ===<br />
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2<br />
<br />
Please review it and add any comments or what ever.<br />
<br />
== Questions for the UX team ==<br />
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?<br />
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?<br />
** Answer: It gets removed.<br />
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.<br />
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?<br />
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.<br />
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?<br />
* When an activity combines both a ''due date'' and an ''expected completed on'' date (e.g. assignment module with completion), what is the date of the task?<br />
<br />
== Questions for the Integrators ==<br />
* What should we do with the existing block_course_overview block and the corresponding hooks in the activities (eg. xxx_print_overview())?<br />
# Leave the block and keep the hooks.<br />
## Have to maintain more code. This is not desirable as we have a new fancy block now.<br />
# Leave the block in the code and deprecate the hooks in the activities.<br />
## Will be odd having a block in core we know will display debugging messages. <br />
# Delete the block and don't put it in plugins DB and remove the hooks from the activities completely, no debugging messages or anything.<br />
## This will break for users who are relying on the code being there, or third party activities who have extensive code in their hook to display something fancy that no longer gets used.<br />
# We should move the block to the plugins DB and deprecate the hooks.<br />
## It is odd having a block in the plugins DB that when installed will display debugging messages.<br />
# We should ask integrators.</div>
Markn
https://docs.moodle.org/dev/index.php?title=My_course_overview_improvements&diff=51572
My course overview improvements
2016-12-13T05:43:33Z
<p>Markn: /* Questions for the Integrators */</p>
<hr />
<div>This page will detail the technical specification for the improvements to the My course overview block.<br />
<br />
{{Infobox Project<br />
|name = Improvements to my course overview block.<br />
|state = Starting<br />
|tracker = MDL-55611<br />
|discussion = https://tracker.moodle.org/browse/UX-8<br />
|assignee = HQ Projects Team<br />
}}<br />
<br />
== Summary ==<br />
<br />
The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.<br />
<br />
The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview). <br />
<br />
== Requirements ==<br />
<br />
=== Course Overview Block ===<br />
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.<br />
<br />
* Mustache templates:<br />
** General template for the block (wrapping template)<br />
*** Timeline view<br />
**** Sort by dates (wrapping template)<br />
***** Template for displaying single todo (rendered in list)<br />
**** Sort by courses (wrapping template)<br />
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)<br />
** Courses view<br />
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data<br />
*** As above, single template for a course<br />
* Javascript<br />
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)<br />
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Module for courses view that handles requesting the data and rendering the templates<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Use the new pie chart we add<br />
** User the todo api javascript module to interact with the server external API<br />
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)<br />
** Style Boost theme<br />
** Style bootstrap base theme (e.g. clean)<br />
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)<br />
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)<br />
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)<br />
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)<br />
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)<br />
<br />
=== Todo API ===<br />
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user. <br />
<br />
The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc. <br />
<br />
Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.<br />
<br />
Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.<br />
<br />
* Add a todo class (pretty please can we have an actual class rather than just stdClass)<br />
** Some properties of the class:<br />
*** unique id (context id, component, area and item id?)<br />
*** name - the name of the thing the todo relates to (e.g. activity name)<br />
*** url - the url of the thing the todo relates to (e.g. view.php of the module)<br />
*** user id - the id of the user this todo belong to<br />
*** course id - the course if that the todo relates to<br />
*** icon url - the icon for the todo (default to the module icon)<br />
*** start date (optional) - when the todo starts<br />
*** end date (optional) - when the todo must be actioned by<br />
*** item count - how many associated items there are (e.g. 4 unread posts)<br />
*** action name - display name of the todo (e.g. "submit assignment")<br />
*** action url - url of the todo action (e.g. link to the assignment submission page)<br />
*** action start date - a date after which the todo can be actioned (only display the action url after this date)<br />
*** action state - Has this been actioned? Eg, The assignment was submitted.<br />
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).<br />
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).<br />
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).<br />
** The API class would benefit from this.<br />
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.<br />
** It can also handle all of the caching<br />
** Support pagination as above<br />
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).<br />
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.<br />
* Add an external API class.<br />
** This class shouldn't contain any business logic (that all lives in the API class). <br />
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.<br />
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.<br />
* Add some renderables for the todo<br />
** The todos should probably just be renderable / template-able themselves<br />
** These will be used by the external API class.<br />
* Improve performance using caching (this will be trial and error with the performance testing)<br />
* Write unit tests for all new API functions and external API functions<br />
* Add a javascript module to interact with the Todo API (no bespoke ajax requests everywhere please)<br />
<br />
=== Chart.js ===<br />
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above<br />
<br />
=== Calendar Event API ===<br />
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.<br />
<br />
* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation<br />
* Add indexes to the event table if they are missing<br />
** display/order by date<br />
** course id<br />
** user id<br />
* Add functions to the calendar event API to retrieve groups of events for a given user(s)<br />
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code<br />
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set<br />
** API needs to support order by new date field<br />
** API needs to support limit and offset<br />
* Add unit tests for new API functions<br />
<br />
=== Calendar Block ===<br />
* Make sure all of the todos are showing up in the calendar for the user<br />
** Note: we *should* get this for free since we are simply creating calendar events<br />
<br />
=== Course Completion Tracking ===<br />
* Develop a way to track completion on for all courses<br />
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled<br />
* Add an API to query the completion status of a course that implements the agreed approach<br />
* Do we need to persist the course progress somewhere or can it be calculated at run time?<br />
** Assess performance of both options<br />
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate<br />
<br />
=== General Moodle stuff ===<br />
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block<br />
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events<br />
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit<br />
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)<br />
* Add an implementation of the callback interface thingo to each module that will be creating a todo <br />
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc<br />
** It will then create the appropriate todo from the calendar event and add all of the action stuff.<br />
<br />
=== General Testing ===<br />
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.<br />
<br />
=== Proof Of Concept Code ===<br />
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2<br />
<br />
Please review it and add any comments or what ever.<br />
<br />
== Questions for the UX team ==<br />
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?<br />
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?<br />
** Answer: It gets removed.<br />
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.<br />
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?<br />
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.<br />
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?<br />
* When an activity combines both a ''due date'' and an ''expected completed on'' date (e.g. assignment module with completion), what is the date of the task?<br />
<br />
== Questions for the Integrators ==<br />
* What should we do with the existing block_course_overview block?<br />
# Leave the block and keep the hooks.<br />
## Have to maintain more code. This is not desirable as we have a new fancy block now.<br />
# Leave the block in the code and deprecate the hooks in the activities.<br />
## Will be odd having a block in core we know will display debugging messages. <br />
# Delete the block and don't put it in plugins DB and remove the hooks from the activities completely, no debugging messages or anything.<br />
## This will break for users who are relying on the code being there, or third party activities who have extensive code in their hook to display something fancy that no longer gets used.<br />
# We should move the block to the plugins DB and deprecate the hooks.<br />
## It is odd having a block in the plugins DB that when installed will display debugging messages.<br />
# We should ask integrators.</div>
Markn
https://docs.moodle.org/dev/index.php?title=My_course_overview_improvements&diff=51571
My course overview improvements
2016-12-13T05:41:42Z
<p>Markn: </p>
<hr />
<div>This page will detail the technical specification for the improvements to the My course overview block.<br />
<br />
{{Infobox Project<br />
|name = Improvements to my course overview block.<br />
|state = Starting<br />
|tracker = MDL-55611<br />
|discussion = https://tracker.moodle.org/browse/UX-8<br />
|assignee = HQ Projects Team<br />
}}<br />
<br />
== Summary ==<br />
<br />
The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.<br />
<br />
The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview). <br />
<br />
== Requirements ==<br />
<br />
=== Course Overview Block ===<br />
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.<br />
<br />
* Mustache templates:<br />
** General template for the block (wrapping template)<br />
*** Timeline view<br />
**** Sort by dates (wrapping template)<br />
***** Template for displaying single todo (rendered in list)<br />
**** Sort by courses (wrapping template)<br />
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)<br />
** Courses view<br />
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data<br />
*** As above, single template for a course<br />
* Javascript<br />
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)<br />
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Module for courses view that handles requesting the data and rendering the templates<br />
*** Module needs to handle paginated results (view more button being clicked)<br />
** Use the new pie chart we add<br />
** User the todo api javascript module to interact with the server external API<br />
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)<br />
** Style Boost theme<br />
** Style bootstrap base theme (e.g. clean)<br />
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)<br />
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)<br />
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)<br />
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)<br />
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)<br />
<br />
=== Todo API ===<br />
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user. <br />
<br />
The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc. <br />
<br />
Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.<br />
<br />
Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.<br />
<br />
* Add a todo class (pretty please can we have an actual class rather than just stdClass)<br />
** Some properties of the class:<br />
*** unique id (context id, component, area and item id?)<br />
*** name - the name of the thing the todo relates to (e.g. activity name)<br />
*** url - the url of the thing the todo relates to (e.g. view.php of the module)<br />
*** user id - the id of the user this todo belong to<br />
*** course id - the course if that the todo relates to<br />
*** icon url - the icon for the todo (default to the module icon)<br />
*** start date (optional) - when the todo starts<br />
*** end date (optional) - when the todo must be actioned by<br />
*** item count - how many associated items there are (e.g. 4 unread posts)<br />
*** action name - display name of the todo (e.g. "submit assignment")<br />
*** action url - url of the todo action (e.g. link to the assignment submission page)<br />
*** action start date - a date after which the todo can be actioned (only display the action url after this date)<br />
*** action state - Has this been actioned? Eg, The assignment was submitted.<br />
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).<br />
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).<br />
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).<br />
** The API class would benefit from this.<br />
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.<br />
** It can also handle all of the caching<br />
** Support pagination as above<br />
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).<br />
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.<br />
* Add an external API class.<br />
** This class shouldn't contain any business logic (that all lives in the API class). <br />
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.<br />
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.<br />
* Add some renderables for the todo<br />
** The todos should probably just be renderable / template-able themselves<br />
** These will be used by the external API class.<br />
* Improve performance using caching (this will be trial and error with the performance testing)<br />
* Write unit tests for all new API functions and external API functions<br />
* Add a javascript module to interact with the Todo API (no bespoke ajax requests everywhere please)<br />
<br />
=== Chart.js ===<br />
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above<br />
<br />
=== Calendar Event API ===<br />
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.<br />
<br />
* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation<br />
* Add indexes to the event table if they are missing<br />
** display/order by date<br />
** course id<br />
** user id<br />
* Add functions to the calendar event API to retrieve groups of events for a given user(s)<br />
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code<br />
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set<br />
** API needs to support order by new date field<br />
** API needs to support limit and offset<br />
* Add unit tests for new API functions<br />
<br />
=== Calendar Block ===<br />
* Make sure all of the todos are showing up in the calendar for the user<br />
** Note: we *should* get this for free since we are simply creating calendar events<br />
<br />
=== Course Completion Tracking ===<br />
* Develop a way to track completion on for all courses<br />
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled<br />
* Add an API to query the completion status of a course that implements the agreed approach<br />
* Do we need to persist the course progress somewhere or can it be calculated at run time?<br />
** Assess performance of both options<br />
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate<br />
<br />
=== General Moodle stuff ===<br />
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block<br />
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events<br />
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit<br />
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)<br />
* Add an implementation of the callback interface thingo to each module that will be creating a todo <br />
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc<br />
** It will then create the appropriate todo from the calendar event and add all of the action stuff.<br />
<br />
=== General Testing ===<br />
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.<br />
<br />
=== Proof Of Concept Code ===<br />
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2<br />
<br />
Please review it and add any comments or what ever.<br />
<br />
== Questions for the UX team ==<br />
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?<br />
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?<br />
** Answer: It gets removed.<br />
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.<br />
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?<br />
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.<br />
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?<br />
* When an activity combines both a ''due date'' and an ''expected completed on'' date (e.g. assignment module with completion), what is the date of the task?<br />
<br />
== Questions for the Integrators ==<br />
* Should we move the block to plugins DB? If we do, then we need to consider the hooks it uses in the activities, should they throw a debugging message? Installing a block you know will throw debugging messages will be odd.<br />
* Options -<br />
# Leave the block and keep the hooks.<br />
## Have to maintain more code. This is not desirable as we have a new fancy block now.<br />
# Leave the block in the code and deprecate the hooks in the activities.<br />
## Will be odd having a block in core we know will display debugging messages. <br />
# Delete the block and don't put it in plugins DB and remove the hooks from the activities completely, no debugging messages or anything.<br />
## This will break for users who are relying on the code being there, or third party activities who have extensive code in their hook to display something fancy that no longer gets used.<br />
# We should move the block to the plugins DB and deprecate the hooks.<br />
## It is odd having a block in the plugins DB that when installed will display debugging messages.<br />
# We should ask integrators.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Backup_2.0_for_developers&diff=50828
Backup 2.0 for developers
2016-09-01T08:00:09Z
<p>Markn: /* Annotating files */</p>
<hr />
<div>{{Template:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}<br />
<br />
== Introduction ==<br />
<br />
This page tries to explain, from a development perspective, '''how to implement''' the backup feature for various Moodle 2.x plugins, mainly, modules and blocks. <br />
<br />
Note that, at the time of writing this, the backup & restore subsystem itself is '''under development''', so still there are some missing bits, specially about the way to handle '''subplugins''' (question types, data fields...) under the new backup infrastructure, so any module using such artifacts, like data, assignment, quiz, workshop, aren't good candidates right now. This will be addressed (and this Docs updated) once we have determined how each subplugin is expected to work (from a DB / backup perspective).<br />
<br />
Everything in backup '''is about tasks and steps''' (see [[Backup 2.0 general architecture|Backup 2.0 general architecture]] for more information), all them conforming one backup plan. Each module instance and each block instance will be backup by one backup task instance that is, basically, one collection of backup steps. How steps are organized within the task will dictate to the backup system what to do and in which order.<br />
<br />
Another important point is that Moodle backup 2.0, supports '''multiple backup formats''' ("moodle2", "imscc"...) each one having its own tasks/steps, completely unrelated between them. In any case, for now, we are focusing all the explanations below in the "moodle2" format, that is the one required in order to keep any module/block '''transportable between Moodle instances''' without any loss of data. Surely, for the rest of formats, we'll end with other documents describing them, since each one can have its own particularities.<br />
<br />
Talking about backup steps we must differentiate '''two type of steps''':<br />
<br />
* '''Execution steps''': That, simply, execute arbitrary PHP code. They are useful to prepare different structures, create directories, whatever have to be done not involving the generation of XML files. Normally you won't need them.<br />
* '''Structure steps''': That, using one PHP API (detailed below) define completely the XML structure to be exported and its contents. Hopefully, "normal" modules only will have to use one step of this type in order to have the backup functionality 100% implemented.<br />
<br />
Said that, in the next steps we are going through all the steps necessary to create the backup of one simple module and one block, in order to get all the possibilities covered.<br />
<br />
== How to backup one module ==<br />
<br />
For this section, we have selected one simple module (choice) that requires practically all the backup "machinery" to be used, so it will get explained as we progress in the development. The only point not covered here are the "subplugin" facilities, covered later in a separate section.<br />
<br />
=== Prerequisites ===<br />
<br />
In order to achieve the backup implementation for the module, some prerequisites should be fulfilled. They are default recommendations that are especially helpful while getting used to the backup process.<br />
<br />
# '''Learn about the module'''. If you aren't the creator of the module, spend some time playing with the module, creating and using it, exploring each one of its functionalities. By doing this you will end with some "real" data in the module instances that will be really useful when testing / debugging how the module backup is being generated.<br />
# '''Draw one schema of the module''' DB structures. While you are playing with the module, look continuously to the DB, how records are saved and what the relationships are between the module's tables. Since a backup is, basically, one "selective dump" of those tables, knowing the maximum about them is highly recommended. At the end, you must end with one tree structure will be the basis for the generated XML file.<br />
# '''Annotate which tables contain user-related info''' and which ones don't. One of the core functionalities that must be present on each module is the ability to include user related information or skip it, as you will need that information later.<br />
<br />
'''Tip''': If the module already existed before Moodle 2.0, it can be a '''good idea''' to look at its 1.9 backuplib.php file, since the structure is already defined there and can help to understand the organization better and, at the same time, '''keeping the XML structure as similar as possible''', that will, definitively, '''make things easier''' when converting 1.9 backup files to the new backup 2.0 format.<br />
<br />
'''Note''': It's important to highlight that the structure schema, should be as stable as possible moving forward, because any change in the structure makes restore much more complex to implement. There aren't problems with adding/deleting fields, nor adding new elements to the structure. '''The structure (tree) itself must persist as stable as possible''', so be careful when deciding it, as it will have implications on future maintenance.<br />
<br />
Applying these pre-requisites to our candidate module (choice), here it's the corresponding schema. We'll use it along the whole process.<br />
<br />
=== Schema ===<br />
<br />
In the schema, you must try to put as much information as possible, so that will produce the coding process later to be quicker and easier while keeping the final results free from errors and missing bits. So, once more, don't start coding immediately, instead spend some time with the requisites above, understanding how the module works and designing the final structure that represents it better.<br />
<br />
==== The (correct) candidate ====<br />
<br />
[[Image:Backup20 choice alt.png|left|Alternative choice backup structure]]<br />
<br />
The tree on the left shows the ER/DB structure of the choice module, where one choice have one or more options and each option is answered by users one or more times (note: ignore cardinality accuracy in the previous phrase).<br />
<br />
And that's the best schema representing the structure of the module, with each element properly nested so, we won't have any problem with restore since the order required by restore (1, 2, 3) are naturally given. <br />
<br />
Looks easy, cool, but continue reading… you will get surprised! :-)<br style="clear: both" /><br />
<br />
==== The (chosen) candidate ====<br />
<br />
Instead we are going to use the (complete this time) diagram below. See the rationale about that after the image.<br />
<br />
[[Image:Backup20 choice.png|center|Used choice backup structure]]<br />
<br />
The main reason to use this tree (instead of the "correct" one) is that this is the structure that has been used by Moodle 1.9 backup since ages ago for the choice module and, of course have done its work ok. As commented above we must '''try to reduce the number of structural changes''' in one module backup in order to keep the restore operations working along the time (the same is applicable for the conversion of 1.9 backup files to the new 2.0 format). Finally, this is a good example about how one module '''can have different XML representations''' and we need to try to get that best one (this is not the case) on each case. So, once more, '''spending some time analyzing''' the activity is worth it.<br />
<br />
Let's analyze the schema with some detail:<br />
<br />
* '''Detecting user information''': We must be able to define the entities (tables) in the diagram that are used to store user information. One of the core features of the backup subsystem since its early days have been the ability to produce backup with and without user information. So we need that info. Hence, the "no user info" in the choice and choice_options elements (they are configuration, user-independent), while the choice_answers is marked as "user info" (contains user's answers to the choice).<br />
<br />
* '''Determining the correct order of backup''': This, while simple, is critical too (especially from a restore perspective). Since the restore reads progressively the xml file and performs actions in that order, we '''must guarantee that the "read order" is the correct''' one, fulfilling any possible dependency. Back to our schema it's clear that we need to backup the "choice" element at first, and then the "choice_options" and "choice_answers" ones. Moreover, the "choice_options" must be backup before "choice_answers", since the later needs to save the values of the former (the "optionid" information). Note that, as commented some paragraphs above, the "correct" alternative really gave us that order information easily. Doesn't matter, since we have been able to establish it also in the "chosen" schema.<br />
<br />
* '''Attributes and elements''': Now it's time to decide which fields will be considered attributes in the resulting XML file and which ones will be child elements (tags). The rule is simple: '''All the "id" fields must (should) be defined as attributes'''. Note this is just one arbitrary rule without much rationale behind it since, from a restore perspective, everything (attributes and child tags) will be handled in the same way (object attributes). So, in our schema, all the "id" fields have been marked as "attr".<br />
<br />
* '''Not needed elements''': If we have designed the schema properly, we'll find that some fields aren't necessary, since such information is already included in some parent element. In our schema, the field "choiceid", pointing to the "choice->id", both in the options and in the answer elements, have been marked as "not needed" since their parent "choice" already contains it. Something similar happens with the "course" field in the choice element. It doesn't need to be included in the backup file since something above it (course element, outside the module scope) already has it defined. Finally, there is one element marked as "needed" that shows us, once more, that the schema we are using is not the best. Since "choice_answers" isn't nested under "choice_options", we must keep the "choice_answers->optionid" field in the backup, or restore won't know to which option each answer belongs to. Instead, with the "correct" schema, where answers are nested under options, that field is not needed. Summarizing, '''any field except those already existing in parent elements must be included in backup'''.<br />
<br />
* '''Detecting file areas used by the module''': Along the module we can be using various file areas in different elements and fields. We need to know exactly which file area is handled by which element and the (optional) itemid information used for that file area. In general, '''anything being one text field, or anything looking like one attachment''' has high chances to have one (hidden) file area associated. In our schema, we have one file area (choice_intro) corresponding to the introduction of the module and available to put any images or whatever in that field. Also, in general, all the "xxx_intro" file areas use to have no itemid, since the module's context is enough to define them without ambiguities. So, we mark the choice->intro as "choice_intro" file area and "no itemid"). From our expertise playing with the module we know there are no more file areas associated with this module.<br />
<br />
* <span id="annotate_is_important">'''Annotating some important bits''':</span> Due to the modularity of the backup and in order to know exactly which information must be saved (because it's used) and which one can be skipped, '''it's important to annotate some important elements along the whole backup''' process. So, back to our schema, we have marked the "choice_answer->userid" field as "annotation" (so backup will, automatically, add all the information for that user). Here it's the list of elements that we must not forget to annotate (or we could end with non-restorable backups). Note that we must, always, be annotating "id" values and not other types of data:<br />
** '''user''': Any field pointing to one user->id present along the schema (as said above, our schema has one).<br />
** '''grouping''': Any field pointing to one grouping->id<br />
** '''group''': Any field pointing to one group->id<br />
** '''role''': Any field pointing to one role->id<br />
** '''scale''': Any field pointing to one scale->id<br />
** '''outcome''': Any field pointing to one outcome->id<br />
<br />
And this is all the information we need to know, before starting to code. Surely, once used to backup and restore, you will be able to start coding sooner, but '''don't forget about the importance of choosing one good and stable structure''' before anything else. It's really the critical part of any module's backup.<br />
<br />
That said, let's see how to code all this information in order to get one cool backup for our beloved module.<br />
<br />
=== Coding ===<br />
<br />
Already here? Have you read, at least once, all the explanations and comments in the previous sections? Yes? Sure? I can imagine it's hard to read so much text, just imagine how hard is to write it! Go, go, go and read it!<br />
<br />
Jokes aside, in this section we are going to code the module's (choice, in our example) backup code. As you'll see soon, all the information gathered in previous steps is really important and will make the coding task easier and less prone to errors.<br />
<br />
==== Setting up the environment ====<br />
<br />
By default, any backup operation will end with one .zip file stored in some course / section / activity area. That means that, each time you execute one backup, you'll need to go across the web interface to that file area, download the generated .zip file, uncompress it, and then see how things have been generated. And you will be executing a bunch of backup files until you get everything working as expected, so the whole develop / test process isn't really "agile". To improve things a bit, there is one $CFG setting that you should consider using '''in your development environment'''. Just put this in your config.php:<br />
<br />
<code php><br />
$CFG->keeptempdirectoriesonbackup = true;<br />
</code><br />
<br />
With this setting enabled, backup won't delete the temporary directory where everything is calculated, so you will be able to access to it directly, skipping all the ui / download / unzip steps above. Those temp directories are under $CFG->dataroot/temp/backup. Note that, for each backup invocation, a new directory is created.<br />
<br />
Also, in order to be able to execute backups quickly (instead of navigating along the UI), you can, simply, put one script like this in your $CFG->dirroot directory:<br />
<br />
<code php><br />
<?php<br />
<br />
define('CLI_SCRIPT', 1);<br />
require_once('config.php');<br />
require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');<br />
<br />
$course_module_to_backup = XX; // Set this to one existing choice cmid in your dev site<br />
$user_doing_the_backup = YY; // Set this to the id of your admin accouun<br />
<br />
$bc = new backup_controller(backup::TYPE_1ACTIVITY, $course_module_to_backup, backup::FORMAT_MOODLE,<br />
backup::INTERACTIVE_NO, backup::MODE_GENERAL, $user_doing_the_backup);<br />
$bc->execute_plan();<br />
</code><br />
<br />
just set proper values for XX and YY above and execute it from the command line. If you get one error about one not found class (with the name of your module) everything is ok.<br />
<br />
==== Required stuff ====<br />
<br />
The first thing you need to make is to, explicitly, declare that your module (choice in our example) is going to support the MOODLE2 backup format, to do so, you need to go to mod/choice/lib.php and, in the choice_supports() function add one new feature by adding this line:<br />
<br />
<code php><br />
case FEATURE_BACKUP_MOODLE2: return true;<br />
</code><br />
<br />
If you execute another backup (with the script provided above, you will continue getting one error, since we haven't still coded anything related to backup, that's ok.<br />
<br />
Next step is to create the directory where all the backup code for the choice module will be. Just create the directory(s) mod/choice/backup/moodle2<br />
<br />
At this point, we have all the required stuff ready and all the pending tasks will be done under that recently created directory.<br />
<br />
==== Settings, Steps and Tasks ====<br />
<br />
In the introduction of the tutorial, we commented about backup being structured into tasks, each one being one collection of steps (and potentially using some custom settings). Those are, exactly, the objects that we need to create to achieve the backup functionality in our module.<br />
<br />
First of all, lets' create the settings file, where all the custom settings to be used by our module will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_settingslib.php''' and their contents are really meaningful:<br />
<br />
<code php><br />
<?php<br />
<br />
// This file is part of Moodle - http://moodle.org/<br />
//<br />
// Moodle is free software: you can redistribute it and/or modify<br />
// it under the terms of the GNU General Public License as published by<br />
// the Free Software Foundation, either version 3 of the License, or<br />
// (at your option) any later version.<br />
//<br />
// Moodle is distributed in the hope that it will be useful,<br />
// but WITHOUT ANY WARRANTY; without even the implied warranty of<br />
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br />
// GNU General Public License for more details.<br />
//<br />
// You should have received a copy of the GNU General Public License<br />
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.<br />
<br />
/**<br />
* @package moodlecore<br />
* @subpackage backup-moodle2<br />
* @copyright 2010 onwards YOUR_NAME_GOES_HERE {@link YOUR_URL_GOES_HERE}<br />
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later<br />
*/<br />
<br />
// This activity has not particular settings but the inherited from the generic<br />
// backup_activity_task so here there isn't any class definition, like the ones<br />
// existing in /backup/moodle2/backup_settingslib.php (activities section)<br />
</code><br />
<br />
Looks simple, isn't it? Nothing but a few comments. This is looking really easy. For now, we aren't going to introduce any custom setting for any module, only the "core activity settings" will be used. Once backup and Moodle 2.0 is stable we can start analyzing useful settings to customize how the module's backup is performed. For now, just leave it blank, please. In fact, if it's empty,''' you can safely not create it''' at all. It's here just for explanation purposes.<br />
<br />
Side note: To save some space, we only will be showing the © message/license in the code above. Just add it to each file created.<br />
<br />
Now we are going to create the steps file, where all the steps to be executed by our backup activity task will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' and their contents are these:<br />
<br />
<code php><br />
<?php<br />
<br />
/**<br />
* Define all the backup steps that will be used by the backup_choice_activity_task<br />
*/<br />
</code><br />
<br />
Yes, it's another empty file. No worries we'll fill it later.<br />
<br />
Finally we need to create the task file, where our just created settings and steps files will be included and used. It must be named '''mod/choice/backup/moodle2/backup_choice_activity_task.class.php''' and their contents are these:<br />
<br />
<code php><br />
<?php<br />
<br />
require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_stepslib.php'); // Because it exists (must)<br />
require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_settingslib.php'); // Because it exists (optional)<br />
<br />
/**<br />
* choice backup task that provides all the settings and steps to perform one<br />
* complete backup of the activity<br />
*/<br />
class backup_choice_activity_task extends backup_activity_task {<br />
<br />
/**<br />
* Define (add) particular settings this activity can have<br />
*/<br />
protected function define_my_settings() {<br />
// No particular settings for this activity<br />
}<br />
<br />
/**<br />
* Define (add) particular steps this activity can have<br />
*/<br />
protected function define_my_steps() {<br />
// Choice only has one structure step<br />
}<br />
<br />
/**<br />
* Code the transformations to perform in the activity in<br />
* order to get transportable (encoded) links<br />
*/<br />
static public function encode_content_links($content) {<br />
return $content;<br />
}<br />
}<br />
</code><br />
<br />
This is the main file (class) of the choice backup and it will be used to define any setting (define_my_settings() method) and any step (define_my_steps() method) to be executed in the backup process. It also contains one 3rd method (encode_content_links($content)) that will allow manually URLs pointing to the choice to be properly converted when the choice is moved to other site / course using the backup / restore functionality.<br />
<br />
As you see, for now, the three required methods are doing nothing. Just execute the backup again. Wow, no errors anymore. We have already fulfilled all the minimum coding needs in order to have the choice backup working. <br />
<br />
Now you should go to your $CFG->dataroot/temp/backup/xxxx directory (the more recent) and spend some time looking what has been created under the activities/choice_XX directory. There is already a lot of stuff that backup has generated for you: comments, blocks, logs, grades, module info, roles... some of them empty and others already showing real information.<br />
<br />
In any case, now, we need to add one important file there, the "choice.xml" where the real information for your module will be present, following the specs given by the schema we decided some sections above.<br />
<br />
So, let's go, it's time to create our choice structure step. To do so, we edit the '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' file and add this code after the existing comments:<br />
<br />
<code php><br />
/**<br />
* Define the complete choice structure for backup, with file and id annotations<br />
*/ <br />
class backup_choice_activity_structure_step extends backup_activity_structure_step {<br />
<br />
protected function define_structure() {<br />
<br />
// To know if we are including userinfo<br />
$userinfo = $this->get_setting_value('userinfo');<br />
<br />
// Define each element separated<br />
<br />
// Build the tree<br />
<br />
// Define sources<br />
<br />
// Define id annotations<br />
<br />
// Define file annotations<br />
<br />
// Return the root element (choice), wrapped into standard activity structure<br />
<br />
}<br />
}<br />
</code><br />
<br />
So, we have defined one structure step that will be the responsible, using one PHP API to provide backup with all the information needed to generate the choice.xml file. Now, go back to the task file and add these contents in the define_my_steps() methods:<br />
<br />
<code php><br />
$this->add_step(new backup_choice_activity_structure_step('choice_structure', 'choice.xml'));<br />
</code><br />
<br />
That way, our choice task knows it must execute one new step, the one involving the generation of the choice.xml file. Let's execute one new backup and see results.You should be getting one new error with something like that "backup_structure_step_wrong_structure". It means that everything is ok up to now, the task has tried to execute the structure step, but this is not properly defined.<br />
<br />
===== Defining each element =====<br />
<br />
So, next step is about to define the choice structure. Going back to our step, under the ''// Define each element separate'' comment we'll add this code:<br />
<br />
<code php><br />
$choice = new backup_nested_element('choice', array('id'), array(<br />
'name', 'intro', 'introformat', 'publish',<br />
'showresults', 'display', 'allowupdate', 'allowunanswered',<br />
'limitanswers', 'timeopen', 'timeclose', 'timemodified'));<br />
<br />
$options = new backup_nested_element('options');<br />
<br />
$option = new backup_nested_element('option', array('id'), array(<br />
'text', 'maxanswers', 'timemodified'));<br />
<br />
$answers = new backup_nested_element('answers');<br />
<br />
$answer = new backup_nested_element('answer', array('id'), array(<br />
'userid', 'optionid', 'timemodified'));<br />
</code><br />
<br />
===== Return the root element =====<br />
<br />
And also, in order to get it working, let's define the return element, so, after the ''// Return the root element'' comment, add this code:<br />
<br />
<code php><br />
return $this->prepare_activity_structure($choice);<br />
</code><br />
<br />
Now we can execute the backup again and, as long as we have already defined the root element of the module, should have now one choice.xml file created (without proper contents but must be there).<br />
<br />
About the code above, all we have done is to define, separately each element that will be part of the choice.xml file. Special note about the $options and $answers elements. Since Moodle 1.9 we use to enclose real elements (the singular ones) inside one extra plural element, hence we create them here (as empty elements without attributes nor child tags). About the rest (the singular ones) we use 3 params in the instantiation:<br />
* The name of the element<br />
* One array of attributes of the element<br />
* One array of child tags (fields) of the element.<br />
And we include all the fields that previously we had defined in our schema '''but''' the ones marked as '''not needed'''.<br />
<br />
===== Building the tree =====<br />
<br />
Now it's time to declare the relations between all those elements, so, after the ''// Build the tree'' comment we'll add this code:<br />
<br />
<code php><br />
$choice->add_child($options);<br />
$options->add_child($option);<br />
<br />
$choice->add_child($answers);<br />
$answers->add_child($answer);<br />
</code><br />
<br />
Self explanatory, using $choice as root element, we define the whole tree using the add_child() method. And, of course, we respect '''the order''' that we had decided, so $options will be '''physically''' before $answers in the tree (and in the generated XML).<br />
<br />
===== Defining the sources =====<br />
<br />
After this, it's the moment to instruct our tree about how to fetch information from DB in order to generate the choice.xml file, so after the ''// Define sources'' comment, we'll add this code:<br />
<br />
<code php><br />
$choice->set_source_table('choice', array('id' => backup::VAR_ACTIVITYID));<br />
<br />
$option->set_source_sql('<br />
SELECT *<br />
FROM {choice_options}<br />
WHERE choiceid = ?',<br />
array(backup::VAR_PARENTID));<br />
<br />
// All the rest of elements only happen if we are including user info<br />
if ($userinfo) {<br />
$answer->set_source_table('choice_answers', array('choiceid' => '../../id'));<br />
}<br />
</code><br />
<br />
So we define the source for the $choice element as the information present in the 'choice' table for the id that is being backup (backup::VAR_ACTIVITYID). Or we define the source for the $option element like one SQL (could have been one table too, just to show more possibilities of the API, using the parent (the choice one) as value for the query (backup::VAR_PARENTID).<br />
<br />
And finally, conditionally, if user information is going to be included, we define the source for the $answer (note we had already annotated in our schema that this element was dependent of that). <br />
<br />
And we define the source condition as having the 'choiceid' field matching the value of the 'id' field two levels above (../../id). If you follow the tree created in the previous code section, that's exactly the choice->id (remember we have introduced one extra level (the plural one between the 'choice' and the 'answer' singular elements). Note this is 100% equivalent to use backup::VAR_PARENTID (as we have done in the $option source) just used to show possibilities of the API.<br />
<br />
Summarizing, with the API, we have these 3 method for defining sources:<br />
<br />
* '''set_source_table($tablename, array $conditions)''': When the information is get straight from one table (vast majority of cases in backup)<br />
* '''set_source_sql($sql, array $params)''': When the information doesn't map one table directly and we need something more complex<br />
* '''set_source_array($array)''': When we have some fixed information to backup. Not really useful in nested information, but used by core here and there.<br />
<br />
Note that both the $conditions and $params above only accept one limited number of constants or values (not all available in all backups!), mainly:<br />
<br />
* '''backup::VAR_COURSEID''': The id of the course this activity belongs to / the course id being backup<br />
* '''backup::VAR_SECTIONID''': The id of the section this activity belongs to / the section id being backup<br />
* '''backup::VAR_ACTIVITYID''': The id of the activity id being backup<br />
* '''backup::VAR_MODID''': The id of the course_module being backup<br />
* '''backup::VAR_MODULENAME''': The name of the module being backup<br />
* '''backup::VAR_BLOCKID''': The id of the block being backup<br />
* '''backup::VAR_BLOCKNAME''': The name of the block being backup<br />
* '''backup::VAR_CONTEXTID''': The context id of the activity / course being backup<br />
* '''backup::VAR_PARENTID''': The value of the first parent id found in the structure.<br />
* '''../some/path/to/parent''': To manually point to other value of any parent.<br />
<br />
Is important to note that, in 99% of the case we should be using, exclusively, some of the constants above, and backup, automatically will handle them properly. In case we have any other condition or param to be added like, for example, the number 23, or the string 'user', we cannot add them directly, but enclose them with the helper '''backup_helper::is_sqlparam(23)''' or '''backup_helper::is_sqlparam('user')'''. That way backup will know they are raw SQL params not needing any special handling, like the constants above.<br />
<br />
Well, now it's time to run backup again and take a look to our activities/choice_XX/choice.xml file. Now everything should be there, properly nested, the choice, the options and the answers. We are really near finishing now.<br />
<br />
===== Annotating IDs =====<br />
<br />
Now it's time to perform all the annotations that we had already detected in our analysis of the module. So, after the ''// Define id annotations'' comment we'll be adding:<br />
<br />
<code php><br />
$answer->annotate_ids('user', 'userid');<br />
</code><br />
<br />
It simply means, annotate for each $answer element, the value of the 'userid' field as one 'user' to be backup. In other words we are instructing backup that there is one new user to include later, when generating the users information and, at the same time, we are determining that those users are needed for the choice XX, so, if on restore we decide to skip that choice and such user isn't necessary for any other module / subsystem, it won't be restored. All this "uses" information is handled by the "inforef.xml" files within each activity backup, just in case you're interested to take a look to them. Else, just consider them, "dark magic".<br />
<br />
'''Note''': If you're not sure about which elements must be annotated, review [[Backup 2.0 for developers #annotate_is_important|"Annotating some important bits"]] above for details about '''must-be-done''' annotations.<br />
<br />
===== Annotating files =====<br />
<br />
And, finally, reviewing our elaborate and detailed schema, the last thing we need to take care of are the file areas used, so, after the ''// Define file annotations'' comment we'll add:<br />
<br />
<code php><br />
$choice->annotate_files('mod_choice', 'intro', null, $contextid = null); // This file area does not have an itemid.<br />
</code><br />
<br />
That means that, within the $choice element we have one file area in use, of course belonging to the 'mod_choice' component (where all the choice module files belong to), named 'intro' and not using itemid (null). Note that, since it is possible to have multiple file areas in the same element (table), you may end up having multiple calls to the annotate_files() method, one for each filearea to be added to backup. The third parameter, if it is needed, must be the name of one of the attributes or fields of the $choice element (usually, in the vast majority of cases, the 'id' of the element), otherwise we'll use null. The fourth parameter is optional and will default to the context id of the backup, but if you want to specify the context id you do so here.<br />
<br />
=== One encoded wor(l)d ===<br />
<br />
Already out from the step definition, that should be working ok now, with the choice.xml file being generated and all the annotations being processed and added to the inforef.xml file, there is one more point to fulfill before considering choice's backup 100% finished.<br />
<br />
And it's about how to provide the ability to transform some links to the choice module when the backup file is restored into another server / course. That is automatically handled by a two-step approach:<br />
# On backup, we transform as many well-know URLs as possible to one encoded form.<br />
# On restore, we transform those encoded URLS back to their original form, but pointing to their new targets.<br />
<br />
So, in backup, we must provide services for the point 1 above, and that is done by adding some "encoding" conversions to the '''encode_content_links()''' method in our '''backup_choice_activity_task'''. So, define it to look like this<br />
<br />
<code php><br />
/**<br />
* Code the transformations to perform in the activity in<br />
* order to get transportable (encoded) links<br />
*/<br />
static public function encode_content_links($content) {<br />
global $CFG;<br />
<br />
$base = preg_quote($CFG->wwwroot,"/");<br />
<br />
// Link to the list of choices<br />
$search="/(".$base."\/mod\/choice\/index.php\?id\=)([0-9]+)/";<br />
$content= preg_replace($search, '$@CHOICEINDEX*$2@$', $content);<br />
<br />
// Link to choice view by moduleid<br />
$search="/(".$base."\/mod\/choice\/view.php\?id\=)([0-9]+)/";<br />
$content= preg_replace($search, '$@CHOICEVIEWBYID*$2@$', $content);<br />
<br />
return $content;<br />
}<br />
</code><br />
<br />
Básically, it gets any URL (manually written) in any content of the backup being generated and transform some (well-known) URLs to one encoded alternative. In this case we are encoding:<br />
* Any URL pointing to the list of choices in a course == is changed to ==> $@CHOICEINDEX*XX@$<br />
* Any URL pointing to one exact choice == is changed to ==> $@CHOICEVIEWBYID*YY@$<br />
<br />
In restore, well have the opposite conversions happening, replacing the XX and YY above to their new equivalents, so those links will be transportable via backup/restore without any need to edit them manually later.<br />
<br />
Tip: Don't forget to look to the module's 1.9 backup code, as far as there you'll find which conversions must be considered to be added here.<br />
<br />
=== Final notes ===<br />
<br />
* Don't get stressed, it's really more difficult / longer to explain than to do it. 100% guaranteed, else we'll return your money. :-P<br />
* If you've become lost, or your code is not working properly, you always can [https://github.com/moodle/moodle/tree/master/mod/choice/backup/moodle2 see the complete choice working code in git]. Or, alternatively, look to other well known modules, like [https://github.com/moodle/moodle/blob/master/mod/forum/backup/moodle2/ forum] or also the [https://github.com/moodle/moodle/blob/master/backup/moodle2/backup_stepslib.php big core library of steps], where you will find all sort of uses of the API.<br />
* If you are going to implement backup for module XXXX, just copy this document, replace any "choice" occurrence within it by XXXX and follow it from the beginning to the end. Should work.<br />
* If the module already existed in Moodle 1.x, try to follow the same structure if possible, that will make things easier for restore / conversion.<br />
* Right now there are some pending tasks related with different exceptions that will be thrown if you code something wrongly (bad nesting, incorrect field names, bad constant/sql param uses...) and how they are shown. Fix for that will be coming soon.<br />
* Also, as stated at the beginning of this tutorial, we are still missing "subplugins" final support in modules, so try to avoid implementing backup on them for now. Once ready, there will be one new section in this document about them.<br />
* Any question / improvement / comment, feel free to contact with Moodle HQ, better if using the Tracker or, alternatively, forums / email / direct contact with your very-best-developer-friend. Note this is version x.0 (dot zero) of the backup API, so sure there are possibilities to improve it along the time.<br />
<br />
== Other components that can be backed up ==<br />
<br />
Most plugins which can be added to a course can also include data in a course backup. Some examples:<br />
<br />
* Course formats<br />
* Themes: [[ Backup 2.0 theme data| Backup 2.0 theme data]]<br />
* Plagiarism plugins</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=49403
Projects for new developers
2016-02-03T10:43:16Z
<p>Markn: /* Ability to crop/resize/rotate an image in atto */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Ability to crop/resize/rotate an image in atto ===<br />
<br />
Moodle comes with it's own HTML editor known as 'atto' (see https://docs.moodle.org/dev/Atto). The editor functions similarly to other editors out there, like TinyMCE, but is tailored to Moodle. It comes with multiple plugins that allow users to perform tasks, such as changing the font size, the alignment, adding links etc. One of these plugins allows the user to add an image to the text editor with the ability to specify the size and alignment of the image via text input. The idea of this project is to extend and improve this current plugin so the user can crop/resize/rotate the image via JS - making the whole experience easier and more aesthetically pleasing.<br />
<br />
This project details/discussion can be located at MDL-52982.<br />
<br />
:'''Skills required''': Javascript (YUI), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/view.php?id=1057750 Mark Nelson]<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Create a desktop version of Moodle Mobile using Electron ===<br />
<br />
[http://electron.atom.io/ Electron] is a tool for creating cross platform desktop applications using web technologies.<br />
<br />
[https://github.com/moodlehq/moodlemobile/ Moodle Mobile 1] (the previous version of Moodle Mobile) had an experimental desktop application using a similar tool ([http://nwjs.io/ Node-Webkit, now NW.js]), for Moodle Mobile 2 we’d like to see the application packaged for desktop using Electron.<br />
<br />
In this project you will implement some of the Cordova APIs to use the Node.js API provided by electron:<br />
* FileSystem API - For browsing the local file system<br />
* FileTransfer API - For downloads and uploads<br />
* Camera and capture API - For taking photos, videos and audios using the webcam<br />
<br />
Notice that these APIs are already implemented in the previous version of Moodle Mobile 1, this project is about migrating this old APIs from Node-Webkit to the new version of the application using Electron.<br />
<br />
:'''Skills required: Javascript (Node.js)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Generator of Moodle plugins scaffold code ===<br />
<br />
There are many [[Plugin types|plugin types]] in Moodle. There are [[Plugin files|files]] and code patterns that all plugins have in common. Also there are specific interfaces that individual plugin types are expected to implement. When developing a new plugin, Moodle contributors use some available templates for various plugin types as well as existing plugins as a reference.<br />
<br />
The goal of this project is to develop a tool that helps Moodle contributors to generate a scaffold code for a new Moodle plugin. Given parameters such as plugin type, plugin name, list of enabled/disabled features and other meta-data (such as author name etc), the tool should generate a scaffold code for that plugin that the developer can build on.<br />
<br />
Deliverables:<br />
* Research and analysis of existing tools and approaches used in other software projects.<br />
* Specification of the format/syntax of templates that will be used to generate the plugin code (consider Mustache as it is templating language that Moodle developers are most familiar with).<br />
* Templates for all Moodle plugin types and specification of their storage, organisation and maintenance (so that it is possible to keep them up to date in further Moodle versions).<br />
* Software tool that makes use of these templates and actually generates the plugin scaffold code.<br />
<br />
Requirements:<br />
* The generated code should pass 100% of the Moodle codechecking tools to ensure it meets with Moodle Guidelines.<br />
* The generator itself should be written in either PHP or JavaScript (Node.js) and provide both CLI and GUI.<br />
<br />
:'''Skills required:''' PHP / Node.js, experience with Moodle plugins development is a big plus.<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=1601&course=5 David Mudrák]<br />
<br />
=== Add search to more moodle components ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. There are some module components, like glossary or databases that can use the search engine to index their data on it, so moodle users with permissions can access them quickly. This project would be about implementing the search API in some moodle components, the number of components can vary depending on the time available, but ideally this should land into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
=== Elastic search ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. The only search engine that will be initially supported will be solr, as elasticsearch has a good use base would be nice to write a search_elastic plugin implementing moodle's search engine API. This does not necessarily need to go into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=49402
Projects for new developers
2016-02-03T10:41:28Z
<p>Markn: /* Ability to crop/resize/rotate an image in atto */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Ability to crop/resize/rotate an image in atto ===<br />
<br />
Moodle comes with it's own HTML editor known as 'atto'. The editor functions similarly to other editors out there, like TinyMCE, but is tailored to Moodle. It comes with multiple plugins that allow users to perform tasks, such as changing the font size, the alignment, adding links etc. One of these plugins allows the user to add an image to the text editor with the ability to specify the size and alignment of the image via text input. The idea of this project is to extend and improve this current plugin so the user can crop/resize/rotate the image via JS - making the whole experience easier and more aesthetically pleasing.<br />
<br />
This project details/discussion can be located at MDL-52982.<br />
<br />
:'''Skills required''': Javascript (YUI), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/view.php?id=1057750 Mark Nelson]<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Create a desktop version of Moodle Mobile using Electron ===<br />
<br />
[http://electron.atom.io/ Electron] is a tool for creating cross platform desktop applications using web technologies.<br />
<br />
[https://github.com/moodlehq/moodlemobile/ Moodle Mobile 1] (the previous version of Moodle Mobile) had an experimental desktop application using a similar tool ([http://nwjs.io/ Node-Webkit, now NW.js]), for Moodle Mobile 2 we’d like to see the application packaged for desktop using Electron.<br />
<br />
In this project you will implement some of the Cordova APIs to use the Node.js API provided by electron:<br />
* FileSystem API - For browsing the local file system<br />
* FileTransfer API - For downloads and uploads<br />
* Camera and capture API - For taking photos, videos and audios using the webcam<br />
<br />
Notice that these APIs are already implemented in the previous version of Moodle Mobile 1, this project is about migrating this old APIs from Node-Webkit to the new version of the application using Electron.<br />
<br />
:'''Skills required: Javascript (Node.js)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Generator of Moodle plugins scaffold code ===<br />
<br />
There are many [[Plugin types|plugin types]] in Moodle. There are [[Plugin files|files]] and code patterns that all plugins have in common. Also there are specific interfaces that individual plugin types are expected to implement. When developing a new plugin, Moodle contributors use some available templates for various plugin types as well as existing plugins as a reference.<br />
<br />
The goal of this project is to develop a tool that helps Moodle contributors to generate a scaffold code for a new Moodle plugin. Given parameters such as plugin type, plugin name, list of enabled/disabled features and other meta-data (such as author name etc), the tool should generate a scaffold code for that plugin that the developer can build on.<br />
<br />
Deliverables:<br />
* Research and analysis of existing tools and approaches used in other software projects.<br />
* Specification of the format/syntax of templates that will be used to generate the plugin code (consider Mustache as it is templating language that Moodle developers are most familiar with).<br />
* Templates for all Moodle plugin types and specification of their storage, organisation and maintenance (so that it is possible to keep them up to date in further Moodle versions).<br />
* Software tool that makes use of these templates and actually generates the plugin scaffold code.<br />
<br />
Requirements:<br />
* The generated code should pass 100% of the Moodle codechecking tools to ensure it meets with Moodle Guidelines.<br />
* The generator itself should be written in either PHP or JavaScript (Node.js) and provide both CLI and GUI.<br />
<br />
:'''Skills required:''' PHP / Node.js, experience with Moodle plugins development is a big plus.<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=1601&course=5 David Mudrák]<br />
<br />
=== Add search to more moodle components ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. There are some module components, like glossary or databases that can use the search engine to index their data on it, so moodle users with permissions can access them quickly. This project would be about implementing the search API in some moodle components, the number of components can vary depending on the time available, but ideally this should land into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
=== Elastic search ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. The only search engine that will be initially supported will be solr, as elasticsearch has a good use base would be nice to write a search_elastic plugin implementing moodle's search engine API. This does not necessarily need to go into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=49401
Projects for new developers
2016-02-03T10:39:28Z
<p>Markn: /* Ability to crop/resize/rotate an image in atto */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Ability to crop/resize/rotate an image in atto ===<br />
<br />
Moodle comes with it's own default editor known as 'atto'. The editor functions similarly to other editors out there, like TinyMCE, but is tailored to Moodle. It comes with multiple plugins that allow users to perform tasks, such as changing the font size, the alignment, adding links etc. One of these plugins allows the user to add an image to the text editor with the ability to specify the size and alignment of the image via text input. The idea of this project is to extend and improve this current plugin so the user can crop/resize/rotate the image via JS - making the whole experience easier and more aesthetically pleasing.<br />
<br />
This project details/discussion can be located at MDL-52982.<br />
<br />
:'''Skills required''': Javascript (YUI), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/view.php?id=1057750 Mark Nelson]<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Create a desktop version of Moodle Mobile using Electron ===<br />
<br />
[http://electron.atom.io/ Electron] is a tool for creating cross platform desktop applications using web technologies.<br />
<br />
[https://github.com/moodlehq/moodlemobile/ Moodle Mobile 1] (the previous version of Moodle Mobile) had an experimental desktop application using a similar tool ([http://nwjs.io/ Node-Webkit, now NW.js]), for Moodle Mobile 2 we’d like to see the application packaged for desktop using Electron.<br />
<br />
In this project you will implement some of the Cordova APIs to use the Node.js API provided by electron:<br />
* FileSystem API - For browsing the local file system<br />
* FileTransfer API - For downloads and uploads<br />
* Camera and capture API - For taking photos, videos and audios using the webcam<br />
<br />
Notice that these APIs are already implemented in the previous version of Moodle Mobile 1, this project is about migrating this old APIs from Node-Webkit to the new version of the application using Electron.<br />
<br />
:'''Skills required: Javascript (Node.js)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Generator of Moodle plugins scaffold code ===<br />
<br />
There are many [[Plugin types|plugin types]] in Moodle. There are [[Plugin files|files]] and code patterns that all plugins have in common. Also there are specific interfaces that individual plugin types are expected to implement. When developing a new plugin, Moodle contributors use some available templates for various plugin types as well as existing plugins as a reference.<br />
<br />
The goal of this project is to develop a tool that helps Moodle contributors to generate a scaffold code for a new Moodle plugin. Given parameters such as plugin type, plugin name, list of enabled/disabled features and other meta-data (such as author name etc), the tool should generate a scaffold code for that plugin that the developer can build on.<br />
<br />
Deliverables:<br />
* Research and analysis of existing tools and approaches used in other software projects.<br />
* Specification of the format/syntax of templates that will be used to generate the plugin code (consider Mustache as it is templating language that Moodle developers are most familiar with).<br />
* Templates for all Moodle plugin types and specification of their storage, organisation and maintenance (so that it is possible to keep them up to date in further Moodle versions).<br />
* Software tool that makes use of these templates and actually generates the plugin scaffold code.<br />
<br />
Requirements:<br />
* The generated code should pass 100% of the Moodle codechecking tools to ensure it meets with Moodle Guidelines.<br />
* The generator itself should be written in either PHP or JavaScript (Node.js) and provide both CLI and GUI.<br />
<br />
:'''Skills required:''' PHP / Node.js, experience with Moodle plugins development is a big plus.<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=1601&course=5 David Mudrák]<br />
<br />
=== Add search to more moodle components ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. There are some module components, like glossary or databases that can use the search engine to index their data on it, so moodle users with permissions can access them quickly. This project would be about implementing the search API in some moodle components, the number of components can vary depending on the time available, but ideally this should land into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
=== Elastic search ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. The only search engine that will be initially supported will be solr, as elasticsearch has a good use base would be nice to write a search_elastic plugin implementing moodle's search engine API. This does not necessarily need to go into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=49400
Projects for new developers
2016-02-03T10:29:37Z
<p>Markn: /* Allow to crop/resize/rotate images when inserting them */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Ability to crop/resize/rotate an image in atto ===<br />
<br />
This project details are located at MDL-52982.<br />
<br />
:'''Skills required''': Javascript (YUI), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/view.php?id=1057750 Mark Nelson]<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Create a desktop version of Moodle Mobile using Electron ===<br />
<br />
[http://electron.atom.io/ Electron] is a tool for creating cross platform desktop applications using web technologies.<br />
<br />
[https://github.com/moodlehq/moodlemobile/ Moodle Mobile 1] (the previous version of Moodle Mobile) had an experimental desktop application using a similar tool ([http://nwjs.io/ Node-Webkit, now NW.js]), for Moodle Mobile 2 we’d like to see the application packaged for desktop using Electron.<br />
<br />
In this project you will implement some of the Cordova APIs to use the Node.js API provided by electron:<br />
* FileSystem API - For browsing the local file system<br />
* FileTransfer API - For downloads and uploads<br />
* Camera and capture API - For taking photos, videos and audios using the webcam<br />
<br />
Notice that these APIs are already implemented in the previous version of Moodle Mobile 1, this project is about migrating this old APIs from Node-Webkit to the new version of the application using Electron.<br />
<br />
:'''Skills required: Javascript (Node.js)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Generator of Moodle plugins scaffold code ===<br />
<br />
There are many [[Plugin types|plugin types]] in Moodle. There are [[Plugin files|files]] and code patterns that all plugins have in common. Also there are specific interfaces that individual plugin types are expected to implement. When developing a new plugin, Moodle contributors use some available templates for various plugin types as well as existing plugins as a reference.<br />
<br />
The goal of this project is to develop a tool that helps Moodle contributors to generate a scaffold code for a new Moodle plugin. Given parameters such as plugin type, plugin name, list of enabled/disabled features and other meta-data (such as author name etc), the tool should generate a scaffold code for that plugin that the developer can build on.<br />
<br />
Deliverables:<br />
* Research and analysis of existing tools and approaches used in other software projects.<br />
* Specification of the format/syntax of templates that will be used to generate the plugin code (consider Mustache as it is templating language that Moodle developers are most familiar with).<br />
* Templates for all Moodle plugin types and specification of their storage, organisation and maintenance (so that it is possible to keep them up to date in further Moodle versions).<br />
* Software tool that makes use of these templates and actually generates the plugin scaffold code.<br />
<br />
Requirements:<br />
* The generated code should pass 100% of the Moodle codechecking tools to ensure it meets with Moodle Guidelines.<br />
* The generator itself should be written in either PHP or JavaScript (Node.js) and provide both CLI and GUI.<br />
<br />
:'''Skills required:''' PHP / Node.js, experience with Moodle plugins development is a big plus.<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=1601&course=5 David Mudrák]<br />
<br />
=== Add search to more moodle components ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. There are some module components, like glossary or databases that can use the search engine to index their data on it, so moodle users with permissions can access them quickly. This project would be about implementing the search API in some moodle components, the number of components can vary depending on the time available, but ideally this should land into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
=== Elastic search ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. The only search engine that will be initially supported will be solr, as elasticsearch has a good use base would be nice to write a search_elastic plugin implementing moodle's search engine API. This does not necessarily need to go into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=49399
Projects for new developers
2016-02-03T10:25:08Z
<p>Markn: /* Allow to crop/resize/rotate images when inserting them */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Allow to crop/resize/rotate images when inserting them ===<br />
<br />
This project is inspired by MDL-52982 - the ability to alter an image via JS in atto.<br />
<br />
:'''Skills required''': Javascript (YUI), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/view.php?id=1057750 Mark Nelson]<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Create a desktop version of Moodle Mobile using Electron ===<br />
<br />
[http://electron.atom.io/ Electron] is a tool for creating cross platform desktop applications using web technologies.<br />
<br />
[https://github.com/moodlehq/moodlemobile/ Moodle Mobile 1] (the previous version of Moodle Mobile) had an experimental desktop application using a similar tool ([http://nwjs.io/ Node-Webkit, now NW.js]), for Moodle Mobile 2 we’d like to see the application packaged for desktop using Electron.<br />
<br />
In this project you will implement some of the Cordova APIs to use the Node.js API provided by electron:<br />
* FileSystem API - For browsing the local file system<br />
* FileTransfer API - For downloads and uploads<br />
* Camera and capture API - For taking photos, videos and audios using the webcam<br />
<br />
Notice that these APIs are already implemented in the previous version of Moodle Mobile 1, this project is about migrating this old APIs from Node-Webkit to the new version of the application using Electron.<br />
<br />
:'''Skills required: Javascript (Node.js)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Generator of Moodle plugins scaffold code ===<br />
<br />
There are many [[Plugin types|plugin types]] in Moodle. There are [[Plugin files|files]] and code patterns that all plugins have in common. Also there are specific interfaces that individual plugin types are expected to implement. When developing a new plugin, Moodle contributors use some available templates for various plugin types as well as existing plugins as a reference.<br />
<br />
The goal of this project is to develop a tool that helps Moodle contributors to generate a scaffold code for a new Moodle plugin. Given parameters such as plugin type, plugin name, list of enabled/disabled features and other meta-data (such as author name etc), the tool should generate a scaffold code for that plugin that the developer can build on.<br />
<br />
Deliverables:<br />
* Research and analysis of existing tools and approaches used in other software projects.<br />
* Specification of the format/syntax of templates that will be used to generate the plugin code (consider Mustache as it is templating language that Moodle developers are most familiar with).<br />
* Templates for all Moodle plugin types and specification of their storage, organisation and maintenance (so that it is possible to keep them up to date in further Moodle versions).<br />
* Software tool that makes use of these templates and actually generates the plugin scaffold code.<br />
<br />
Requirements:<br />
* The generated code should pass 100% of the Moodle codechecking tools to ensure it meets with Moodle Guidelines.<br />
* The generator itself should be written in either PHP or JavaScript (Node.js) and provide both CLI and GUI.<br />
<br />
:'''Skills required:''' PHP / Node.js, experience with Moodle plugins development is a big plus.<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=1601&course=5 David Mudrák]<br />
<br />
=== Add search to more moodle components ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. There are some module components, like glossary or databases that can use the search engine to index their data on it, so moodle users with permissions can access them quickly. This project would be about implementing the search API in some moodle components, the number of components can vary depending on the time available, but ideally this should land into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
=== Elastic search ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. The only search engine that will be initially supported will be solr, as elasticsearch has a good use base would be nice to write a search_elastic plugin implementing moodle's search engine API. This does not necessarily need to go into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn
https://docs.moodle.org/dev/index.php?title=Projects_for_new_developers&diff=49398
Projects for new developers
2016-02-03T10:22:11Z
<p>Markn: /* Allow to crop/resize/rotate images when inserting them */</p>
<hr />
<div>{{GSOC}}<br />
<br />
==Getting started==<br />
<br />
Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.<br />
<br />
When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.<br />
<br />
''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].<br />
<br />
''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].<br />
<br />
''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].<br />
<br />
As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].<br />
<br />
==Potential projects==<br />
<br />
This evolving page lists possible Moodle projects for new developers derived from community suggestions.<br />
<br />
''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''<br />
<br />
=== Allow to crop/resize/rotate images when inserting them ===<br />
<br />
This project is inspired by MDL-52982 - the ability to alter an image via JS in atto.<br />
<br />
:'''Skills required''': Javascript (YUI), PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''':<br />
<br />
=== Improve Behat tests in SCORM plugin ===<br />
The Moodle SCORM plugin does not contain very many behat tests and most tests are manual. The Claude Ostyn diagnostic SCO should be used to implement a range of new Behat tests to cover the functionality that the SCORM module provides.<br />
<br />
Deliverables:<br />
* Behat tests for all existing SCORM QA tests (where possible)<br />
* Behat tests for all SCORM settings (eg standards mode, mastery score settings etc) <br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Advanced Grading in Forums ===<br />
Finish the work required to add the advanced grading feature to the Moodle forum activity. This builds on some existing work available at MDL-31860<br />
<br />
Deliverables:<br />
* Modify the forum grading so that it pushes 2 grade areas (or 3 including ratings) into the gradebook instead of a single grade.<br />
* Improve interface that allows overall forum participation grading.<br />
* Behat tests for all new functionality.<br />
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.<br />
<br />
Extra requirement for prospective students:<br />
* We require prospective students to make an attempt at fixing at least 1 issue in the Moodle tracker before their proposal can be considered - on top of this you must also attempt to convert one existing QA test into a Behat test. This MUST be completed before your application can be considered valid. If you do not have time to do this before the submission deadline your application will not be considered.<br />
<br />
:'''Skills required''': PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]<br />
<br />
=== Add support to end-to-end testing in the Mobile app ===<br />
<br />
[https://angular.github.io/protractor/#/ Protractor] is an end-to-end test framework for AngularJS applications. Protractor runs tests against your application running in a real browser, interacting with it as a user would.<br />
<br />
The basements for this project are done, see MOBILE-1179, the only remaining work is to add more tests to the app and document the set-up process in the Moodle developers wiki.<br />
<br />
:'''Skills required: Javascript (AngularJS)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Create a desktop version of Moodle Mobile using Electron ===<br />
<br />
[http://electron.atom.io/ Electron] is a tool for creating cross platform desktop applications using web technologies.<br />
<br />
[https://github.com/moodlehq/moodlemobile/ Moodle Mobile 1] (the previous version of Moodle Mobile) had an experimental desktop application using a similar tool ([http://nwjs.io/ Node-Webkit, now NW.js]), for Moodle Mobile 2 we’d like to see the application packaged for desktop using Electron.<br />
<br />
In this project you will implement some of the Cordova APIs to use the Node.js API provided by electron:<br />
* FileSystem API - For browsing the local file system<br />
* FileTransfer API - For downloads and uploads<br />
* Camera and capture API - For taking photos, videos and audios using the webcam<br />
<br />
Notice that these APIs are already implemented in the previous version of Moodle Mobile 1, this project is about migrating this old APIs from Node-Webkit to the new version of the application using Electron.<br />
<br />
:'''Skills required: Javascript (Node.js)<br />
:'''Difficulty level: Medium<br />
:'''Possible mentor: [https://moodle.org/user/profile.php?id=49568 Juan Leyva]<br />
<br />
=== Generator of Moodle plugins scaffold code ===<br />
<br />
There are many [[Plugin types|plugin types]] in Moodle. There are [[Plugin files|files]] and code patterns that all plugins have in common. Also there are specific interfaces that individual plugin types are expected to implement. When developing a new plugin, Moodle contributors use some available templates for various plugin types as well as existing plugins as a reference.<br />
<br />
The goal of this project is to develop a tool that helps Moodle contributors to generate a scaffold code for a new Moodle plugin. Given parameters such as plugin type, plugin name, list of enabled/disabled features and other meta-data (such as author name etc), the tool should generate a scaffold code for that plugin that the developer can build on.<br />
<br />
Deliverables:<br />
* Research and analysis of existing tools and approaches used in other software projects.<br />
* Specification of the format/syntax of templates that will be used to generate the plugin code (consider Mustache as it is templating language that Moodle developers are most familiar with).<br />
* Templates for all Moodle plugin types and specification of their storage, organisation and maintenance (so that it is possible to keep them up to date in further Moodle versions).<br />
* Software tool that makes use of these templates and actually generates the plugin scaffold code.<br />
<br />
Requirements:<br />
* The generated code should pass 100% of the Moodle codechecking tools to ensure it meets with Moodle Guidelines.<br />
* The generator itself should be written in either PHP or JavaScript (Node.js) and provide both CLI and GUI.<br />
<br />
:'''Skills required:''' PHP / Node.js, experience with Moodle plugins development is a big plus.<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [http://moodle.org/user/view.php?id=1601&course=5 David Mudrák]<br />
<br />
=== Add search to more moodle components ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. There are some module components, like glossary or databases that can use the search engine to index their data on it, so moodle users with permissions can access them quickly. This project would be about implementing the search API in some moodle components, the number of components can vary depending on the time available, but ideally this should land into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
=== Elastic search ===<br />
<br />
MDL-31989 is introducing global search to Moodle to index moodle data in an external source and to retrieve data back from that external source. The only search engine that will be initially supported will be solr, as elasticsearch has a good use base would be nice to write a search_elastic plugin implementing moodle's search engine API. This does not necessarily need to go into core.<br />
<br />
:'''Skills required:''' PHP<br />
:'''Difficulty level''': Medium<br />
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=122326 David Monllao]<br />
<br />
==See also==<br />
<br />
* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program<br />
* [https://tracker.moodle.org/issues/?jql=type%20in%20%28%22New%20Feature%22%2C%20Improvement%29%20AND%20resolution%20%3D%20unresolved%20and%20labels%20in%20%28addon_candidate%29%20ORDER%20BY%20votes%20DESC Popular new feature and improvement requests in Tracker that can be implemented as plugins]<br />
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects<br />
* [https://docs.moodle.org/dev/Moodle_Wishlist a Wishlist] by some Moodle users. Some of the good ideas here may be adopted.</div>
Markn