Module fundamentals and naming convention

Fundamentals

Modules are a way of adding functionality to Zenario, and of changing its standard functionality. Some modules add panels in Organizer so that new administrator-facing features are available, while others can spawn plugins which are seen on the website front-end (or indeed a module can do both things). Modules can add new database tables, and make other kinds of interface changes.

Modules are created by writing a class in PHP, and adding some meta information written in YAML.

To create a new module, you should create a new directory in the relevant directory.

Zenario's standard modules (as written by Tribal Systems) are in the zenario/modules directory, and potentially zenario/zenario_extra_modules (less-used modules). Don't add your new module in either of those places (unless you work for Tribal Systems!)

Instead, put your new module in the zenario_custom/modules/ directory. This custom area will be protected from upgrades when you upgrade your Zenario installation.

A module needs the following as a minimum:

• A directory inside zenario_custom/modules/ with the module's name (e.g. clientname_module_name)
• A PHP file called module_code.php inside your_module_name
• A YAML file (in Zenario's TUIX user interface definition language) containing meta information, called description.yaml

And for the simplest modules:

• A PHP class defined inside module_code.php, where that class extends ze\moduleBaseClass, or it extends another class that extends ze\moduleBaseClass. The class name for the module needs to match its directory name.

While for more complex modules, the class in module_code.php and additionally:

• A subdirectory clientname_module_name/classes, which may contain subdirectories admin_boxes, organizer and visitor; if classes/ exists then its subdirectories must contain one or more separate files with classes.

Using the classes/ subdirectory is helpful to separate up the various functionalities of larger modules and is recommended for all new modules.

Module naming conventions

Directory name

A module's directory name should be of the form (replace the parts in square brackets with your text):

[clientname]_[module_name]

The clientname part must be a single word with no underscores. This is important!

Zenario's standard modules have "zenario" as the clientname, while custom modules written for specific customers (and located in the zenario_custom/modules directory) have the developer's name or the name of a customer, e.g. "mycustomer".

The module_name part can contain one or more words with underscores.

For example, a module for managing a database of products might be called clientname_product_manager.

Path names

When Zenario makes an Organizer panel, floating admin box or other parts of its interface, it blends together TUIX paths (which can be represented as JSON objects) from a range of modules. To the extent that paths' names match, the objects will be merged together into a larger object that in turn defines the interface.

Your module's paths must all start with the same clientname as the module directory name.

Your module may have a number of paths for various purposes, but provided they all start with the module's clientname they avoid a clash with another module.

For example, a module written for client mycustomer could use classes mycustomer_products and mycustomer_product_ranges.

Files in the classes subdirectory

A module may optionally contain a classes/ subdirectory. By putting PHP files in the classes/ subdirectory, you can separate your module's functionality into functional components:

• admin_boxes/ sub-directory for admin boxes
• organizer/ sub-directory for Organizer features, and
• visitor/ subdirectory for the FEA system of visitor-facing (i.e. front-end admin) functionality.

The directory structure, with classes/ opened out, might be like this example:

clientname_module_name/
    classes/
       admin_boxes/
          plugin_settings.php
          product_details.php
       organizer/
          product_manager.php
          products.php
       visitor/
          list_products.php
          view_products.php
    db_updates/
        tables.inc.php
    description.yaml
    js/
       plugin.js
    latest_revision_number.inc.php
    module_code.php
    tuix/
       admin_boxes/
          plugin_settings.yaml
          product_details.yaml
       organizer/
          product_manager.yaml
          products.yaml
       visitor/
          list_products.yaml
          view_products.yaml

If classes/ exists, it must contain at least one of the three lower-level subdirectories, and if a lower-level subdirectory exists it must contain at least one PHP file. (If, for example, you don't need an FEA-based interface (front-end admin), then you would not need the visitor/ subdirectory, and so it would be omitted.)

The names of the files in the classes/ must correspond to the name/tag-path of the Organizer Panel/Admin Box/Plugin Mode that they are for. (However the clientname portion of the tag-path is omitted, if it contains the client name.)

If you get this filename wrong, Zenario won't be able to find the correct file when displaying your Organizer Panel/Admin Box/Plugin Mode, and you will see an error message that tells you the name of the file that Zenario was expecting to find. (Note: this error message only appears from version 8.7 onwards.)

These PHP files need to contain the definition of a PHP class in the following format:

clientname_module_name__type__name

Note the double underscores.

For example, if you have files:

classes/organizer/name_of_organizer_panel.php
classes/admin_boxes/name_of_admin_box.php
classes/visitor/name_of_mode.php

then their classes would be as follows:

clientname_module_name__organizer__name_of_organizer_panel
clientname_module_name__admin_boxes__name_of_admin_box
clientname_module_name__visitor__name_of_mode

Again, if you get this wrong, you will see an error message that explains what the class name should be.