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. |