How it works...

In this recipe, we are exploring the mathematical capabilities of Smarty, and how we can use them in our stylesheets. To demonstrate this, we will create a box that is divided into two portions with a fixed divider between them. The box, the two portions, and the divider are all defined using simple HTML div tags with IDs that we can use to target them with our CSS rules.

We begin by setting a few basic variables using Smarty "assign" statements. First, we set our outer box dimension to the unitless value of 300. We omit the units since we will be performing arithmetic on the value and can assign the units later when we substitute in the variable in the CSS itself. You can see that below in the CSS in the rules for #wrapper, where there is the width specification:

#wrapper {
border: 1px solid black;
width: [[$box_width]]px;

Next, we assign the other values that will define our geometry. We set the width of the division, which we call middle_width, as ten units. Then we set left_percent, that will determine the percentage of the total box occupied by the left portion, and we use the value 20 (for twenty percent).

Once the basic geometrical description is set, we use Smarty to compute the size of the left portion. In this case, since we will be doing more complex math than addition and subtraction, we use the Smarty "math" command to specify an equation and to assign the computed value to a variable named left_size. As you can see, the Smarty math command binds the variables in the equation template to Smarty variables. For simplicity, we used our existing variable names in the equation, but we still have to bind the equation template variables to our defined variables, which is why we have the seemingly redundant assignments like box_width=$box_width.

The output of the Smarty computation, stored in left_size, is still unitless. When we substitute the value into our CSS, you can see that we put the units of px (for pixels) after the variable instantiation.

The manual page for Smarty recommends avoiding the use of the math command when performance is an issue, for example, like in a loop. It turns out that for simple arithmetic, it's easy to avoid. As you will see where we compute the width of the right_portion div, you can put subtraction into an ordinary Smarty variable instantiation. In this case, we subtract our left portion and middle portion from the overall width.

Now that you have the dimensions determined mathematically, you can play around to see how it functions. Try changing the percentage of the div that the left_portion occupies, or modifying the overall box width. From this, you can see that if your entire layout was done using Smarty math, it takes only a single variable change to alter your design — all without affecting proportions.

There's more...

One thing to look out for when using Smarty logic in your stylesheet is caching. People are occasionally surprised by the results they get when they put Smarty logic in their CSS that is supposed to do something conditionally, based upon the current page name or Smarty variables set in the "Smarty data or logic that is specific to this page" field of the Page admin. The symptom is that the logic doesn't work at all, or alternatively works the first time, but then triggers on pages where it shouldn't. The reason for this is stylesheet caching. For performance reasons, CMS Made Simple generates stylesheets the first time they're needed, and uses caches thereafter. Until you change the stylesheet source, the same CSS will be served up to all pages.

The solution to this problem is to move any page-specific logic to your page template. If you want a different style for H1 tags on your home page, put the class into a conditional rather than putting the condition in the stylesheet:

<h1 class="{if $special_condition==true}special_class{else}normal_class{/if}">

This will work as you expect.

See also

Getting ready

This recipe requires that you have login access to the site's Administration area as a member of the "Admin" group (or as a member of a group with "Modify Any Page" permission settings). You will also need permissions to create a file on the server, either via FTP or some other means.

How to do it...

How it works...

The CMS Made Simple Administration area has built-in localization support. The way localization works is that the text strings that are displayed by the Admin area are abstracted: within the code, a string name is used instead of the string itself, and that name is used in conjunction with files of translated strings. For example, the string that is expressed in English as "Extra Page Attribute 1" is labeled in the code using a tag "extra1".

If you have the Admin set to "US English", the translation subsystem reads in the en_US version of the admin.inc.php file where the tag "extra1" is translated to "Extra Page Attribute 1". Similarly, if your Admin is set to German, the translation subsystem reads in the de_DE version of admin.inc.php, and the tag "extra1" is translated to "Zusätzliches Seiten-Attribut 1".

As shown in this recipe, you simply put a list of tag definitions into your custom "admin.inc.php" file to change how the tags are displayed.

There's more...

