Templates

Defining a term "template"

What exactly is a CMSity template? It is a file stored at CMSity installation folder, containing a PHP code executed by CMSity once it matches triggered node's type and action.

Defining a term "action"

Action is URL's first query string parameter, or "view" is there are no parameters. For example:

http://www.mysite.com/about triggers action "view"
http://www.mysite.com/blog?post triggers action "post"
http://www.mysite.com/?search=installer triggers action "search"
http://www.mysite.com/?search=installer&page=2 still triggers action "search"

This implies that query string parameters order matters for CMSity tell which action will be executed.

Going deeper

Let's focus on the first template sample from Documentation's Intruduction.

<html>
 <head>
  <title>
   <? p('title') ?>
  </title>
 </head>
 <body>
  <? p('title', 'h1') ?>
  <? p('author', 'p.author') ?>
  <? p('content', 'div#content') ?>
 </body>
</html>

So may notice small pieces of PHP code injected into HTML code of the template. This is the major idea of CMSity, let you create great templates with minimum of PHP code. Of course this is not a limitation, you may put any PHP code you want in the template.

If you suspect that <? p('title') ?> prints a node's title (which is one of node's property) and <? p('author', 'p.author') ?> will print node's author wrapped with <p> tag having class "author", you are absolutely right! p is core CMSity function responsible for printing current node's properties (data).

Once again, a template is just PHP code that is executed by CMSity in the context of current node relative to requested URL. Having that, you may also use includes to make your code more clean and elegant splitting your templates into reusable chunks:

header.php

<html>
 <head>
  <title>
   <? p('title') ?>
  </title>
 </head>
 <body>

topic.view.php

<? include('header.php') ?>
  <? p('title', 'h1') ?>
  <? p('author', 'p.author') ?>
  <? p('content', 'div#content') ?>
<? include('footer.php') ?>

footer.php

 </body>
</html>

Template code is NEVER executed directly

Proper CMSity installation will never let your template PHP code to be executed directly by web server. Which means there will be no URL such as http://www.mysite.com/templates/topic.view.php triggering the template code while omitting the context of CMSity itself. This is similar concept as you may find in Ruby on Rails.

So if you install properly CMSity you can be sure that no web user will access you template files and all helper side files directly and even know of their existence. Users will not notice also that this site is using PHP, unless you explicitly write this at your site ;)

Automatic menus and tabs

Every site has some navigation elements at each page. So we shall add basic navigation to our templates too. Best place to do it may be header.php:

<html>
 <head>
  <title>
   <? p('title') ?>
  </title>
 </head>
 <body>
   <?php p_links(2, 'page,blog,forum') ?>

This time we have used next usefull CMSity API function p_links. This function builds a menu of tree elements of type "page", "blog" or "forum". By default p_links is using <ul> and <li> tags, however this may be overridden. First parameter means depth, for current element and children, 1 children, 2 all descendants.

Now let's take an example from CMSity site where we have tabs of 1st level elements only wrapped just with <a> anchor elements, this was generated using:

<?php p_links(1, 'page,blog,user-list,forum,doc', false, 'a', 0, false) ?>

First parameters means we want just children, 2nd parameter is type of elements we want to have at the tabs, 3rd's false for main list tag, 4th 'a' for item tag (we want just an anchor here). Next goes 5th parameters having value of that tells p_links to start printing the elements from the tree's root rather than current element.

Having that we can expect for this page it will generate following code:

<a href="/cmsity/blog">Blog</a>
<a class="active" href="/cmsity/documentation">Documentation</a>
<a href="/cmsity/download">Download</a>
<a href="/cmsity/features">Features</a>
<a href="/cmsity/forum">Forum</a>
<a href="/cmsity/users">Users</a>

Note class="active" added by p_links automatically is current page is within the listed element.

Listing subnodes of current node using l_each

We have learnt that p_links can create various menus of links to site's pages. However if we want to create more sophisticated lists such as blogs we may want to have a look at l_each function.

l_each loops trough subnodes of current node changing the context of some printing functions such as p. This means that inside l_each loop p will print property values of looped subnode element rather than current node. Let's create blog.view.php template for node of type "blog":

<? include('header.php') ?>
  <? p('title', 'h1') ?>
  <? p('author', 'p.author') ?>
  <? p('content', 'div#content') ?>
  <? while(l_each('post')): ?>
    <? p('title', 'h1', true) ?>
    <? p('content', false, 'More...') ?>
  <? endwhile ?>
<? include('footer.php') ?>

If you look at the result of this template you will see that p calls withing l_each indeed prints "title" and "content" of all descendants of type "post" of current element.

You may also notice extra 3rd parameters to p function, which is responsible for wrapping the printed property with a link (anchor) to the printed element itself, true in this case means wrapping all value (text) into a tag, while textual parameter adds a text as specified that will be a link to the element.

Content brief and "more" links

3rd p's parameter has also some extra feature that prints only the brief (beginning) of the content when the parameter's value is non-empty. So if content contains a paragraph with single dash (<p>-</p>), that is treated as a divider, text that follows the divider is printed only when 3rd parameters is empty (false).