Stencil Official Docs

A simple and awesome template system for Codeigniter. Stencil is the perfect out-of-the-box solution for all your Codeigniter projects.

It's the perfect starter for all your projects. Getting CodeIgniter up and running on a server is a breeze, and it works with almost any development environment. Stencil was built with the same intention in mind. Just download, upload, and begin.

I. Introduction

About

Stencil was built to make life easier for development of Websites in Codeigniter. It's light-weight and featured pack. It's good for both your small and large projects.

License

Copyright (c) 2013. scotch.io

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

II. Required Files

Stencil is intended to be used from the beginning of a Codeigniter project. It is not meant to be used halfway through an already built application or website. For this reason, the Stencil files rely on each other and rely on their folder structure to be a certain way to work.

It's nothing too intense! You probably already do a similar setup yourself.

The assets folder needs to be in the root of your directory (with application and system). The assets folder is for all images, stylesheets, JavaScript scripts, and any other assets you have.

./assets/css
./assets/js
./assets/img
./assets/uploads
./assets/files

The Stencil library is where all the magic happens. The bread and butter. The Big Lebowski. You will use this to easily set things like layouts, titles, pages, page specific CSS and JS assets, and more.

The Slices library is used for Slice Callbacks. Slice Callbacks are a way for you to execute blocks of code and return them to your views without having to rewrite the code over and over again. To understand callbacks fully, first read over the Slices section and continue to the Callbacks section.

The Stencil Helper is what makes sense of all the data you and Stencil will create. It has tons of HTML Helpers that you can use. To learn more about it, go here.

The layouts folder is required inside of your views. You will use this for creating your templates.

The pages folder is required inside of your view folder. Pages are where you'll put your site content. Pages are loaded inside of your layouts. For example, you may have a layout called "subpage_layout.php", and you could have multiple pages for that layout -- such as an About Page or a Contact Page.

Need to reuse that sidebar or maybe you don't? Stencil supports this with "slices" (aka elements, partials, includes, etc.)

To learn more about Slices, please go here.

The pages controller is not necessary. The pages controller only exists for easily building static pages with the URI Segment of your choice. No need to worry about routing, it does it all for you. For more information, please go to controllers.

This config file is not required. It only has a bunch of helpful arrays and such for making development faster. For example, it contains a US State Array.

III. Helpers

The Stencil Helper contains numerous functions to make HTML development easier. Functions are HTML5 ready so it's best to use the HTML5 Doctype (<!doctype html>) for your pages. Most the functions are for returning or creating URLs (bunch of shortcodes). The Stencil Library uses these functions for generaton of HTML, but you can also use these functions independently!

add_css()

This function allows you to easily create CSS links to either your assets folder or a full/absolute URL path.

Adding CSS from your assets folder
Code
<?php echo add_css('style'); ?>
<?php echo add_css('style.css'); ?>
<?php echo add_css(array('style')); ?>
<?php echo add_css(array('style.css')); ?>
Result
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
Adding CSS with an absolute path
Code
<?php echo add_css('http://somesite.example.com/wherever/i/want/style.css'); ?>
<?php echo add_css('https://somesite.example.com/wherever/i/want/style.css'); ?>
<?php echo add_css('www.somesite.example.com/wherever/i/want/style.css'); ?>
<?php echo add_css('//somesite.example.com/wherever/i/want/style.css'); ?>
Result
<link rel="stylesheet" href="http://somesite.example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="https://somesite.example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="www.somesite.example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="//somesite.example.com/wherever/i/want/style.css">
Adding multiple CSS files via an Array
Code
<?php echo add_css(array('one', 'two', 'three')); ?>
<?php echo add_css(array('one', '//cdn.example.com/two.css', 'three.css')); ?>
Result
<link rel="stylesheet" href="http://example.com/assets/css/one.css">
<link rel="stylesheet" href="http://example.com/assets/css/two.css">
<link rel="stylesheet" href="http://example.com/assets/css/three.css">

<link rel="stylesheet" href="http://example.com/assets/css/one.css">
<link rel="stylesheet" href="//cdn.example.com/two.css">
<link rel="stylesheet" href="http://example.com/assets/css/three.css">

add_js()

This function allows you to easily create JS links to either your assets folder or a full/absolute URL path. It's the JS counterpart to the add_css() helper function.

