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 delimiters 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:
- php_to_template_syntax - Convert PHP syntax to the specified templating syntax (as best it can). Must use the PHP alternative syntax for if and foreach loops to be translated correctly.
- parse_template_syntax - Parses a strings specified templating syntax.
The below documentation is specific to the Dwoo templating engine. See the Twig documentation 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).
- {site_url('/my/path/')}
- {assets_path('images/my_asset.jpg')} - Maps to the assets_path() function
- {img_path('my_img.jpg')} - Maps to the img_path() function.
- {js_path('my_js.js')} - Maps to the js_path() function. The .js extension is optional.
- {swf_path('my_swf.swf')} - Maps to the swf_path() function. The .swf extension is optional.
- {media_path('my_movie.mov')} - Maps to the media_path() function.
- {pdf_path('my_pdf.pdf')} - Maps to the pdf_path() function. The .pdf extension is optional.
- {safe_mailto('my@email.com', 'text')} - Maps to the safe_mailto() function.
- {redirect('my_redirect_page')} - Maps to the redirect() function.
- {show_404} - Maps to the show_404() function.
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).
- {uri_segment(1, true/false)} - Maps to the uri_segment(n) function.
- {fuel_var} - Maps to the fuel_var() function.
- {fuel_model('module_name', array(key="val"...)} - Maps to the fuel_model() function. The first parameter is usually the name of your model and does not need to include the "_model" suffix (usually the same as the module name).
- {fuel_block(array(key="val"...))} - Maps to the fuel_block() function.
- {fuel_nav(array(key="val"...))} - Maps to the fuel_nav() function.
- {fuel_edit(id, label, module, xOffset, yOffset)} - Maps to the fuel_edit() function.
Note that several of the functions require an associative array parameter 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}