tpl format crash course

tpl format is a templating system and core component of ShiftLibrary. It has been built from the ground up and structured with both designers and developers in mind. Designers are not expected to be coders but should know their way around HTML.

Key advantages of tpl format

  • Designer and developer friendly
  • Dreamweaver friendly
  • Human readable urls
  • Files are more organised
  • Less repeated code
  • SEO benefits like: Auto page titles / Auto sitemap
  • Error reporting
  • Powerful set of functions and components at your disposal

tpl format folder structure

root ----
	|
	---- _inc
	|
	---- _lib
	|
	---- _tpl
		|
		----- template.php

_inc folder contains configuration files: namely config.php and custom.php.
_lib folder is linked to a collection of shared libraries.
_tpl folder is where all the templates go.
template.php is the main template file.

Anatomy of a template

Webpages from the same website tend to share a lot of the same content. Most webpages will have the same header / navigation / footer and sometimes side navigation. They will then have some content in the middle which is totally unique to that page.

template.php is the content of that typical page minus the unique content. In the place of the unique content is a placeholder:
<?=$include_content;?>

Adding pages

Adding pages is simple. Just create a file in the template folder e.g. about.php. The file extension is always php. Populate the new file with the unique content. The unique content is the middle part of the page and should not contain any <html> or <body> tags.

You can now access this page from http://<your-domain>/about
And link to this page like so: <a href="about">about us</a>
note the absence of .php

To create an index page you should call the file index.php

You can also create folders within the _tpl folder. So you could create a folder called news. And within that you could have an index page and an article page.

root ----
	|
	---- _tpl
		|
		----- news
		|	|
		|	----- article.php
		|	|
		|	----- index.php
		|
		----- template.php

These new pages would be accessed like so:

http://<your-domain>/news/article
http://<your-domain>/news/

Multiple templates

In the above example you could also have a completely separate template for the news section. e,g,

root ----
	|
	---- _tpl
		|
		----- news
		|	|
		|	----- article.php
		|	|
		|	----- index.php
		|	|
		|	----- template.php
		|
		----- template.php

In this case the template.php in the news folder will be used instead of the one in the root.

Page without template.php

You may need to display a page without having it pulled into template.php at all.
For example you might have a popup window or an iframe.
To prevent the page being pulled into template.php add the following to the bottom of the template:

<?php
$use_template=false;
?>

This works because the page template is executed before template.php itself.

Auto page titles

Unique page titles are inportant as they are used by search engines, bookmarks and tabs.

templates are automatically scanned for the first heading tag e.g: <h1>page title</h1>.
The content of the h1 tag can then be used in the page title.

You can add it to your template page like so:

<title>My site | <?=$title ? $title : 'default page title';?></title>

The default title is used when the included page does not contain a h1 tag.

These titles can be over-rided on a per-page basis by defining $title at the top of the include.
e.g.
    <? $title='Use this title instead'; ?>

AJAX libraries

You can include popular AJAX libraries using the following code:

<? load_js('jquery'); ?>

Or for more than one:

<? load_js(array('jquery','swfobject')); ?>

This should be placed in the head section of template.php.
Where supported the libraries will be loaded via a CDN (content delivery network), resulting in faster loading.
The following AJAX options are supported:

  • jquery
  • prototype
  • extjs
  • lightbox
  • scriptaculous
  • swfobject

Dependencies are automatically worked out. So for example if you include lightbox - it will automatically load prototype and scriptaculous as well.
It will load the latest versions of the libraries.

Sitemaps

An XML sitemap is automatically generated and can be sunmitted to google.
It is located here: http://<your-domain>/sitemap.xml

Forced www

By default ShiftLib will 301 redirect the non-www address to www.

e.g. example.com will be redirected to www.example.com.

This is to prevent duplicate content issues in search engines - as well as prevent cookie problems.

config.php

This file is located in the _inc folder.
It contains the site configuration including database login details and the default email address.

custom.php

This file is located in the _inc folder.
It contains custom functions specific to the site.

Page load time

You can display how long it took the page to load (without scripts/ images) by adding the following php code anywhere in your template:

    <? $show_load_time=true; ?>

404 error page

A 404 error page will be displayed if a template is not found. You can create your own custom 404 page by creating a file called 404.php in the template directory.

You can programatically force a 404 error by adding the following php code:

    <? $trigger_404=true; ?>

This can be useful when working with a database-driven page that returns no results.

Reserved php variables

$include_content
Parsed content of the included template.

$title
The content of the first H1 tag found in the included template.

$auth
An authentication class used to allow users to log into the website.

$request
The page request URI.

$current_tab
The first item from the sections array

$trigger_404
A boolean that when set to true displays a 404 message.

$sections
The URI broken into an array separated by '/'

$show_load_time
A boolean that when set to true displays the page load time.

Reserved page names

admin
The admin system

logout
Logs a user out of the system and then redirects to the home page.