Simple Plugins

We need your assistance to make the documentation accurate, user friendly and understandable. Therefore we welcome any tips or suggestions regarding documentation. Thank you in advance for your contribution.

However, we will not respond to technical support questions submitted using this form. If you are having difficulty with CMSMS and cannot find the solution on this website, please submit your question appropriately on our support forum at: http://forum.cmsmadesimple.org. Please remember to follow the forum rules when posting.

CMS Made Simple™ Partner



In CMSMS 2.3 Simple Plugins replace user defined tags (UDT).

A Simple Plugin provides an easy way to add custom functionality to your website.

Simple Plugins are PHP files that have the 'cmsplugin' filename extension and are stored in the /assets/simple_plugins directory.

   When is a Simple Plugin useful

Simple Plugin's are intended to be small pieces of php code to perform simple, site specific functions. Generally, there are a few conditions that indicate that a Simple Plugin 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 Simple Plugin.

  • The code needs to be callable by hooks

    If you need specific functionality to be callable by hooks consider writing a Simple Plugin.

   How to make Simple Plugin

Like most things in CMS Made Simple adding a new Simple Plugin isn't difficult, although you have to know some PHP coding...

CMS Made Simple core does not provide an editor for nor an user interface to create/manage Simple Plugins.

Create a new file in the directory: /assets/simple_plugins

The name of a Simple Plugin:

  • Must not conflict with PHP or Smarty function names
  • Must start with a letter
  • Should contain only characters from the latin alphabet, digits and underscores

The file extension 'cmsplugin' is obligatory.

Example filenames:

  • foo.cmsplugin
  • bar.cmsplugin
  • foo_bar.cmsplugin
  • foo123.cmsplugin

You can call your Simple Plugin with Smarty like this:

{foo}
{bar my_parameter_1='value1'}
{foo_bar my_parameter_1='value1' my_parameter_2=123}
{foo123}

The contents of the file should be valid PHP code. It must start with the PHP opening tag: <?php

It is preferable to omit the PHP closing tag at the end of this file.

The basics on how to make a Simple Plugin

In this page we will learn you the basics in what way a Simple Plugin in CMS Made Simple works.
We challenge you to also learn a grab of PHP-code and start creating your own plugins. 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

Simple Plugins are merely smarty functions for which the body of the function is stored in the .cmsplugin files. Like with Smarty plugins there are arguments to the function that are available in your Simple Plugin's scope:

  • $params (array) - An associative array that contains the parameters and their values that were used in the call to the Simple Plugin.

    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 Simple Plugin

This is a simple plugin that outputs a hardcoded string.

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: File content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;

  echo 'Hello World!';

C: Add in page editor content:

{my_simpleplugin}

D: Output:

Hello World!

   Add a parameter to the Simple Plugin

This Simple Plugin builds on the previous one by outputting a hardcoded string followed by some supplied text.

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: Simple Plugin Content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;

  echo '<p>Hello ' . $params['name'] . '!</p>';

C: Add in page editor content:

{my_simpleplugin name='Ted'}

D: Output:

Hello Ted!

   Add a parameter to the Simple Plugin with a default value

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

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: Simple Plugin Content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;

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

C: Add to page editor content:

{my_simpleplugin name='Robert'}

D: Output

Hello Robert!

E: (variant) Add in page editor content:

{my_simpleplugin}

F: (variant) Output

Hello Anne-Mieke!

   Pass a variable from the Simple Plugin to the page

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

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: Simple Plugin Content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;
  $name = 'Mark';
  $other_name = 'Goran';
 
  $smarty->assign('name', $name);
  $smarty->assign('other_name', $other_name);
 

C: Add to page content:

<p>{my_simpleplugin}</p>
<p>Howdy {$name}!<br /> Hello {$other_name}!</p>

D: Output:

Howdy Mark!
Hello Goran!

 

Another example

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: Simple Plugin Content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;
  $mydata = array();
  $mydata['value1'] = 'foo';
  $mydata['value2'] = 'bar';
  $mydata['value3'] = 'baz';
  $smarty->assign('mydata',$mydata);
 

C: Add to page or template content:

{my_simpleplugin}
{if isset($mydata.value1)}
  <p>Value1 is: {$mydata.value1}</p>
{/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 Simple Plugin with the global Smarty object.
In example in a Simple Plugin this code is invalid and will cause errors:


$smarty = cmsms()->GetSmarty()


   Call a Template from a Simple Plugin

This Simple Plugin is here for example purposes only as it fills no real function.
Generic templates can easily, and more efficiently be called with the {include} tag distributed with CMSMS.

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: Simple Plugin Content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;
 
  $foo = 'footer';
  $bar = $smarty->fetch('cms_template:'.$foo);
  return $bar;
 

   Get the page title of the current page from a Simple Plugin

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

A: Simple Plugin filename: my_simpleplugin.cmsplugin

B: Simple Plugin Content:

<?php

  // for security purposes, we ensure that this file cannot be directly requested by browsers
  if( !defined('CMS_VERSION')) exit;
 
  $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;
        }
       
        echo $page_title;
  }

C: Add to page content:

{my_simpleplugin}

The Simple Plugin will return the title of each page.

   Simple Plugin 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 Simple Plugin'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.