FUEL CMS User Guide : Version 1.3.2


Template Parsing

Overview

By default, FUEL disables PHP code from being saved in your module data (you must change the sanitize_input setting for the module). FUEL has three options to choose from for the parsing engine of ci, Dwoo and Twig (new!). The default parsing engine is currently Dwoo for legacy reasons but has been deprecated in favor of Twig. New to FUEL CMS 1.3 are some additional FUEL template configurations that can be overwritten in your fuel/application/config/MY_fuel.php file:

// The directory to put the parsed compiled files
$config['parser_compile_dir'] = APPPATH.'cache/dwoo/compiled/';

// The delimiters used by the parsing engine
$config['parser_delimiters'] = array(
				'tag_comment'   => array('{#', '#}'), // Twig only
				'tag_block'     => array('{%', '%}'), // Twig only
				'tag_variable'  => array('{', '}'), // Used by Twig, Dwoo and CI. Default for twig is '{{', '}}'
				'interpolation' => array('#{', '}'), // Twig only
			);

// Functions allowed by the parsing engine
$config['parser_allowed_functions'] = array(
	'strip_tags', 'date', 
	'detect_lang','lang',
	'js', 'css', 'swf', 'img_path', 'css_path', 'js_path', 'swf_path', 'pdf_path', 'media_path', 'cache_path', 'captcha_path', 'assets_path', // assets specific
	'fuel_block', 'fuel_model', 'fuel_nav', 'fuel_edit', 'fuel_set_var', 'fuel_var', 'fuel_var_append', 'fuel_form', 'fuel_page', // FUEL specific
	'quote', 'safe_mailto', // HTML/URL specific
	'session_flashdata', 'session_userdata', // Session specific
	'prep_url', 'site_url', 'show_404', 'redirect', 'uri_segment', 'auto_typography', 'current_url' // CI specific
);

// Object references passed to the parsing engine
$config['parser_refs'] = array('config', 'load', 'session', 'uri', 'input', 'user_agent');

Note that the default parsing delimieters are set to "{" and "}" which is different then the default Twig parsing parameters. This is done for legacy reasons.

Fuel_parser Class

New to FUEL CMS 1.3 is the Fuel_parser class which provides a unified way to dealing with the different parsing engines now available in FUEL.

String Helper Functions

FUEL comes with the following string helper functions to help with parsing and converting from the Dwoo templating syntax:

The below documentation is specific to the Dwoo templating engine. See the Twig documenation for Twig specific documentation.

Non-Namespaced Functions

The following are non-namespaced functions that can be used in your application and will be translated by the templating system (below are Dwoo examples).

Namespaced Functions

The following are namespaced functions that can be used in your application and will be translated by the templating system (below are Dwoo examples).

Note that several of the functions require an associative array paramter with the key="val" syntax.

Blocks

Tag pairs allow you to loop through arrays of data. The syntax requires an opening {my_var} and closing {/my_var} tag. For example:

$my_data = array();
$my_data[] = array('name' => 'Darth Vader', 'weapon' => 'light saber');
$my_data[] = array('name' => 'Han Solo', 'weapon' => 'blaster');
...
{loop $my_data}
	{$name} - {$weapon}
{loop}

You can also iterate over objects. For example, you may have a user model with some custom methods on it:

... 
{$mydata = fuel_model('users', find="all")}

{foreach $my_data user}
	{$user->name} - {$user->weapon}
{/foreach}

The user part can actually be any value. You cannot insert outside variables inside a tag pair block.

Conditional Statements

FUEL also allows for php like conditional statements to be inserted into the view using {if ... }, {elseif ...} and {/if}. For example (Dwoo example):

{$name='Darth Vader'}
{if $name == 'Darth Vader'}
I am your father.
{/if}

Creating your own tags

Dwoo provides several ways for it to extend it's templating syntax through plugins. The Dwoo folder to add your plugins is located at application/libraries/dwoo/plugins.

Examples

Below are examples of FUEL's supported parsing syntax. For even more information, visit the Dwoo Wiki

Scalar Variable Merge

$var['name'] = 'Luke';
$str = '{$name}, I am your father.';

$parsed_str = $this->parser->parse_string($str, $var);

Array Variable Merge

$var['darths_kiddos'] = array();
$var['darths_kiddos'][] = array('name' => 'Luke Skywalker', 'relationship' => 'son');
$var['darths_kiddos'][] = array('name' => 'Princess Leia', 'relationship' => 'daughter');

$str = '
{loop $darths_kiddos}
	{$name} is Vader\'s {$relationship}. 
{/loop}';

$parsed_str = $this->parser->parse_string($str, $var);

Object Merge

$this->load->model('fuel_users_model');
$data['users'] = $this->fuel_users_model->find_by_key(1);
$template = '{$user->full_name}';
$test = $this->parser->parse_string($template, $data);
echo $test; //'Darth Vader';

Array of Objects Merge

$this->load->model('fuel_users_model');
$data['users'] = $this->fuel_users_model->find_all();
$str = '
{loop $users}

{$user->first_name} {$user->last_name}

{$user->get_bio_formatted()} {/loop}'; $parsed_str = $this->parser->parse_string($str, $data);

Conditionals

{if 1 + 1 == 2}
One plus one equals 2!
{/if}

{$my_var="test"}
{if $my_var == "test"}
my_var equals the word "test"!
{/if}