Adding JS from your assets folder
Code
<?php echo add_js('scripts'); ?>
<?php echo add_js('scripts.js'); ?>
<?php echo add_js(array('scripts')); ?>
<?php echo add_js(array('scripts.js')); ?>
Result
<script src="http://example.com/assets/js/scripts.js"></script>
<script src="http://example.com/assets/js/scripts.js"></script>
<script src="http://example.com/assets/js/scripts.js"></script>
<script src="http://example.com/assets/js/scripts.js"></script>
Adding JS with an absolute path
Code
<?php echo add_js('http://somesite.example.com/wherever/i/want/scripts.js'); ?>
<?php echo add_js('https://somesite.example.com/wherever/i/want/scripts.js'); ?>
<?php echo add_js('www.somesite.example.com/wherever/i/want/scripts.js'); ?>
<?php echo add_js('//somesite.example.com/wherever/i/want/scripts.js'); ?>
Result
<script src="http://somesite.example.com/wherever/i/want/scripts.js"></script>
<script src="https://somesite.example.com/wherever/i/want/scripts.js"></script>
<script src="www.somesite.example.com/wherever/i/want/scripts.js"></script>
<script src="//somesite.example.com/wherever/i/want/scripts.js"></script>
Adding multiple JS files via an Array
Code
<?php echo add_js(array('one', 'two', 'three')); ?>

<?php echo add_js(array('one', '//cdn.example.com/two.js', 'three.js')); ?>
Result
<script src="http://example.com/assets/js/one.js"></script>
<script src="http://example.com/assets/js/two.js"></script>
<script src="http://example.com/assets/js/three.js"></script>

<script src="http://example.com/assets/js/one.js"></script>
<script src="//cdn.example.com/two.js"></script>
<script src="http://example.com/assets/js/three.js"></script>

add_meta()

The function add_meta() allows you to easily create Meta tags for your HTML page by passing in an associative array.

Code
<?php echo add_meta(array('description' => 'This is my description!', 'keywords' => 'cats, animals, dogs')); ?>			
Result
<meta name="description" content="This is my description!">
<meta name="keywords" content="cats, animals, dogs">			

shiv()

The function shiv() allows you to easily return the HTML for referencing the infamous HTML5 shiv (sometimes called shim) on Google's CDN.

If you don't know already, the HTML5 Shiv is a short javascript snippet that enables you to use HTML5 elements in legacy Internet Explorer browsers (anything less than 9). It works by displaying block on HTML5 elements such as "header", "footer", "nav", etc.

Code
<?php echo shiv(); ?>			
Result
<!--[if lt IE 9]><script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->

chrome_frame()

The function chrome_frame() returns the HTML that tells the users browser to use the latest rendering engine of IE if they are using IE. This is great for forcing compatability and for people on legacy IE who use Google's Chrome Frame.

Code
<?php echo chrome_frame(); ?>			
Result
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1"><![endif]-->

view_port()

The function view_port() returns the HTML meta snippet for optimizing mobile support. Currently, it accepts no paramaters for manipulating and will only make viewport "width" equal to "device width". Experienced mobile web developers will understand its benefit.

Code
<?php echo view_port(); ?>			
Result
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">

apple_mobile()

The function apple_mobile() returns the HTML meta snippet for enabling Apple Mobile support on Apple iOS devices. For more information please visit the Official Apple Docs.

Code
<?php echo apple_mobile(); ?>

<?php echo apple_mobile('default'); ?>

<?php echo apple_mobile('black'); ?>

<?php echo apple_mobile('black-translucent'); ?>			
Result
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">			

windows_tile()

The function windows_tile() returns the necessary meta information for creating the a Windows 8 Tile. With this, a user can pin your app or site to their Windows 8 Start Screen and have a sexy bookmark with your logo and color choices.

Code
<?php echo windows_tile(array('name' => 'Example Site!', 'image' => base_url().'/assets/img/icons/tile-32x32.png', 'color' => '#BADA55')); ?>
Result
<meta name="application-name" content="Example Site!"><!-- Windows 8 Tile Name -->
<meta name="msapplication-TileImage" content="http://example.com/assets/img/icons/tile-32x32.png"><!-- Windows 8 Tile Image -->
<meta name="msapplication-TileColor" content="#4eb4e5"><!-- Windows 8 Tile Color -->			