In this recipe, we only overrode the names of the extra page attribute tags in English. If your site has multiple administrators who use different languages, you'll want to override the names of the attributes in all of those languages.

The process for doing this is equally simple. Inside of the "custom/lang" directory, you'll need to create a directory for each language that needs to be overridden. The naming convention for these directories is the two-letter ISO 639-1 language code (in lowercase) followed by an underscore, followed by the two-letter ISO 3166-1 country code. For an easy way to find the list of the languages supported by CMS Made Simple, take a look in the "admin/lang/ext" directory under your base installation.

Once you have created the language directory, create an "admin.inc.php" file within it, and add your translations to that file.

See also

Getting ready

This recipe requires that you have login access to your site's Administration area with permission to "Add Pages", "Add Global Content Blocks", "Manage Menu", and "Modify Any Content". You will also need permissions to create a file on the server.

How to do it...

How it works...

This recipe takes advantage of several built-in CMS Made Simple features and several tricks:

The first of these tricks, changing Extra Page Attribute names, is described in detail in another recipe in this chapter, so it won't be described here.

Let's start by looking at the "personnel" Global Content Block (GCB) we defined. It is used to present structured information: in this case, the people in our imaginary company. It guarantees a standardized presentation. The data-entry person who fills in the user pages doesn't have to remember any particular format. To achieve that end, you'll notice that the entire GCB is generic — it makes no reference to any specific person. Each piece of information it presents comes from page variables or is based on the page alias.

First, the "personnel" GCB presents an image of the person. The image name is simply the page alias (followed by the ".jpg" extension). It assumes a subdirectory of the usual image upload directory, which helps in keeping the personnel pictures separate and organized. The "alt" tag for the image uses the standard {title} tag, that is available to all CMS Made Simple pages. When we create pages for people, we will use their names for the page titles, so the image will be their picture and the "alt" tag will contain their name. The "personnel" GCB then includes the three Extra Page Attributes, and labels them according to how we use them.

When the Global Content Block is included in a page, all of the data fields that are referred to generically will be filled in with the appropriate value for the containing page. So when we create Sierra and Javier's biographical pages, we start by including the "personnel" GCB to present their information in a consistent, structured fashion.

At this point, we have consistent biographical pages for our personnel, but if we were to just leave it at that, someone would need to make the top-level directory, that links to the individual bio pages. Instead, we use the Menu Manager to do the work for us.

In our main personnel directory page, we add a tag to call Menu Manager. While Menu Manager is typically used to create menus (as its name suggests), what it does under the hood is generate a data structure of hierarchical page information, which it then formats according to a template. Menus often format the data structure into unordered lists, but we're not limited to that kind of markup. In this case, we're specifying our "personnel" Menu Manager template, that formats the lists into separate divs for each page. We'll describe that in more detail below.

Before we examine our Menu Manager template, we need to look at a few parameters that we use that aren't generally used in site menus. These parameters are quite handy, and once you use them a few times, you'll find yourself discovering other uses. The first of these is "loadprops." By default, Menu Manager loads only a limited set of information about the pages: name, menu text, link, and so on. By specifying "loadprops=1", we're saying that we want Menu Manager to load the extended properties of the page, which include such useful things as the Extra Page Attributes.

The next interesting parameter to Menu Manager is "childrenof." By passing a page alias, this parameter limits the information it returns to the children of the specified page in the content hierarchy. If you want to limit a menu to a site section, this is one way of doing that. In this case, we're being sneaky, and passing "childrenof" a variable: the page alias for the current page. In other words, we're telling Menu Manager to return a hierarchical list of pages that are the children of the page containing this tag. We'll be assigning all our biographical pages this personnel directory page as their parent, so this tag will bring in a list of all of these bio pages.

