Modules Tutorial Part 1

Redaxscript comes with a wide range of optional modules providing everything from a WYSIWYG editor to a sitemap generator, a contact form to image gallery. However, the way modules are integrated is very simple so writing your own custom module is not very difficult. You can even share your module with the community via the redaxscript-third-party repository on GitHub.

File Structure

Each module lives in its own folder within the "modules" folder in the Redaxscript installation. Each module consists of at least two files, plus a number of optional folders containing additional files.

  • modules
    • example1
      • install.php
      • index.php

For our first example we will only consider the two mandatory files. The folder name must match the alias of the module which turns up in several places as we shall see. It's important to get the naming right so that Redaxscript can tie everything together.

The install.php file contains install and uninstall functions which are called via the Admin interface. The index.php file contains the actual functionality of the module.

install.php

Unsurprisingly, install.php contains the module install function:

/** * example1 install * * @since 2.0.0 * @deprecated 2.0.0 * * @package Redaxscript Third Party * @category Modules * @author Gary Aylward */ function example1_install() { $query = 'INSERT INTO ' . PREFIX . 'modules (name, alias, author, description, version, status, access) VALUES ('First example module', 'example1', 'GaryA', 'Very simple hello world', '2.0.0', 1, 0)'; mysql_query($query); }

The install function must be named module_name_install() and the value of the alias field must also match the module name. The installation is simply an SQL query to add a record for the module into the modules table of the Redaxscript database.

The format of document block in the comments is also important, starting with /** followed by the name of the module plus 'install' on the next line.

The install.php file also includes the uninstall function:

/** * example1 uninstall * * @since 2.0.0 * @deprecated 2.0.0 * * @package Redaxscript Third Party * @category Modules * @author Gary Aylward */ function example1_uninstall() { $query = 'DELETE FROM ' . PREFIX . 'modules WHERE alias = 'example1' LIMIT 1'; mysql_query($query); }

Like the install function, the uninstall function must be named module_name_uninstall() and the alias field must be specified correctly. Uninstalling a module simply removes its database entry. The document block follows the same format as the install function.

index.php

At its simplest, index.php contains just one function called module_name() which may or may not take some arguments. example1 is a simple "Hello World" function that takes one optional argument.

/** * example1 * * @since 2.0.0 * @deprecated 2.0.0 * * @package Redaxscript Third Party * @category Modules * @author Gary Aylward * * @param string $name * @return string */ function example1($name = 'world') { $output = '<span>Hello ' . $name . '</span>'; return $output; }

The function is very simple and returns a string containing the required HTML. As yet, there is no axclamation mark as part of our greeting. Redaxscript handles special characters like this via its language sysrtem which will be explained in part 2. Note that the comment block contains lines describing the input parameters and the return value type.

The index.php file can contain as many php functions as necessary; the entry point is always the function called module_name() but it can in turn call other functions. The module can also access the Redaxscript database, PHP constants and so on. Look at the code for some of the bundled modules to see how it's done.

Using the Module

So now we have a module, how do we use it? There are two ways. The preferred way is to call the function in an article or an extra by using the function pseudo-tag:

<function>example1</function>

If you wish to pass a value to the function, the syntax changes between Redaxscript versions. For versions up to and including 1.2.1 you place the arguments after a pipe symbol following the function name:

<function>example1|"Gary"</function>

For version 2.0 onwards, you have to use JSON syntax:

<function> { "example1": { "name": "Gary" } } </function>

If your module is to be a core component of your site, you may wish to add it to your template. If you want to customise the template in this way, then be sure to create a complete custom template so that your changes don't get overwritten when you upgrade Redaxscript. To add your module to your template, you can just call the php function from wherever you need it in one (or more) of the template phtml files.

Since our example does not directly generate any output - it just returns a string - we will have to echo the function to make the output appear:

<?php echo example1("Gary"); ?>

So that's it, a simple php-only add-on module for Redaxscript. :-)

One last note, before submitting your masterpiece to the community, please make sure you install and use the QA tools. There is an easy to follow screencast to show you what to do http://www.screenr.com/w07H and a step-by-step guide in the redaxscript-third-party wiki

The screencast shows the main redaxscript repository, but you will probably want to set up the redaxscript-third-party repository instead (or maybe in addition!).

In part 2 we will make use of Redaxscript's language facilities to add translations to our hello world greeting...

No comment present.