Example Module 4: a plugin to show an Organizer application

The Animal Manager is a sample Organizer application that enables an administrator to manage a set of data records containing "animals".

It demonstrates how to create a management panel in Organizer, with full support for creating, editing, deleting, listing and searching.

Database updates

If you wish your module to create a database table, you will need to create a directory called db_updates/ and place one or more php files in this directory.

Database update files can have any name as long as they end in .inc.php; the CMS will scan your db_updates/ directory and run them alphabetically.

They should contain one or more revisions. Each revision must have:

• A revision number that is no smaller than the revision numbers above it, and no larger than the current revision number of your module.
• One more more SQL statements to run, with multiple SQL statements separated by a comma.

The latest_revision_no.inc.php file

Tribiq CMS is designed to be easy to update, as are its modules.

The latest_revision_no.inc.php file inside your module's directory contains a number which is the current version number of your module.

If you make changes to your module's database schema or description.yaml file, you should increment this number when publishing the new version of your module.

It is important to make the revision number unique; this makes it easier to provide upgrades to your module. If an administrator has your module installed, and then you later offer an update, this number enables the CMS to compare the new version of your module with the older (installed) version of your module.

The CMS uses this number to decide whether to run any database updates included with your module. When reading the files in your db_updates directory, it will only run a revision if the revision's number is higher than the previous revision number of your module.

.yaml files for Organizer

The .yaml files in your tuiz/organizer/ directory are used to create elements in Organizer.

The tuix/organizer/_navigation.yaml file contains the specification for navigation elements. (The "_" in the file's name has no special meaning; it is just there to ensure that Organizer reads this file first as Organizer reads files alphabetically.)

The tuix/organizer/animals.yaml file contains the specification for a panel in Organizer. It includes snippets of SQL code that the CMS uses to populate items in the panel, some columns and some buttons.

Merging .yaml files

Whenever the CMS encounters multiple .yaml files containing the same tag path, it will "merge" them together as it reads them. This means that the elements in one file will appear alongside the elements in another.

If you view this module's panel in the dev tools, you will be able to see the source files and their contents, as well as the result of the merged files.

The fillOrganizerPanel() Method

The fillOrganizerPanel() method of your module will be called by the CMS every time one of your panels is displayed. It lets you customise or dynamically change things inside the panel.

If you have created more than one panel, or if you have placed elements on more than one panel, you will need to check the $path variable to know which one is being displayed.

The handleOrganizerPanelAJAX() Method

The handleOrganizerPanelAJAX() method of your module will be called by the CMS when an administrator clicks on an AJAX button in your panel.

In this example, it handles when the administrator clicks on the "delete" button.

.yaml files for Admin Boxes

The .yaml files in your tuiz/admin_boxes/ directory are used to create Admin Boxes, and define tabs/fields inside them.

The tuix/organizer/animals.yaml file contains the specification for a simple Admin Box with one tab and two fields.

The fillAdminBox() Method

The fillAdminBox() method of your module will be called by the CMS every time one of your Admin Boxes is displayed. It lets you customise things inside the Admin Box and load the values of your fields.

If you have created more than one Admin Box, or if you have placed elements on more than one Admin Box, you will need to check the $path variable to know which one is being displayed.

The validateAdminBox() Method

The validateAdminBox() method of your module will be called by the CMS if someone is editing a tab on your Admin Box. It lets you add validation for the values that have been entered.

The saveAdminBox() Method

The saveAdminBox() method of your module will be called by the CMS when an administrator clicks on the "Save" button on your Admin Box. It lets you save the values they have entered into the database.

Your saveAdminBox() method will only be called if your validateAdminBox() method did not find any errors.

Merging with .yaml files from other Modules

You can also write .yaml files that create new elements in Organizer panels and Admin Boxes from other modules.

The tuix/organizer/admin_perms.yaml file contains some checkboxes to add to the "Permissions" tab of an administrator's property box. This adds four new administrator permissions to the CMS.

Using Admin Phrases

Whenever you output text to an administrator, if it's not in a .yaml file then you should use the adminPhrase() function.

Just like the normal phrase() functions for visitors, you can use English text as your phrases or a phrase code.

We recommend that you use English text rather than codes. If you use codes, then you will need to define text for them in a flat-file-database, and save this as a text file called admin_phrase_codes/en.txt.

Testing your Module

When this module is running you will see a new entry in the left-hand column that looks like a paw-print. (This icon can be changed by editing the adminstyles/organizer.css file if you wish.)

Clicking on this will open the Animal Manager and enable you to start adding Animals!

You should now be able to interact with your Organizer application, to create, edit and delete "Animals".