Location: PHPKode > projects > Runner > docs/template_maker.html
<!--
 **********************************************************************
 *  Copyright 2008
 * 
 *  This file is part of Runner.
 * 
 *  Runner is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 * 
 *  Runner is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 * 
 *  You should have received a copy of the GNU General Public License
 *  along with Runner.  If not, see <http://www.gnu.org/licenses/>.
 *
 ********************************************************************** 
*/
-->

<html>
<head>
<title>Template Developer Documentation</title>


<style type="text/css">

@media all {
	body {
		font-family: Verdana, Arial, Helvetica, Garamond, sans-serif;
		text-align: left;
		background-color: #FFF;
		font-size: 90%;
		margin: 5px;
		padding: 10px 5px 10px 5px ; 
	}
	a:link {color: #993333; text-decoration: underline}
	a:visited {color: #993333; text-decoration: underline}//#006699;
	a:active {color: #FF3300; text-decoration: underline}
	a:hover {color: navy; text-decoration: underline}
	h1 { font-family: Comic, Lithograph, Arial; color:black; text-align: left; font-size: 180%; font-weight: 600; display: inline;}
	h2 { font-family: Comic, Lithograph, Arial; color:black; text-align: left; font-size: 160%; font-weight: bold}
	img, table {border-width: 0px}
	
	h3 {font-family: Comic, Lithograph, Arial; color:black; text-align: left; font-size: 120%}
	p, td {font-family: Verdana, Arial, Helvetica, Garamond, sans-serif; font-size: 90%; text-align: left; vertical-align: top;}
		
	th {
		font-family: Verdana, Arial, Lithograph, Helvetica, sans-serif;
		text-align: left;
		font-size: 90%;
		font-weight: bold;
		vertical-align:top;
	}
	
	code {
		font-family: "Courier New", Courier, mono;
		font-size: 100%;
		white-space: pre;
	}
	blockquote {
		width:800px;
		background-color:#DFDFDF;
		border:1px dashed #4D4D4D;
		padding:10px;
	}
table.sample {
	border-width: 1px 1px 1px 1px;
	border-spacing: 2px;
	border-style: solid solid solid solid;
	border-color: gray gray gray gray;
	border-collapse: separate;
	background-color: rgb(255, 245, 238);
}
table.sample th {
	border-width: 1px 1px 1px 1px;
	padding: 2px 2px 2px 2px;
	border-style: none none solid none;
	border-color: black black black black;
	background-color: rgb(250, 240, 230);
	-moz-border-radius: 0px 0px 0px 0px;
}
table.sample td {
	border-width: 1px 1px 1px 1px;
	padding: 2px 2px 2px 2px;
	border-style: none none none none;
	border-color: black black black black;
	background-color: rgb(250, 240, 230);
	-moz-border-radius: 0px 0px 0px 0px;
}	
}
</style>
</head>

<body>

<img src='images/runner_logo.png' width='35px' style='margin:0px;padding:00px;'><span style='float:left;'><h3>Runner v. 1.0</h3></span><br><br><span style='float:right;'>Copyright (c) 2008</span><br>
<br>
<hr>

<h1>Template Developer Documentation</h1><br>
<a href='index.html'><< Back</a>

<h2>Table of contents</h2>
<ul>
	<li><a href='#intro'>Introduction</a></li>
	<li><a href='#template_files'>Template Files</a></li>
	<ul>
		<li><a href='#config_files'>Config Files</a></li>
	</ul>
	<li><a href='#variables'>Variables</a></li>
	<ul>
		<li><a href='#var_modifiers'>Modifiers</a></li>
		<li><a href='#var_attributes'>Attributes</a></li>
	</ul>
	<li><a href='#include_files'>Include Files</a></li>
	<li><a href='#include_php'>Include PHP</a></li>
	<li><a href='#if'>IF statements</a></li>
	<li><a href='#foreach'>FOREACH loops</a></li>
	<li><a href='#select'>SELECT</a></li>
	<ul>
		<li><a href='#option'>Select OPTIONS</a></li>
	</ul>
	<li><a href='#index'>Index</a></li>
	<ul>
		<li><a href='#var_mod_table'>Variable Modifiers Table</a></li>
		<li><a href='#runner_vars'>Reserved Variables</a></li>
	</ul>
</ul>

<h2><a name="intro" id="intro"></a>Introduction</h2>
<p>
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. 
</p>

<h2><a name="template_files" id="template_files"></a>Template Files</h2>
<p>
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. 

</p>

<h2><a name="config_files" id="config_files"></a>Configuration File</h2>
<p>
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.
<br>
<br>
<code>./templates/design_one.tpl</code>

<blockquote>
	<code>Name = Design One
Version = 0.1.9
Designer = John Doe
Copyright = 2008
Directory = design_one
StyleSheet = default_skin.css
StyleSheetIE = css_for_ie.css</code>
</blockquote>
</p>

<h2><a name="variables" id="variables"></a>Variables</h2>
<p>
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.
<br>
<br>
	<code>{$variable_name}</code>
<br>
<br>
Variables can also be arrays. If the main php script created an 
array, lets say $fish, and $fish contains the elements, <code>('herring', 'tuna', 'flounder', 'sharks' => 'great white' 'whale shark')</code>.

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

<h2><a name='var_modifiers'></a>Variable Modifiers</h2>
<p>	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 <a href='#var_mod_table'>MODIFIER table</a> for full list) 

<br><br>
<h4>Example:</h4>
	<code>$name = "jAne doE";</code>
	<blockquote>
		<code>{$name|capitalize}
{$name|lowercase|capitalize}</code>
	</blockquote>
	<blockquote><samp>
	JAne DoE<br>
	Jane Doe</samp>
	</blockquote>
</p>

<h2><a name='var_attributes'></a>Variable Attributes</h2>
<p>	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.
<br><br>
<h4>Example:</h4>
	<code>$when = "January 30th 2009";
$where = "The Park";</code>
	<blockquote><code>When: {$when|date_format="m.d.y"}
Where: {$where|default="Anywhere"}
Who: {$who|default="Everyone"}</code>
	</blockquote>
	<blockquote>
		<samp>When: 1.30.9<br>Where: The Park<br>Who: Everyone</samp>
	</blockquote>
</p>

<h2><a name='include_files'></a>Include Files</h2>
<p>	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.
<br><br>
<h4>Example:</h4>
	<code>Top_Half.tpl</code>
	<blockquote><code>Top half file< br></code>
	</blockquote>
	<code>index.tpl</code>
	<blockquote><code>{include 'Top_Half.tpl'}
< br>
< center>  :)  < /center></code>
	</blockquote>
	<blockquote>
		<samp>Top half file<br><br><center>:)</center></samp>
	</blockquote>