favicons()

The function favicons() returns the HTML for creating perfectly compliant favicons. This includes the default favicons for modern and legacy browsers, all to most mobile devices, and even tablets. It supports the millions of fragmented Android and Apple devices.

Show All Icons (supports all devices)
Code
<?php echo favicons(); ?>			
Result

<link rel="icon" href="http://example.com/assets/img/icons/favicon-32.png" type="image/png"><!-- default favicon -->
<link rel="shortcut icon" href="http://example.com/favicon.ico"><!-- legacy default favicon (in root, 32x32) -->
<link rel="apple-touch-icon" sizes="57x57" href="http://example.com/assets/img/icons/favicon-57.png"><!-- iPhone low-res and Android -->
<link rel="apple-touch-icon-precomposed" sizes="57x57" href="http://example.com/assets/img/icons/favicon-57.png"><!-- legacy Android -->
<link rel="apple-touch-icon" sizes="72x72" href="http://example.com/assets/img/icons/favicon-72.png"><!-- iPad -->
<link rel="apple-touch-icon" sizes="114x114" href="http://example.com/assets/img/icons/favicon-114.png"><!-- iPhone 4 -->
<link rel="apple-touch-icon" sizes="144x144" href="http://example.com/assets/img/icons/favicon-144.png"><!-- iPad hi-res -->			
Show Individual Icons
Code
<?php echo favicons(array('16' => 'assets/images/icons/icon-16.png')); ?>
<?php echo favicons(array('32' => 'assets/images/icons/icon-32.png')); ?>
<?php echo favicons(array('57' => 'assets/images/icons/icon-57.png')); ?>
<?php echo favicons(array('64' => 'assets/images/icons/icon-64.png')); ?>
<?php echo favicons(array('72' => 'assets/images/icons/icon-72.png')); ?>
<?php echo favicons(array('114' => 'assets/images/icons/icon-114.png')); ?>
<?php echo favicons(array('144' => 'assets/images/icons/icon-144.png')); ?>			
Result

