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<[email protected]>"; } ?>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"[email protected]"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.