If you're reading this book, you already know that CMS Made Simple is a powerful system for creating websites. Even the base install enables you to easily produce sites with many sophisticated features. There are times, however, when you need to be able to do things that are beyond the basic capabilities. You can often find pre-made extensions on the official CMS Made Simple sites: Tags and Modules in the Developer's Forge (or directly through the Module Manager), and examples of User-Defined Tags on Wiki or posted in the forum.
What are these different kinds of extension? This chapter will answer that question in greater detail. However, we will define them briefly here. All three types of extension share some things in common: they are PHP code which can be embedded in site pages, templates, or Global Content Blocks, or may be called by other code. A User-Defined Tag is distinct in that you can create and edit it through the CMSMS admin area. A Tag is similar, but must be placed as a file on your server, and provides more information to the site administrator. A module has available to it the rich functionality of the Module API, and enables the creation of much more complex applications.
As mentioned before, there is a wealth of pre-made extensions which are available to you. But even if these pre-made extensions don't meet your needs, all is not lost. You can jump in and create your own extensions! You will discover that the power of CMS Made Simple is only limited by your imagination.
Note
In this chapter, we will learn how to approach the problem you're trying to solve. Is it something that can be solved without writing an extension? Would you be able to use or adapt an existing extension? If not, what conditions will the extension need to handle? The requirements that you think of will help you determine what kind of extension you should implement.
There are three recipes here that will help you to identify which kind of extension is appropriate for a given problem, and three recipes that go over the basics of creating each major type.
You have reached the point where you know you need to extend CMS Made Simple to solve some particular problem, but you may not yet know what approach to take. Your options are to create a Tag, a User-Defined Tag (UDT), or a Module, but which will be best to solve your specific problem?
This recipe will help you examine your problem and consider whether creating a UDT is the most appropriate solution.
First, we determine if the problem you want to solve is one that will require you to write some custom code. This is the easy part. You've already considered whether or not an existing solution will suffice and have decided that it will not. So the next step is to figure out whether or not a User-Defined Tag is the correct approach to solving the problem.
Go through the following list, and for each item, determine if it applies to the problem you are trying to solve. Feel free to write down a list of your answers (yes/no).
1. Can your problem be solved with Smarty logic or standard CMS authoring practices like using Global Content Blocks in your page template?
2. Are you trying to solve a problem that requires multiple actions? An example of multiple actions would be both displaying a form and processing its results.
3. Will you need to support localization and internationalization to solve your problem? For example, if your code will be displaying messages, will the messages need to be translated into multiple languages?
4. Will your solution require an Administration panel?
5. Will you want to share this solution with other people so that they can install it into their own CMS Made Simple sites?
6. Do you need to create new database tables or set up new preferences to solve your problem?
7. Do you want your code to display help text in the Admin area, so site administrators understand what parameters are available and what the code does?
8. Will your solution serve as a Smarty modifier (a modifier in Smarty is a function that does something to convert a variable for display)? An example of a Smarty modifier would be
{$variable|uppercase}where the modifier ("uppercase") serves to transform the variable ("$variable").
If you answered "no" to all of the above questions, a User-Defined Tag is a good candidate!
A User-Defined Tag is a way to connect a tag, that will be recognized by Smarty, to an arbitrary bit of PHP code. That PHP code can do anything. While there are very few things that cannot be done in CMS Made Simple using UDTs, it doesn't necessarily mean that a UDT is the best approach for everything. Because User-Defined Tags are so versatile, the best way to determine if they are the ideal approach is by disqualification. We ask questions about the few things for which UDTs are less optimal, to see if any of those things match our requirements. If none of them match, then a User-Defined Tag is probably the best approach.
If we do find that our requirements include functionality for which UDTs are not ideally suited, we should consider using a Tag or a module instead. We will explore these options in greater detail elsewhere in this chapter.
For now, let's look at those qualifying questions again and examine why they would encourage us to use a different approach.
|
Disqualifying Question |
If you answered "Yes" |
|---|---|
|
Can the problem be solved by simply using Smarty? |
We don't need to write any PHP code at all! For some great examples, please see Chapter 2, Programming with Smarty and Core Modules. |
|
Does your problem require multiple actions? |
It is, in fact, possible to handle multiple actions using a User-Defined Tag, but it is not elegant. If you need to support multiple actions, the CMS Made Simple Module API has extensive support for doing so, as well as conventions that will help keep the code separated nicely into maintainable chunks. |
|
Do you need localization or internationalization? |
Again, this would be possible to do in a User-Defined Tag, but you would have to do all the work. The Module API provides utilities for simplifying this enormously. |
|
Will you need an Administration Panel? |
There is no easy way to implement an Administration panel in a UDT, so this would strongly push you in the direction of using a Module, where a rich set of functions make the task easier. |
|
Will you want to share your code? |
While nothing would stop you from sharing the code you write as a User-Defined Tag, there are neither facilities for making the process simple nor standards for documenting the UDT. Furthermore, UDTs exist only in the database, as contrasted with Tags and Modules that exist as files, so they are not as easy to simply package up and share. |
|
Do you need to create database tables or preferences? |
You could write logic into your UDT to check on the existence and conditionally create database tables or preferences, but it would be easier to use the Module API that has specific support and standards for doing those operations. |
|
Do you want your code to display help text in the Admin area? |
As mentioned before, User-Defined Tags offer no facility for displaying help text to the Admin. Both Tags and Modules, on the other hand, have standard methods for doing so. |
|
Will your solution serve as a Smarty modifier? |
User-Defined Tags cannot natively work as Smarty modifiers, while Tags can do so easily. |
As in the previous recipe, you know that we have three different possibilities for extending CMS Made Simple and solving a problem: User-Defined Tag, Tags, and Modules. Deciding which of these is the best approach, however, requires additional knowledge about the strengths and weaknesses of each technique.
This recipe will help you examine your problem and consider whether creating a Tag is the most appropriate solution.
The criteria for deciding to use a Tag to extend CMS Made Simple are quite similar to the criteria for a User-Defined Tag.
To figure this out, consult the following list, and determine if each item applies to the problem you are trying to solve. Feel free to write down a list of your answers (yes/no).
1. Can your problem be solved with Smarty logic in your page template?
2. Are you trying to solve a problem that requires multiple actions? An example of multiple actions would be both displaying a form and processing its results.
3. Will you need to support localization and internationalization to solve your problem? For example, if your code will be displaying messages, will the messages need to be translated into multiple languages?
4. Will your solution require an Administration panel?
5. Do you need to create new database tables or set up new preferences to solve your problem?
If you answered "no" to all of the above questions, either a Tag or a User-Defined Tag would be a viable approach. To decide whether a Tag would be better than a UDT, consider the following questions:
1. Will you want to share this solution with other people so they can install it into their own CMS Made Simple sites, or will you want to reuse this code yourself on other sites?
2. Do you want your code to display help text in the Admin area, so site administrators understand what parameters are available and what the code does?
3. Will your solution serve as a Smarty modifier? A Smarty modifier is a function that reformats a variable for display, for example,
{$variable|uppercase}where the modifier("uppercase")serves to transform the variable ("$variable").
If you answer "yes" to any of these three questions, you should write a Tag instead of a User-Defined Tag.
A Tag is a way to connect a Smarty tag to some PHP code. The PHP code can do anything. Like in the case of User-Defined Tags, there are very few things that cannot be done in CMS Made Simple using Tags.
Because Tags are so versatile, the best way to determine if they are the ideal approach is by disqualification. We ask questions about the few things for which Tags are not ideal, to see if any of those things match our requirements. If none of them match, then the problem could be solved by either a Tag or a User-Defined Tag. To make the decision between those two approaches, we consider a few other criteria that will steer us in the right direction.
Let's consider the disqualifying questions again and examine why they would encourage us to use a different approach. The first five questions are the same as they were for User-Defined Tags.
|
Disqualifying Question |
If you answered "Yes" |
|---|---|
|
Can the problem be solved simply using Smarty? |
If this is the case, we don't need to extend CMS Made Simple at all! For some great examples, please see Chapter 2, Programming with Smarty and Core Modules. |
|
Does your problem require multiple actions? |
It is, in fact, possible to handle multiple actions using a Tag, but the CMS Made Simple Module API has extensive support to simplify multiple actions, as well as conventions that will help keep the code separated nicely into maintainable chunks. Thus a Module would be a much better choice. |
|
Do you need localization or internationalization? |
These features could theoretically be implemented using a Tag, but there is no built-in support for either. The Module API, on the other hand, has facilities specifically to simplify those tasks. |
|
Will you need an Administration Panel? |
There is no easy way to implement an Administration panel in a Tag, while the Module API has numerous methods specifically for this purpose. |
|
Do you need to create database tables or preferences? |
You could write logic into your Tag to check on the existence and conditionally create database tables or preferences, but it would be easier to use the Module API which has specific support and standards for doing those operations. |
Now, let's consider the three things that differentiate a Tag from a User-Defined Tag:
|
Tag Qualifying Question |
If you answered "Yes" |
|---|---|
|
Will you be sharing this solution with other people? |
A Tag is stored as a file on the server, which makes it easier to share with other CMS Made Simple users, since they can simply place the file in their own installation. A User-Defined Tag, on the other hand, is stored in the database, that adds extra steps if you want to share it. |
|
Do you want your code to display help text in the Admin area? |
The structure of a Tag has a special method for presenting information to the site administrator, while a User-Defined Tag has no such mechanism. |
|
Will your solution serve as a Smarty modifier? |
There are several kinds of Tags, including Smarty modifier tags. There is only one kind of User-Defined Tag, and it will not work as a Smarty modifier. |
The previous two recipes have shown you how to assess two possible types of CMS extension, and to see if they are optimal for any specific problem. This recipe rounds out the analysis and shows you how to determine whether creating a Module is the most appropriate solution.
By examining your requirements, and comparing them to the strengths of the Module API, we can figure out whether or not a Module is the best way to implement your extension.
To do so, consult the following list, and determine if each item applies to the problem you are trying to solve. Feel free to write down a list of your answers (yes/no).
1. Are you trying to solve a problem that requires multiple actions? An example of multiple actions would be both displaying a form and processing its results.
2. Will you need to support localization and internationalization to solve your problem? For example, if your code will be displaying messages, will the messages need to be translated into multiple languages?
3. Will your solution require an Administration panel?
4. Will you want to share this solution with other people so they can install it into their own CMS Made Simple sites?
5. Do you need to create new database tables or set up new preferences to solve your problem?
6. Do you want your code to display help text in the Admin area, so site administrators understand what parameters are available and what the code does?
If you answered "yes" to any of the above questions, a Module is going to be the best way to implement your extension — with one possible exception. If you want to write an extension that you can apply to Smarty variables within a template to reformat their output (that is, a Smarty modifier), you will need to use a Tag. However, outside of that one case, a Module will be your best bet. If you answered "no" to all of the above questions, you could still use a module, but you might want to consider using a Tag or User-Defined Tag, as you will still be able to solve your problem with less complexity and overhead.
A Module is PHP code that extends the CMSModule Class, which means that you start with a rich API that will save you a great deal of work. Module code can do virtually anything that PHP can do. The only thing that Modules cannot do (and which Tags can do) is act directly as Smarty modifiers.
Modules are extremely powerful and versatile, but that power comes with additional complexity. If you find that it would be possible to solve your problem with a Tag or User-Defined Tag, you should opt for the simpler approach. If, however, your requirements go beyond the capabilities of those extensions, there are very few limits to what you can accomplish with a Module!
If you have decided to create a User-Defined Tag to solve a problem, you might want to know what a UDT looks like.
This recipe shows you how to make a simple User-Defined Tag.
Like most of the recipes in this book, you will need to have CMS Made Simple installed and working. You will need login access to the site's Administration area as a member of the "Admin" group (or as a member of a group with "Modify User-defined Tags" and "Add Pages" permission settings).
2. On the top menu, select "Extensions" and click on "User-Defined Tags".
3. Click on the "Add User Defined Tag" button.
4. Enter the name "helloworld" in the"Name" field for your new User-Defined Tag.
5. Enter the following code snippet into the "Code" field, and click on"Submit".
echo "Hello World, Welcome to CMS Made Simple version ".CMS_VERSION;
6. On the top level menu, select "Content" and click on "Pages".
7. Click on the "Add New Content" button.
8. Fill in the name of the new page as "Hello World".
9. Enter "Hello World" as the menu text.
10. For the page content, put in your new tag
{helloworld}, and then hit "Submit".11. View your site from the user side. Click on the new "Hello World" page.
12. Admire the output from your User-Defined Tag!
A User-Defined Tag is a way of attaching arbitrary PHP code to a Smarty tag. When the CMS Made Simple templates get parsed, Smarty will call the User-Defined Tag and execute the code. Any output from the code will be substituted into the template at the point of the tag.
Our basic example creates a Smarty tag which is called "helloworld." The code for the tag simply outputs a string of text, in this case, the welcome message. To add a bit of interest, we also have it output some useful information: the version of CMS Made Simple that you're running. That value is available in CMS Made Simple via a PHP define, and it can be used in any code run by the CMS.
Keep in mind that CMS Made Simple page content is also sent to Smarty for processing — even though we consider it "Content", Smarty regards it as a template. This means that you can place your User-Defined Tag in your underlying page template or in your page content, and it will work just the same either way.
We've seen that any output from a User-Defined Tag gets substituted for that tag in the final rendering of the page. It may not be obvious at first, but UDTs aren't required to produce output at all! A User-Defined Tag may do invisible things behind the scenes: set a flag in the PHP session object, update a counter, and even generate an e-mail. If a UDT does not create any visible output, its Smarty tag will simply be removed from the finally rendered page.
CMS Made Simple has mechanisms built-in for caching pages in order to improve performance. Under normal circumstances, a User-Defined Tag is not cached — if the UDT creates output, that output is not cached. Similarly, if a UDT does not create any output, it will be called even if the page itself is cached.
You have decided that you want to create a Tag to add some functionality to your site, but you don't yet know what this entails. This recipe shows you how to make a simple Tag.
For this recipe, you will need login access to the site's Administration area as a member of the "Admin" group (or as a member of a group with "Add Pages" permission settings). You will also need permissions to create a file on the server, whether via FTP or some other means.
1. Open your favorite text editing program, and create a new file.
2. Type the following code:
<?php function smarty_cms_function_helloworld($params, &$smarty) { return "Howdy, World! You're visiting a site made with CMS Made Simple version ".CMS_VERSION; } function smarty_cms_help_function_helloworld() { echo "Put the tag {helloworld} in your page or template for a special message."; } function smarty_cms_about_function_helloworld() { echo "Hello World version 1.0, written by your_name<you@yourdomain.com>"; } ?>Note
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.
3. Substitute
"your_name"with your name, and"you@yourdomain.com"with your e-mail address.4. Save this file as
"function.helloworld.php"in your CMS Made Simple base install's "plugins" directory.5. Log in to the Administration panel of your CMS.
6. Verify that the CMS sees your Tag: using the top menu, go to "Extensions" and click on "Tags".
7. Next to your new tag name, click on the "Help" link to view the help text, or on the "About" link to view the about text.
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 your new tag {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 Tag!
A Tag is a way of attaching PHP code to a Smarty tag, modifier, pre-compile function, or post-compile function. This recipe is an example of a Smarty tag.
A Tag has three functions it must declare:
the Primary function
a "Help" text function
an "About" text function
These functions are defined using a naming convention that tells CMS Made Simple what they do. For a given Tag named "helloworld," the functions are named as follows:
|
Function |
Naming Convention |
|---|---|
|
Primary function |
|
|
Help text function |
|
|
About text function |
|
When the CMS Made Simple templates get parsed, Smarty will call the Tag's Primary function. Any strings returned by this function will be substituted into the template at the point of the tag.
Our basic example creates a Tag which has a Primary function that simply returns a string of text, in this case, the welcome message. To make it more interesting, we also output the version number of your specific CMS installation. The CMS sets this version number in a PHP define, so the number is available to any Tag, User-Defined Tag, or Module.
The Help text function is typically used to describe any parameters or other usage notes for the Tag. The About text function is typically used to give the author, contact, changelog, or other non-usage information for the Tag. Unlike the Primary function that returns its output, the Help text and About text functions output directly with "echo" statements.
You can place your Tag into the content of a CMS page, into a CMS template, or even in a Global Content Block (GCB). CMS Made Simple passes all of these through the Smarty templating engine, so your tag will get interpreted the same way in any of those cases.
We've seen that any string returned from a Tag gets substituted for that tag in the final rendering of the page. It may not be obvious at first, but Tags aren't required to produce output at all! A Tag may do invisible things behind the scenes: set a flag in the PHP session object, update a counter, and even generate an e-mail. If a Tag does not create any visible output, its Smarty tag will simply be removed from the finally rendered page.
As mentioned previously, CMS Made Simple has mechanisms built-in for caching pages in order to improve performance. If your Tag implementation is not a modifier, pre-compile function, or post-compile function, you can control whether or not your tag will be cached.
If you want your Tag's output to be cached, you need to simply alter the naming convention for the Primary function from smarty_cms_function_helloworld to smarty_function_helloworld.
Tags and User-Defined Tags both establish a Smarty tag that can be embedded in your templates or pages. The Smarty syntax for both is identical. It turns out that the namespace is also shared. So what happens if you have a Hello World Tag and a Hello World User-Defined Tag and they're both known to Smarty by the tag {helloworld}? It turns out that User-Defined Tags have precedence, so in this situation, the output will be from the UDT.
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.
When you start developing extensions of any kind for CMS Made Simple, a certain amount of your development time will involve tracking down things that aren't working the way you expect them to. Happily, CMS Made Simple has some built-in tools for helping in the debugging process.
This recipe shows you how to run CMS Made Simple in debug mode, and gives you some idea of what to look for in debug output.
1. Find your CMS Made Simple base install directory. Within that directory will be your install's
config.phpfile.2. Edit
config.phpand locate the following section# CMSMS Debug Mode? Turn it on to get a better error when you # see {nocache} errors, or to allow seeing php notices, warnings, and errors in the html output. # This setting will also disable browser css caching. $config['debug'] = false;3. Change the
"false"to"true"and save the file.4. Browse through your site. At the bottom of each page will be the debug information:
Debug mode causes CMS Made Simple to do a number of things differently than in normal production mode:
1. PHP error reporting is changed to
E_ALL, so warnings and errors will all be displayed.2. Page and CSS caching is disabled.
3. Page redirecting via the API is disabled; instead, a link is displayed that will lead to the original destination.
4. All database interactions are displayed.
5. Select core functions display diagnostic information
Often, the display of otherwise hidden warnings or errors will be sufficient for you to track down issues by revealing problems like typos in variable names, missing parentheses, or other syntax errors.
The display of database interactions is useful for diagnosing query problems. Ideally, of course, all extension code we write has proper error checking and reporting. If, however, our code isn't that robust (or if we're still in early development, when such error handling has not yet been added), debug mode helps us identify problems.
Chapter 10, Setting Special Diagnostic Messages for Debug Mode recipe
