Skins and Tokens Explained

June 22, 2008

Recommended

Designing with Web Standards (2nd Edition)

The SkyBlueCanvas template system, also referred to as the skin system, uses a simple content token replacement technique. A content token is a placeholder that allows you to tell SkyBlueCanvas that a particular part of a page, usually an HTML element, will contain some type of content. That content can be an article of text, a list of links or a photo gallery.

SkyBlueCanvas is designed to make web site creation as simple as possible so unlike true template scripting languages like Smarty, the SkyBlueCanvas content token replacement system does not include any logic such as loops or conditionals. Stated very simply, the SkyBlueCanvas skin system uses basic string-replacement to allow you to specify which content will appear where in your HTML template.

Structure of a Skin

The simplest breakdown of a skin is what I refer to as the skeleton of a page. The skeleton includes elements that will appear on every web page, no matter what elements make up the body of the page. These common elements include the document type declaration, the HTML, HEAD, TITLE, META, SCRIPT, STYLE and BODY elements.

The code shown in Diagram 1 is the HTML skeleton that comes with SkyBlueCanvas.

Diagram 1

Located in /skyblue/rsrc/page.skeleton.html

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN”
  ”http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>
<html{doc:lang}>
  <head>
    <title>{page:title}</title>
    <meta http-equiv=”Content-Type”
          content=”text/html; charset=iso-8859-1?
          />    
    {region:meta}
    <meta http-equiv=”imagetoolbar”
          content=”no”
          />
    <script type=”text/javascript”>
        var base_uri = ‘{page:base_uri}‘;
    </script>
    {region:links}
    {region:styles}
    {region:scripts}
    {region:favicon}
    {plugin:preloader}
  </head>
  <body{page:bodyid}{body:class}>
      <!– Begin Your Skin Code –>
      {page:body}
      <!– End Your Skin Code –>
  </body>
</html>

This is the HTML that is used to render every page in a SkyBlueCanvas site. When a page is requested by a site visitor, the Skin Engine uses this HTML as the framework - or skeleton - for the page. You will notice that there are several tokens in the format {token-name} where you might usually find literal values or HTML elements such as SCRIPT and META tags. These tokens represent variable elements and act as placeholders until SkyBlueCanvas determines the specific values of the items with which the tokens will be replaced.

About the Tokens

There are two types of tokens used in SkyBluecanvas: user-owned and system-owned tokens. By owned we mean that either the user - the person building/managing the web site - or the system has control over where the tokens in question appear and with what they will be replaced. I refer to the process of mapping content to tokens as ‘targeting’ the content to a token.

It is very easy to distinguish between user-owned and system-owned tokens. Any token that appears in page.skeleton.html is system-owned. This means that the system will determine with what each of these tokens will be replaced. The complete list of system-owned tokens with their corresponding PHP constants are listed below.

HTML Token PHP Constant
{build} TOKEN_BUILD
{page:title} TOKEN_PAGE_TITLE
{inc:scripts} TOKEN_SCRIPTS
{analytics} TOKEN_ANALYTICS
{body:class} TOKEN_BODY_CLASS
{region:links} REGION_LINKS
{region:meta} REGION_META
{region:styles} REGION_STYLES
{region:scripts} REGION_SCRIPTS

The person building the site skin would probably not have any reason to ever use these tokens.* Most of them are non-displaying items for things such as meta, script and stylesheet tags.

User-owned tokens are any tokens that the person building the skin places in some HTML element as a placeholder for content. The complete list of user-owned tokens and their corresponding constants are listed below.

HTML Token PHP Constant
{region:main} REGION_MAIN
{region:top} REGION_TOP
{region:left} REGION_LEFT
{region:right} REGION_RIGHT
{region:footer} REGION_FOOTER
{region:pathway} REGION_PATHWAY

SkyBlueCanvas does not have any knowledge of the structure of the HTML of a page. It only looks for the content replacement tokens and replaces them with the content you specify in the SkyBlueCanvas administrator control panel. An in-depth explanation of how this ‘content targeting’ is done can be found in the article on Content Publishing.

A Simple Skin Example

Perhaps a better understanding of the content token replacement can be gained by examining a simple skin example and a diagram of the regions represented by each token. Diagram 2 shows the HTML for a very simple skin. Diagram 3 uses the token names to demonstrate where content targeted to each token will appear.

