MoodleDocs - User contributions [en]

User:Neill Magill

2022-01-25T08:45:18Z

Nmagill: Created page with "I have been working with Moodle since 2.2 when the University of Nottingham adopted it as their main VLE. I have several patches that have made their way into Moodle core (mo..."

I have been working with Moodle since 2.2 when the University of Nottingham adopted it as their main VLE.

I have several patches that have made their way into Moodle core (mostly related to improving performance) and look after numerous plugins that have been developed for the University.

Activity completion API

2022-01-24T14:38:13Z

Nmagill: /* Add information about the completion settings to the activities cm_info object */

{{Moodle_2.0}}
{{Note|There are changes to the completion API introduced in '''Moodle 3.11''' to be incorporated to this page. Please refer to [[Student activity completion]] for details.}}
Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

If you make no changes to a module whatsoever, it can only support 'manual' completion (where the user ticks a box).
== Feature support ==
To support the completion system, your module must include a ''modulename''<tt>_supports</tt> function in its <tt>lib.php</tt>. Here is an example:
/**
* Indicates API features that the forum supports.
*
* @param string $feature
* @return mixed True if yes (some features may use other values)
*/
function forum_supports($feature) {
switch($feature) {
case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
case FEATURE_COMPLETION_HAS_RULES: return true;
default: return null;
}
}
The relevant features for completion are:
* '''FEATURE_COMPLETION_TRACKS_VIEWS''' - the module can support completion 'on view', meaning that an activity becomes marked complete as soon as a user clicks on it.

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

* '''FEATURE_COMPLETION_HAS_RULES''' - the module has custom completion rules.
== Completion on view ==
Completion on view means that, if selected, an activity is marked complete as soon as the user views it. 'View' is usually defined as seeing the module's main page; if you click on the activity, and there isn't an error, you have probably viewed it. However it is up to each module precisely how they define 'view'.
=== How to implement ===
In your module's ''modulename''<tt>_supports</tt> function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity. In order for navigation to work as expected (i.e. so that the navigation block on the module's page takes account that you have viewed this activity, if there is another activity that depends on it) you should put this code before printing the page header.
$completion = new completion_info($course);
$completion->set_module_viewed($cm);
=== Performance issues ===
Calling this method has no significant performance cost if 'on view' completion is not enabled for the activity. If it is enabled, then the performance cost is kept low because the 'viewed' state is cached; it doesn't add a database query to every request.
== Completion on grade ==
Completion on grade means that, if selected, an activity is marked complete as soon as the user receives a grade from that activity.
=== How to implement ===
In your module's _supports function, return true for FEATURE_GRADE_HAS_GRADE. No other action is necessary.
=== Performance issues ===
When 'on grade' completion is enabled, there will be some additional database queries after a grade is assigned or changed. Unless your activity changes grades very frequently, this is unlikely to be an issue.
== Custom completion rules ==
Custom completion rules allow for module-specific conditions. For example, the forum has custom rules so that you can make it mark a user completed when they make a certain number of posts to the forum.

It is a lot harder to implement custom completion rules than it is to use the system-provided 'view' or 'grade' conditions, but the instructions below should help make it clear.
=== Implementation overview ===
To implement custom completion rules, you need to:
# Return true for FEATURE_COMPLETION_HAS_RULES in your module's _supports function.
# Add database fields to your module's main table to store the custom completion settings.
# Add backup and restore code to back up these fields.
# Add information about the completion settings to the activities cm_info object
# Add controls to your module's settings form so that users can select the custom rules, altering these database settings.
# Add a function that checks the value of these rules (if set).
# Add function returns descriptions for the completion states
# Add code so that whenever the value affecting a rule might change, you inform the completion system.
=== Database fields for completion settings ===
When you provide a custom completion rule for a module, that rule requires data to be stored with each module instance: whether the rule is enabled for that instance, and any options that apply to the rule.

Usually the best place to store this information is your module's main table because:
* The information in the relevant row of this table is likely to be available in most parts of your code, so code changes are minimised.
* You already read this row with most requests, so there is no need for additional database queries which would reduce performance.
* The main table is used for most other module options so it is a logical place for this information.
If you are adding a basic completion condition you probably only need to add one field. To add a field to an existing module, you need to change the db/install.xml and the db/upgrade.php in the same way as adding any other field.
==== Example ====
Throughout this section I am using the forum as an example. The forum provides three completion options but because they all behave the same way, I am only showing one of them.

The forum adds this field to store a completion option:
* '''completionposts''' - this may be 0 or an integer. If it's an integer, say 3, then the user needs to add 3 forum posts (either new discussions or replies) in order for the forum to count as 'completed'.
=== Backup and restore for completion fields ===
Modules do not need to back up the generic completion options, which are handled by the system, but they do need to back up any custom options. You should add backup and restore logic for the fields mentioned above.

Remember that your restore code should handle the case when these fields are not present, setting the fields to a suitable default value.
==== Example ====
The following code in <tt>backup_forum_stepslib.php</tt> lists the fields to back up:
$forum = new backup_nested_element('forum', array('id'), array(
'type', 'name', 'intro', 'introformat',
'assessed', 'assesstimestart', 'assesstimefinish', 'scale',
'maxbytes', 'maxattachments', 'forcesubscribe', 'trackingtype',
'rsstype', 'rssarticles', 'timemodified', 'warnafter',
'blockafter', 'blockperiod', 'completiondiscussions', 'completionreplies',
'completionposts'));
As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.
=== Add information about the completion settings to the activities cm_info object ===
{{Moodle 3.3}}You will need to add information about the custom rules into the activities cm_info object by either adding, or modifying the module_get_coursemodule_info callback<syntaxhighlight lang="php">
/**
* Add a get_coursemodule_info function in case any forum type wants to add 'extra' information
* for the course (see resource).
*
* Given a course_module object, this function returns any "extra" information that may be needed
* when printing this activity in a course listing. See get_array_of_activities() in course/lib.php.
*
* @param stdClass $coursemodule The coursemodule object (record).
* @return cached_cm_info An object on information that the courses
* will know about (most noticeably, an icon).
*/
function forum_get_coursemodule_info($coursemodule) {
global $DB;

$dbparams = ['id' => $coursemodule->instance];
$fields = 'id, name, intro, introformat, completionposts, completiondiscussions, completionreplies, duedate, cutoffdate';
if (!$forum = $DB->get_record('forum', $dbparams, $fields)) {
return false;
}

$result = new cached_cm_info();
$result->name = $forum->name;

if ($coursemodule->showdescription) {
// Convert intro to html. Do not filter cached version, filters run at display time.
$result->content = format_module_intro('forum', $forum, $coursemodule->id, false);
}

// Populate the custom completion rules as key => value pairs, but only if the completion mode is 'automatic'.
if ($coursemodule->completion == COMPLETION_TRACKING_AUTOMATIC) {
$result->customdata['customcompletionrules']['completiondiscussions'] = $forum->completiondiscussions;
$result->customdata['customcompletionrules']['completionreplies'] = $forum->completionreplies;
$result->customdata['customcompletionrules']['completionposts'] = $forum->completionposts;
}

// Populate some other values that can be used in calendar or on dashboard.
if ($forum->duedate) {
$result->customdata['duedate'] = $forum->duedate;
}
if ($forum->cutoffdate) {
$result->customdata['cutoffdate'] = $forum->cutoffdate;
}

return $result;
}
</syntaxhighlight>
=== Form changes for completion settings ===
When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.
* Implement the <tt>add_completion_rules</tt> function which adds the form controls for your new rules.

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

* Implement other form changes if necessary to set up the form with your data. If your data is in the form of simple text boxes or dropdowns then this is not necessary, but you might want to have a checkbox that enables the rule with a separate control to set its value. This needs form tweaks.
==== Example ====
The forum offers a checkbox with a text input box beside it. You tick the checkbox to enable the rule, then type in the desired number of posts.

First, the function that adds these controls:
<syntaxhighlight lang="php">
/**
* Add elements for setting the custom completion rules.
*
* @category completion
* @return array List of added element names, or names of wrapping group elements.
*/
public function add_completion_rules() {

$mform = $this->_form;

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

return ['completionpostsgroup'];
}
</syntaxhighlight>
* The function creates a checkbox and a text input field, which is set to accept only numbers.
* These are grouped together so they appear on the same line, and we add a help button.
* The text input field is disabled if the checkbox isn't ticked.
* Note that this function must return the top-level element associated with the completion rule. (If there are multiple elements, you can return more than one.)
** This is used so that your controls become disabled if automatic completion is not selected.
Next, a function for checking whether the user selected this option:
<syntaxhighlight lang="php">
/**
* Called during validation to see whether some module-specific completion rules are selected.
*
* @param array $data Input data not yet validated.
* @return bool True if one or more rules is enabled, false if none are.
*/
public function completion_rule_enabled($data) {
return (!empty($data['completionpostsenabled']) && $data['completionposts'] != 0);
}
</syntaxhighlight>
* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.
** This is used to give an error if the user selects automatic completion, but fails to select any conditions.
That's all the 'required' functions, but we need to add some extra code to support the checkbox behaviour. I overrode get_data so that if there is a value in the edit field, but the checkbox is not ticked, the value counts as zero (the rule will not be enabled).
function get_data() {
$data = parent::get_data();
if (!$data) {
return $data;
}
if (!empty($data->completionunlocked)) {
// Turn off completion settings if the checkboxes aren't ticked
$autocompletion = !empty($data->completion) && $data->completion==COMPLETION_TRACKING_AUTOMATIC;
if (empty($data->completionpostsenabled) || !$autocompletion) {
$data->completionposts = 0;
}
}
return $data;
}

You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <syntaxhighlight lang="php">$data</syntaxhighlight> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.
Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:
function data_preprocessing(&$default_values){
// [Existing code, not shown]

// Set up the completion checkboxes which aren't part of standard data.
// We also make the default value (if you turn on the checkbox) for those
// numbers to be 1, this will not apply unless checkbox is ticked.
$default_values['completionpostsenabled']=
!empty($default_values['completionposts']) ? 1 : 0;
if(empty($default_values['completionposts'])) {
$default_values['completionposts']=1;
}
}
Phew! That's the form done.
=== Completion state function ===
When you create completion conditions, you need to write a function ''module''<tt>_get_completion_state</tt> that checks the value of those conditions for a particular user.