</p>

<h2><a name='include_php'></a>Include PHP</h2>
<p>	If a template requires an additional .php file, you <i>MUST</i> 
include it using the <code>{include_php}</code> tag. I works in the 
same way as the <code>{include}</code> tag above.
<br><br>
<h4>Example:</h4>
	<code>Top_Half.php</code>
	<blockquote><code>< ?php echo "Hello from the top half!"; ?></code>
	</blockquote>
	<code>index.tpl</code>
	<blockquote><code>{include_php 'Top_Half.php'}
< br>
< center>  :)  < /center></code>
	</blockquote>
	<blockquote>
		<samp>Hello from the top half!<br><center>:)</center></samp>
	</blockquote>
</p>

<h2><a name='if'></a>IF tags</h2>
<p>	With the introduction of variables it becomes vital to include <code>{if}</code> 
	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"/"||").
<br><br>
<h4>Example:</h4>
	<code>$user_type = "admin";</code>
	<blockquote>
		<code>{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}</code>
	</blockquote>
	<blockquote>
		<samp>You are an Admin!</samp>
	</blockquote>
</p>

<h2><a name='foreach'></a>FOREACH tag</h2>
<p>	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.
<br><br>
<h4>Example:</h4>
	<code>$fish_array = 'herring', 'tuna', 'salmon'</code>
	<blockquote>
<code>{foreach from=$fish_array item='fish'}
				
	A {$fish} is a fish.< br>
				
{/foreach}</code>
	</blockquote>
	<blockquote><samp>A herring is a fish.<br>
			A tuna is a fish.<br>
			A salmon is a fish.<br></samp>
	</blockquote>
	
 Keys may also be used for cycling though arrays
 <br><br>
<h4>Example:</h4>
	<code>$fish = array(
	"herring" => array(
		"description" => "Good fish",
		"found_in" => "atlantic")
	"tuna" => array(
		"description" => "BIG fish",
		"found_in" => "cans")
	);</code>
	<blockquote>
<code>{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}</code>
	</blockquote>
	<blockquote><samp>herring:<br>
			&nbsp;&nbsp;&nbsp;&nbsp;Description - Good fish<br>
			&nbsp;&nbsp;&nbsp;&nbsp;Found In - atlantic<br></samp><hr>
			<samp>tuna:<br>
			&nbsp;&nbsp;&nbsp;&nbsp;Description - BIG fish<br>
			&nbsp;&nbsp;&nbsp;&nbsp;Found In - cans<br><hr></samp>
	</blockquote>
 </p>
 
 <h2><a name='select'></a>SELECT tag</h2>
 <p>
 	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. 
</p>

 <h2><a name='option'></a>OPTION tag</h2>
 <p>
 	Option tags are alternates to the <code>< option></code> tag set in 
 	HTML. The advantage to using the Runner <code>{option}</code> 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.
</p>
<p>
	A few options can be passed to the <code>{option}</code> tag.
	<table class='sample' width='800px'>
		<tr><th><b>Option</b></th><th><b>Meaning</b></th><th><b>Example</b></th></tr>
		<tr><td>name</td><td>Sets the displayed value for the tag</td><td>name='Cat'</td></tr>
		<tr><td>value</td><td>Sets form value for the option</td><td>value='2'</td></tr>
		<tr><td>name_set</td><td>Array containing names to be set.</td><td>name_set=$options</td></tr>
		<tr><td>value_set</td><td>Array containing values to be set.</td><td>value_set=$form_values</td></tr>
	</table>
