-
Notifications
You must be signed in to change notification settings - Fork 32
Writing your own Step Subplugin
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:
- lang file
- lip.php with the functions:
- version.php
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:
- process_course()
- process_waiting_course()
- rollback_course()
- pre_processing_bulk_operation()
- post_processing_bulk_operation()
More detailed descriptions of the functions can be found below.
Further each step can specify some settings for a step instance. For this functionality three methods are of interest:
- instance_settings()
- extend_add_instance_form_definition()
- extend_add_instance_form_definition_after_data()
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
Create a file lang/en/cleanupcoursesstep_.php containing at least:
$string['pluginname'] = '...';
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.
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.
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 the all instances of this step subplugin are shown to the user.
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_cleanupcourses\step;
use tool_cleanupcourses\response\step_response;
defined('MOODLE_INTERNAL') || die();
require_once(__DIR__ . '/../lib.php');
class <yourstep> implements libbase {
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.)
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.
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.
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.
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.
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.
The version.php should contain at least the following values:
defined('MOODLE_INTERNAL') || die;
$plugin->version = 2017050901;
$plugin->component = 'cleanupcoursesstep_<yourstep>';