Yet Another Template System

YATS is a template system designed as a library with helper functions for Code Igniter 1.5. This library was designed after the CI philosophies -- it's lean and straight forward. After installing YATS you'll see how easy is to create and edit templates for your projects!

Here's some features of YATS 1.1:

• Multiple templates support
• Configurable items
• Helper functions
• Modular structure
• Build a page with just one line of code
• Resources folder outside the MVC structure
• Permissive license
• Easy to design for and easy for designers

[b] Download File:yats11.zip[/b]

[h3]Installing[/h3] To get YATS up and running is quite easy, just a few steps, and you'll be running Code Igniter with a complete template system. See how you should do it.

[b]Drag and Dropping[/b]

1. Uncompress the downloaded file on your desktop and open the folder
2. Copy the folder application to your CI folder (if you're on a mac you'll have to copy the files individually)
3. Copy the assets folder called layout to your CI folder

[b]Configuring[/b]

1. Open the file application/config/autoload.php on your favorite text editor
2. Look for $autoload['libraries'] and set it to array('layout');
3. Look for $autoload['helpers'] and set it to array('html', 'url', 'layout');
4. Save and close it

Optionally you can edit or even add settings to YATS. For that just open the file application/config/layout.php and do your business.

[b]Now what?[/b]

Just open your browser and hit your CI project, and all should be running flawlessly.

[h3]Using YATS[/h3]

You can pretty much do any crazy graphic design for your page, and YATS will build it together with CI for your users. Yet, before we dig in we need to clarify one thing, and here it is: leave the graphic design in the CSS file and all should be okay. In other words, all data you generate with CI is there on all view files. So create the layout of your dreams that YATS will get the job done for you.

[b]Theme Files[/b]

Each theme has its own folder inside the assets folder which by default is [your-ci-project-folder]/layout/[theme]. There you'll see a folder for each type of common file that we use for making web pages. Just drop your theme files inside their folders and you can easily display it on the views.

[b]Assets folder structure[/b]

[code] layout L theme_name L css L images L script [/code]

[b]View Files[/b]

Each theme has its own folder inside the application/views folder, and its files are divided in two groups, commons and everything else. In the commons folder you'll place files shared by all theme, such as header.php, footer.php, and your custom layout elements files as well.

The other group of files are the views you create for your controllers. In order to keep things organized create a folder for each controller and there a view file for each action this controller does. For example we have a controller called welcome, then we create a folder after it, and inside that folder we create a view file to display the data which the controller generates.

[b]View folder structure[/b]

[code] views L theme_name | L common | | L footer.php | | L header.php
| | L hello.php
| L content | L module_name | L main.php | L form.php | L loader.php [/code]

As you can see here the view files are modular. So you'll never get lost while developing a project that needs a great deal of custom views.

[h3]Building Layout Elements[/h3]

Inside the layout_model.php we will code all common layout elements. For example, if a project has a menu we create a function inside this class, and when the page is built YATS automatically will call this function and display the menu. On a side note, do not edit this file outside the specified area (on the distribution files you can edit between the lines 31 and 74) unless you know what you're doing. Bellow you can see a template for these functions.

[code] function whatever() {
$retval['whatever'] = "Hello world!"; return $this->layout->load->view($this->theme . "whatever", $retval, true); } [/code]

On the first line inside the function the $retval variable is where you'll put the common data that will be sent to the function's view. On the second line we return the data completely formated to the YATS library. See that after $this->theme we have 'whatever' between double quotes, that's the view file for this function.

Once you've coded the function, open the file config/layout.php and look for this array $config['layout_elements'], and add it there. The function's name as a key and its parameters as value, if you have more than one parameter set an array for them. This way YATS will automatically generate and make that element available to all CI's view system.

Note: If you need to reset some of these parameters you can do it in the Constructor function bellow line 25.

[h3]Building The Whole Thing[/h3]

Here we can see how simple is to send a page to the user from any given controller. We have just two functions [b]buildPage[/b] which you can call to build and send a page to the user, and for dumping a view inside a variable use [b]dumpPage[/b]. Both functions work with a syntax that is very similar to the one used by CI views.

