Writing your own Trigger Subplugin

For the start, you can also have a look at the implementation of a Dummy Trigger. In the following, we outline what you have to do to implement your own functionality into it.

To create a new trigger subplugin, start with creating a subfolder in the folder trigger. Each trigger subplugin needs some files in order to work. There are some features of the API, which are optional. In the following you will find a description of all available features. The minimal requirements for a working step subplugin are:

• lang file
• lip.php with the functions:
  • check_course(...)
  • get_subpluginname()
• version.php

Functionality of a trigger subplugin

A trigger subplugin has the responsibility to check whether a process should be started for a course. There are two relevant functions for this purpose, which are placed within the lib.php: check_course(...) and get_course_recordset_where(...). Besides this function most of the code described below is boiler plate code, necessary to guarantee the proper functioning of the trigger.

File structure

In the following code segments <yourtrigger> has to be replaced by the name of your subplugin!

db files

A subplugin within Moodle can use all files within the db folder that you already know from a general plugin. This way, you could create a database schema, create event observers of scheduled tasks. However, through the different manager classes offered by the tool_lifecycle API, an own database table is usually not necessary.

lang file

Create a file lang/en/cleanupcoursestrigger_.php containing at least:

$string['pluginname'] = '...';

lib.php

This file contains the logic of your trigger. It contains a class which extends the base_automatic interface, specifying the available API functions. The header of this file should look like:

    namespace tool_lifecycle\trigger;
    use tool_lifecycle\local\response\trigger_response;
    defined('MOODLE_INTERNAL') || die();
    require_once(__DIR__ . '/../lib.php');

    class <yourtrigger> implements base_automatic {

check_course($course)

Then, the function check_course($course) has to be implemented. $course represents the returned object of a get_course($id) call. The function can return one of three possible results:

• return trigger_response::exclude(): This return value tells the core API that this course should be excluded from being processed by this and any succeeding workflow. This is no permanent exclusion. Thus, the trigger plugin is asked every time if this exclusion has changed. However, the exclusion is made if any trigger of a workflow returns this response.
• return trigger_response::next(): This return value tells the core API that the trigger does not want to launch a process for this course. The API proceeds for this course with the next workflow.
• return trigger_response::trigger(): This return value tells the core API that a process for this course should be started. However, only if all trigger of a workflow agree upon this response a process is actually started.

get_course_recordset_where($triggerid)

Making complicated queries within the check_course function can be very expensive. This is especially costly on large installations, in which a huge portion of the courses will not be triggered. For this purpose the API offers this additional methods, which allows to extend the query that selects the set of relevant courses. This way, the logic is outsourced to the database, which handles it much faster. The function can be implemented so that it returns an array tuple. The first part should contain the sql that is appended to the where clause and the second portion contains the set of parameters. The following statement selects, for instance, only the site course:

public function get_course_recordset_where($triggerid) {
        global $DB;
        list($insql, $inparam) = $DB->get_in_or_equal(SITEID, SQL_PARAMS_NAMED);
        return array("{course}.id {$insql}", $inparam);
    }

Additional common subplugin functions

There are additional functions that can offer features that trigger and steps have in common: Common subplugin features

settings.php

A settings.php can be used to define specific settings for the trigger. This file is parsed automatically and appended to the General & Subplugins administration view. You can use the variable $settings to append new settings options. An example for a working settings.php is:

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

require_once(__DIR__ . '/lib.php');

$settings->add(new admin_setting_configduration('cleanupcoursestrigger_startdatedelay_delay',
    get_string('delay', 'cleanupcoursestrigger_startdatedelay'),
    get_string('delay', 'cleanupcoursestrigger_startdatedelay'),`16416000));

For settings that are specific to an instance of a trigger have a look at Common subplugin features.

version.php

The version.php should contain at least the following values:

defined('MOODLE_INTERNAL') || die;

$plugin->version  = 2017050901;
$plugin->component = 'lifecycletrigger_<yourtrigger>';