Example Module 5: a plugin to show how to extend an Organizer application

In the guide Example Module 4: An Organizer Application we showed you how to create an application in Organizer from scratch.

However in many real world cases you may find that the functionality of the product may not do exactly what you need. Perhaps there is a field missing or you want to add some bespoke logic at a certain point.

In this example, we'll show you how to take a module that already exists and add extra functionality. The Animal Manager Module from Example Module 4: An Organizer Application can be extended in the following ways:

• Add a new field called Classification
• Create a new table in the database, which has a foreign key to the animals table and will be used to store the value of the new field
• The module will listen for the exampleModuleEventAnimalDeleted signal and tidy up by removing the value of the deleted animal from the table
• The module will listen for the exampleModuleEventAnimalCreated signal and send an email to an administrator letting them know when a new animal has been created
• Create a site setting to let an administrator change which email template is sent

The description.yaml file

This new module won't be able to run unless Example Module 4 is also running so we need to list it as a dependancy.

In order to receive a signal, we also need to list the signals that we listen for in the description.yaml file. (The CMS will not call the module when these signals happen unless they are listed here.) 

N.b. if you ever change which signals a module listens to in its description.yaml file then you will need to increase the number in the latest_revision_no.inc.php file and then apply database updates before your changes will take affect.

Creating Email Templates

Currently there's no API function to define a new email template. To create one you must write a database update that inserts a new row into the email templates table.

When you define your email template you should be sure to give it a code name. You can then use the code name to refer to it in your static YAML files.

In your PHP code you can also refer to an email template by its id, but as this will be a different number for every site you can't refer to it in the static YAML files.

Defining new site settings

You can create a new Site Setting by targeting the Site Settings panel and the Site Settings Admin Box in the core CMS and merging in new fields.

The tuix/organizer/site_settings.yaml file defines a new site settings group by adding another item into the Organizer panel that displays that group.

The tuix/admin_boxes/site_settings.yaml file defines three new site settings by adding three fields into the Admin Box for the group that we just created.

Handling Signals

If your description.yaml file says that your module handles a signal, when the CMS receives the signal it will look for a method in your module with the name of the signal and then call it.

For example, Example Module 4 sends a signal called exampleModuleEventAnimalDeleted, and when it sends this signal it also provides the id of the deleted animal. So to handle this signal, a module would need a method called exampleModuleEventAnimalDeleted with one input parameter called $id.

You can see which signals are available and what parameters they have by reading documentation, by reading examples or - if these are not available - by reading the source code and looking for the sendSignal() function.