Now to go for the kill we'd simply code something like this: [code] $this->layout->buildPage('welcome/home', $data); [/code]

[h3]Need a Helper?[/h3]

YATS has a built in helper which well helps you :-) It's a set of functions to make things easier while writing views. Using this helping is entirely up to you since all that these functions do is write code for you, code which is there in form of theme properties or layout variables. However, some functions may give you some advantages such as the possibility of running validation routines before displaying data. Following you can see these functions along its details.

[b]display()[/b]

Tests and outputs a template variable to display it on a view. Its use is recommended directly in the view files. The first parameter is a string with the template variable or data to display. The second in an array with the validation calls. Once called it will display the data if the optional validation ran successfully or it will simply echo null.

Prototype: [code]display("template-variable", array("library" => "function"));[/code]

The validation here is quite different from the CI's validation library, this one is more like a shortcut. For example, we need to display a hello user message, however we wouldn't need to show it for google's spider. So following we see an example code where we call the is_browser the CI's agent library.

Also you could use this function to test whether or not a user is logged therefore leaving for the helper to decide if the content is to be shown.

Example: [code]display("hello_user", array("agent" => "is_browser"));[/code]

[b]dump()[/b]

This function works exactly like display(). However, instead of echoing the data it will just return it.

Prototype: [code]dump("template-variable", array("library" => "function"));[/code]

[b]property()[/b]

Outputs a template property which are those config variables started by 'app_' (See more about these variables on the following topic called Creating Application Properties).

Prototype: [code]property("template-property");[/code]

Instead of writhing the following code... [code]<?=settings['app_title']?>[/code] You'd simply write... [code]<?property("app_title")?>[/code]

[b]style()[/b]

It outputs a css link tag with the specified file. The first parameter is the filename inside the template's css folder. The second is an array with additional attributes, having the key as the attribute name and the value as value.

Prototype: [code]style("archive.css", additional-attributes);[/code] Example: [code]style("main.css", array('media'=>'screen', 'charset'=>'utf-8'));[/code]

Instead of writhing the following code... [code]<link rel="stylesheet" href="<?=settings['asset_style']?>master.css" type="text/css" media="all" />[/code] You'd simply write... [code]<?style('master.css)?>[/code]

[b]script()[/b]

It outputs a script tag to include javascript files. The only parameter is the filename inside the template's script folder.

Prototype: [code]script("archive.js");[/code] Example: [code]style("init.js");[/code]

Instead of writhing the following code... [code]</script> You'd simply write... [code]<?script('init.js)?>[/code]

[b]image()[/b]

It outputs a tag. The first parameter is the image's filename. The second is a 'alt' description. The third is an array with additional attributes, having the key as the attribute name and the value as value.

Prototype: [code]image("image.yyz", alt-attribute, additional-attributes);[/code] Example: [code]image("movingpictures.jpg", "Moving Pictures", array('style'=>'border:0;float:right;margin:10px;'));[/code]

Instead of writhing the following code... [code][/code] You'd simply write... [code]<?image('logo.png', "The Logo")?>[/code]

[h3]Configuring YATS[/h3]

Customizing YATS is quite easy. We have two groups of settings, the library's have the prefix 'layout_', and your custom properties having the prefix 'app_'.

[b]Library Settings[/b]

layout_default: name of the default theme layout_folder: the path to the assets folder (make sure you don't forget the ending slash) layout_styles: path to css folder inside assets layout_images: path to images folder inside assets layout_script: path to javascript folder inside assets

[b]Layout Elements[/b]

References all the functions in this model so the Library can automatically call each one of them. Don't forget to write them on the layout_model.php ;-)

Prototype: [code]array("function" => "parameter", ...);[/code]

Where function is the function name and parameter is a single value or an array of them to send to that function as we'd usually do with a hard coded call.

[b]Creating Application Properties[/b]

In this section of the config/layout.php file you can come up with any setting you find necessary. From a site title to anything you need. Just remember that in order to work all properties must have the 'app_' prefix.

[h3]Final Message[/h3] Happy coding! :-)