Documentation for CI

Content:

• Installation
• Getting started
• Paths
• Data
• Cycles
• Conditions
• Including
• Configuration
• Output
• Debug
• Summary
• Support and Donation

I. Installation

Hi, there! First of all you have to download parser from our download page. Then copy Parser.php into your application's library folder. Now you are ready. Load parser using autoloading or just typing: $this->load->library('parser');

To the top ↑

II. Getting started

I. Preparing templates

All your templates must be stored in views folder (or its subfolder) (application/views/). Your files should have extension .tpl. Template files shouldn't contain PHP scripts (because they will not work). So, make template_file.tpl in your views and write in: Parser is working!

II. Security of templates

Our templates are now in risk, because when you type http://site.com/application/views/template_file.tpl, it shows what template_file.tpl contains. And that's wrong. So, everything what you need to do is to add these lines into your (root) .htaccess file: <Files "*.tpl">
Order Allow,Deny
Deny from All
</Files>

III. Loading templates

Now, you have your templates prepared as well as parser. Next step is getting them work together. It's time for controller. So make new controller, call it controller_file.php and put down: $this->parser->parse('template_file'); If you did it correctly, your browser showed 'Parser is working!'. As you can see from example, you just type name of file without extension. That's the way you can save your hands, time, planet etc.!

To the top ↑

IV. Parsing strings NEW!

When you just want to parse a string, not the whole file, then put it down as the first parameter, and set is_string to TRUE in configuration, as shown in example: $this->parser->parse('Hello!', array(), array('is_string' => TRUE));

To the top ↑

III. Paths

As it was mentioned in the section II.I, files are stored in view folder. It's a good habit to separate your CSS from HTML by making external CSS files. But how you load your CSS now? Easily! For demonstration make in your views folder new folder, and name it css. In this new folder make a new file called style.css, which contains: body { color: green; } Now we want to connect our CSS file with our template file. We can do it by typing: <link rel="stylesheet" href="http://your_site.com/application/views/css/style.css"> This is not effective solution! Or much easier: <link rel="stylesheet" href="{T_Folder}/css/style.css"> If you did it correctly, you can see 'Parser is working!' in green color.

If it's not working for you, try to change your .htaccess files. If you are using .htaccess from CodeIgniter Docs, than change lines: RewriteCond $1 !^(index\.php|images|robots\.txt)
RewriteRule ^(.*)$ /index.php/$1 [L] To: RewriteCond % !-f
RewriteCond % !-d
RewriteRule ^(.*)$ index.php?/$1 [L] If you are using CI 2.0 you have to make new .htaccess in views/ folder: Allow from all

Bonus feature: Theming

Make a lot of visual themes and let your users decide, which is the best! How? We've made function theme(), which helps you. So, make new folder structure in your views folder. Then move template_file.tpl into TPL folder and style.css into CSS folder. Folder structure: /views/
    /my_theme
        /css
            style.css
        /img
        /js
        /tpl (this folder is required)
            template_file.tpl When you are ready open your controller_file.php and write down new line: $this->parser->theme('my_theme');
$this->parser->parse('template_file'); As you can see, it works, and {T_Folder} still has the right path. You can set your theme via configuration, too.

In next parts of this documentation we will not use themes.

To the top ↑

IV. Data

Now, you have your first template file, but it's still unuseful. It's time to pass some data.

I. Basic pseudo-variables

Main feature of COMPER Template Parser is to pass some data as pseudo-variables. It's easy, let's have a look. First of all, make some data on your controller_file.php: $data = array
    (
        'pseudo-variable' => 'Some data',
        'content' => 'Some new exciting content',
        'author' => 'That's me!'
    );

$this->parser->parse('template_file', $data); To your template_file paste this code: <h1>{pseudo-variable}</h1>
<p>{content}</p>
<small>Author: {author}</small> As you can see, you just passed an array as $data parameter and then you just set the place, where it should appear via pseudo-variables (pseudo-variable starts with { and ends with })

II. Function append

