Chapter 13. Anatomy of a Module

13.1. Overview
13.2. Folder Structure
13.3. Components

13.1. Overview

A module is a package that provides or extends functionality in Perforce Chronicle. Most of the features in Chronicle are implemented via modules. By creating your own modules you can add new functionality or modify existing features.

Modules can contain configuration, controllers, resources, view scripts, and other assets. Chronicle uses the Model-View-Controller (MVC) design pattern. Chronicle has a built-in auto loader, so there is no need to use include() or require(). If your class files are correctly named and located, Chronicle automatically loads and initializes them.

13.1.1. Required and Recommended Knowledge

To develop modules for Chronicle, you must:

  • Know PHP, and have a rough idea of how to use PHP classes and objects. Details: OOP in PHP.
  • Know the basic idea of the Model-View-Controller design pattern as implemented by the Zend Framework.
  • Have basic experience developing for the Web.

We also recommend that you know, or have some familiarity with:

Finally, the full source-generated API documentation is included with Chronicle, so you can review all of the available classes, including their descriptions, inheritance hierarchy, methods, arguments, and attributes.

13.1.2. Configuring the Application Environment for Development

When developing modules, you generally want to disable caching/aggregation and enable debugging information. You can toggle these aspects of Chronicle by setting the APPLICATION_ENV variable. To specify this setting, edit the .htaccess file, which is located in the folder where Chronicle is installed. Valid values are as follows:

  • production: (default) Errors are logged but not displayed to end users, and caching and asset aggregation are enabled.
  • development: Errors are displayed, debug information is logged, and caching and asset aggregation are disabled.

This setting also determines which section of the application.ini file is loaded, as described below.

To make more finely grained changes to your deployment, edit the application.ini file. This file can be configured to run a different Bootstrap class, add custom routing rules, change PHP settings and control many other application options and behaviors. For details, consult the Zend Application chapter of the Zend Framework Reference Guide for additional information. Default settings for the application.ini are defined in the getDefaultOptions method of the Bootstrap class; this can be a useful reference when trying to determine which properties are available for customization.

13.1.3. Request Routing

Chronicle uses Zend's routing mechanism. The default route is simply a Zend_Controller_Router_Route_Module object stored under the name (index) of 'default' in RewriteRouter. This route that matches URIs in the shape of module/controller/action. This mechanism also matches any additional parameters appended to the URI by default; for example:

module/controller/action/var1/value1/var2/value2. The index controller and the index action are defaults. If you omit the controller or action, the index versions are used. Variables and values can still be passed with these shorter URLs, if they do not collide with previously defined controllers and actions.

If you wish to define additonal routing rules for your module, you can do so either in your module.ini or, as documented by Zend, in PHP code.

Perforce Chronicle - Release: 2012.2/486814