The function receives as parameters <tt>$course</tt>, <tt>$cm</tt>, and <tt>$userid</tt> - all self-explanatory, I hope - and <tt>$type</tt>. This has two values:
* '''COMPLETION_AND''' - if multiple conditions are selected, the user must meet all of them.
* '''COMPLETION_OR''' (not currently used) - if multiple conditions are selected, any one of them is good enough to complete the activity.
Your function should return:
* '''true''' if your custom completion options are enabled and the user meets the conditions.
* '''false''' if your custom completion options are enabled but the user does not yet meet the conditions.
* <tt>$type</tt> (not false!) if none of your custom completion options are not enabled.
==== Example ====
Here's the function for forum (simplified to include only the one completion option):
<syntaxhighlight lang="php">
/**
* Obtains the automatic completion state for this forum based on any conditions
* in forum settings.
*
* @param object $course Course
* @param object $cm Course-module
* @param int $userid User ID
* @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
* @return bool True if completed, false if not, $type if conditions not set.
*/
function forum_get_completion_state($course,$cm,$userid,$type) {
global $CFG,$DB;

// Get forum details
$forum = $DB->get_record('forum', array('id' => $cm->instance), '*', MUST_EXIST);

// If completion option is enabled, evaluate it and return true/false
if($forum->completionposts) {
return $forum->completionposts <= $DB->get_field_sql("
SELECT
COUNT(1)
FROM
{forum_posts} fp
INNER JOIN {forum_discussions} fd ON fp.discussion=fd.id
WHERE
fp.userid=:userid AND fd.forum=:forumid",
array('userid'=>$userid,'forumid'=>$forum->id));
} else {
// Completion option is not enabled so just return $type
return $type;
}
}
</syntaxhighlight>
=== Add function returns descriptions for the completion states ===
{{Moodle 3.3}}When you create completion conditions, you need to write a function ''module''<tt>_get_completion_active_rule_descriptions</tt> that gives a human readable description of the completion state.

The input for the method is the cm_info object for that activity.

You need to return an array of strings for each completion rule that is active.<syntaxhighlight lang="php">
/**
* Callback which returns human-readable strings describing the active completion custom rules for the module instance.
*
* @param cm_info|stdClass $cm object with fields ->completion and ->customdata['customcompletionrules']
* @return array $descriptions the array of descriptions for the custom rules.
*/
function mod_forum_get_completion_active_rule_descriptions($cm) {
// Values will be present in cm_info, and we assume these are up to date.
if (empty($cm->customdata['customcompletionrules'])
|| $cm->completion != COMPLETION_TRACKING_AUTOMATIC) {
return [];
}

$descriptions = [];
foreach ($cm->customdata['customcompletionrules'] as $key => $val) {
switch ($key) {
case 'completiondiscussions':
if (!empty($val)) {
$descriptions[] = get_string('completiondiscussionsdesc', 'forum', $val);
}
break;
case 'completionreplies':
if (!empty($val)) {
$descriptions[] = get_string('completionrepliesdesc', 'forum', $val);
}
break;
case 'completionposts':
if (!empty($val)) {
$descriptions[] = get_string('completionpostsdesc', 'forum', $val);
}
break;
default:
break;
}
}
return $descriptions;
}
</syntaxhighlight>
=== Notifying the completion system ===
Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.
* To ensure performance is not compromised, you should notify the system only when the completion state might actually have changed. Don't notify the system unless your custom completion rule is actually enabled.
* You need to pass in the 'possible result' of the change. This is used to significantly improve performance. There are three values:
**'''COMPLETION_COMPLETE''' - this change will either have no effect on the user's completion state, or it will make it complete. The change cannot make a user's state ''in''complete if it was complete previously. In the forum example, when you add a post, there is no way this can make the user's state incomplete, so this possible result applies.
** '''COMPLETION_INCOMPLETE''' - this change will either have no effect on the user's completion state, or it will make it incomplete. The change cannot make a user's state complete if it was incomplete previously. Deleting a forum post would fall into this category.
** '''COMPLETION_UNKNOWN''' - this change might have either effect. Using this option is much slower than the others, so try to avoid using it in anything that might happen frequently.
* If the user whose completion state would be updated is not the current user, then the optional <tt>$userid</tt> parameter must be included. For example, if a teacher deletes a student's forum post, then it is the student's completion state which may need updating, not the teacher's.
==== Example ====
Here's the code that runs when somebody makes a new forum post:
// Update completion state
$completion=new completion_info($course);
if($completion->is_enabled($cm) && $forum->completionposts) {
$completion->update_state($cm,COMPLETION_COMPLETE);
}
=== Completion Checks in Cron Tasks ===
If you need to check completion as part of a cron task or another part of Moodle that does not already include the completion_info class, you will need to include it.
==== Example ====
require_once($CFG->dirroot.'/lib/completionlib.php');
== See Also ==
[[Conditional activities|Activity completion and availability]] - Original Specification

[[Course completion]] - Original Specification

[[Policy - Retroactive effects of completion settings]]

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

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

[https://docs.moodle.org/en/Course_completion Course Completion]
[[Category:Conditional activities]]
[[Category:API]]

Activity completion API

2022-01-24T14:27:57Z

Nmagill: /* Custom completion rules */ Added in documentation on Moodle 3.3 changes to the API

{{Moodle_2.0}}
{{Note|There are changes to the completion API introduced in '''Moodle 3.11''' to be incorporated to this page. Please refer to [[Student activity completion]] for details.}}
Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

If you make no changes to a module whatsoever, it can only support 'manual' completion (where the user ticks a box).
== Feature support ==
To support the completion system, your module must include a ''modulename''<tt>_supports</tt> function in its <tt>lib.php</tt>. Here is an example:
/**
* Indicates API features that the forum supports.
*
* @param string $feature
* @return mixed True if yes (some features may use other values)
*/
function forum_supports($feature) {
switch($feature) {
case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
case FEATURE_COMPLETION_HAS_RULES: return true;
default: return null;
}
}
The relevant features for completion are:
* '''FEATURE_COMPLETION_TRACKS_VIEWS''' - the module can support completion 'on view', meaning that an activity becomes marked complete as soon as a user clicks on it.

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

* '''FEATURE_COMPLETION_HAS_RULES''' - the module has custom completion rules.
== Completion on view ==
Completion on view means that, if selected, an activity is marked complete as soon as the user views it. 'View' is usually defined as seeing the module's main page; if you click on the activity, and there isn't an error, you have probably viewed it. However it is up to each module precisely how they define 'view'.
=== How to implement ===
In your module's ''modulename''<tt>_supports</tt> function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity. In order for navigation to work as expected (i.e. so that the navigation block on the module's page takes account that you have viewed this activity, if there is another activity that depends on it) you should put this code before printing the page header.
$completion = new completion_info($course);
$completion->set_module_viewed($cm);
=== Performance issues ===
Calling this method has no significant performance cost if 'on view' completion is not enabled for the activity. If it is enabled, then the performance cost is kept low because the 'viewed' state is cached; it doesn't add a database query to every request.
== Completion on grade ==
Completion on grade means that, if selected, an activity is marked complete as soon as the user receives a grade from that activity.
=== How to implement ===
In your module's _supports function, return true for FEATURE_GRADE_HAS_GRADE. No other action is necessary.
=== Performance issues ===
When 'on grade' completion is enabled, there will be some additional database queries after a grade is assigned or changed. Unless your activity changes grades very frequently, this is unlikely to be an issue.
== Custom completion rules ==
Custom completion rules allow for module-specific conditions. For example, the forum has custom rules so that you can make it mark a user completed when they make a certain number of posts to the forum.

It is a lot harder to implement custom completion rules than it is to use the system-provided 'view' or 'grade' conditions, but the instructions below should help make it clear.
=== Implementation overview ===
To implement custom completion rules, you need to:
# Return true for FEATURE_COMPLETION_HAS_RULES in your module's _supports function.
# Add database fields to your module's main table to store the custom completion settings.
# Add backup and restore code to back up these fields.
# Add information about the completion settings to the activities cm_info object
# Add controls to your module's settings form so that users can select the custom rules, altering these database settings.
# Add a function that checks the value of these rules (if set).
# Add function returns descriptions for the completion states
# Add code so that whenever the value affecting a rule might change, you inform the completion system.
=== Database fields for completion settings ===
When you provide a custom completion rule for a module, that rule requires data to be stored with each module instance: whether the rule is enabled for that instance, and any options that apply to the rule.

Usually the best place to store this information is your module's main table because:
* The information in the relevant row of this table is likely to be available in most parts of your code, so code changes are minimised.
* You already read this row with most requests, so there is no need for additional database queries which would reduce performance.
* The main table is used for most other module options so it is a logical place for this information.
If you are adding a basic completion condition you probably only need to add one field. To add a field to an existing module, you need to change the db/install.xml and the db/upgrade.php in the same way as adding any other field.
==== Example ====
Throughout this section I am using the forum as an example. The forum provides three completion options but because they all behave the same way, I am only showing one of them.

The forum adds this field to store a completion option:
* '''completionposts''' - this may be 0 or an integer. If it's an integer, say 3, then the user needs to add 3 forum posts (either new discussions or replies) in order for the forum to count as 'completed'.
=== Backup and restore for completion fields ===
Modules do not need to back up the generic completion options, which are handled by the system, but they do need to back up any custom options. You should add backup and restore logic for the fields mentioned above.

Remember that your restore code should handle the case when these fields are not present, setting the fields to a suitable default value.
==== Example ====
The following code in <tt>backup_forum_stepslib.php</tt> lists the fields to back up:
$forum = new backup_nested_element('forum', array('id'), array(
'type', 'name', 'intro', 'introformat',
'assessed', 'assesstimestart', 'assesstimefinish', 'scale',
'maxbytes', 'maxattachments', 'forcesubscribe', 'trackingtype',
'rsstype', 'rssarticles', 'timemodified', 'warnafter',
'blockafter', 'blockperiod', 'completiondiscussions', 'completionreplies',
'completionposts'));
As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.

