9 min read

CMS Made Simple Development Cookbook

CMS Made Simple Development Cookbook

Over 70 simple but incredibly effective recipes for extending CMS Made Simple with detailed explanations – useful for beginners and experts alike!

These recipes have been specially selected to demonstrate capabilities. While they may be useful as provided, they are designed to show the range of what can be done with tags, and to provide examples of useful operations such as setting Smarty variables, interfacing with the database, interacting with modules, and consuming data from remote web services. You are encouraged to use these recipes as starting points for your own projects.

Introduction

One of the most popular uses of CMS Made Simple involves an administrator who creates a basic site structure and template, and one or more editors who maintain page content without having to worry about the site layout. In this configuration, you can think of the CMS essentially as a big template engine with some utilities to add content.

Each page of the site comprises a page template with areas that get populated with various kinds of content. These areas are either tags or variables, where the distinction is that a tag involves the execution of code, while a variable is a simple substitution of values. The CMS comes with a large assortment of built-in tags, including the fundamental “content” tag and a variety of useful supporting tags for building navigation, links, including images, and so forth.

Because CMS Made Simple can be seen as being built around tags, it is not surprising that there are facilities for creating your own tags. You can create tags directly through the Admin panel—these are called User-Defined Tags or UDTs. If you want even more extensive capabilities in your tag, you can have those capabilities by creating a file that follows a few basic conventions.

The template engine used by CMS Made Simple comes from the Smarty project. Pages are Smarty templates, and the built-in CMS tag types are all Smarty tags. Behind the scenes, both UDTs and file-based tags also become Smarty tags.

For additional information on Smarty, the documentation provided by the Smarty project is invaluable. You can read more at http://www.smarty.net/docsv2/en/

Displaying the User’s IP address from a User-Defined Tag

This recipe demonstrates creating a very simple User-Defined Tag, and using it to display information, that it gets from PHP globally-defined variables.

Getting ready

For this recipe, you will need to have CMS Made Simple installed and working. 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 permissions to “Modify User-Defined Tags” and “Manage All Content”.

How to do it…

  1. Log in to your CMS Administration area.
  2. Using the top menu, go to “Extensions” and click on “User Defined Tags“.
  3. Click on the “Add User Defined Tag” button.
  4. In the “Name” field type “user_ip“.
  5. In the “Code” text area, type the following code: 
    echo 'Welcome user from '.$_SERVER['REMOTE_ADDR'].' -- enjoy your
visit!';
  6. Click on the “Submit” button.
  7. Using the top menu, go to “Content” and click on “Pages“.
  8. Click on the “Add New Content” button.
  9. In the “Title” and “Menu Text” fields, type “Tag Test“.
  10. In the “Content” text area, type the following code: 
    {user_ip}
  11. Click on the “Submit” button.
  12. View your site from the user side. Click on the new “Tag Test” page.

CMS Made Simple Development Cookbook

How it works…

User-Defined Tags work by linking a piece of PHP code to a tag which is recognized by Smarty. When Smarty parses a template and encounters that tag, it executes the code in question, and substitutes the tag markup with any output from that PHP code.

When we create a UDT in the CMS Made Simple admin area, the name we enter into the text field becomes the tag which Smarty will look for, and the code we enter into the text area is the PHP associated with the tag.

This recipe is an example of outputting text directly from a User-Defined Tag. It works by echoing a string, that then replaces the {user_ip} tag in the content. This substitution of the tag can take place either in a page template or in the page content, which might seem a little confusing since it’s stated earlier that Smarty processes tags that it finds in templates. The confusion, though, is mostly due to terminology; CMS Made Simple processes both layout templates and page content through Smarty, so while it is being processed, page content serves as a template from Smarty’s perspective.

The User-Defined Tag we create accesses one of the PHP “superglobals“—the $_SERVER variable . This variable contains information about the HTTP request and some environmental information about the PHP server. In this case, we’re getting the user’s IP address information to display.

Using the CmsObject and the current content object in a User-Defined Tag

This recipe shows you how to access the Page Content object via the CmsObject in a User-Defined Tag.

The primary technique that it demonstrates—getting a reference to the CmsObject and using the CmsObject to get a reference to other important CMS runtime objects—is one that you will use to solve many different kinds of problems.

In this recipe, we use the CmsObject to get a reference to the Page Content object. Once we have a reference to this object, we can call upon its methods to report all kinds of interesting information about the current page content.