Now that we know we're processing a list of all the bio pages, complete with Extra Page Attributes, let's look at our Menu Manager template. For each entry in the list, we're given a "node" variable that has the specific page details as attributes. Each directory entry is going to start with a picture. Remember our naming convention where the people's pictures are named after their page alias? We use that same convention here, except we prepend the name with "thumb_" to retrieve the thumbnail image that is automatically generated by the Image Manager when we upload JPEG images. For the "alt" tag in the images, we use the menu text attribute for the bio page; if we wanted to be more formal and use the person's full name, we could use the page title instead. We then specify the person's name again, and wrap it in a link to their page. You'll notice that accessing the Extra Page Attributes in Menu Manager templates is even easier than in a standard page template, since it's a direct attribute of the node ($node->extra1).

There's more...

Much of this recipe is designed to simplify the creation of a personnel section for a site without requiring the person to do the data entry to key in redundant information or worry too much about formatting. This is not done just to make the job of the data entry person easier — long experience has shown that forcing someone to enter the same data in multiple places results in errors, and counting on someone to use consistent formatting on multiple pages rarely works out.

There is one place where we could improve this recipe and minimize the opportunity for error even further: we could obviate the necessity for the data entry person to include the Global Content Block tag for each biography page. The way we do this is to make a copy of our main template, put the GCB tag into this template before the {content} tag, and then save it as the "personnel" template. Then, when the data entry person creates a new biographical page, they simply select the "personnel" template when they are keying information into the "Options" tab.

Why use a naming convention for images?

You probably already knew that you could assign an image and thumbnail to a content page. As you can see in the list of attributes above, the names of those files are available to the Menu Manager template. Given this, why would we use a naming convention based on the page alias rather than these attributes?

There are a few tradeoffs for each approach:

In our recipe we're already telling Menu Manager to load extended properties for each page, so there's not much of an advantage to using a naming convention. If, however, we were not using the Extra Page Attributes in our directory, we could improve performance by loading only standard content attributes.

In the end, you should select the approach that you think will be simplest for the person or people who will maintain the site.

See also

Getting ready

This recipe requires login access to your site's Administration area as a member of a group with permissions to "Add Pages", "Manage Menu", and "Modify Any Content". For the recipe to work completely, you need to be running Apache web server or a web server that has some mod_rewrite compatible capability. You will need to be able to update the Apache configuration, either directly or via .htaccess files. You will also need permissions to create files on the server.

How to do it...

How it works...

This recipe uses Menu Manager to output a list of all the pages on the site, and a custom template to format that list as XML according to the Google sitemap standard. The structure of the XML file is elementary: an XML declaration and a "urlset" tag that contains a collection of site-specific URLs, each with a few descriptive attributes.

Let's examine the Menu Manager template. It starts by declaring that the file is an XML file and the characters are encoded in UTF-8. Next, it outputs the main container, which is the urlset tag. This urlset attribute specifies an XML name space (xmlns) from the sitemaps.org website; in this case, we're specifying that we'll be using the namespace for the sitemap 0.9 schema.

Next, the template sets a variable containing the current time. This will be used when describing the currency of each URL.

The next part is the main substance of the template: we loop through the site pages (in the nodelist variable), and for each page, we output an URL tag. Each URL tag contains several attributes:

Once we have the Menu Manager template, we place the menu tag into a page. The page is set to be active, but not to show up in the site navigation.

The last step is to link this page to a standardized URL — according to the sitemap standard, search engines look for a filename "sitemap.xml" in the site root (although many search engines allow you to register a different location, if you choose to).

We use the magic of Apache's mod_rewrite module to map the filename "sitemap.xml" to our page containing the sitemap tag. Specifically, the mod_rewrite rules check to see if the incoming request is not for a directory or an existing filesystem file. If those tests pass, it checks to see that "sitemap.xml" was requested. If so, it rewrites the URL and drops out of further rewrite tests.

The rewritten URL has one special feature — it calls the page containing the sitemap, but also passes the parameter "showtemplate=false". This noteworthy parameter tells CMS Made Simple to output the page but suppress the page template that surrounds the page's {content} tag output. This allows us to output the unadorned XML of the sitemap.

There's more...

The sitemap generated by this recipe includes all active pages in your site, whether or not they show up in the menu. In some cases, you may want to use the menu visibility to determine what is included in the site map. It is easy to change this recipe to include only pages that are in the menu. In your "sitemap" page, change the "show_all='1'" to "show_all='0'".

