Runner v. 1.0



Copyright (c) 2008


Template Developer Documentation


<< Back

Table of contents

Introduction

Because of the complications the new database driven website creates, it became necessary to create a template engine to efficiently create new designed and styles for the website. With this new system, Runner, it is now easier than ever to create an entirely different layout without having to worry about all the technical stuff, but instead making the site look good. So because of the advanced functionality of Runner, it quickly became necessary for there to be some documentation and that is what you are about to read.

Template Files

Template files have the file extension ".tpl" This keeps them from being executable without the parser parsing them first. Additionally all template files are stored in their template directory. For most web sites this will be ./templates/[template name] This way many templates can be uploaded to the site without interfering with each other.

Configuration File

Each template is defined by its config file. ([template name].tpl) This file is located in the ./templates/ directory of the webiste. If contains all the required information for the template, including the css file(s), the directory of the .tpl files, as well as creation info. An example config file is shown here.

./templates/design_one.tpl

Name = Design One Version = 0.1.9 Designer = John Doe Copyright = 2008 Directory = design_one StyleSheet = default_skin.css StyleSheetIE = css_for_ie.css

Variables

Variables play a large roll in Runner. They are the real connection between the long and nasty lines of code and the clean stylish results of Runner. The basic syntax of a variable is shown below.

{$variable_name}

Variables can also be arrays. If the main php script created an array, lets say $fish, and $fish contains the elements, ('herring', 'tuna', 'flounder', 'sharks' => 'great white' 'whale shark'). now that the array was created in the php script, each element can be called from the template simply by referring to its array index

Example:

$fish = ('herring', 'tuna', 'flounder', 'sharks' => ('great white', 'whale shark') )
{$fish.0} {$fish.sharks.1}
'herring' 'whale shark'
There are also set variables that cannot be changed for are auto-updated. These can be referenced by using {$runner.} they are known as runner vars. They include things like {$runner.time} {$runner.date} {$runner.website.url} and {$runner.session}. They can refernce many useful things please refer to Appendix A for a complete listing of these variables.

Variable Modifiers

Often it becomes necessary to change the formating of a particular variable. Modifiers allow us to do this. Simply be adding "|" and then the modifier after the variable we are able to define certain characteristics.(See MODIFIER table for full list)

Example:

$name = "jAne doE";
{$name|capitalize} {$name|lowercase|capitalize}
JAne DoE
Jane Doe

Variable Attributes

There are other types of modifiers as well, including attribute modifiers. These include functions such as 'default' and 'date_format'. By using these modifiers one can have the variable assume standard values, or take a defined syntax.

Example:

$when = "January 30th 2009"; $where = "The Park";
When: {$when|date_format="m.d.y"} Where: {$where|default="Anywhere"} Who: {$who|default="Everyone"}
When: 1.30.9
Where: The Park
Who: Everyone

Include Files

Often times it is necessary, and more efficient to simply include a template file into another template file. For example it would be easiest to re include the page's unchanging top half from a template file. Files are first assumed to be in the current directory of the template (Ex /templates/demo/Top_Half.tpl). This can be changed by specifying the path to the file, using the file="" attribute.

Example:

Top_Half.tpl
Top half file< br>
index.tpl
{include 'Top_Half.tpl'} < br> < center> :) < /center>
Top half file

:)

Include PHP

If a template requires an additional .php file, you MUST include it using the {include_php} tag. I works in the same way as the {include} tag above.

Example:

Top_Half.php
< ?php echo "Hello from the top half!"; ?>
index.tpl
{include_php 'Top_Half.php'} < br> < center> :) < /center>
Hello from the top half!
:)

IF tags

With the introduction of variables it becomes vital to include {if} statements, in order to better design the page around those variables. The basic syntax of the if statements is quite simple, as it is the common syntax used in PHP, of coarse all standard conditionals can be used , (==, !=, <=, >=), as well as "and"/"&&" and "or"/"||").

Example:

$user_type = "admin";
{if $user_type == "admin"} You are an Admin! {elseif $user_type == "moderator"} You are almost and Admin. {elseif $user_type == "user"} You are just a lonesome user... {elseif $user_type != ""} We dont know what you are :\ {else} Log in and we can see what you are {/if}
You are an Admin!