Getting ready

For this recipe, you will need login access to your site’s Administration area with permission to “Modify User-Defined Tags” and “Manage All Content”.

How to do it…

  1. Log in to your CMS Administration area.
  2. Using the top menu, go to “Extensions” and click on “User Defined Tags“.
  3. Click on the “Add User Defined Tag” icon.
  4. In the “Name” field, type “content_description“.
  5. In the “Code” field, type the following code: 
    $gCms = cmsms();
$contentops = $gCms->GetContentOperations();
$content_obj = $contentops->getContentObject();
echo 'Current content object is "'.$content_obj->Name().'"<br />';
echo 'which was created on '.$content_obj->GetCreationDate().'<br
/>';
echo 'its alias is "'.$content_obj->Alias().'"<br />';
echo 'and its URL is "'.$content_obj->GetURL().'"<br />';
  6. Click on the “Submit” button.
  7. Using the top menu, select “Content” and click on “Pages“.
  8. Click on the “Add New Content” button.
  9. Enter “New Content Page” into the “Title” and “Menu Text” fields.
  10. In the “Content” field, enter: 
    {content_description}
  11. Click on the “Submit” button.
  12. View your site from the user side. Click on the new “Content Page” page.

CMS Made Simple Development Cookbook

How it works…

CMS Made Simple uses an internal object called “CmsObject” to keep track of a great deal of what it needs to serve content. This information includes the site hierarchy, the installed and active modules, references to the database, and more. The CmsObject is available to Modules, Tags, and User-Defined Tags via the cmsms() function.

In this recipe, we want to display information from the current Content object. However, this object is not directly accessible. To get access to this object, we need to make a static call to the ContentOperations object, but this object is also not directly accessible from our code. To get access to these objects, we need to get references to them.

We start by gaining access to the CmsObject by calling the global cmsms() function. From our reference to the CmsObject, we request a reference to the ContentOperations object, that we then use to request a reference to the current content object.

Once we have the current content object, we can call assorted methods on it to retrieve information about the current content. In this recipe, we get the content’s name, when it was last modified, its alias, and its URL. Since this recipe is an example, we don’t format these various pieces of information or use a template, but simply echo them. In a production UDT or one in which there’s any complexity to what is being displayed, it would be more advisable to use the values to populate Smarty variables for later display, or use a template for formatting them.

There’s more…

There are a number of interesting objects, that CmsObject manages. References can be requested to:

  • BookmarkOperations— used in the Admin area
  • ContentOperations—which has methods to handle Content and content metadata
  • Db— which wraps the ADODB database API
  • GlobalContentOperations— which has methods to handle Global Content Blocks
  • GroupOperations— which has methods to handle Admin Groups
  • HierarchyManager— which has methods for handling site content hierarchies
  • ModuleOperations— which has methods for managing Modules
  • Smarty— which wraps the Smarty template engine
  • StylesheetOperations—which has methods for handling
  • TemplateOperations— which has methods for handling Smarty templates
  • UserOperations— which has methods for handling Admin Users
  • UserTagOperations— which has methods for handling User-Defined Tags

Getting attributes using page_attr

If you’re looking to display information about the current content object, CMS Made Simple has a custom Smarty tag that provides some attributes: {page_attr}. You can use this tag to display page attribute information—simply by specifying a key to the information you’re requesting. For example, to get the page’s “image” attribute, you could use the tag {page_attr key=”image”}. Other keys that are supported include:

  • target
  • image
  • thumbnail
  • extra1
  • extra2
  • extra3
  • searchable
  • pagedata
  • disable_wysiwyg
  • content_en

As you can see, this is not as rich a collection of information as you can get from the content object directly using your own UDT.

Old code and the use of globals

If you look at old modules or User-Defined Tags that have been posted in the CMS Made Simple forum, you may see the following code:

global $gCms;

instead of the $gCms = cmsms() used here. For a long time, the use of the global declaration was the preferred way to access the CmsObject. This approach is now deprecated for a number of reasons, most important of which is a security issue and also including portability of code between CMS Made Simple 1.x and the upcoming 2.x versions.

While use of the global declaration to access the CmsObject will likely still work, it is strongly discouraged.

 

Packt

LEAVE A REPLY

Please enter your comment!
Please enter your name here