If you are passing an array with a structure of "key" => "value", you 
may just define <code>value_set</code> and it will assume "key" to be 
the displayed value and "value" to be the value of the option.

<h4>Example:</h4>
	<code>
$val_and_key = "Red" => "1", "Orange" => "2", "Yellow" => "3", "Green" => "4", "Blue" => "5";
$name = "Red", "Orange", "Yellow", "Blue";
$val = "1", "2", "3", "4";</code>
	<blockquote>
<code>{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}</code>
	</blockquote>
	<blockquote>
		<select name='color_box' id='colors'>
			<option value='1'>red</option><option value='2'>orange</option><option value='3'>yellow</option><option value='4'>green</option><option value='5'>blue</option>
		</select>
		<hr>
		<select name='color_box_2' id='colors'>
			<option value='1'>Red</option><option value='2'>Orange</option><option value='3'>Yellow</option><option value='4'>Green</option><option value='5'>Blue</option><option value='6'>Purple</option>
		</select>
		<hr>
		<select name='food' id='food'>
			<option value='p'>pizza</option>
			<option value='c'>carrots</option>
			<option value='pas'>pasta</option>
			<option value='i'>ice cream</option>
		</select>
	</blockquote>
 </p>
<h2><a name='index'></a>Index</h2>
<h3><a name='var_mod_table'></a>Varibale Modifications Table</h3>
<p>Modifiers can be used more than once and are executed in the order given<p>
Ex. $name = JaNe DOe;<br><code>{$name|lowercase|capitalize|reverse|capitalize|reverse}</code> --> JanE DoE
<table class='sample' width='800px'>
<tr><th>Option</th><th>Action</th><th>Example</th></tr>
<tr><td>uppercase</td><td>Converts string to all upercase</td><td>{$name|uppercase} --> JANE DOE</td><tr>
<tr><td>lowercase</td><td>Converts string to all lowercase</td><td>{$name|lowercase} --> jane doe</td><tr>
<tr><td>captialize</td><td>Capitalizes each word</td><td>{$name|capitalize} --> Jane Doe</td><tr>
<tr><td>reverse</td><td>Reverses the sting order</td><td>{$name|reverse} --> eod enaj</td><tr>
<tr><td>count</td><td>Returns the number of characters in the string</td><td>{$name|count} --> 8</td></tr>
</table>
<h3><a name='runner_vars'></a>Reserved Vars</h3>
<table class='sample' width='800px'>
<tr><th>Variable Name</th><th>Content</th></tr>

<tr><td>$runner.page</td><td>Script file name (index.php)</td></tr>
<tr><td>$runner.unix_time</td><td>Current Unix timestamp</td></tr>
<tr><td>$runner.now</td><td>Current Unix timestamp</td></tr>
<tr><td>$runner.time</td><td>Current time (format set in webiste config file)</td></tr>
<tr><td>$runner.date</td><td>Current date (format set in webiste config file)</td></tr>
<tr><td>$runner.random</td><td>Returns a random number [0,100]</td></tr>

<tr><td>$runner.webiste</td><td>Array containing webiste info</td></tr>
<tr><td>$runner.webiste.url</td><td>webiste root url</td></tr>
<tr><td>$runner.webiste.root_dir</td><td>webiste root directory</td></tr>
<tr><td>$runner.webiste.page</td><td>current page</td></tr>
<tr><td>$runner.webiste.dir</td><td>current directory of website</td></tr>

<tr><td>$runner.template</td><td>array of template specific data</td></tr>
<tr><td>$runner.template.name</td><td>Name of template</td></tr>
<tr><td>$runner.template.version</td><td>template version</td></tr>
<tr><td>$runner.template.designer</td><td>Designer of template</td></tr>
<tr><td>$runner.template.copyright</td><td>copyright of template</td></tr>
<tr><td>$runner.template.web_dir</td><td>URL to template root directory</td></tr>
<tr><td>$runner.template.file_dir</td><td>file directory to template files</td></tr>
<tr><td>$runner.template.short_dir</td><td>string to reference files from website root</td></tr>
<tr><td>$runner.template.css_file</td><td>filename of default CSS file</td></tr>
<tr><td>$runner.template.css</td><td>complete path to default CSS file</td></tr>
<tr><td>$runner.template.css_ie_file</td><td>filename of default IE CSS file</td></tr>
<tr><td>$runner.template.css_ie</td><td>complete path to default IE CSS file</td></tr>

<tr><td>$runner.session</td><td>array of session data</td></tr>
<tr><td>$runner.get</td><td>array of GET data</td></tr>
<tr><td>$runner.post</td><td>array of POST data</td></tr>
<tr><td>$runner.cookie</td><td>array of cookies</td></tr>
<tr><td>$runner.env</td><td>array of enviornment data</td></tr>
<tr><td>$runner.server</td><td>array of server data ($_SERVER)</td></tr>
</table>
Return current item: Runner