LiveWhale modules are the bread and butter of the software. They are the construct by which you alter existing behavior or create new behaviors within the framework.

There are three primary forms of modules:

• Application modules are the most frequently created as they alter/create new behaviors around existing data types. That is, they work without referencing any data from the database or alter behaviors around the use of existing datetypes (news stories, events, blurbs, etc.). In the MVC construct, they are best described as a combination of Views and Controllers.
• Widget modules are for displaying dynamic content on your web page. In the MVC construct, they are most closely aligned with the View.
• Data modules are for creating new forms of dynamic content. In the MVC construct, they are most closely aligned with the Model.

Every custom module is built using handlers, and the most commonly-used handlers operate on $buffer variables that allow you to alter output from the CMS before your users or visitors see it.

Creating a Custom Module

When developing modules, you’ll want to make sure that the name you choose matches with what LiveWhale expects, so that all the pieces are loaded properly. An example is below, but if key pieces are based on the name “My Module,” they would appear as follows:

1. In the client/modules folder the enclosing folder would be:
   /my_module

2. The files within the /my_module folder would be (examples):
   public.application.my_module.php
   private.data.my_module.php
   public.widget.my_module.php

3. In each of the files, there should be a leading reference to append the module to the proper registered scope:
   $_LW->REGISTERED_APPS[‘my_module’] = …
   $_LW->REGISTERED_WIDGETS[‘my_module’] = …

4. In the same file, there should be a matching class, using a camelCased version of the name:
   class LiveWhaleApplicationMyModule { …
   class LiveWhaleWidgetMyModule { …

5. Within that class, there should be public methods matching any handlers you intend to use, but all other methods or properties are then open, as they are limited to your class alone. You may include/require other classes as desired, but avoid calling the same class twice (for obvious reasons). Do not call one module from another.

Here is an example with a notification module:

// in clients/modules/public_notifier/public.application.public_notifier.php
 
$_LW->REGISTERED_APPS['public_notifier']=[
     'title'=>'Public Submission Notifier',
      ...
      'handlers' => ['onAfterPublicSubmission']
];

class LiveWhaleApplicationPublicNotifier {
     ...
    public function onAfterPublicSubmission () {
        ...
    }
    ...
}

In the above, onAfterPublicSubmission is an example of a handler. Your custom module can hook into one or more of the many handlers available in LiveWhale.