Basic pseudo-variables are fine, but when you are using a lot of them, choas on your template file may appear. That's why we made an append function. It helps you to pass different arrays and makes your templates clean. Follow this code (controller_file.php): $urls = array('comper' => 'http://comper.sk', 'parser' => 'http://parser.comper.sk');

$this->parser->append('url', $urls);
$this->parser->parse('template_file'); We are making a list of urls, so let's continue with template_file.tpl <a href="{url: comper}">COMPER</a> made this <a href="{url: parser}">parser</a> As you can see, it's pretty simple! First parameter is name, which will be referred in template file, the second one is an array. You can pass multidimensional array, too! Check this example: controller_file.php $urls = array('parser' => array('url' => 'http://parser.comper.sk', 'version' => '1.5'));

$this->parser->append('url', $urls);
$this->parser->parse('template_file'); template_file.tpl <a href="{url: parser->url}">COMPER Template Parser {url: parser->version}</a>

To the top ↑

V. Cycles

That's nice, but sometimes (very often) you need cycles - blocks of code that repeat x-times, with different data. Basic example of usage is dumping data from database. In PHP, there are several functions for this purpose - for, foreach, while and do-while. COMPER Template Parser has native support for cycles. Usage is very clean and simple - check it!

First of all, we'll get some data from database and then we'll pass them to parser.

controller_file.php $query = $this->db->get('user');

$data['user'] = $query->result_array();

$this->parser->parse('template_file', $data); template_file.tpl <!-- BEGIN user -->

Username: {username}
Password: Haha .. it's secret :)
Email: {email}
Address: {address}