See also

Getting ready

For this recipe, you will need to access the site's Administration area with "Modify Templates" permissions. This recipe assumes you are using NCleanBlue as your default site template.

How to do it...

How it works...

This recipe is a contrived example to illustrate the use of Smarty's {literal} tag. In the version of Smarty used in CMS Made Simple, curly braces are reserved for template directives. The fact that they are syntactically important in JavaScript becomes a problem: Smarty thinks that your curly braces are meant for it, so it throws template errors when it attempts to render the page containing JavaScript.

The {literal} and {/literal} tags tell Smarty to ignore curly braces within an area. This allows you to include your JavaScript without confusing Smarty.

{literal}
<script type="text/javascript">
function confirm_exit(e) {
if(!e) e = window.event;
e.cancelBubble = true;
e.returnValue = 'You will be leaving the page "{/literal}{title}{literal}"?';
if (e.stopPropagation) {
e.stopPropagation();
e.preventDefault();
}
}
window.onbeforeunload=confirm_exit;
</script>
{/literal}

Getting ready

This recipe requires that you have access to the site's Administration area with permission to "Add Stylesheets", "Add Stylesheet Associations", and "Manage All Content".

How to do it...

How it works...

This recipe uses built-in Smarty looping to generate separate, but related, CSS rule sets.

It starts with a CMS Made Simple-specific Smarty tag called "setlist", which allows you to create a Smarty variable that is an associative array. The tag takes two parameters: "var", that specifies the name of variable to use, and "value", that specifies the array to be stored. The syntax for the "value" parameter is similar to a JSON format, with colon-delimited name-value pairs in a comma-separated list.

So the first line creates an associative array named "boxes" with the color names as the keys and the color hex triplet as the value.

The next line is where we tell Smarty that we want it to loop through the array we just created. The foreach command takes a number of parameters:

Our command says to loop through the array stored in the "boxes" variable. That means that for each element in the array, we'll be interpreting all of the code between the [[foreach]] and [[/foreach]], and within that scope, we will have a variable called "current_box", that will be the current array element's key, and a variable called "box_color", that will be the current array element's value.

From there, we have a set of CSS rules, where we substitute in our values. In this case, we're using our "current_box" for a CSS ID, and we're using the "box_color" to set the color attributes. In our template, we only need to write out the rules once, and the loop will generate one set of rules for each box in our array.

In our HTML, each of the divs we create is given an ID which will match the IDs generated in the CSS.

There's more...

You might worry that the generation of stylesheets with looping is computationally expensive. Never fear! The CMS Made Simple architecture caches stylesheets, so the computation will only happen once after each source change.

Also, keep in mind that the power of looping is not restricted to looping through sets of colors. You could use a loop along with some Smarty arithmetic to generate a set of header tags (H1 H10, say) and set the sizes programmatically. The kinds of things you can do with Smarty logic in your stylesheets is only limited by your imagination.

See also

Getting ready

This recipe requires access to the Admin area with "Add Global Content Blocks", "Modify Templates", and "Manage All Content" permissions. We also assume you are using the default NCleanBlue template.

How to do it...

How it works...

This recipe uses Smarty logic in the template to display a block of content only on the Home page of the site. The comparison takes place in the template, with the condition comparing the variable $page_alias to the string'home'. If there is a match, everything within the conditional clause is rendered into the template.

In this example, we place our "welcome" content into a Global Content Block. You would typically do it this way so that an admin user would not need to edit the template to update the welcome block. This works out well, since users are usually more comfortable editing a Global Content Block than a template, and you as the site developer don't have to worry about someone accidentally messing up the entire site template by removing the {/if} tag or something similar.

You'll note that this example assumes that the Home page of the site has the alias "home." In the default content distributed with CMS Made Simple, this will be true. If your site is set up differently, you will need to compare the $page_alias to whatever is appropriate for your site.

There's more...

There are several other Smarty variables that are set for each CMS Made Simple page. You could choose to compare with any of those variables when creating a conditional, including:

This is also a good place to use the Extra Page Attributes, although they're a little harder to get to. Extra Page Attributes can be found on the "Options" tab when editing content. They are stored in a Smarty variable called $content_obj and you refer to them using a function called GetPropertyValue. So, for example, if you wanted to use the Extra Page Attribute 2 to flag whether or not to show your "welcome" content, you could use:

{if {if $content_obj->GetPropertyValue('extra2') eq 'true'}
{global_content name='welcome'}
{/if}

Then, for any page where you typed the word "true" into Extra Page Attribute 2, your "welcome" content would be displayed.

{if $page_alias eq 'home'}
{global_content name='welcome'}
{else}
{global_content name='something_else'}
{/if}

{if $smarty.now|date_format:"%m%d" == '0101'}
<img src="logo_newyears.jpg" />
{elseif $smarty.now|date_format:"%m%d" == '0314'}
<img src="logo_einstein_birthday.jpg" />
{else}
<img src="logo.jpg" />
{/if}

See also

Getting ready

You will need to access your site Administration area with "Modify Templates" and "Manage All Content" permissions. This recipe assumes you are using the default NCleanBlue template, but will work with any template.

How to do it...

How it works...

This recipe focuses on two Smarty features, namely, capture and conditionals. Capture is the ability to trap the output of a tag or other content and store it into a Smarty variable. Conditionals, as shown in other recipes, give us the ability to output different content based upon variables.

We start by editing the NCleanBlue template, and we add a new content block. This is a powerful feature of CMS Made Simple, where it is possible to break out separate content areas on a page, give each area a name, and have them all available for editing together in the Page admin. We wrap the new content block in a Smarty Capture, where we assign it to the variable "special." Captured content suppresses display of anything between the opening capture tag and the closing capture tag. Instead, any output is stored in the variable.

Effectively, if a site editor has put anything into the "special" text area when editing a page, our logic places that content into a variable.

In our next line, we test the "special" variable to see if it does, in fact, contain anything. If it does, we wrap it in some formatting, and display it. If it is empty, however, we skip that.

There's more...

Once you have captured site content into a variable, you can do all kinds of creative things. You can run Smarty modifiers against it for all kinds of effects like capitalizing the first letter of each word, converting to upper or lowercase, running replacements with regular expressions, and so on.

There are other Smarty features that could be used for altering the layout of the page, such as the count_words modifier. For example, if you want to alter the layout when there is a lot of text, you could do something like the following:

{capture assign="my_content"}{content}{/capture}
<div class="{if $my_content|word_count < 10}narrow{else}wide{/if}">{$my_content}</div>

This little snippet will display the content block in a div with a class of "narrow", if there are fewer than ten words of content, or in a div with a class of "wide" if there are ten or more words.

See also

Getting ready

This recipe requires you have Administration area access with "Modify Templates", "Modify News", and "Manage All Content" permissions. This recipe assumes you are using all of the default content and templates from a basic installation, but the principles will work regardless.

How to do it...

How it works...

The {get_template_vars} tag is a CMS Made Simple-specific wrapper to an underlying Smarty function that, as its name suggests, returns the entire set of template variables assigned to Smarty. The tag does some minimal formatting to give some idea if a variable contains an array (and if so, how many elements it comprises) or whether a variable contains an object.

The information presented may appear somewhat trivial, but it can save an enormous amount of time when working with a module that doesn't provide strong documentation on the variables it makes available to various templates.

There's more...

As you can see in the sample output, the {get_template_vars} tag provides only superficial insight into more complex variables. Sometimes, it's enough to know that something is an object or array, but sometimes you want to know the specifics.

One way of displaying this kind of detail is using the "print_r" Smarty modifier. For example, you may see a variable "$items" exists in your page, and contains an object. From experience, you may have an idea that it's defined by the News module, but you may be uncertain or you may want to know exactly which attributes it possesses. To get this information, you could put the following tag into a page or template:

{$items|print_r}

Then when you view the page, you will see output like the following:

As this demonstrates, the print_r modifier is the same as the PHP function of the same name.

See also