官术网_书友最值得收藏!

Create a "Hello World" Tag

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.

Getting ready

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.

How to do it...

  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>";
    }
    ?>
    

    Tip

    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!

How it works...

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:

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.

There's more...

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.

Caching

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.

Tag Names and Namespaces

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.

See also

  • Will a Tag solve my problem recipe?
  • Create a "Hello World" User-Defined Tag recipe
主站蜘蛛池模板: 射洪县| 辽源市| 蒙阴县| 涿州市| 忻州市| 鄂托克旗| 克拉玛依市| 丰台区| 广西| 玛多县| 安阳县| 大洼县| 浦县| 美姑县| 会东县| 镇康县| 锦屏县| 峨边| 宁波市| 英吉沙县| 罗田县| 靖州| 林口县| 阿坝| 曲阳县| 慈利县| 遂川县| 韩城市| 略阳县| 沈阳市| 台东市| 石棉县| 临潭县| 凤凰县| 龙陵县| 竹北市| 开远市| 鄢陵县| 南木林县| 咸丰县| 怀安县|