<link rel="shortcut icon" type="image/png" href="http://example.com/assets/img/icons/favicon-16.png"><!-- default favicon --><link rel="icon" href="http://example.com/assets/img/icons/favicon-32.png" type="image/png"><!-- default favicon -->
<link rel="apple-touch-icon" sizes="57x57" href="http://example.com/assets/img/icons/favicon-57.png"><!-- iPhone low-res and Android -->
<link rel="shortcut icon" type="image/png" href="http://example.com/assets/img/icons/favicon-64.png"><!-- default favicon -->
<link rel="apple-touch-icon" sizes="72x72" href="http://example.com/assets/img/icons/favicon-72.png"><!-- iPad -->
<link rel="apple-touch-icon" sizes="114x114" href="http://example.com/assets/img/icons/favicon-114.png"><!-- iPhone 4 -->
<link rel="apple-touch-icon" sizes="144x144" href="http://example.com/assets/img/icons/favicon-144.png"><!-- iPad hi-res -->			
Loading Multiple Icons via an Array
Code
<?php $favicons = array(); ?><?php $favicons['16'] = 'assets/images/icons/icon-16.png'; ?>
<?php $favicons['32'] = 'assets/images/icons/icon-32.png'; ?>
<?php $favicons['57'] = 'assets/images/icons/icon-57.png'; ?>
<?php $favicons['64'] = 'assets/images/icons/icon-64.png'; ?>
<?php $favicons['72'] = 'assets/images/icons/icon-72.png'; ?>
<?php $favicons['114]' = 'assets/images/icons/icon-114.png'; ?>
<?php $favicons['144]' = 'assets/images/icons/icon-144.png'; ?>

<?php echo favicons($favicons); ?>			
Result
<link rel="shortcut icon" type="image/png" href="http://example.com/assets/img/icons/favicon-16.png"><!-- default favicon -->
<link rel="icon" href="http://example.com/assets/img/icons/favicon-32.png" type="image/png"><!-- default favicon -->
<link rel="apple-touch-icon" sizes="57x57" href="http://example.com/assets/img/icons/favicon-57.png"><!-- iPhone low-res and Android -->
<link rel="shortcut icon" type="image/png" href="http://example.com/assets/img/icons/favicon-64.png"><!-- default favicon -->
<link rel="apple-touch-icon" sizes="72x72" href="http://example.com/assets/img/icons/favicon-72.png"><!-- iPad -->
<link rel="apple-touch-icon" sizes="114x114" href="http://example.com/assets/img/icons/favicon-114.png"><!-- iPhone 4 -->
<link rel="apple-touch-icon" sizes="144x144" href="http://example.com/assets/img/icons/favicon-144.png"><!-- iPad hi-res -->			

jquery()

The function jquery() returns the jQuery link to Google's CDN for easily embedding the jQuery library in your views.

Get the Latest jQuery Version
Code
<?php echo jquery(); ?>			
Result
<script src="//ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>			
Get a Specific Version Number
Code
<?php echo jquery('1.7.2'); ?>
<?php echo jquery('1.9.1'); ?>			
Result
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>			

asset_url()

The function asset_url() is very similar to the popular Codeigniter Helper base_url() except that it references your asset folder.

Code
<?php echo asset_url(); ?>			
Result
http://example.com/assets/			
Specific File Location
Code
<?php echo asset_url('img/example.png'); ?>			
Result
http://example.com/assets/img/example.png			

IV. Getting Started

Learn by Example

The Stencil Library is used for loading all your views. Using the Stencil Library you can also set page specific attributes such as a page title, CSS and JS assets, and more.

Stencil is simple. It's super easy to learn. For starters, just view the example below to learn how to get this up and running. After you study the example, the functions and other stuff will make more sense.

Example Controller
Example Layout
Example Result

Bare Minimum to Get Started

Set a Layout in your Controller

You always will need to set a layout. This is required for Stencil.

Layouts are located in "/views/layouts/". To learn more, visit the docs about layouts.

$this->stencil->layout('default_layout');			
Set and Load a View with the "paint()" function

To set and load a view you will initiate the "paint()" function. This function is the equivalent to "$this->load->view($view)" in Codeigniter.

To learn how to bind data to the view, please click here.

These are located in the "Pages" folder inside of the views folder. The HTML from these pages are made available in the layout as the $content variable.

$this->stencil->paint('example_view');			

V. Controllers

You can use Stencil functions in the construct of your controllers. This is nice for setting things like a common layout that will be shared amongst all your functions of that class.

Making variables available in the layout, slices, and pages

Your variables are available in your Layouts, Slices, and Pages. They are loaded into each section of HTML code every time. So you'll never have to wonder if data you are binding or sending to the view will be available in a view file. The data you bind in your controllers are available in all your view files as variables.

Pages Controller

This controller is not required to use Stencil. It only exists for an easy and simplified way of doing speedy routing of static pages. You can create with ease any URI of your choosing. For example: "/about-us", "/terms-of-service", and "privacy-policy"

routes.php

Your 404 route will need to route to the pages Controller in order to be able to quickly generate static pages.

$route['404_override'] = 'pages';			

Body Class

The variable $body_class will always be set and equal to the class name. You can override this by binding data to your view with the key being equal to "body_class".

VI. Setting Titles

This creates a $title variable that is available in your view files (layouts, pages, slices).

Controller
$this->stencil->title('Example Title');			
Views
<?php echo $title; ?>			
Result
Example Title			

VII. Page Specific CSS and JS

This creates a $css and $js variables that your views file (layouts, pages, slices) that are set in your controllers. These are purely optional. This is amazing to use for large websites or for using jQuery plugins. It allows you to load and cache resources only when you need to.

Adding CSS

Controller
$this->stencil->css('style');
$this->stencil->css('style.css');
$this->stencil->css(array('style'));
$this->stencil->css(array('style.css'));

$this->stencil->css('http://example.com/wherever/i/want/style.css');
$this->stencil->css('https://example.com/wherever/i/want/style.css');
$this->stencil->css('//example.com/wherever/i/want/style.css');
$this->stencil->css('www.example.com/wherever/i/want/style.css');

$this->stencil->css(array('one', 'two', 'three.css', '//cdn.example.com/wherever/i/want/style.css'));			
Views
<?php echo $css; ?>			
Result
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/style.css">

<link rel="stylesheet" href="http://example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="https://example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="www.example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="//example.com/wherever/i/want/style.css">
<link rel="stylesheet" href="http://example.com/assets/css/one.css">
<link rel="stylesheet" href="http://example.com/assets/css/two.css">
<link rel="stylesheet" href="http://example.com/assets/css/three.css">
<link rel="stylesheet" href="//cdn.example.com/wherever/i/want/style.css">

Adding JS

Controller
$this->stencil->js('scripts');
$this->stencil->js('scripts.js');
$this->stencil->js(array('scripts'));
$this->stencil->js(array('scripts.js'));

$this->stencil->js('http://cdn.example.com/wherever/i/want/scripts.js');
$this->stencil->js('https://cdn.example.com/wherever/i/want/scripts.js');
$this->stencil->js('//cdn.example.com/wherever/i/want/scripts.js');
$this->stencil->js('www.cdn.example.com/wherever/i/want/scripts.js');

$this->stencil->js(array('one', 'two', 'three.js', '//cdn.example.com/wherever/i/want/scripts.js'));		
Views
<?php echo $js; ?>		
Result
<script src="http://example.com/assets/js/scripts.js"></script>
<script src="http://example.com/assets/js/scripts.js"></script>
<script src="http://example.com/assets/js/scripts.js"></script>
<script src="http://example.com/assets/js/scripts.js"></script>

<script src="http://cdn.example.com/wherever/i/want/scripts.js"></script>
<script src="https://cdn.example.com/wherever/i/want/scripts.js"></script>
<script src="//cdn.example.com/wherever/i/want/scripts.js"></script>
<script src="www.cdn.example.com/wherever/i/want/scripts.js"></script>

<script src="http://example.com/assets/js/one.js"></script>
<script src="http://example.com/assets/js/two.js"></script>
<script src="http://example.com/assets/js/three.js"></script>
<script src="//cdn.example.com/wherever/i/want/scripts.js"></script>

VIII. Setting Meta Data

Adding Meta Tags and Data

Having page specific meta data is important for things like Search Engine Optimization (SEO). Stencil makes this easy to add Meta data to your individual pages. This is purely optional. The $meta variable will be created for your views.

Controller
<?php echo $this->stencil->meta(array('description' => 'This is my description!', 'keywords' => 'cats, animals, dogs')); ?>			
Views
<?php echo $meta; ?>			
Result
<meta name="description" content="This is my description!">
<meta name="keywords" content="cats, animals, dogs">			

IX. Binding Data to Views

Woo! Binding data to your views is always the fun part. Codeigniter makes it easy with $this->load->view('view', $data);, and Stencil was designed to mimic this and then build on top of this.

There are many ways to bind data to your views. Below are the many ways that you can do so.

Usage 1 - Using the old fasioned, Codeigniter way

Note: This method takes precedence over all other ways to set data. Meaning if you have a variable called $test, this is what test will be equal to. If you set test in the other usage cases, it will always be equal to what you set here if that variable has the same key/name. This is useful for overriding data that is set in the construct.

Controller
$data['some_text'] = 'This is some text!';
$this->stencil->paint('example_view', $data);			
Views
<?php echo $some_text; ?>			
Result
This is some text!			

Usage 2 - Using Stencil function data() to store data (repetitive occurances)

Note: Data Arrays are merged. So you could set this data in the construct to let it be available in all your functions/pages.

Controller
$this->stencil->data('key', 'value');
$this->stencil->data('name', 'Nicholas V. Cerminara');
$this->stencil->data('birth_date', 'January, 29, 1989');			
views
<?php echo $key;?>
<?php echo $name;?>
<?php echo $birth_date;?>			
Result
value
Nicholas V. Cerminara
January, 29, 1989			

Usage 3 - Using Stencil function data() to store data (as an array)

Note: Data Arrays are merged. So you could set this data in the construct to let it be available in all your functions/pages.

Controller
$data['some_key'] = 'This is some value!';
$data['some_key_2'] = 'This is some value 2!';
$this->stencil->data($data);			
Views
<?php echo $some_key; ?>
<?php echo $some_key_2; ?>			
Result
This is some value!
This is some value 2!			

Construct Example

This example shows you how the different ways of binding data override each other.

Note: You can repeat $this->stencil->data() as if you were building an array in your function. This is because you are! Except that it is happening in the Stencil Library. This also works for $this->stencil->css(), $this->stencil->js(), $this->stencil->slice(), and $this->stencil->meta()

X. Building Layouts and Pages

In order to use the $this->stencil->paint() function you need to have set a layout or you will get an error.

All of the examples you will see here have _layout at the end of each file. This isn't required, it's only for convention which is ultimately your decision.

Controller
$this->stencil->layout('example_layout');

Note:

You will see it makes a lot of sense to set this in your Construct. If you need to override what you set in the Construct, calling this function twice will override it.

The $content variable

After you set a layout, you can call the paint() function. This is the Stencil equivalent to $this->load->view('...'). The view that you specify in the paint function is made available in your layouts as $content.

$this->stencil->paint('view_name');			

XI. Slices

Partials | Nested Views | Elements | Includes | Slices | Child Views

If you ever need to reuse sections of a webpage such as a navigation, sidebar, or some other commonly used snippet, Stencil's Slices provide the perfect functionality for doing this -- making it very easy to customize layouts or programmatically generate different web pages.

Stencil's Slices are very robust so that the end-user can be as creative as they want with their layouts and webpages.

Each variable in the views will load the HTML of their respective file inside of the views/slices folder. The variables are made available in both layouts and pages.

Usage 1 - Basic Use Case

Controller
$this->stencil->slice('head');
$this->stencil->slice('header');
$this->stencil->slice(array('footer'));

$this->stencil->slice(array('head', 'header', 'footer'));			
Views
<?php echo $head; ?>
<?php echo $header; ?>
<?php echo $footer; ?>

<?php echo $head; ?>
<?php echo $header; ?>
<?php echo $footer; ?>			
Result
This is the HTML from inside of /views/slices/head.php
This is the HTML from inside of /views/slices/header.php
This is the HTML from inside of /views/slices/footer.php

This is the HTML from inside of /views/slices/head.php
This is the HTML from inside of /views/slices/header.php
This is the HTML from inside of /views/slices/footer.php

Usage 2 - Setting Custom Paths

This is especially useful so you wouldn't have to create an entirely new layout to have different sidebar layouts for example. With this solution you can swap slices out with ease while keeping the same variable name in your layout or page.

Controller
$this->stencil->slice(array('sidebar' => 'sidebar_3'));
Views
<?php echo $sidebar; ?>
Result
All the HTML from /views/slices/sidebar_3.php

Usage 3 - Loading many slices per an Array

Controller
$this->stencil->slice(array('head', 'header', 'footer', array('sidebar' => 'sidebar_1'));
Views
<?php echo $head; ?>
<?php echo $header; ?>
<?php echo $footer; ?>
<?php echo $sidebar; ?>			

XII. Slice Callbacks

Binding Data to Slices with Callback Methods

By default, any data you bind or send to the views using Stencil will already be available in your slices, however, this may have you rewriting code over and over again everytime you want to use a Slice that has a variable in it. Callbacks elimate that problem.

Slice Callbacks are callbacks or class methods that are called when a Slice is created. If you have data that you want bound to a given view each time that view is created throughout your application, a Slice Callback can organize that code into a single location. Therefore, view Slice Callbacks may function like "view models" or "presenters". This will maintain an MVC approach to your Views without you having to write redundant code. This is inspired by Laravel's View Composers.

Follow the example below for a full explanation.

Bad Example

Obviously, you can see why this would get annoying. Everytime you use sidebar_layout and the sidebar slice your views will be expecting to loop through the $recent_posts variable. If you don't bind that to the views, you'll get an error for an Undefined Variable.

This is especially tedious and redundant if you are using the sidebar slice often across multiple Controllers and functions.

Good Example

That's it! You'll see that there is now a function called sidebar() inside of the file Stencil.php in the libraries folder. What this does is create a callback everytime a slice is called with the name sidebar.

Note that you must return an associative array. Also, the function name must be the same as the slice name in order to run.

Overriding Callbacks

For whatever reason if you need to override a variable that is set in the Slices.php callback library, all you have to do is bind data to the view with the same key-value assocation as the array returned in the library. The data binded to views in the Controller will always take priority over the Slice Callbacks. Shibby!

XIII. The End

If you have any questions please feel free to contact us. If you believe you have found a bug or have a feature request, please also feel free to open an issue on GitHub.

Thanks! Enjoy.