=== Add information about the completion settings to the activities cm_info object ===
You will need to add information about the custom rules into the activities cm_info object by either adding, or modifying the module_get_coursemodule_info callback<syntaxhighlight lang="php">
/**
* Add a get_coursemodule_info function in case any forum type wants to add 'extra' information
* for the course (see resource).
*
* Given a course_module object, this function returns any "extra" information that may be needed
* when printing this activity in a course listing. See get_array_of_activities() in course/lib.php.
*
* @param stdClass $coursemodule The coursemodule object (record).
* @return cached_cm_info An object on information that the courses
* will know about (most noticeably, an icon).
*/
function forum_get_coursemodule_info($coursemodule) {
global $DB;

$dbparams = ['id' => $coursemodule->instance];
$fields = 'id, name, intro, introformat, completionposts, completiondiscussions, completionreplies, duedate, cutoffdate';
if (!$forum = $DB->get_record('forum', $dbparams, $fields)) {
return false;
}

$result = new cached_cm_info();
$result->name = $forum->name;

if ($coursemodule->showdescription) {
// Convert intro to html. Do not filter cached version, filters run at display time.
$result->content = format_module_intro('forum', $forum, $coursemodule->id, false);
}

// Populate the custom completion rules as key => value pairs, but only if the completion mode is 'automatic'.
if ($coursemodule->completion == COMPLETION_TRACKING_AUTOMATIC) {
$result->customdata['customcompletionrules']['completiondiscussions'] = $forum->completiondiscussions;
$result->customdata['customcompletionrules']['completionreplies'] = $forum->completionreplies;
$result->customdata['customcompletionrules']['completionposts'] = $forum->completionposts;
}

// Populate some other values that can be used in calendar or on dashboard.
if ($forum->duedate) {
$result->customdata['duedate'] = $forum->duedate;
}
if ($forum->cutoffdate) {
$result->customdata['cutoffdate'] = $forum->cutoffdate;
}

return $result;
}
</syntaxhighlight>

=== Form changes for completion settings ===
When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.
* Implement the <tt>add_completion_rules</tt> function which adds the form controls for your new rules.

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

* Implement other form changes if necessary to set up the form with your data. If your data is in the form of simple text boxes or dropdowns then this is not necessary, but you might want to have a checkbox that enables the rule with a separate control to set its value. This needs form tweaks.
==== Example ====
The forum offers a checkbox with a text input box beside it. You tick the checkbox to enable the rule, then type in the desired number of posts.

First, the function that adds these controls:
<syntaxhighlight lang="php">
/**
* Add elements for setting the custom completion rules.
*
* @category completion
* @return array List of added element names, or names of wrapping group elements.
*/
public function add_completion_rules() {

$mform = $this->_form;

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

return ['completionpostsgroup'];
}
</syntaxhighlight>
* The function creates a checkbox and a text input field, which is set to accept only numbers.
* These are grouped together so they appear on the same line, and we add a help button.
* The text input field is disabled if the checkbox isn't ticked.
* Note that this function must return the top-level element associated with the completion rule. (If there are multiple elements, you can return more than one.)
** This is used so that your controls become disabled if automatic completion is not selected.
Next, a function for checking whether the user selected this option:
<syntaxhighlight lang="php">
/**
* Called during validation to see whether some module-specific completion rules are selected.
*
* @param array $data Input data not yet validated.
* @return bool True if one or more rules is enabled, false if none are.
*/
public function completion_rule_enabled($data) {
return (!empty($data['completionpostsenabled']) && $data['completionposts'] != 0);
}
</syntaxhighlight>
* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.
** This is used to give an error if the user selects automatic completion, but fails to select any conditions.
That's all the 'required' functions, but we need to add some extra code to support the checkbox behaviour. I overrode get_data so that if there is a value in the edit field, but the checkbox is not ticked, the value counts as zero (the rule will not be enabled).
function get_data() {
$data = parent::get_data();
if (!$data) {
return $data;
}
if (!empty($data->completionunlocked)) {
// Turn off completion settings if the checkboxes aren't ticked
$autocompletion = !empty($data->completion) && $data->completion==COMPLETION_TRACKING_AUTOMATIC;
if (empty($data->completionpostsenabled) || !$autocompletion) {
$data->completionposts = 0;
}
}
return $data;
}

You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <syntaxhighlight lang="php">$data</syntaxhighlight> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.
Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:
function data_preprocessing(&$default_values){
// [Existing code, not shown]

// Set up the completion checkboxes which aren't part of standard data.
// We also make the default value (if you turn on the checkbox) for those
// numbers to be 1, this will not apply unless checkbox is ticked.
$default_values['completionpostsenabled']=
!empty($default_values['completionposts']) ? 1 : 0;
if(empty($default_values['completionposts'])) {
$default_values['completionposts']=1;
}
}
Phew! That's the form done.
=== Completion state function ===
When you create completion conditions, you need to write a function ''module''<tt>_get_completion_state</tt> that checks the value of those conditions for a particular user.