FOREACH tag

This handy function is often used for cycling through arrays. The basic idea of this function is to execute the contained code once for each of the values in an array.

Example:

$fish_array = 'herring', 'tuna', 'salmon'
{foreach from=$fish_array item='fish'} A {$fish} is a fish.< br> {/foreach}
A herring is a fish.
A tuna is a fish.
A salmon is a fish.
Keys may also be used for cycling though arrays

Example:

$fish = array( "herring" => array( "description" => "Good fish", "found_in" => "atlantic") "tuna" => array( "description" => "BIG fish", "found_in" => "cans") );
{foreach from=$fish key='fish_name' item='about_fish'} {$fish_name}:< br> Description - {$about_fish.description}< br> Found In - {$about_fish.found_in}< br> < hr> {/foreach}
herring:
    Description - Good fish
    Found In - atlantic

tuna:
    Description - BIG fish
    Found In - cans

SELECT tag

Drop down boxes are very common in we pages. Thus we included a handy tag to create them for you. Simply call the {select} tag along with any {option} tags to create a quick and easy drop down box.

OPTION tag

Option tags are alternates to the < option> tag set in HTML. The advantage to using the Runner {option} tag is that you can pass arrays for the arguments, and each element will be treated as a separate < option> tag, saving a lot of time, as well as making creating dynamic select boxes much easier.

A few options can be passed to the {option} tag.
OptionMeaningExample
nameSets the displayed value for the tagname='Cat'
valueSets form value for the optionvalue='2'
name_setArray containing names to be set.name_set=$options
value_setArray containing values to be set.value_set=$form_values
If you are passing an array with a structure of "key" => "value", you may just define value_set and it will assume "key" to be the displayed value and "value" to be the value of the option.

Example:

$val_and_key = "Red" => "1", "Orange" => "2", "Yellow" => "3", "Green" => "4", "Blue" => "5"; $name = "Red", "Orange", "Yellow", "Blue"; $val = "1", "2", "3", "4";
{select name='color_box' id='colors'} {option val_set=$val_and_key} {/select} < hr> {select name='color_box_2' id='colors'} {option val_set=$val name_set=$name} {/select} < hr> {select name='food' id='food'} {option name='pizza' value='p'} {option name='carrots' value='c'} {option name='pasta' value='pas'} {option name='ice cream' value='i'} {/select}


Index

Varibale Modifications Table

Modifiers can be used more than once and are executed in the order given

Ex. $name = JaNe DOe;
{$name|lowercase|capitalize|reverse|capitalize|reverse} --> JanE DoE
OptionActionExample
uppercaseConverts string to all upercase{$name|uppercase} --> JANE DOE
lowercaseConverts string to all lowercase{$name|lowercase} --> jane doe
captializeCapitalizes each word{$name|capitalize} --> Jane Doe
reverseReverses the sting order{$name|reverse} --> eod enaj
countReturns the number of characters in the string{$name|count} --> 8

Reserved Vars

Variable NameContent
$runner.pageScript file name (index.php)
$runner.unix_timeCurrent Unix timestamp
$runner.nowCurrent Unix timestamp
$runner.timeCurrent time (format set in webiste config file)
$runner.dateCurrent date (format set in webiste config file)
$runner.randomReturns a random number [0,100]
$runner.webisteArray containing webiste info
$runner.webiste.urlwebiste root url
$runner.webiste.root_dirwebiste root directory
$runner.webiste.pagecurrent page
$runner.webiste.dircurrent directory of website
$runner.templatearray of template specific data
$runner.template.nameName of template
$runner.template.versiontemplate version
$runner.template.designerDesigner of template
$runner.template.copyrightcopyright of template
$runner.template.web_dirURL to template root directory
$runner.template.file_dirfile directory to template files
$runner.template.short_dirstring to reference files from website root
$runner.template.css_filefilename of default CSS file
$runner.template.csscomplete path to default CSS file
$runner.template.css_ie_filefilename of default IE CSS file
$runner.template.css_iecomplete path to default IE CSS file
$runner.sessionarray of session data
$runner.getarray of GET data
$runner.postarray of POST data
$runner.cookiearray of cookies
$runner.envarray of enviornment data
$runner.serverarray of server data ($_SERVER)


SourceForge.net Logo