So far in this chapter, we have seen examples of simple Tags and User-Defined Tags. The last remaining type of extension to explore is the Module.
This recipe will show you how to create a simple Module for CMS Made Simple.
This recipe requires access to your site's Administration area with "Add Pages" and "Modify Modules" permissions, and permissions to create a file on the server.
1. Find your CMS Made Simple base install directory. Within that directory will be a "Modules" directory.
2. Inside the "Modules" directory create a new directory, and name it
"HelloWorld"(keeping in mind that the directory name is case-sensitive in most operating systems).3. Open your favorite text editor, and type in the following code:
<?php class HelloWorld extends CMSModule { functionGetName() { return 'HelloWorld'; } functionIsPluginModule() { return true; } functionDoAction($action, $id, $params, $returnid=-1) { echo 'Hello World. Welcome to the '.$this->GetName().' module (version '.$this->GetVersion(); echo ') running in CMS Made Simple version '.CMS_VERSION; } } ?>4. Save this file in your new
"HelloWorld"directory with the filename"HelloWorld.module.php"(again, keeping in mind that most operating systems are case-sensitive).5. Log in to your CMS Made Simple admin area.
6. Using the top menu, go to "Extensions" and click on "Modules".
7. Click on "Install" next to the HelloWorld module.
8. On the top level menu, select "Content" and click on "Pages".
9. Click on the "Add New Content" button.
10. Fill in the name of the new page as "Hello World."
11. Enter "Hello World" as the menu text.
12. For the page content, put in the tag for your new Module
{cms_module module='HelloWorld'}, then hit "Submit".13. View your site from the user side. Click on the new "Hello World" page.
14. Admire the output from your Module!
When you install CMS Made Simple, one piece of the core library that gets installed is the CMSModule base class. This class includes a vast collection of useful methods for simplifying all kinds of module-related tasks; we refer to this collection as the CMS Made Simple Module API (or, more briefly, the Module API).
When you implement a module, you do it by extending the CMSModule base class. By extending the CMSModule class, your code automatically inherits all of the methods of the Module API. As you can see in the previous code, the first thing you do is declare the Hello World Module's class as an extension of the CMSModule class.
Next, your job as a module developer is to identify which methods of the CMSModule class you will be calling or overriding in order to solve your particular programming problem. The Module API has in excess of 225 methods. Fortunately, there are only a few dozen you'll ever need to override. In fact, as this recipe shows, you can implement a Module by overriding only three methods!
The first method you override needs to be the GetName() method. This method must return the class name of your module. Be careful here, since it is case-sensitive and must match both the name of the class and the name of the primary Module file!
The second method you need to override is the IsPluginModule(). This returns a true or false value, depending on whether your module will be inserted into your site using a Smarty tag. The base method in the CMSModule class returns false. In our case, we are writing a Plugin module, so we return true.
The last method that you will need to override is the DoAction() method. This is the method that actually gets called by CMS Made Simple, and it's where your module performs its appointed purposes. If you're writing a Plugin module, any output created by this method replaces the module tag in your page or template. In this simplest case, we ignore the parameters to this method, and just output our string.
Just to add interest, the string we output in this example makes a few API calls. Because the API calls are methods that are inherited from the base CMSModule class, these methods are part of our current Module object, so we call them via the $this reference. The function of the two methods we call are evident from their names: GetName() returns the name of the Module, and GetVersion() returns the version of the Module. In our example, we have overridden the base class's definition of GetName(), but we have not overridden the base class's definition of GetVersion(). As you see in the output, the base GetVersion() method defaults to returning a version number of "0.0.0.1".
We also make reference to a special PHP define called CMS_VERSION. This define is set by the CMS, and contains the version of the CMS Made Simple installation.
Don't let the simplicity of this example deceive you! The majority of the recipes in this book involve different aspects of the Module API, and some of its powerful capabilities.