The function receives as parameters <tt>$course</tt>, <tt>$cm</tt>, and <tt>$userid</tt> - all self-explanatory, I hope - and <tt>$type</tt>. This has two values:
* '''COMPLETION_AND''' - if multiple conditions are selected, the user must meet all of them.
* '''COMPLETION_OR''' (not currently used) - if multiple conditions are selected, any one of them is good enough to complete the activity.
Your function should return:
* '''true''' if your custom completion options are enabled and the user meets the conditions.
* '''false''' if your custom completion options are enabled but the user does not yet meet the conditions.
* <tt>$type</tt> (not false!) if none of your custom completion options are not enabled.
==== Example ====
Here's the function for forum (simplified to include only the one completion option):
<syntaxhighlight lang="php">
/**
* Obtains the automatic completion state for this forum based on any conditions
* in forum settings.
*
* @param object $course Course
* @param object $cm Course-module
* @param int $userid User ID
* @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
* @return bool True if completed, false if not, $type if conditions not set.
*/
function forum_get_completion_state($course,$cm,$userid,$type) {
global $CFG,$DB;

// Get forum details
$forum = $DB->get_record('forum', array('id' => $cm->instance), '*', MUST_EXIST);

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

=== Add function returns descriptions for the completion states ===
When you create completion conditions, you need to write a function ''module''<tt>_get_completion_active_rule_descriptions</tt> that gives a human readable description of the completion state.

The input for the method is the cm_info object for that activity.

You need to return an array of strings for each completion rule that is active.<syntaxhighlight lang="php">
/**
* Callback which returns human-readable strings describing the active completion custom rules for the module instance.
*
* @param cm_info|stdClass $cm object with fields ->completion and ->customdata['customcompletionrules']
* @return array $descriptions the array of descriptions for the custom rules.
*/
function mod_forum_get_completion_active_rule_descriptions($cm) {
// Values will be present in cm_info, and we assume these are up to date.
if (empty($cm->customdata['customcompletionrules'])
|| $cm->completion != COMPLETION_TRACKING_AUTOMATIC) {
return [];
}

$descriptions = [];
foreach ($cm->customdata['customcompletionrules'] as $key => $val) {
switch ($key) {
case 'completiondiscussions':
if (!empty($val)) {
$descriptions[] = get_string('completiondiscussionsdesc', 'forum', $val);
}
break;
case 'completionreplies':
if (!empty($val)) {
$descriptions[] = get_string('completionrepliesdesc', 'forum', $val);
}
break;
case 'completionposts':
if (!empty($val)) {
$descriptions[] = get_string('completionpostsdesc', 'forum', $val);
}
break;
default:
break;
}
}
return $descriptions;
}
</syntaxhighlight>

=== Notifying the completion system ===
Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.
* To ensure performance is not compromised, you should notify the system only when the completion state might actually have changed. Don't notify the system unless your custom completion rule is actually enabled.
* You need to pass in the 'possible result' of the change. This is used to significantly improve performance. There are three values:
**'''COMPLETION_COMPLETE''' - this change will either have no effect on the user's completion state, or it will make it complete. The change cannot make a user's state ''in''complete if it was complete previously. In the forum example, when you add a post, there is no way this can make the user's state incomplete, so this possible result applies.
** '''COMPLETION_INCOMPLETE''' - this change will either have no effect on the user's completion state, or it will make it incomplete. The change cannot make a user's state complete if it was incomplete previously. Deleting a forum post would fall into this category.
** '''COMPLETION_UNKNOWN''' - this change might have either effect. Using this option is much slower than the others, so try to avoid using it in anything that might happen frequently.
* If the user whose completion state would be updated is not the current user, then the optional <tt>$userid</tt> parameter must be included. For example, if a teacher deletes a student's forum post, then it is the student's completion state which may need updating, not the teacher's.
==== Example ====
Here's the code that runs when somebody makes a new forum post:
// Update completion state
$completion=new completion_info($course);
if($completion->is_enabled($cm) && $forum->completionposts) {
$completion->update_state($cm,COMPLETION_COMPLETE);
}
=== Completion Checks in Cron Tasks ===
If you need to check completion as part of a cron task or another part of Moodle that does not already include the completion_info class, you will need to include it.
==== Example ====
require_once($CFG->dirroot.'/lib/completionlib.php');
== See Also ==
[[Conditional activities|Activity completion and availability]] - Original Specification

[[Course completion]] - Original Specification

[[Policy - Retroactive effects of completion settings]]

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

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

[https://docs.moodle.org/en/Course_completion Course Completion]
[[Category:Conditional activities]]
[[Category:API]]

Acceptance testing/Browsers

2021-03-19T13:17:03Z

Nmagill: /* Drivers */ Updated location of edge web driver

This page complements [[Acceptance testing]] providing info about how to run the acceptance tests suite in different browsers.

== Drivers ==

There are Selenium drivers (http://docs.seleniumhq.org/projects/webdriver/) to run acceptance tests in different browsers:

* Firefox - https://code.google.com/p/selenium/wiki/FirefoxDriver
* Chrome - https://code.google.com/p/selenium/wiki/ChromeDriver
* Safari - https://code.google.com/p/selenium/wiki/SafariDriver
* Internet Explorer - https://code.google.com/p/selenium/wiki/InternetExplorerDriver
* Microsoft Edge - https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/
* PhantomJS (Webkit) - http://phantomjs.org/
* IPhone - https://code.google.com/p/selenium/wiki/IPhoneDriver

Each driver should be downloaded and Selenium .jar should be started specifying the path to the driver; depending on the driver there could be other requirements.

=== PhantomJS ===

PhantomJS is different as it is a headless browser as it is quite faster than other drivers, it doesn't need a GUI to run and can execute JS, it doesn't even need to be used through Selenium (you can do it though, but it's not officially supported) and you can do it

* Download PhantomJS: http://phantomjs.org/download.html
* /path/to/your/phantomjs/bin/phantomjs --webdriver=4444

Note that 4444 is the default port used by Selenium so you must specify another one if you want to run them together and specify the port in $CFG->behat_config.

=== Examples ===

# Selenium in Linux (firefox by default + chrome)
java -jar /opt/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/opt/chromedriver

# Selenium in OSx (firefox & safari by default + chrome)
java -jar /Users/moodle/Downloads/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/Users/moodle/Downloads/chromedriver

# Selenium in Windows (started using git bash) (firefox by default + chrome + internet explorer)
java -jar /c/seleniumdrivers/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/c/seleniumdrivers/chromedriver.exe -Dwebdriver.ie.driver=/c/seleniumdrivers/IEDriverServer.exe

# PhantomJS
/path/to/your/phantomjs/bin/phantomjs --webdriver=4444

== Compatibility ==
Not all the drivers can execute all of Moodle's step definitions; we tagged the step definitions that are using features not supported by all browsers and also limitations that some browsers have; refer to the following table to know which browsers can run which tags:

{| class="wikitable"
|
|File uploads (@_file_upload)
|Browser dialogs (@_alert)
|Switch window (@_switch_window)
|Switch frame (@_switch_iframe)
|Bug in phantomjs (@_bug_phantomjs)
|-
|Firefox
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|-
|Chrome
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|-
|Internet Explorer
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:red">No</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|-
|Safari
|<span style="color:#0f0">Yes</span>
|<span style="color:red">No</span>
|<span style="color:red">No</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|-
|PhantomJS
|<span style="color:red">No</span>
|<span style="color:red">No</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:#0f0">Yes</span>
|<span style="color:red">No</span>
|}

== Working combinations of OS+Browser+selenium ==
As OS, Browsers and Selenium keeps updating, some combination of OS+Browser+Selenium will not work on specific moodle version.

We try to support the latest version of these combinations but they are not always BC and hence may not work with older releases. Please refer to [[Acceptance testing/Browsers/Working combinations of OS+Browser+selenium]] to ensure you have correct combination of them to run acceptance test.

[[Category:Quality Assurance]]

Moodle App Plugins Development Guide

2019-09-13T09:12:10Z

Nmagill: /* Before 3.5 */ Fix link

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle_Mobile_2_(Ionic_1)_Remote_add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to support plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
], // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: <nowiki>The language pack string ids used in the plugin by all the handlers. Normally these will be strings from your own plugin, however, you can list any strings you need here (e.g. ['cancel', 'moodle']). If you do this, be warned that in the app you will then need to refer to that string as {{ 'plugin.myplugin.cancel' | translate }} (not {{ 'plugin.moodle.cancel' | translate }})</nowiki>
: Please only include the strings you actually need. The Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform, and this will then be cached, so listing too many strings is very wasteful.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.
* '''moodlecomponent''' (optional): If your plugin supports a component in the app different than the one defined by your plugin, you can use this property to specify it. For example, you can create a local plugin to support a certain course format, activity, etc. The component of your plugin in Moodle would be ''local_whatever'', but in "moodlecomponent" you can specify that this handler will implement ''format_whatever'' or ''mod_whatever''. This property was introduced in the version 3.6.1 of the app.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreBlockDelegate===

* '''displaydata''' (optional): title, class. If ''title'' is not supplied, it will default to "plugins.block_blockname.pluginname", where ''blockname'' is the name of the block. If ''class'' is not supplied, it will default to "block_blockname", where ''blockname'' is the name of the block.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats. When you open a course from the course list in the mobile app, it will check if there is a CoreCourseFormatDelegate handler for the format that site uses. If so, it will display the course using that handler. Otherwise, it will use the default app course format. More information is available on [[Creating mobile course formats]].

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

====CoreBlockDelegate====

You must use this delegate to support a block. As of Moodle App 3.7.0, blocks are only displayed in Site Home and Dashboard, but they'll be supported in other places of the app soon (e.g. in the course page).

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please note that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

For a full list of components, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/components

For a full list of directives, go to https://github.com/moodlehq/moodlemobile2/tree/master/src/directives

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional, default false. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional, default false. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional, default "check". If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherData]="" is the same as not supplying it, so nothing will be copied.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty ('''null, false or empty string''') all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array. Please notice that [useOtherDataForWS]="" is the same as not supplying it, so nothing will be copied.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should throw an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

===Support push notification clicks===

If your plugin sends push notifications to the app, you might want to open a certain page in the app when the notification is clicked. There are several ways to achieve this.

The easiest way is to include a ''contexturl'' in your notification. When the notification is clicked, the app will try to open the ''contexturl''.

Please notice that the ''contexturl'' will also be displayed in web. If you want to use a specific URL for the app, different than the one displayed in web, you can do so by returning a ''customdata'' array that contains an ''appurl'' property:

<code php>
$notification->customdata = [
'appurl' => $myurl->out(),
];
</code>

In both cases you will have to create a link handler to treat the URL. For more info on how to create the link handler, please see [[Mobile_support_for_plugins#Advanced_link_handler|how to create an advanced link handler]].

If you want to do something that only happens when the notification is clicked, not when the link is clicked, you'll have to implement a push click handler yourself. The way to create it is similar to [[Mobile_support_for_plugins#Advanced_link_handler|creating an advanced link handler]], but you'll have to use ''CorePushNotificationsDelegate'' and your handler will have to implement the properties and functions defined in the interface [https://github.com/moodlehq/moodlemobile2/blob/master/src/core/pushnotifications/providers/delegate.ts#L24 CorePushNotificationsClickHandler].

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].
* ForumNG (unfinished support) [https://moodle.org/plugins/mod_forumng Moodle plugins directory entry] and [https://github.com/moodleou/moodle-mod_forumng in github].
* News block [https://github.com/moodleou/moodle-block_news in github].
* H5P activity module [https://moodle.org/plugins/mod_hvp Moodle plugins directory entry] and [https://github.com/h5p/h5p-moodle-plugin in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)
[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-03-18T16:12:35Z

Nmagill: /* Advanced features */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle Mobile Remote add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to suport plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
]. // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: The language pack string ids used in the plugin by all the handlers. Please note that you should avoid adding all the plugin string ids (including those unused) because the Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats.

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please notice that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional. If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

===Using strings with dates===

If you have a string that you wish to pass a formatted date for example in the Moodle language file you have:

<code php>
$string['strwithdate'] = 'This string includes a date of {$a->date} in the middle of it.';
</code>

You can localise the string correctly in your template using something like the following:

<code>
{{ 'plugin.mod_myactivity.strwithdate' | translate: {$a: { date: <% timestamp %> * 1000 | coreFormatDate: "dffulldate" } } }}
</code>

A Unix timestamp must be multiplied by 1000 as the Mobile App expects millisecond timestamps, where as Unix timestamps are in seconds.

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)
[[Category:Mobile]]

Moodle App Plugins Development Guide

2019-03-18T13:51:47Z

Nmagill: /* Advanced features */

{{Moodle Mobile}}
{{Moodle Mobile 3.5}}

==Before 3.5==

Since Moodle 3.1 Moodle plugins could be supported in the Mobile app, but only by writing an Angular JS/Ionic module, compiling it to a zip, and including that in your plugin. See [[Moodle Mobile Remote add-ons|Remote add-ons]] for details.

In Moodle 3.5 the app switched to a new way to suport plugins that was much easier for developers.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript is optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them. Plugins using the old Remote add-ons mechanism will have to be migrated to the new simpler way (following this documentation)

This new way is natively supported in Moodle 3.5. For previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Types of plugins==

We could classify all the plugins in 3 different types:

===Templates generated and downloaded when the user opens the plugins===

[[File:Templates_downloaded_when_requested.png|thumb]]

With this type of plugin, the template of your plugin will be generated and downloaded when the user opens your plugin in the app. This means that your function will receive some context params. For example, if you're developing a course module plugin you will receive the courseid and the cmid (course module ID). You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Templates downloaded on login and rendered using JS data===

[[File:Templates_downloaded_on_login.png|thumb]]

With this type of plugin, the template for your plugin will be downloaded when the user logins in the app and will be stored in the device. This means that your function will not receive any context params, and you need to return a generic template that will be built with JS data like the ones in the Mobile app. When the user opens a page that includes your plugin, your template will receive the required JS data and your template will be rendered. You can see the list of delegates that support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

===Pure Javascript plugins===

You can always implement your whole plugin yourself using Javascript instead of using our API. In fact, this is required if you want to implement some features like capturing links in the Mobile app. You can see the list of delegates that only support this type of plugin in the [[Mobile_support_for_plugins#Delegates|Delegates]] section.

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (https://github.com/markn86/moodle-mod_certificate/commit/003fbac0d80fd96baf428255500980bf95a7a0d6)

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = [
'mod_certificate' => [ // Plugin identifier
'handlers' => [ // Different places where the plugin will display content.
'coursecertificate' => [ // Handler unique name (alphanumeric).
'displaydata' => [
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
],

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => [
'mobile_course_view' => [],
'mobile_issues_view' => [],
]. // Function that needs to be downloaded for offline.
],
],
'lang' => [ // Language strings that are used in all the handlers.
['pluginname', 'certificate'],
['summaryofattempts', 'certificate'],
['getcertificate', 'certificate'],
['requiredtimenotmet', 'certificate'],
['viewcertificateviews', 'certificate'],
],
],
];
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the method in the Moodle \(component)\output\mobile class to be executed the first time the user clicks in the new option displayed in the app.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).
: Note: If your functions use additional custom parameters (for example, if you implement multiple pages within a module's view function by using a 'page' parameter in addition to the usual cmid, courseid, userid) then the app will not know which additional parameters to supply. In this case, do not list the function in offlinefunctions; instead, you will need to manually implement a [[#Module_prefetch_handler|module prefetch handler]].

;Lang:
: The language pack string ids used in the plugin by all the handlers. Please note that you should avoid adding all the plugin string ids (including those unused) because the Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

defined('MOODLE_INTERNAL') || die();

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
],
],
'javascript' => '',
'otherdata' => '',
'files' => $issues,
];
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code xml>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
<p class="item-heading">{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</p>
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
<p>{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}</p>
</ion-item>
<%/showget%>


<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}"></span>
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = [
'issues' => $issues
];

return [
'templates' => [
[
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
],
],
'javascript' => '',
'otherdata' => '',
];
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code xml>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
<p class="item-heading">{{ <%timecreated%> | coreToLocaleString }}</p>
<p><%grade%></p>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = [

'mod_certificate_get_certificates_by_courses' => [
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'],
],
];
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

Within the app, make sure to turn on the option: '''App settings''' / '''General''' / '''Display debug messages'''. This means popup errors from the app will show more information.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.

===Options only for CoreCourseOptionsDelegate===

* '''displaydata''' (mandatory): title, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreMainMenuDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first. Main Menu plugins are always displayed in the "More" tab, they cannot be displayed as tabs in the bottom bar.

===Options only for CoreCourseModuleDelegate===

* '''displaydata''' (mandatory): icon, class.
* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.
* '''displayopeninbrowser''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Open in browser" option in the top-right menu. This can be done in JavaScript too: this.displayOpenInBrowser = false;
* '''displaydescription''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Description" option in the top-right menu. This can be done in JavaScript too: this.displayDescription = false;
* '''displayrefresh''': (optional) Supported from the 3.6 version of the app. Whether the module should display the "Refresh" option in the top-right menu. This can be done in JavaScript too: this.displayRefresh = false;
* '''displayprefetch''': (optional) Supported from the 3.6 version of the app. Whether the module should display the download option in the top-right menu. This can be done in JavaScript too: this.displayPrefetch = false;
* '''displaysize''': (optional) Supported from the 3.6 version of the app. Whether the module should display the downloaded size in the top-right menu. This can be done in JavaScript too: this.displaySize = false;

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for CoreSettingsDelegate===

* '''displaydata''' (mandatory): title, icon, class.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

===Options only for AddonMessageOutputDelegate===

* '''displaydata''' (mandatory): title, icon.
* '''priority''' (optional): Priority of the handler. Higher priority is displayed first.

==Delegates==

The delegates can be classified by type of plugin. For more info about type of plugins, please see the See [[Mobile_support_for_plugins#Types_of_plugins|Types of plugins]] section.

===Templates generated and downloaded when the user opens the plugins===

====CoreMainMenuDelegate====

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

====CoreCourseOptionsDelegate====

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

====CoreCourseModuleDelegate====

You must use this delegate for supporting activity modules or resources.

====CoreUserDelegate====

You must use this delegate when you want to add additional options in the user profile page in the app.

====CoreCourseFormatDelegate====

You must use this delegate for supporting course formats.

====CoreSettingsDelegate====

You must use this delegate to add a new option in the settings page.

====AddonMessageOutputDelegate====

You must use this delegate to support a message output plugin.

===Templates downloaded on login and rendered using JS data===

====CoreQuestionDelegate====

You must use this delegate for supporting question types.
https://docs.moodle.org/dev/Creating_mobile_question_types

====CoreQuestionBehaviourDelegate====

You must use this delegate for supporting question behaviours.

====CoreUserProfileFieldDelegate====

You must use this delegate for supporting user profile fields.

====AddonModQuizAccessRuleDelegate====

You must use this delegate to support a quiz access rule.

====AddonModAssignSubmissionDelegate and AddonModAssignFeedbackDelegate====

You must use these delegates to support assign submission or feedback plugins.

====AddonWorkshopAssessmentStrategyDelegate====

You must use this delegate to support a workshop assessment strategy plugin.

===Pure Javascript plugins===

These delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please notice that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional. If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: '<% issue.url %>', filename: '<% issue.name %>', timemodified: '<% issue.timemodified %>', filesize: '<% issue.size %>'}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

You can also use this to add options to the context menu. Example usage:

<code php>
<core-navbar-buttons>
<core-context-menu>
<core-context-menu-item [priority]="500" [content]="'Nice boat'" (action)="boatFunction()" [iconAction]="'boat'"></core-context-menu-item>
</core-context-menu>
</core-navbar-buttons>
</code>

Note that it is not currently possible to remove or modify options from the context menu without using a nasty hack.

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''preSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [useOtherData]="['userid']" (onSuccess)="certificateViewed($event)">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>
<code javascript>
this.certificateViewed = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''showError''' (boolean): Whether to show an error message if the WS call fails. Defaults to true. This field was added in v3.5.2.
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.
* '''jsData''' (any): JS variables to pass to the new page so they can be used in the template or JS. If true is supplied instead of an object, all initial variables from current page will be copied. This field was added in v3.5.2.
* '''newContentPreSets''' (object): Extra options for the WS call of the new content: whether to use cache or not, etc. This field was added in v3.6.0.
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

Same example as the previous one but implementing a custom JS code to run on success:

<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']" (onSuccess)="callDone($event)">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

Note that this will cause an error to appear on each page load if the user is offline in v3.5.1 and older, the bug was fixed in v3.5.2.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''onSuccess''' (Function): A function to call when the WS call is successful (HTTP call successful and no exception returned). This field was added in v3.5.2.
* '''onError''' (Function): A function to call when the WS call fails (HTTP call fails or an exception is returned). This field was added in v3.5.2.
* '''onDone''' (Function): A function to call when the WS call finishes (either success or fail). This field was added in v3.5.2.

Example usage:
<code php>
<span core-site-plugins-call-ws-on-load name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" (onSuccess)="callDone($event)"></span>
</code>
<code javascript>
this.callDone = function(result) {
// Code to run when the WS call is successful.
};
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===Running JS code after a content template has loaded===

When you return JavaScript code from a handler function using the 'javascript' array key, this code is executed immediately after the web service call returns, which may be before the returned template has been rendered into the DOM.

If your code needs to run after the DOM has been updated, you can use setTimeout to call it. For example:

<code php>
return [
'template' => [ ... ],
'javascript' => 'setTimeout(function() { console.log("DOM is available now"); });',
'otherdata' => '',
'files' => []
];
</code>

''Note: If you wanted to write a lot of code here, you might be better off putting it in a function defined in the response from an init template, so that it does not get loaded again with each page of content.''

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Use the rich text editor===

The rich text editor included in the app requires a FormControl to work. You can use the library FormBuilder to create this control (or to create a whole FormGroup if you prefer).

With the following Javascript you'll be able to create a FormControl:

<code javascript>
this.control = this.FormBuilder.control(this.CONTENT_OTHERDATA.rte);
</code>

In the example above we're using a value returned in OTHERDATA as the initial value of the rich text editor, but you can use whatever you want.

Then you need to pass this control to the rich text editor in your template:

<code>
<ion-item>
<core-rich-text-editor item-content [control]="control" placeholder="Enter your text here" name="rte_answer"></core-rich-text-editor>
</ion-item>
</code>

Finally, there are several ways to send the value in the rich text editor to a WebService to save it. This is one of the simplest options:

<code>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_webservice" [params]="{rte: control.value}" ....
</code>

As you can see, we're passing the value of the rich text editor as a parameter to our WebService.

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Advanced link handler=====
Link handlers have some advanced features that allow you to change how links behave under different conditions.
======Patterns======
You can define a Regular Expression pattern to match certain links. This will apply the handler only to links that match the pattern.
<code javascript>
function AddonModFooLinkHandler() {
....
this.pattern = RegExp('\/mod\/foo\/specialpage.php');
....
}
</code>
======Priority======
Multiple link handlers may apply to a given link. You can define the order of precedence by setting the priority - the handler with the highest priority will be used.
All default handlers have a priority of 0, so 1 or higher will override the default.
<code javascript>
function AddonModFooLinkHandler() {
....
this.priority = 1;
....
}
</code>
======Multiple actions======
Once a link has been matched, the handler's getActions() method determines what the link should do. This method has access to the URL and its parameters.
Different actions can be returned depending on different conditions.
<code javascript>
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
return [{
action: function(siteId, navCtrl) {
// The actual behaviour of the link goes here.
},
sites: [...]
}, {
...
}];
}
</code>
Once handlers have been matched for a link, the actions will be fetched for all the matching handlers, in priorty order. The first "valid" action will be used to open the link.
If your handler is matched with a link, but a condition assessed in the getActions() function means you want to revert to the next highest priorty handler, you can "invalidate"
your action by settings its sites propety to an empty array.
======Complex example======
This will match all URLs containing /mod/foo/, and force those with an id parameter that's not in the "supportedModFoos" array to open in the user's browser, rather than the app.

<code javascript>
var that = this;
var supportedModFoos = [...];
function AddonModFooLinkHandler() {
this.pattern = new RegExp('\/mod\/foo\/');
this.name = "AddonModFooLinkHandler";
this.priority = 1;
}
AddonModFooLinkHandler.prototype = Object.create(that.CoreContentLinksHandlerBase.prototype);
AddonModFooLinkHandler.prototype.constructor = AddonModFooLinkHandler;
AddonModFooLinkHandler.prototype.getActions = function(siteIds, url, params) {
var action = {
action: function() {
that.CoreUtilsProvider.openInBrowser(url);
}
};
if (supportedModFoos.indexOf(parseInt(params.id)) !== -1) {
action.sites = [];
}
return [action];
};
that.CoreContentLinksDelegate.registerHandler(new AddonModFooLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

// Create a class that "inherits" from CoreCourseActivityPrefetchHandlerBase.
function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseActivityPrefetchHandlerBase.call(this, that.TranslateService, that.CoreAppProvider, that.CoreUtilsProvider,
that.CoreCourseProvider, that.CoreFilepoolProvider, that.CoreSitesProvider, that.CoreDomUtilsProvider);

this.name = "AddonModCertificateModulePrefetchHandler";
this.modName = "certificate";
this.component = "mod_certificate"; // This must match the plugin identifier from db/mobile.php, otherwise the download link in the context menu will not update correctly.
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseActivityPrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

// Override the prefetch call.
AddonModCertificateModulePrefetchHandler.prototype.prefetch = function(module, courseId, single, dirPath) {
return this.prefetchPackage(module, courseId, single, prefetchCertificate);
};

function prefetchCertificate(module, courseId, single, siteId) {
// Perform all the WS calls.
// You can access most of the app providers using that.ClassName. E.g. that.CoreWSProvider.call().
}

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

One relatively simple full example is where you have a function that needs to work offline, but it has an additional argument other than the standard ones. You can imagine for this an activity like the book module, where it has multiple pages for the same cmid. The app will not automatically work with this situation - it will call the offline function with the standard arguments only, so you won't be able to prefetch all the possible parameters.

To deal with this, you need to implement a web service in your Moodle component that returns the list of possible extra arguments, and then you can call this web service and loop around doing the same thing the app does when it prefetches the offline functions. Here is an example from a third-party module (showing only the actual prefetch function - the rest of the code is as above) where there are multiple values of a custom 'section' parameter for the mobile function 'mobile_document_view':

<code javascript>
function prefetchOucontent(module, courseId, single, siteId) {
var component = 'mod_oucontent';

// Get the site, first.
return that.CoreSitesProvider.getSite(siteId).then(function(site) {
// Read the list of pages in this document using a web service.
return site.read('mod_oucontent_get_page_list', {'cmid': module.id}).then(function(response) {
var promises = [];

// For each page, read and process the page - this is a copy of logic in the app at
// siteplugins.ts (prefetchFunctions), but modified to add the custom argument.
for(var i = 0; i < response.length; i++) {
var args = {
courseid: courseId,
cmid: module.id,
userid: site.getUserId()
};
if (response[i] !== '') {
args.section = response[i];
}

promises.push(that.CoreSitePluginsProvider.getContent(
component, 'mobile_document_view', args).then(
function(result) {
var subPromises = [];
if (result.files && result.files.length) {
subPromises.push(that.CoreFilepoolProvider.downloadOrPrefetchFiles(
site.id, result.files, true, false, component, module.id));
}
return Promise.all(subPromises);
}));
}

return Promise.all(promises);
});
});
}
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the delegates specified in the section [[Mobile_support_for_plugins#Templates_downloaded_on_login_and_rendered_using_JS_data_2|Templates downloaded on login and rendered using JS data]] supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

===Translate dynamic strings===

If you wish to have an element that displays a localised string based on value from your template you can doing something like:

<code>
<ion-card>
<ion-card-content translate>
plugin.mod_myactivity.<% status %>
</ion-card-content>
</ion-card>
</code>

This could save you from having to write something like when only one value should be displayed:

<code>
<ion-card>
<ion-card-content>
<%#isedting%>{{ 'plugin.mod_myactivity.editing' | translate }}<%/isediting%>
<%#isopen%>{{ 'plugin.mod_myactivity.open' | translate }}<%/isopen%>
<%#isclosed%>{{ 'plugin.mod_myactivity.closed' | translate }}<%/isclosed%>
</ion-card-content>
</ion-card>
</code>

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<ion-list radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<ion-list radio-group [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</ion-list>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

==Moodle plugins with mobile support==

* Group choice: [https://moodle.org/plugins/mod_choicegroup Moodle plugins directory entry] and [https://github.com/ndunand/moodle-mod_choicegroup code in github].
* Custom certificate: [https://moodle.org/plugins/mod_customcert Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_customcert code in github].
* Gapfill question type: [https://moodle.org/plugins/qtype_gapfill Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_gapfill in github].
* Wordselect question type: [https://moodle.org/plugins/qtype_wordselect Moodle plugins directory entry] and [https://github.com/marcusgreen/moodle-qtype_wordselect in github].
* RegExp question type: [https://moodle.org/plugins/qtype_regexp Moodle plugins directory entry] and [https://github.com/rezeau/moodle-qtype_regexp in github].
* Certificate: [https://moodle.org/plugins/mod_certificate Moodle plugins directory entry] and [https://github.com/markn86/moodle-mod_certificate in github].
* Attendance [https://moodle.org/plugins/mod_attendance Moodle plugins directory entry] and [https://github.com/danmarsden/moodle-mod_attendance in github].

See the complete list in the plugins database [https://moodle.org/plugins/browse.php?list=award&id=6 here] (it may contain some outdated plugins)
[[Category:Mobile]]

Calendar API

2018-08-24T08:55:57Z

Nmagill: Clarify the use of $checkcapability parameter in event creation and updating

{{ Moodle 3.3 }}

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

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.

==Overview==

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.

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.

==Creating an event==
Creating a new calendar event. The optional parameter $checkcapability is used to check user's capability to add events. By default the $checkcapability parameter is set to true. You should set it to false if you have already checked that the user has the capabilities required for the event to be created, for example when an activity is creating an event based on a deadline.

<code php>
require_once($CFG->dirroot.'/calendar/lib.php');

$event = new stdClass();
$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.
$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.
$event->name = get_string('calendarstart', 'scorm', $scorm->name);
$event->description = format_module_intro('scorm', $scorm, $cmid);
$event->courseid = $scorm->course;
$event->groupid = 0;
$event->userid = 0;
$event->modulename = 'scorm';
$event->instance = $scorm->id;
$event->timestart = $scorm->timeopen;
$event->visible = instance_is_visible('scorm', $scorm);
$event->timeduration = 0;

calendar_event::create($event);
</code>

==Updating an event==
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 yet. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. You should set it to false if you have already checked that the user has the capabilities required for the event to be updated, for example when an activity is updating an event based on a change to it's settings.

<code php>
$eventid = required_param('id', PARAM_INT);
$event = calendar_event::load($eventid);

$data = $mform->get_data();
$event->update($data);
</code>

==Deleting an event==
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.

<code php>
$eventid = required_param('id', PARAM_INT);
$event = calendar_event::load($eventid);
$event->delete($repeats);
</code>

==Event priority==
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.

The event priority is set to the following:
* NULL for non-override events.
<code php>
$event->priority = null;
</code>
* 0 for user override events.
<code php>
$event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;
</code>
* A positive integer for group events.

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:
# In the assignment module, the event priorities for group overrides are being determined from the 'sortorder' column in the 'assign_overrides' table.
# 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).

Should you ever decide to sort out group override priorities by implementing *_get_group_override_priorities(), the recommended return structure would be something like
<code php>
[
'youreventtype1' => $prioritiesforeventtype1,
...
]
</code>
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:
<code php>
/**
* Calculates the priorities of timeopen and timeclose values for group overrides for a lesson.
*
* @param int $lessonid The lesson ID.
* @return array|null Array of group override priorities for open and close times. Null if there are no group overrides.
*/
function lesson_get_group_override_priorities($lessonid) {
global $DB;

// Fetch group overrides.
$where = 'lessonid = :lessonid AND groupid IS NOT NULL';
$params = ['lessonid' => $lessonid];
$overrides = $DB->get_records_select('lesson_overrides', $where, $params, '', 'id, groupid, available, deadline');
if (!$overrides) {
return null;
}

$grouptimeopen = [];
$grouptimeclose = [];
foreach ($overrides as $override) {
if ($override->available !== null && !in_array($override->available, $grouptimeopen)) {
$grouptimeopen[] = $override->available;
}
if ($override->deadline !== null && !in_array($override->deadline, $grouptimeclose)) {
$grouptimeclose[] = $override->deadline;
}
}

// Sort open times in ascending manner. The earlier open time gets higher priority.
sort($grouptimeopen);
// Set priorities.
$opengrouppriorities = [];
$openpriority = 1;
foreach ($grouptimeopen as $timeopen) {
$opengrouppriorities[$timeopen] = $openpriority++;
}

// Sort close times in descending manner. The later close time gets higher priority.
rsort($grouptimeclose);
// Set priorities.
$closegrouppriorities = [];
$closepriority = 1;
foreach ($grouptimeclose as $timeclose) {
$closegrouppriorities[$timeclose] = $closepriority++;
}

return [
'open' => $opengrouppriorities,
'close' => $closegrouppriorities
];
}
</code>

==Action events==

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.

Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.

<code php>
$event->type = CALENDAR_EVENT_TYPE_ACTION;
$event->timesort = $scorm->timeclose;
</code>

[[File:my overview sam student.png]]

===The callbacks===

There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.

====mod_xyz_core_calendar_is_event_visible()====
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.

<code php>
/**
* Is the event visible?
*
* This is used to determine global visibility of an event in all places throughout Moodle. For example,
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.
*
* @param calendar_event $event
* @return bool Returns true if the event is visible to the current user, false otherwise.
*/
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {
global $CFG, $USER;

require_once($CFG->dirroot . '/mod/assign/locallib.php');

$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];
$context = context_module::instance($cm->id);

$assign = new assign($context, $cm, null);

if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {
return $assign->can_grade();
} else {
return !$assign->can_grade() && $assign->can_view_submission($USER->id);
}
}
</code>

====mod_xyz_core_calendar_provide_event_action()====
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.

Eg.
<code php>
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,
\core_calendar\action_factory $factory) {
global $CFG;

require_once($CFG->dirroot . '/mod/scorm/locallib.php');

$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];

if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {
// The scorm has closed so the user can no longer submit anything.
return null;
}

// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.
$customdata = $cm->customdata ?: [];
$customdata['id'] = $cm->instance;
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);

// Check that the SCORM activity is open.
list($actionable, $warnings) = scorm_get_availability_status($scorm);

return $factory->create_instance(
get_string('enter', 'scorm'),
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),
1,
$actionable
);
}
</code><br />
The variables to pass to <code>create_instance()</code> are -

# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').
# $url \moodle_url The URL the user visits in order to perform this action.
# $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.
# $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.

====mod_xyz_core_calendar_event_action_shows_item_count()====
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.

Eg.

<code php>
/**
* Callback function that determines whether an action event should be showing its item count
* based on the event type and the item count.
*
* @param calendar_event $event The calendar event.
* @param int $itemcount The item count associated with the action event.
* @return bool
*/
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {
// List of event types where the action event's item count should be shown.
$eventtypesshowingitemcount = [
ASSIGN_EVENT_TYPE_GRADINGDUE
];
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;
}
</code>

==Refreshing calendar events of activity modules==
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.

Sample usage:
<code php>
// Create the instance.
$refreshtask = new refresh_mod_calendar_events_task();

// Add custom data.
$customdata = [
'plugins' => ['assign', 'lesson', 'quiz'] // Optional. If not specified, it will refresh the events of all of the activity modules.
];
$refreshtask->set_custom_data($customdata);

// Queue it.
\core\task\manager::queue_adhoc_task($refreshtask);
</code>

==calendar_get_legacy_events()==
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.

''Note that this function will not work as expected if you pass a list of user ids as the current user session is internally used to determine which events should be visible. More info in https://tracker.moodle.org/browse/MDL-60340''

==Changes to Behat==
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.

==Drag & drop==

The calendar supports dragging and dropping events within the calendar in order to change the start day for the event. Each type of calendar event can be dragged by a user with sufficient permissions to edit the event.

===Dragging action events===

When an action event is dragged the corresponding property will also be updated in the activity instance that generated the event. For example, dragging the assignment due date event will result in the assignment activity’s due date to be changed.

In order to drag an action event the logged in user must have the moodle/course:manageactivities capability in the activity that generated the event.

For an action event to be draggable the activity that generated it will need to have implemented at least one (but ideally both) callback to handle updating itself after the calendar event is dragged.

====core_calendar_event_timestart_updated (required)====
This callback is required to be implemented by any activity that wishes to have it’s action events draggable in the calendar.

This callback handles updating the activity instance based on the changed action event. The callback will receive the updated calendar event and the corresponding activity instance.

Example:
<code php>
function mod_feedback_core_calendar_event_timestart_updated(\calendar_event $event, \stdClass $feedback) {
global $CFG, $DB;

if (empty($event->instance) || $event->modulename != 'feedback') {
return;
}

if ($event->instance != $feedback->id) {
return;
}

if (!in_array($event->eventtype, [FEEDBACK_EVENT_TYPE_OPEN, FEEDBACK_EVENT_TYPE_CLOSE])) {
return;
}

$courseid = $event->courseid;
$modulename = $event->modulename;
$instanceid = $event->instance;
$modified = false;

$coursemodule = get_fast_modinfo($courseid)->instances[$modulename][$instanceid];
$context = context_module::instance($coursemodule->id);

// The user does not have the capability to modify this activity.
if (!has_capability('moodle/course:manageactivities', $context)) {
return;
}

if ($event->eventtype == FEEDBACK_EVENT_TYPE_OPEN) {
// If the event is for the feedback activity opening then we should
// set the start time of the feedback activity to be the new start
// time of the event.
if ($feedback->timeopen != $event->timestart) {
$feedback->timeopen = $event->timestart;
$feedback->timemodified = time();
$modified = true;
}
} else if ($event->eventtype == FEEDBACK_EVENT_TYPE_CLOSE) {
// If the event is for the feedback activity closing then we should
// set the end time of the feedback activity to be the new start
// time of the event.
if ($feedback->timeclose != $event->timestart) {
$feedback->timeclose = $event->timestart;
$modified = true;
}
}

if ($modified) {
$feedback->timemodified = time();
$DB->update_record('feedback', $feedback);
$event = \core\event\course_module_updated::create_from_cm($coursemodule, $context);
$event->trigger();
}
}
</code>

====core_calendar_get_valid_event_timestart_range====
This callback should calculate the minimum and maximum allowed timestart property for the given calendar event. This will typically be based on the properties of the activity instance, for example the timeopen and timeclose properties of the activity could form the minimum and maximum bounds, respectively.

These values will be used to provide a visual indicator to the user in the calendar UI for which days are valid for the event to be dragged to. It will also be used to validate that the calendar event is being updated to a valid timestart value.

The callback should return an array with two values, the first value representing the minimum cutoff and the second the maximum.

The callback can return an array for each of the minimum and maximum cutoffs, if it has them. The array should contain the timestamp of the cutoff and an error message to be displayed to the user if they attempt to drag an event to a day that violates the limit. For example:
<code php>
[
[1505704373, 'The due date must be after the sbumission start date'], // Minimum cutoff.
[1506741172, 'The due date must be before the cutoff date'] // Maximum cutoff.
]
</code>

If the calendar event has no limits then it should return null in for either/both of the min and max cutoff values to indicate that it isn’t limited. For example:
<code php>
[null, null] // No limits.
</code><br />
<code php>
[null, [1510625037, “This is the maximum cutoff”]] // No minimum cutoff.
</code><br />
<code php>
[[1510625037, “This is the minimum cutoff”], null] // No maximum cutoff.
</code>

If the calendar event has no valid timestart values then the callback should return [false, false]. This is used to prevent the drag and drop of override events in activities that support them (e.g. Assign, Quiz).

Example:
<code php>
function mod_feedback_core_calendar_get_valid_event_timestart_range(\calendar_event $event, \stdClass $instance) {
$mindate = null;
$maxdate = null;

if ($event->eventtype == FEEDBACK_EVENT_TYPE_OPEN) {
// The start time of the open event can't be equal to or after the
// close time of the choice activity.
if (!empty($instance->timeclose)) {
$maxdate = [
$instance->timeclose,
get_string('openafterclose', 'feedback')
];
}
} else if ($event->eventtype == FEEDBACK_EVENT_TYPE_CLOSE) {
// The start time of the close event can't be equal to or earlier than the
// open time of the choice activity.
if (!empty($instance->timeopen)) {
$mindate = [
$instance->timeopen,
get_string('closebeforeopen', 'feedback')
];
}
}

return [$mindate, $maxdate];
}
</code>

Setting up your development environment for Moodle Mobile 2 (Ionic 1)

2017-02-15T10:48:26Z

Nmagill: /* node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers */

{{Moodle Mobile}}
{{Work in progress}}

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

== Requirements ==

'''Install a browser for development'''

I recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read Moodle_Mobile_development_using_Chrome_or_Chromium for more information

'''Install Node.js'''

http://nodejs.org for Mac users I recommend to install nodejs via macports.

'''IMPORTANT''': Don't use node 4.0 or higher, there are incompatibilities with some of the packages we use. Please use v0.12.7 instead. The download directory for v0.12.7 is [https://nodejs.org/dist/v0.12.7/ here]

"note": if you also need later versions of node for other projects, use Node Version Manager aka "nvm" [https://github.com/creationix/nvm here]. Linux and OSX is supported, and the site has pointers to windows alternatives. Simply type:
nvm install 0.12.15
nvm use 0.12.15

'''Install ionic:'''
npm cache clean
npm install -g cordova ionic

'''Install the npm required packages'''
sudo npm install -g bower (This will install bower in a folder that should be in the PATH)
sudo npm install -g gulp (This will install gulp in a folder that should be in the PATH)

== Clone the app base code ==

'''Clone the code base into a local directory in your computer.'''
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory

'''Install the npm plugins dependencies'''
npm install (This will install all the dependencies listed in package.json)

'''Add the iOS and Android platforms and install the required Cordova plugins'''

Install the platforms. It's important to use these versions because newer versions are going to cause some problems with the plugins installed.
ionic platform add android@5.1.1
ionic platform add ios@4.1.0

Run the following command to install the platforms and all the required Cordova plugins
ionic state restore

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json file and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

'''Install bower globally and the required javascript files'''
bower install (this will install all the libraries listed in bower.json)

'''Run gulp’s default tasks (in order to create the build files)'''
gulp

'''Open the app in the browser'''

First start chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

== Editor ==

There are several plugins for AngularJS and Ionic development available for common editors.

Sublime 3 has plugins for [https://github.com/SublimeLinter/SublimeLinter-jscs jscs] (coding style) and [https://github.com/SublimeLinter/SublimeLinter-jshint jshint] (linter)

Configuration files for jscs and jshint can be downloaded from https://github.com/angular/angular.js (.jscs.json and .jshint*)

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

ionic platform update android
ionic platform update ios

== Updating plugins ==

cordova plugin rm your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see this guide to be able to build for Android and iOS using the command line:

http://cordova.apache.org/docs/en/5.0.0/guide_platforms_index.md.html#Platform%20Guides

'''Common errors when building'''

* com.android.dex.DexException: Multiple dex files define XXX
Open the file ''platforms/android/build.gradle'' and add these code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

* Could not resolve all dependencies for configuration ':_debugCompile'.
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using:

npm install -g npm@latest

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for Moodle Mobile 2 (Ionic 1)

2017-02-15T10:47:14Z

Nmagill: /* Troubleshooting */

{{Moodle Mobile}}
{{Work in progress}}

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

== Requirements ==

'''Install a browser for development'''

I recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read Moodle_Mobile_development_using_Chrome_or_Chromium for more information

'''Install Node.js'''

http://nodejs.org for Mac users I recommend to install nodejs via macports.

'''IMPORTANT''': Don't use node 4.0 or higher, there are incompatibilities with some of the packages we use. Please use v0.12.7 instead. The download directory for v0.12.7 is [https://nodejs.org/dist/v0.12.7/ here]

"note": if you also need later versions of node for other projects, use Node Version Manager aka "nvm" [https://github.com/creationix/nvm here]. Linux and OSX is supported, and the site has pointers to windows alternatives. Simply type:
nvm install 0.12.15
nvm use 0.12.15

'''Install ionic:'''
npm cache clean
npm install -g cordova ionic

'''Install the npm required packages'''
sudo npm install -g bower (This will install bower in a folder that should be in the PATH)
sudo npm install -g gulp (This will install gulp in a folder that should be in the PATH)

== Clone the app base code ==

'''Clone the code base into a local directory in your computer.'''
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory

'''Install the npm plugins dependencies'''
npm install (This will install all the dependencies listed in package.json)

'''Add the iOS and Android platforms and install the required Cordova plugins'''

Install the platforms. It's important to use these versions because newer versions are going to cause some problems with the plugins installed.
ionic platform add android@5.1.1
ionic platform add ios@4.1.0

Run the following command to install the platforms and all the required Cordova plugins
ionic state restore

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json file and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

'''Install bower globally and the required javascript files'''
bower install (this will install all the libraries listed in bower.json)

'''Run gulp’s default tasks (in order to create the build files)'''
gulp

'''Open the app in the browser'''

First start chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

== Editor ==

There are several plugins for AngularJS and Ionic development available for common editors.

Sublime 3 has plugins for [https://github.com/SublimeLinter/SublimeLinter-jscs jscs] (coding style) and [https://github.com/SublimeLinter/SublimeLinter-jshint jshint] (linter)

Configuration files for jscs and jshint can be downloaded from https://github.com/angular/angular.js (.jscs.json and .jshint*)

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

ionic platform update android
ionic platform update ios

== Updating plugins ==

cordova plugin rm your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see this guide to be able to build for Android and iOS using the command line:

http://cordova.apache.org/docs/en/5.0.0/guide_platforms_index.md.html#Platform%20Guides

'''Common errors when building'''

* com.android.dex.DexException: Multiple dex files define XXX
Open the file ''platforms/android/build.gradle'' and add these code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

* Could not resolve all dependencies for configuration ':_debugCompile'.
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

=== node-gyp\src\win_delay_load_hook.c(34): error C2373: '__pfnDliNotifyHook2': redefinition; different type modifiers ===

Try updating npm to the latest version using: npm install -g npm@latest

== See also ==

http://ionicframework.com/docs/cli/

Cache API

2014-10-16T14:34:08Z

Nmagill: /* Specifying a data source */

This document details the Cache API aka MUC aka Moodle's Universal Cache.
I've chosen to use a tutorial/example flow for this document always working with a theoretical module plugin called myplugin.
There is also a [[Cache API - Quick reference]] if you would rather read that.

==Basic usage==
It's very easy to get started with the Cache API. It is designed to be as easy and as quick to use as possible and is predominantely self contained.
All you need to do is add a definition for your cache and you are ready to start working with the Cache API.

===Creating a definition===
Cache definitions exist within the db/caches.php file for a component/plugin.<br />
In the case of core that is the moodle/lib/db/caches.php file, in the case of a module that would be moodle/mod/myplugin/db/caches.php.

The definition is used API in order to understand a little about the cache and what it is being used for, it also allows the administrator to set things up especially for the definition if they want.
From a development point of view the definition allows you to tell the API about your cache, what it requires, and any (if any) advanced features you want it to have.<br />
The following shows a basic definition containing just the bare minimum:
<code php>
// moodle/mod/myplugin/db/caches.php
$definitions = array(
'somedata' => array(
'mode' => cache_store::MODE_APPLICATION
)
);
</code>
This informs the API that the myplugin module has a cache called ''somedata'' and that it is an application (globally shared) cache.<br />
When creating a definition thats the bare minimum, to provide an area ''(somedata)'' and declare the type of the cache application, session, or request.<br />
:An application cache is a shared cache, all users can access it.<br />
:Session caches are, well, just stores in the users session.<br />
:Request caches you can think of as static caches, only available to the user owning the request, and only alive until the end of the request.<br />
There are of course many more options available that allow you to really take the cache by the reigns, you can read about some of the important ones further on, or skip ahead to [[#The definition]] section which details the available options in full.

Please note that for each definition a language string with the name ''cachedef_'' followed by the name of the definition is expected. Using the example above you would have to define:

<code php>
// moodle/mod/myplugin/lang/en/mod_myplugin.php
$string['cachedef_somedata'] = 'This is the description of the cache somedata';
</code>

===Getting a cache object===
Once your definition has been created you should bump the version number so that Moodle upgrades and processes the definitions file at which point your definition will be useable.

Now within code you can get a cache object to interact with in the following manner.

<code php>
$cache = cache::make('mod_myplugin', 'mycache');
</code>

The cache::make method is a factory method, it will create a cache object to allow you to work with your cache. The cache object will be one of several classes chosen by the API based upon what your definition contains. All of these classes will extend the base cache class, and in nearly all cases you will get one of cache_application, cache_session, or cache_request depending upon the mode you selected.

===Using your cache object===
Once you have a cache object (will extend the cache class and implements cache_loader) you are ready to start interacting with the cache.

Of course there are three basic basic operations. get, set, and delete.

The first is to send something to the cache.
<code php>
$result = $cache->set('key', 'value');
</code>
Easy enough. The key must an int or a string. The value can be absolutely anything your want.
The result is true if the operation was a success, false otherwise.

The second is to fetch something from the cache.
<code php>
$data = $cache->get('key');
</code>
$data will either be what ever was being stored in the cache, or false if the cache could not find the key.

The third and final operation is delete.
<code php>
$result = $cache->delete('key');
</code>
Again just like set the result will either be true if the operation was a success, or false otherwise.

You can also set, get, and delete multiple key=>value pairs in a single transaction.
<code php>
$result = $cache->set_many(array(
'key1' => 'data1',
'key3' => 'data3'
));
// $result will be the number of pairs sucessfully set.

$result = $cache->get_many(array('key1', 'key2', 'key3'));
print_r($result);
// Will print the following:
// array(
// 'key1' => 'data1',
// 'key2' => false,
// 'key3' => 'data3'
// )

$result = $cache->delete_many(array('key1', 'key3');
// $result will be the number of records sucessfully deleted.
</code>

That covers the basic operation of the Cache API.<br />
In many situations there is not going to be any more to it than that.

==Ad-hoc Caches==
This is the alternative method of using the cache API.<br />
It involves creating a cache using just the required params at the time that it is required. It doesn't require that a definition exists making it quicker and easier to use, however it can only use the default settings and is only recommended for insignificant caches (rarely used during operation, never to be mapped or customised, only existsing in a single place in code).

Once a cache object has been retrieved it operates exactly as the same as a cache that has been created for a definition.

To create an ad-hoc cache you would use the following:
<code php>
$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_myplugin', 'mycache');
</code>

Really don't be lazy, if you don't have a good reason to use an ad-hoc cache you should be spending a extra 5 minutes creating a definition.

==The definition==

The above section illustrated how to create a basic definition, specifying just the area name (the key) and the mode for the definition. Those being the two required properties for a definition.<br />
There are many other options that will let you make the most of the Cache API and will undoubtedly be required when implementing and converting cache solutions to the Cache API.

The following details the options available to a definition and their defaults if not applied:

<code php>
$definitions = array(
// The name of the cache area is the key. The component/plugin will be picked up from the file location.
'area' => array(
'mode' => cache_store::MODE_*,
'simplekeys' => false,
'simpledata' => false,
'requireidentifiers' => array('ident1', 'ident2'),
'requiredataguarantee' => false,
'requiremultipleidentifiers' => false,
'requirelockingread' => false,
'requirelockingwrite' => false,
'maxsize' => null,
'overrideclass' => null,
'overrideclassfile' => null,
'datasource' => null,
'datasourcefile' => null,
'staticacceleration' => false,
'staticaccelerationsize' => null,
'ttl' => 0,
'mappingsonly' => false,
'invalidationevents' => array('event1', 'event2'),
'sharingoptions' => cache_definition::SHARING_DEFAULT,
'defaultsharing' => cache_definition::SHARING_DEFAULT,
)
);
</code>

===Setting requirements===
The definition can specify several requirements for the cache.<br />
This includes identifiers that must be provided when creating the cache object, that the store guarantees data stored in it will remain there until removed, a store that supports multiple identifiers, and finally read/write locking.
The options for these are as follows:

; simplekeys : [bool] Set to true if your cache will only use simple keys for its items.<br />Simple keys consist of digits, underscores and the 26 chars of the english language. a-zA-Z0-9_<br />If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes. It will be better for performance and possible only because we know the keys are safe.
; simpledata : [bool] If set to true we know that the data is scalar or array of scalar.
; requireidentifiers : [array] An array of identifiers that must be provided to the cache when it is created.
; requiredataguarantee : [bool] If set to true then only stores that can guarantee data will remain available once set will be used.
; requiremultipleidentifiers : [bool] If set to true then only stores that support multiple identifiers will be used.
; requirelockingread : [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required.<br />Remember 99.9% of caches will NOT need this setting.<br />This setting will only be used for application caches presently.
; requirelockingwrite : [bool] If set to true then a lock will be gained before writing to the cache store. As above this is not recommended unless truly needed. Please think about the order of your code and deal with race conditions there first.<br />This setting will only be used for application caches presently.

===Cache modifiers===
You are also to modify the way in which the cache is going to operate when working for your definition.<br />
By enabling the static option the Cache API will only ever generate a single cache object for your definition on the first request for it, further requests will be returned the original instance.<br />This greatly speeds up the collecting of a cache object.<br />
Enabling persistence also enables a static store within the cache object, anything set to the cache, or retrieved from it will be stored in that static array for the life of the request.
This makes the persistence options some of the most powerful. If you know you are going to be using you cache over and over again or if you know you will be making lots of requests for the same items then this will provide a great performance boost.
Of course the static storage of cache objects and of data is costly in terms of memory and should only be used when actually required, as such it is turned off by default.
As well as persistence you can also set a maximum number of items that the cache should store (not a hard limit, its up to each store) and a time to live (ttl) although both are discouraged as efficient design negates the need for both in most situations.

; staticacceleration : [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for this definition once, further requests will be given the original instance.<br />Second the cache loader will keep an array of the items set and retrieved to the cache during the request.<br />This has several advantages including better performance without needing to start passing the cache instance between function calls, the downside is that the cache instance + the items used stay within memory.<br />Consider using this setting when you know that there are going to be many calls to the cache for the same information or when you are converting existing code to the cache and need to access the cache within functions but don't want to add it as an argument to the function.
; staticaccelerationsize : [int] This supplements the above setting by limiting the number of items in the caches persistent array of items.<br />Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store.
; ttl : [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system (even if the event is just time expiring, better not to rely on ttl).<br />Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not.
; maxsize : [int] If set this will be used as the maximum number of entries within the cache store for this definition.<br />Its important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit.

===Overriding a cache loader===
This is a super advanced feature and should not be done. ever. Unless you have an very good reason to do so.
It allows you to create your own cache loader and have it be used instead of the default cache loader class. The cache object you get back from the make operations will be an instance of this class.

; overrideclass : [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution.<br />Any class used here must inherit the cache_loader interface and must extend default cache loader for the mode they are using.
; overrideclassfile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.

===Specifying a data source===
This is a great wee feature, especially if your code is object orientated.<br />
It allows you to specify a class that must inherit the cache_data_source object and will be used to load any information requested from the cache that is not already being stored.<br />
When the requested key cannot be found in the cache the data source will be asked to load it. The data source will then return the information to the cache, the cache will store it, and it will then return it to the user as a request of their get request. Essentially no get request should ever fail if you have a data source specified.

; datasource : [string] A class to use as the data loader for this definition.<br />Any class used here must inherit the cache_data_source interface.
; datasourcefile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.

===Misc settings===
The following are stand along settings that don't fall into any of the above categories.

; invalidationevents : [array] An array of events that should cause this cache to invalidate some or all of the items within it.
; mappingsonly : [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another.
; sharingoptions : [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options.
; defaultsharing : [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default.

==The loader==

==Using a data source==

==Developing cache plugins==

PHPUnit

2014-01-15T10:47:06Z

Nmagill: /* Installation of PHPUnit via Composer */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Check that /your/moodle/dirroot/composer.json exists and the contents are similar to
{
"require-dev": {
"phpunit/phpunit": "3.7.*",
"phpunit/dbUnit": "1.2.*"
}
}
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class stack_cas_keyval_exception_test extends basic_testcase {
</code>

to all the classes in your plugin, the you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

=Common Unit Test Problems=
[[Common unit test problems]]

[[Category:Unit testing]]