Basic CMS Template Development Skills | calguy1000.com

One of the major features of CMS Made Simple is that it uses smarty throughout it's content, modules, and page templates.   This provides a great deal of flexibility, and power to layout every element of your content exactly the way you want it.  CMS Made Simple does not impose any restrictions on you (though some of the third party addon modules may).  You simply do something like

<h3>{$some_smarty_variable}</h3>

in your various templates.  And then that smarty variable will be evaluated, and displayed in an H3 tag.   This sounds so simple... And it is.  However, there is one major problem... How do you find out all the variables that are available... and how do you address them?  That's not quite so simple.

Infact many of the posts on the CMS Made Simple Forum are about exactly this.  Additionally, a great deal of the questions I see on the #cms irc (irc.freenode.net) channel are related to this subject.  There are numerous sticky posts on the forum indicating that the smarty manual is required reading,  and either people don't read these posts, or don't understand them.  Either way, reading them wont provide a quick and easy answer to some of these questions.  So I decided that I would write a small tuturial that should help people figure out exactly how to figure this stuff out.

This will not be a smarty tutorial, or a quick start guide.  I won't be teaching you everything about smarty syntax, how to use modifiers, etc.  But just a basic guide as to how to figure out what variables are available in a template, and how to use them so that you can more easily layout your CMS Made Simple website.

So lets get started:

I'm going to format this article, much like a tutorial, with just a little bit of wisdom and oppinion thrown in here and there.   So we'll start by styling up the News detail template in a new install of CMS Made Simple 1.5.2.  I won't give you the url to the site, because well... I don't plan on keeping it live long.

The default installation of CMS Made Simple comes with the News module that allows creating articles with expiry dates, summary and detail text areas, and also summary and detail views.  The default summary view looks like this (click on the image to popup a larger version):   You can begin to see the pagination information, and the way that the articles post date is formatted, and how the title link is created.

<!-- Start News Display Template -->
{if $pagecount > 1}
  <p>
{if $pagenumber > 1}
{$firstpage}&nbsp;{$prevpage}&nbsp;
{/if}
{$pagetext}&nbsp;{$pagenumber}&nbsp;{$oftext}&nbsp;{$pagecount}
{if $pagenumber < $pagecount}
&nbsp;{$nextpage}&nbsp;{$lastpage}
{/if}
</p>
{/if}
{foreach from=$items item=entry}
<div class="NewsSummary">

{if $entry->postdate}
	<div class="NewsSummaryPostdate">
		{$entry->postdate|cms_date_format}
	</div>
{/if}

<div class="NewsSummaryLink">
	{$entry->titlelink}
</div>

<div class="NewsSummaryCategory">
	{$category_label} {$entry->category}
</div>

{if $entry->author}
	<div class="NewsSummaryAuthor">
		{$author_label} {$entry->author}
	</div>
{/if}

{if $entry->summary}
	<div class="NewsSummarySummary">
		{eval var=$entry->summary}
	</div>

	<div class="NewsSummaryMorelink">
		[{$entry->morelink}]
	</div>

{else if $entry->content}

	<div class="NewsSummaryContent">
		{eval var=$entry->content}
	</div>
{/if}

{if isset($entry->extra)}
    <div class="NewsSummaryExtra">
        {eval var=$entry->extra}
	{* {cms_module module='Uploads' mode='simpleurl' upload_id=$entry->extravalue} *}
    </div>
{/if}
{if isset($entry->fields)}
  {foreach from=$entry->fields item='field'}
     <div class="NewsSummaryField">
        {if $field->type == 'file'}
          <img src="{$entry->file_location}/{$field->value}"/>
        {else}
          {$field->name}:&nbsp;{eval var=$field->value}
        {/if}
     </div>
  {/foreach}
{/if}

</div>
{/foreach}
<!-- End News Display Template -->

Now lets say for exmple that we want to change the title link to not be a link at all... and to have a link somewhere in the template that said 'See the full article...' that did essentially the same thing.   In order to do this we would need to have the URL to the detail page so that we could create our own link.

The first thing we should do is create a new summary template, something that we can work with without screwing up something that is already working.   We would do this by clicking on the 'Summary Templates' tab in the News module admin panel, and click on 'Create a New Template'.  This will display a form which allows us to give the new template a name, and to edit the template.

In order to find out what variables are available, there are a number of tools available... these are:

