Skip Navigation

Deploying Modules

When interacting with a Reason powered website, the user sees the output of various reason minisite modules running in the context of a particular template. In order to deploy modules in the Reason environment, a developer needs to be able to create new minisite modules, and setup a page type to use those minisite modules.

This document is fairly complete, but should include or link to information on cleanup_rules and acceptable parameters.

Referencing Modules

The page_types.php file is used to map sections of a template to a particular module.

From the context of the reason include directory (defined as REASON_INC in package_settings.php), the page_types.php file is located here:

lib/core/minisite_templates/page_types.php

The best practice is to leave the page_types.php file untouched, and redefine or add page types by creating a local page types file in this location (within the context of REASON_INC):

lib/local/minisite_template/page_types_local.php

The page_types.php file will look for this file, and redefine and/or append additional page type definition to the internal page types array.

Your page_types_local.php file should look something like this:

<?php
$GLOBALS['_reason_page_types_local'] = array(
'my_page_type' => array(
'main_post' => 'my_module'
)
);
?>

If you take a look at the page_types.php file, you will notice that the default page_type is defined in $page_types[ ‘default’ ]. It is unnecessary to redefine a section in a custom page type if you wish to use the same module as the default. Lets consider the example page type we setup in the page_types_local.php file described above:

The key "my_page_type" says that the name of the page type is "My Page Type". This name will appear to administrators in the Reason Administrative interface when editing a page. The array that is the value of "my_page_type" says that this page type should run in the main_post section the module located here:

lib/local/minisite_templates/modules/my_module.php (if it exists) OR
lib/core/minisite_templates/modules/my_module.php

It is important to note that the value of the key "main_post" in our definition corresponds to the name of the file (minus the php extension). When creating modules, we must setup a mapping so that the classname is discovered and instantiated as the page type directs.

Defining Modules

Defining modules for the minisites is pretty simple. Here are a few initial steps that need to be noted.

  1. The best practice is to not touch the core directory, and do all your module development in this directory, in the context of REASON_INC:

    lib/local/minisite_templates/modules/

  2. The file name of modules you create should correspond to the name in the page_types_local.php file, with the .php extension appended. In our example module "my_module," the filename should be my_module.php.
  3. In your module, you need to preface the class definition with a line that map its name to the module's class name, using this syntax:

    $GLOBALS[ '_module_class_names' ][ basename( __FILE__, '.php' ) ] = 'MyModuleMinisiteModule';
    

    Make sure that you title the class with the name you defined in the $GLOBALS['_module_class_names'] array. 

Components of a Module

All minisite modules should extend the default module or one of its descendants. In our example module, we declare the class like this:

class MyModuleMinisiteModule extends DefaultMinisiteModule

The default minisite module has three main functions that can be overloaded.

  1. init( $args = array() )
  2. has_content()
  3. run()

These methods are run in the order listed above, and we will discuss their use individually:

init( $args = array() )

The init method is always run.

The method currently takes an array called args for backwards compatibility with ancient Reason modules. You should never use it. The init method is used to setup a module, and should perform database queries, setup instance variables, require login if needed, lookup directory information, and more. The init method should never output HTML.

has_content()

Returns true or false. If has_content returns false, then the run method of a module will not be invoked. The default module return "true" so if there is the module is one that always has content, it is most efficient to not overload this method.

run()

The run method handles the output of the module. Ideally, it outputs HTML and does little else. All modules should be overloading the run method of the default module.

Complete code for the My Module module:

Here is the complete code for a simple module "My Module" which prints a stupid message for logged in users.

<?php
$GLOBALS[ '_module_class_names' ][ basename( __FILE__, '.php' ) ] = 'MyModuleMinisiteModule';

class MyModuleMinisiteModule extends DefaultMinisiteModule
{
var $netid; // store netid since we only run if the user is logged in

/**
* Stores the result of reason_check_authentication in this->netid.
*/
function init( $args = array() )
{
$this->netid = reason_check_authentication();
}

/**
* Returns true if this->netid has any content.
*/
function has_content()
{
return ($this->netid);
}

/**
* Outputs a stupid message.
*/
function run()
{
echo '<div id="mymodule">';
echo '<p>I am running only because you are logged in! Is this a stupid message or what?</p>';
echo '</div>';
}
}