Writing an Exponent CMS Module

I recently wrote a plug-in module for Exponent CMS. I really like the CMS and is very capable to do what I would like. However, when I set out to write my own custom module, I found the documentation lacking. In this article, I’ll outline some tips to help you get started writing a module for Exponent CMS.

Debugging
The first thing to do when writing your own module is to turn on debugging. This is easily done by editing a setting in the pathos_version.php file as described in the Exponent CMS FAQ

Required Files
Start out by making a new folder under the modules folder. Another thing you can do is just make a copy of an existing simple module, such as textmodule, and rename it. For this example, we’ll call it mymodule.

So, here are the files that are needed to accomplish basic tasks.

modules/mymodule/class.php
This is the main file that encompasses the basic module structure. If you’ve copied this from another module, be sure to also rename the class.

modules/mymodule/actions/myaction.php
All the files in this actions folder can be used to define all of the major services that the module provides. The file can be as simple as calling a method of the class like this:
mymodule::myaction(DEFAULT_VIEW,$loc);

modules/mymodules/views/Default.tpl
This template file defines the default view of the class. When you add the module to a page, this is the default template that is rendered. If there are other templates in this folder, they will be selectable when setting up the module for the page.

In the template, you can create a reference back to the action that was previously created. For example:
<a href="{link action=myaction}">myaction</a>

modules/mymodules/views/_standard.tpl
This file is needed to define permissions and configuration for the module. If you want to have your own custom configuration options for the module, make sure that _standard.tpl has this additional block

{if $permissions.configure == 1}
	<a href="{link action=configure _common=1}"
        title="Configure My Module">
        <img class="mngmnt_icon" border="0"
        src="{$smarty.const.ICON_RELATIVE}configure.png" /></a>
{/if}

We’ll define those configuration parameters in a moment, but I want to draw attention to the _common=1 parameter in the second line. This parameter tells exponent that you want to use the default forms for your configuration settings. This actually loads up another module called common and uses its _configure.tpl view to handle your custom settings.

datatypes/mymodule_config.php
Here, we’re creating a new class to handle the loading and storing of custom data you need for your module.

datatypes/definitions/mymodule_config.php
This file defines the actual data types you will be using. For example, if you want a 200 byte string for a URL, add this to the array.

'myurl'=>array(DB_FIELD_TYPE=>DB_DEF_STRING,
	     DB_FIELD_LEN=>200),

With that set up, you can click on the little wrench icon when logged in as the admin to set your custom parameters. To use those values in the code, start out by instantiating an instance of your config class.

$config = $db->selectObject("mymodule_config",
"location_data='" .serialize($loc)."'");

The location data here is important because this will load the data for that instance of the module. As you may know, you can reuse modules all over the Exponent CMS system. You also have the choice of creating a new dataset or reusing the dataset of another instance of the module. The location data keeps all of that straight.

Then, you can simply reference it by the name you chose for it in your datatypes/mymodule_config.php file.

$config->url

subsystems/lang/en/modules/mymodule.php
Last, but not least are translated strings. Any strings that are displayed to the user should be defined in this file and the defines are included in your module files.

define('TR_MYMODULE_URL', 'My URL');

Hopefully this little article gets you started creating an exponent CMS module. I know when I started it would have been nice to just know how some of these files were connected together. Use this along with the other modules as examples to help create your new module.

More Information

If you want to go deeper with Exponent CMS, here are some more resources to get you going.

  • Exponent CMS Website – The main website of Exponent CMS. The place to download along with some user forums. Also look at the Exponent DocWiki for the official documentation.
  • Zimmertech.com – Here, you’ll find some great resources for other ways to tweak Exponent CMS for your needs. Be sure to check out the rest of the site for some cool Paintshop and other Web Design tutorials.
  • Advertisements
This entry was posted in PHP, Programming, Website. Bookmark the permalink.

3 Responses to Writing an Exponent CMS Module

  1. Tim says:

    Nice Job!
    I want to share this nice tut with other people on a just starting german site. I hope you are glad when i take this article as a base for a german modulwriting guide!?
    Maybe we meet us there.
    Nice Page! so long Tim

  2. Firstiar says:

    Nice. But, still, assuming that I’m a newbe on exponent, I still cannot make a clean module from scratch. Because I still don’t know which one is *a must* function and which one is module specific function in the class.
    There’s still no standard rules which define what function I should have when I want to create just a simple and clean module. Much or less, a module template.
    Do you have any information regarding this?

  3. Rodrigo says:

    Thank you, this tutorial has given me a much needed kick start. However, i’m on the same boat as Firstiar i.e. i am a newbie to exponentCMS. I’ve followed your steps describe above with the latest version 97.0 running on a linux box, but i can’t seem to get the module listing. I would like to simply install my php classes using my own db connections, this is because i’m connecting to an mssql db.

    I’d appreciate it very much if you could lead me on the right direction.

    Regards,
    Rodrigo

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s