• {get_template_vars}

  This plugin will display a preformatted list of all of the currently available smarty variables, and their types.  It can be used anywhere, but only shows you what top level variables are available.  This is typically used in the page template where you have no clue as to what smarty variables are available for you to use.

• {dump item="somevariable"}

  This plugin will display a nicely formatted list of members of a single named top level smarty variable.  If the output from {get_template_vars} tells you that the variable $something is available, and that it is an array or an object, you can use {dump item='something'} to see what it contains.

• <pre>{$somevariable|print_r}</pre>

  This plugin is similar to the plugin, but does not parse the results to give you hints as to types, etc. it can be used anywhere, at any time to display the contents of a simple smarty variable or a complex variable like an array of objects.

You can view the help for these items (along with the help for a variety of other plugins available in CMS) by going to Extensions >> Tags in your CMS Made Simple Admin Console, and clicking on the help link that is associated with each tag.

For this purpose, we already know the name of the smarty variable that probably contains the information we want, it's called $entry inside the foreach statement.  But because it is not a top level variable we cannot use the {dump} plugin.  So we will add this text into the summary template just after the foreach, give the template a name of 'new_summary', and hit 'Submit'.

{foreach from=$items item=entry}<pre>{$entry|print_r}</pre>

If you were to refresh your frontend view now you would notice absolutely no changes.  That's because we created an additional summary template, but the system isn't using it yet.  In order for CMS Made Simple to use it we have two choices:

1. Specify the name of the summary template in the call to the News module from the page template
2. Specify that our new_summary template is the default

For the purposes of this demo, we'll use the latter.  In the Summary templates tab you can now see the two summary templates listed.  You can change the current default template by clicking on the red X on the new_summary row.  You should see something like this.

Now if we refresh our frontend view we'll see that it is drastically different, and looks quite ugly.  But that's okay because it's only temporary.   However we can see that  $entry is a stdClass object, and we can see all of it's members.... they are deliniated on a new line with [ and ] and followed by a =>.  For example, we can see that there are members called [title] which appears to contain only the article title, and [link] and [moreurl] that look like they will contain the url that would generate on a detail view.   Copying and pasting this url into a new browser tab would tell us for sure.  Go ahead, and give it a try.

Now we're ready to edit our new_summary template again, and try to accomplish what we want.

The first thing we'll do is change this text in the summary template:

<div class="NewsSummaryLink">
 {$entry->titlelink}
</div>

to this:

<div class="NewsSummaryLink">
 {$entry->title}
</div>

Now click the 'apply' button, and then reload your frontend page.   You should see the link dissappear, and be replaced by just text.  Excellent, now there's only one thing left to do.... Our seperate link.

If you look in the template, there is already a portion of text that says:

<div class="NewsSummaryMorelink">
 [{$entry->morelink}]
 </div>

So why isn't it being used?   A closer look at the template indicates an expression that indicates that that particular portion of the template only gets used if there is summary text for the particular article..... so in order for us to have a link that says 'See the full article' we'll have to make a basic structural change.

You will need to cut tthe lines illustrated above out of the template, and paste them directly after the {/if} statement.

Next, we just need to create our link, using {$entry->link}.  We do this by changing the above text to:

<div class="NewsSummaryMorelink">
 [<a href="{$entry->link}" title="{$entry->title}">See the full article</a>]
 </div>

At the last step, to make our news article summary look good, we need to remove the stuff that we added in for debugging..... so go ahead and remove this text from the top of your template:

<pre>{$entry|print_r}</pre>

So now, refeshing our frontend view again, we can see that our change has been successful.  and that we now have a link that says what we wants, has the attributes we want, and still goes to the desired destination page.

This is just the most basic of changes that can be made to a template... but it illustrates the primary tasks.  These are:

1.  Create a new template

2.  Mark it as default, or specify it by name in the module call so that changes to it are visible.

3.  Get a list of the available variables and attributes to those variables, so that we can see what there is to use, and how to use them.

4. Edit our template numerous times, and view the changes until we are satisfied with it.

Conclusion

So, if you have managed to follow this quick tutorial, and read the smarty manual (particularly the secon on "smarty for template designers", then you have passed the most basic of lessons in how to work with modules and templates in CMS Made Simple.   You should now be able to style your templates pretty much any way that you want and create a countless number of dynamic, accessible, and eye catching websites.

Have a nice day.