<!-- END user -->
Short and nice ... so how it works? In fact you pass multi-dimensional array, which contains name of cycle, index and data: $data = array('user' => array
(
     1 => array('username' => 'life', 'email' => 'life@earth.zz', 'address' => 'Earth 001, Milky way'),
     2 => array('username' => 'anonym', 'email' => seeyou@friday.zz', 'address' => 'Paris, France')
)); If you want to pass your own data (not from database), follow the syntax showed above. Example: $fruits = array('apple', 'banana', 'orange', 'lemon');

for ($i = 0; $i<10; $i++)
{
     $fruit = $fruits[array_rand($fruits)];

     $data['fruits'][] = array('index' => $i, 'fruit' => $fruit);
}

$this->parser->parse('template_file', $data); In this example name of cycle is fruits, index is generated automatically via [], and data contain index and name of fruit.

To the top ↑

VI. Conditions

There are new conditions since COMPER Template Parser 1.5. Syntax was reduced, functionality was improved, and they are also much faster. So here we go! Conditions work with logical values passed in $data parameter of parse() function. First, try something easy to understand: controller_file.php $data['admin'] = TRUE;

$this->parser->parse('template_file', $data); template_file.tpl <!-- IF admin --> Hi admin! <!-- END --> COMPER Template Parser also supports elseif and else causes. template_file.tpl <!-- IF admin -->
     Hi admin!
<!-- ELSEIF vip -->
     Welcome back member!
<!-- ELSE -->
     I don't know you ... sorry ...
<!-- END --> Of course, you can have ELSEIFs as many as you want, and COMPER Template Parser also support nested conditions too (with ELSEIFs and ELSE)! <!-- IF admin -->

     <!-- IF Tomas -->

         <!-- IF SayHello -->
             Hello Tom!
         <!-- ELSEIF SayHi -->
             Hi Tom!
         <!-- END -->

     <!-- ELSE -->
         Who are you?
     <!-- END -->

<!-- ELSEIF vip -->
     Welcome back member!
<!-- ELSE -->
     I don't know you ... sorry ...
<!-- END --> You can continue the nesting to level which you like. Ok, but what if you want to show some info just for the users that have some privileges (for admins, moderators, vips)? You can use operators from PHP! <!-- IF !basic_user -->
This is security zone ... any attempt to destroy our world will be stopped!
<!-- END --> Or ... <!-- IF admin || mod || vip -->
This is security zone ... any attempt to destroy our world will be stopped!
<!-- END --> Or ... <!-- IF admin OR mod OR vip -->
This is security zone ... any attempt to destroy our world will be stopped!
<!-- END --> Ok, and now something complicated :D <!-- IF (is_copywriter && post_article) || is_admin -->
You are copywriter or admin and you can post new article
<!-- ELSEIF is_copywriter && (!admin) -->
You are not allowed to post an article.
<!-- ELSE-->
You are not allowed to view this content (because you are not copywriter or admin).
<!-- END -->

To the top ↑

VII. Including

In this section we won't need PHP, everything works in TPL. Including allows you to load another template file into currently parsered file this way: <body>
<!-- INCLUDE overall_header -->

<h3>Hi there!</h3>
<p>'Cause I'm fine!</p>

<!-- INCLUDE overall_footer --> Remember, you don't have to write extension, it will be added automatically.

To the top ↑

VIII. Configuration

The third parameter of parse function, is $config. Config contains the whole configuration for your parser, check the options:

Option	Type	Usage	Default value
append	array	Set 'common' arrays for append() function	CI config as config, CI language as lang
clean	bool	Should unused pseudo-variables be deleted	TRUE
debug_log_level	int	Level of error logging (see debug())	3
debug_show_level	int	Level of error showing (see debug())	1
disable_conditions NEW!	bool	Parser won't parse conditions	FALSE
disable_cycles NEW!	bool	Parser won't parse cycles	FALSE
disable_includes NEW!	bool	Parser won't parse includes	FALSE
disable_variables NEW!	bool	Parser won't parse variables and appends	FALSE
exception	array	What pseudo-variables shouldn't be deleted?	memory_usage, elapsed_time (Benchmarking Class)
extension	string	What's template files extension?	tpl
is_string NEW!	bool	Is the first paramter string (or file)? See II.IV Parsing strings	FALSE
show	bool	Should be output displayed?	TRUE
theme	string	Set theme for your project (see theme())	---
xss_clean NEW!	bool	Protects data agains XSS	FALSE

Configuration for Parser can be also set in CodeIgniter configuration. You can make your own configuration file, or add these lines in the bottom of config.php: $config['comper_parser'] = array(); That means, when you want to set global theme (i.e. green), just write: $config['comper_parser'] = array('theme' => 'green');

To the top ↑

IX. Output

So, we know how to pass data, make cycles and conditions, but now we want to work with output. There are two ways how to work with output. The first is return value of parse() function. You can use it like this: $config['show'] = FALSE; // turns off displaying output

$content = $this->parser->parse('template_file', array(), $config);

// some processing with text

echo $content; The second way is using variable $this->parser->content. This variable contains last parsered content. The same example: $config['show'] = FALSE; // turns off displaying output

$this->parser->parse('template_file', array(), $config);

// some processing with text

echo $this->parser->content;

To the top ↑

X. Debug

Sometimes things go wrong. It is great, if you can use debug function. You can use it like this: $this->parser->debug();
$this->parser->parse('template_file'); Or ... $config['debug_show_level'] = 4;

$this->parser->parse('template_file', array(), $config); Maybe, you don't understant. So here's explanation. Debug function uses two arguments set at config - debug_show_level and debug_log_level. Each one, contains a level from 0 to 4. 0 - No action
1 - Log/show critical errors
2 - Log/show errors made in template file and above
3 - Log/show errors made in PHP and above
4 - Log/show everything + debugging results
If you set log level to 3, and show level to zero, every error will be logged only.

To the top ↑

Summary

There are only 4 functions, first is parse(): $this->parser->parse($template, $data, $config); Parameter $data contains data for cycles, pseudo-variables and conditions. Parameter $config contains whole configurations and allows you to set everything that next 3 functions do.

Second function is theme() used for making a lot of color themes. $this->parser->theme($theme); For appending some special data, there is a function append(). $this->parser->append($name, $data); Last function is debug(), used for debugging: $this->parser->debug();

To the top ↑

Support and Donation

If you don't understand anything, or you have any question, feel free to contact us.

If you find this parser useful for you, please donate. This way you can support this 'product' which is free for everybody. If you want to make a donation, please, write to our helpdesk. We'll send you information back. Thank you very much!