Writing your own User Defined Tag : : CMS Made Simple 2.x Official Documentation

Writing your own User Defined Tag

User-defined tags are a simple way to insert PHP code into your site. To use them, simply create a new tag and paste your PHP code in (leaving "<?php" and "?>" out). You can call tags with smarty like this: {tag_name}

The name of a User Defined Tag should only contain letters or underscores.

tagname
tag_name
tag-name
2004

Like most things in CMS Made Simple adding a new plug-in isn't difficult, although you have to know some PHP coding...
To add your own plugin, the plugin editor can be found in the Admin Console at Extensions >> User Defined Tags.

In a default setup of CMSMS you will find two (usefull) example UDT's, named custom_copyright and user_agent.

The basics on how to make a User Defined Tag

In this page we will learn you the basics in what way a UDT in CMS Made Simple works.
We challenge you to also learn a grab of PHP-code and start creating your own UDT's. We love to see them in the Tips & Tricks board in our forum.

It is important that you refer to the CMSMS API Documentation when creating user defined tags that interact with CMSMS. Please do not use any classes, methods, properties or functions that are marked as internal, private, or deprecated.

Variables in scope

User defined tags are merely smarty functions for which the body of the function is stored in the database. Like with smarty plugins there are arguments to the function that are available in your UDT's scope:

$params (array) - An associative array that contains the parameters and their values that were used in the call to the UDT.
More on this below.
$smarty (smarty template object reference) - A reference to the smarty template object for the current scope..
CMSMS 2.0 introduced the concept of different smarty scopes. You can no longer assume that a variable created in one template will be automatically available in another in the same request.

A Simple UDT

This is a simple user defined tag that outputs a hardcoded string.

A: UDT Name: my_udt

B: UDT Content:

echo 'Hello World!';

C: Add in page editor content:

{my_udt}

D: Output:

Hello World!

Add a parameter to the UDT

This User Defined Tag builds on the previous user defined tag by outputting a hardcoded string followed by some supplied text.

A: UDT Name: my_udt

B: UDT Content:

echo 'Hello ' . $params['name'] . '!';

C: Add in page editor content:

{my_udt name='Ted'}

D: Output:

Hello Ted!

Add a parameter to the UDT with a default value

Building on the second UDT, this variant assumes a default value if the named parameter is not supplied.

A: UDT Name: my_udt

B: UDT Content:

$name = isset($params['name']) ? $params['name'] : 'Anne-Mieke';
echo 'Hello ' . $name . '!';

C:Add to page editor content:

{my_udt name='Robert'}

D: Output

Hello Robert!

E: (variant) Add in page editor content:

{my_udt}

F: (variant) Output

Hello Anne-Mieke!

Pass a variable from the UDT to the page

This example shows how to create a new smarty variable and output the data back to smarty.

A: UDT Name: my_udt

B: UDT Content:

$name = 'Mark';
$other_name = 'Goran';

$smarty->assign('name', $name);
$smarty->assign('other_name', $other_name);

C: Add to page content:

{my_udt}
Howdy {$name}! 
Hello {$other_name}!

D: Output:

Howdy Mark!
Hello Goran!

Another example

A: UDT Name: my_udt

B: UDT Content:

$mydata = array();
$mydata['value1'] = 'foo';
$mydata['value2'] = 'bar';
$mydata['value3'] = 'baz';
$smarty->assign('mydata',$mydata);

C: Add to page or template content:

{my_udt}
{if isset($mydata.value1)}
Value1 is: {$mydata.value1}
{/if}

D: Output:

Value1 is: foo

As of CMSMS version 1.11 it is invalid to overwrite the $smarty object that is passed in to the UDT with the global smarty object.
In example in a User Defined Tag this code is invalid and will cause errors:

$smarty = cmsms()->GetSmarty()

Call a Template from a UDT

This UDT is here for example purposes only as it fills no real function.
Global Content Blocks can easily, and more efficiently be called with the {include} tag distributed with CMSMS.

A: UDT Name: my_udt

B: UDT Content:

$foo = 'footer';
$bar = $smarty->fetch('cms_template:'.$foo);
return $bar;

Get the page title of the current page from a UDT

This UDT is here for example purposes only as it fills no real function.
As the built in {title} tag does the exact same thing.

A: UDT Name: my_udt

B: UDT Content:

$contentobj = cms_utils::get_current_content();
$page_title = '';
if (is_object($contentobj))
{
$page_title = cms_htmlentities($contentobj->Name());
if( isset($params['assign']) ) { $smarty->assign($params['assign'],$page_title); return; }
return $page_title;
}

C: Add to page content:

{my_udt}

The UDT will return the title of each page.

When is a User Defined Tag useful

UDT's are intended to be small pieces of php code to perform simple, site specific functions. Generally, there are three conditions that indicate that a UDT should be written:

The code is small
(approximately 100 lines or less including comments and whitespace)
Longer chunks of code should be (where possible) placed into modules or plugin files to take advantage of optimizations such as lazy loading and to reduce memory requirements.

It is usually inappropriate to put whole pieces of functionality such as contact forms, or search forms into a User Defined Tag.
The code is site specific.
Plugins and modules can be registered in the forge, providing a source code repository, bug tracking system, and file repository. UDT's cannot and should usually only be considered for functionality that is specific to one website.

If you wish to share your code, and it is not for handling an event, then we suggest you create a plugin and register that plugin on the forge.
The code needs to handle an event
User Defined Tags, and modules can be registered as event handlers. However plugins cannot (as they are thought of as more general purpose pieces of functionality).

If you wish to share your solution with others for handling an event it is probably best to create a simple module consisting of a few hundred lines of code, and a help file and to register that on the forge.

UDT Tips:

Use liberal amounts of documentation and whitespace.
often when diagnosing a problem or making revisions months after initial delivery of a site it is difficult to know via the code itself what you were trying to accomplish. Save yourself (and anybody assisting you) some time, and use liberal amounts of comments, and whitespace to make the code readable.
Return data, don't render data.
Smarty is perfectly suited to rendering data. Whereas creating complex layouts within a simple text area is clumsy at best. It is best to restrict your UDT's to gathering and returning data to smarty rather than formatting it. This also allows your user defined tags to be re-used in numerous places whilst leaving the styling and rendering of the data to the display level.