Documentation for developers

This documentation explains the structure of the local plugin townsquaresupport. Goal is to make the plugin structure and components understandable and easy to work with. Please read also the developer documentation from townsquare to understand this plugin better.

1. Introduction

This plugin extends the moodle block plugin townsquare by providing a way to get more events from other moodle plugins. Townsquaresupport can host and manage subplugins, that each retrieves events from their respective plugin (e.g. subplugin "townsquareexpansion_xyz" retrieves events from the "xyz" moodle plugin).

2. Overall structure

Most of the files describe requirements for the subplugins of townsquaresupport. Only the lib.php has an executable logic, that is called by the townsquare plugin.

Requirement files:

subplugins.json and subplugins.php

These files describe, what plugin type is supported and where it is located within the local plugin. Townsquaresupport defines a new unique plugin type "townsquareexpansion". Each subplugin must be of that type and it needs to be located in the moodledir/local/townsquaresupport/townsquareexpansion/ folder to be recognized by Townsquaresupport.

townsquaresupportinterface

This interface is the core requirement file, as each subplugins declares a class that implements it. The interface declares the function and the structure as well as the attributes that it should have.

lib.php

In this has the main plugin logic. It calls all subplugins from supported type and then access the subplugins class. It is the class that implements the get_events() method. After retrieving the events, every event is getting checked for the required attributes and then added to the events array that townsquare accesses.

3. Subplugin structure and how to write a new subplugin.

Writing a new subplugin is simple and requires additional to the normal moodle files (version.php, language file) one class in the classes folder. The name of the subplugin should be the same as the name of the plugin from where events are retrieved (e.g. a townsquaresupport subplugin for the forum plugin should be named "townsquareexpansion_moodleoverflow".

A plugin structure example for the subplugin "townsquareexpansion_pluginname" looks like this:

pluginname
|
└───classes
│   |   pluginname.php
└───lang
│   └───en
│       │   townsquareexpansion_pluginname.php
│   
|   LICENSE.md
│   README.md
|   version.php

version.php:

Note, that the plugin type must be "townsquareexpansion" and that the townsquaresupport as well as the plugin you are supporting are in the dependencies:

$plugin->component = 'townsquareexpansion_pluginname';
$plugin->dependencies = ['local_townsquaresupport' => ANY_VERSION, 'plugintype_pluginname' => ANY_VERSION];
...

Class file:

In this class, the get_events() function is implemented. It is recommended to import the lib.php from the townsquare plugin to search in the same time span and courses as townsquare. A good example for the implementation of the class can be found here.

The structure should look like this:

[...]
namespace townsquareexpansion_pluginname

// Get the interface.
use local_townsquaresupport\townsquaresupportinterface;

// Access the lib.php from townsquare.
global $CFG;
require_once($CFG->dirroot . '/blocks/townsquare/lib.php');

class pluginname implements townsquaresupportinterface {
    public static function get_events(): array {
        // Get important parameters directly from townsquare.
        $courses = townsquare_get_courses();
        $timestart = townsquare_get_timestart();
        $timeend = townsquare_get_timeend();

       // Search in the database for events.
       ...
    }
}

Feel free to add a lib/locallib and other files if needed. It is recommended to use the public filter functions townsquare_filter_availability() and townsquare_filter_activitycompletions() to filter events. The rest of the logic is up to you. Notice that the user who loads townsquare should only see notifications that he should see. Knowing the plugin that will be supported by the subplugin is essential and important to avoid that the user see's unrelevant or critical information.

Townsquaresupport lists subplugins, that are considered "trustworthy" and that work perfectly with townsquare. Feel free to contact or open an issue to request an addition to this list.