Skip to content

Writing your own Step Subplugin

Jump to bottom
Nina Herrmann edited this page Feb 8, 2022 · 11 revisions

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

To create a new step subplugin, start with creating a subfolder in the folder step. Each step 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:

Functionality of a step subplugin

Course Processing

Each step can specify a bunch of actions, which are executed for courses being at this step. Relevant functions for this purpose are placed within the lib.php and are the following:

More detailed descriptions of the functions can be found below.

Define Settings

Further each step can specify some settings for a step instance. For this functionality three methods are of interest:

see Common Subplugin features

Interaction with users

To offer a central location for all user interactions, each step subplugin is allowed to specify the way of interaction within an optional interactionlib.php

File structure

lang file

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

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

interactionlib.php

When an interactionlib.php is defined, the user can get a list of all courses, which are currently at this step and which await information from the user. This list is provided via the view.php from the core plugin and adds a set of action tools to each course, which can be triggered by the user.

get_relevant_capability()

This function returns the capability string, which should be used for determining whether the user should have access to this course, within the view.php.

show_relevant_courses_instance_dependent()

The view.php always has to be called with the id of the step instance as "stepid" parameter. While some step subplugins might want to show the list of courses dependent on this single step instance, some others might want to show all courses for this step subplugin, independent on the particular instance the course is currently at.

  • true: Only those courses of the given step instance are shown to the user.
  • false (default): All courses of all instances of this step subplugin are shown to the user.

get_action_tools()

This function allows to define the set of actions, a step subplugin offers. The function has to return an array, which contains one entry for every possible action. Each action is again an array with two entries:

  • 'action' => an action string, which is later passed to handle_interaction MUST BE PARAM_ALPHA (no underscores etc. just a-z,A-Z)
  • 'alt' => a string text of the button Each action will result in a button within the interaction table displayed to the end user.

get_status_message(process)

This function returns a status string, which is displayed to the user for every course that is currently processed by an instance of this step.

handle_interaction($process, $step, $action)

This function is called, whenever an action is triggered by a user. The variable $action hold then the identifier of the action defined under get_action_tools(). Possible return values are the values of step_interactive_response:

  • proceed: The step instance has finished and the process can proceed to the next step.
  • stillprocessing: The step instance still wants to process this course.
  • noaction: The transferred action string is not defined for this step.
  • rollback: The process should be rolled back.

lib.php

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

namespace tool_lifecycle\step;
use tool_lifecycle\response\step_response;
defined('MOODLE_INTERNAL') || die();
require_once(__DIR__ . '/../lib.php');

class <yourstep> implements libbase {

process_course()

Then, the function process_course($course) has to be implemented. $course represents the returned object of a get_course($id) call. The function executes some work and then return one of three possible results:

  • return step_response::proceed(): This return value tells the core API that the step is finished processing the course and the process can be proceeded to the next step.
  • return step_response::waiting(): This return value tells the core API that the step has not finished processing with the course. It is probably waiting for some user input. See process_waiting_course() and interactionlib.php, if you want to use this state.
  • return step_response::rollback(): This return value tells the core API that the deprovision process for this course is canceled and all changes made to the course so far, should be rolled back. (The rollback of changes is not yet implemented! Currently, the process is simply terminated.)

process_waiting_course()

This function is optional, but has to be implemented if process_course() returns step_response::waiting() in some cases. The function works in the same way as process_course(), but it is only called for courses in state waiting.

rollback_course()

This function is optional. In theory a process can be aborted and 'rolled back' at any time during its execution. This rollback could for example be triggered during a user interaction. In this case, the rollback_course function is called for every already processed step in reverse order. This functionality gives each step plugin the possibility to clean up or revert changes done to the course. An example of this is the makeinvisible step plugin, which is able to reset the visibility state of a course in case of a rollback.

*_processing_bulk_operation()

If you want to do some work, independent of a specific course, such as bundling emails to users before sending them out you can use the two methods pre_processing_bulk_operation() and post_processing_bulk_operation(). The first one is called before calling process_course() and process_waiting_course() for every single course. The second one is called afterwards.

get_subpluginname()

This method has to be implemented. It returns the technical name of your step subplugin, which is equivalent to the name of the folder of your subplugin.

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 step. This file is parsed automatically and appended to the General & Subplugins administration view. You can use the variable $settings to append new settings options or use $ADMIN->add(...) to add any other navigation node to the admin settings. An example for a working settings.php is:

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

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

if ($hassiteconfig) {

$ADMIN->add('lifecycle_category', new admin_externalpage('lifecyclestep_adminapprove_manage',
        get_string('manage-adminapprove', 'lifecyclestep_adminapprove'),
        new moodle_url('/admin/tool/lifecycle/step/adminapprove/index.php')));

}

For settings that are specific to an instance of a step 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 = 'lifecyclestep_<yourstep>';
Clone this wiki locally