Diagram 2

<div id=”wrapper”>
<div id=”header”>
   <h1>{page:title}</h1>
    {region:header}
</div>
<div id=”top”>{region:top}</div>
<div id=”breadcrumbs”>{region:pathway}</div>
<div id=”left”>{region:left}</div>
<div id=”main”>{region:main}</div>
<div id=”right”>{region:right}</div>
<div id=”footer”>{region:footer}</div>
</div>

Diagram 3

Diagram of SkyBlueCanvas template regions

Look closely at each token in the HTML example then find it in the image in Diagram 3. When you include one of these tokens in your Skin HTML then log into the administrator control panel and go to Collections Publishing [Diagram 4], these tokens are the options that appear in the ‘Region’ selector next to each page.

Diagram 4

Diagram of SkyBlueCanvas publishing regions

Multiple Page Layouts

SkyBlueCanvas makes it possible to use different layouts on different pages. You can make use of this feature by creating additional HTML template files in /skyblue/data/skins/yourskin/.

There are two strict rules regarding layout files:

  1. There must be a file named skin.default.html present in your skin directory
  2. Additional layouts must follow the skin.[name].html format

Diagram 5

Diagram of SkyBlueCanvas page layout selection

If you refer to Diagram 5, you will see the Page Manager interface. When you include more than one HTML layout file in your skin directory, these skins are loaded as the choices in the selector highlighted in blue in Diagram 5.

This next bit will be a little tricky so follow me closely. Refer again to Diagram 4. In this diagram you will see the Collections Publishing Manager interface. When you open the collections publisher, the publisher creates a composite list of all tokens in all of your template HTML files. This composite list are the choices in the Region selector highlighted in blue in Diagram 4.

When you select a region for a particular collection to appear in, SkyBlueCanvas saves this selection as part of the collection publishing objects parameters. Now we have come full circle back to the Skin Engine and how a page is rendered in SkyBlueCanvas. When a specific page is requested by a site visitor, the Skin Engine loads the skeleton, the page data object and all collections associated with that page into memory.

The Skin Engine then parses the template file specified for the page requested by your site visitor. The parsing of the template is a fancy way of saying it looks to see which tokens appear in that template file.

Next, the Skin Engine loads the collection publishing data file and looks for Collections that you indicated are to appear on this page. As the Skin Engine goes through the list of collections it determines whether each collection appears on the current page and if it does, in which region it is to appear. When the page HTML is built, it replaces the token for that region with the output of whichever collection or collections you specified appear in that region. If a token does not have any content specified to replace it, it is replaced with an empty string.

A Word About Collections Output

A full explanation of Collections and their output is beyond the scope of this article. However, a brief word about this subject is warranted.

The output of a Collection is defined in the module file for each collection. These module files can be found in /skyblue/data/modules/. For instance, the HTML output of the Links Collection is created by the /skyblue/data/modules/mod.links.php file.

For information about additional features related to building SkyBlueCanvas templates, go to http://blog.skybluecanvas.com/skybluecanvas-lightweight-cms/skybluecanvas-sitevars-plugin/.

* More advanced programmers can manipulate the system-owned content tokens, which will be the subject of a future article.

Discussion

  1. Hello Scott,

    very interesting article, especially for me. Reading this article and try to follow your diagrams i didn’t find the page displaying your Diagram 4 anywhere on “my” system???

    Mike

    Michael Reichert | June 27, 2008, 2:20 am

  2. Michael,

    Go to Admin > Collections > Collections Publishing and you will find it there. Collections Publishing is the wide button at the very top of the page when you click the Collections tab.

    Scott

    admin | June 27, 2008, 6:29 am

  3. Hey Scott,

    I’m trying to make my skyblue standards compliant and I cant seem to find where I can change {doc:lang}…..

    Any help would be appreciated!

    Lee

    Lee M | July 21, 2008, 1:45 pm

  4. Lee,

    If you go to /your_skyblue_root/configs/server.consts.php and go to around line 126, you will see the following code:

    sb_conf(’SB_LANGUAGE’, ‘en-us’);

    You can change the ‘en-us’ to whatever you need it to be.

    Scott

    admin | July 21, 2008, 2:27 pm

Post a comment