The Template component, template engine, provides a manageable way to separate
application logic from presentation data. The application logic is the PHP code
of your application, including the call to the Template component. Presentation
data are the templates files (containing the template code).
The separation of application logic and presentation data is not only easier to
maintain, it also allows easier different people to work on one of the parts.
(While designing the template language, we tried to make the language also easy
for non developers.)
The following example demonstrate how to use the Template component.
The simplest example we can come up with is writing "Hello world" to your
standard output. Basically it consists of two steps:
The first step is to create a text file "hello_world.ezt" that contains
only one line:
Hello world
and store it in the directory where your application sources reside.
The next step is to copy the following PHP script, and check if the application
works.
1. <?php
2. require_once 'Base/src/base.php';
3.
4. // Autoload the ezcomponent classes.
5. function __autoload( $className )
6. {
7. ezcBase::autoload( $className );
8. }
9.
10. // Use the default configuration.
11. $t = new ezcTemplate();
12.
13. // Compiles the template and returns the result.
14. // It searches for the hello_world template in the current directory.
15. echo $t->process( "hello_world.ezt" );
16. ?>
If you run your application, it should write "Hello world". If it doesn't then
check that:
- The base class can be found. Check your 'include_path' in the PHP.ini
settings, and see if the components are included.
- The template "hello_world.ezt" can be found. Write the absolute
path to your hello_world template in the 'process' method.
- The template engine can write to the current directory. The next
section explains how another output directory can be specified.
From now on, we assume that the Template engine can be loaded and find the
template files.
Templates are not always stored in your local directory and neither do you
want to store the compiled templates among your source files. Therefore we
have to change the configuration:
1. <?php
2.
3. // Autoload.
4. require_once 'tutorial_autoload.php';
5.
6. $config = ezcTemplateConfiguration::getInstance();
7.
8. $config->templatePath = "/usr/share/templates";
9. $config->compilePath = "/tmp/compiled_templates";
10. $config->context = new ezcTemplateXhtmlContext(); // Is already the default, though.
11.
12.
13. $t = new ezcTemplate();
14. $t->process( "hello_world.ezt" );
15. ?>
If you try to copy/paste and run this example, you'll probably get the
following output:
Fatal error: Uncaught exception 'ezcTemplateFileNotFoundException' with message
'The requested template file </usr/share/templates/hello_world.ezt> does not exist.'
This error shows that the template engine looks in the "/usr/share/templates" directory
for the templates.
The ezcTemplate class calls the getInstance() method from the ezcTemplateConfiguration
class and retrieves the "default" configuration. It is possible to set multiple
configurations, which is demonstrated in the next example:
1. <?php
2. require_once 'tutorial_autoload.php';
3.
4. $t = new ezcTemplate();
5.
6. // Set the template configuration for printer templates.
7. $c = ezcTemplateConfiguration::getInstance( "printer" );
8.
9. $c->templatePath = "printer"; // ./printer directory;
10. $c->context = new ezcTemplateNoContext(); // Use a context that doesn't do anything.
11.
12. $c = ezcTemplateConfiguration::getInstance();
13. $c->templatePath = "html"; // ./html directory.
14.
15.
16. // And another way to configure your template engine.
17. $pdfConf = new ezcTemplateConfiguration("pdf", ".", new ezcTemplateNoContext() );
18.
19.
20. try
21. {
22. // Uses the default configuration.
23. $t->process( "hello_world.ezt" );
24. }
25. catch( Exception $e )
26. {
27. echo $e->getMessage() . "\n\n";
28. }
29.
30. try
31. {
32. // Uses the printer configuration
33. $t->process( "hello_world.ezt", ezcTemplateConfiguration::getInstance( "printer" ) );
34. }
35. catch( Exception $e )
36. {
37. echo $e->getMessage() . "\n\n";
38. }
39.
40. try
41. {
42. // Uses the PDF configuration.
43. $t->configuration = $pdfConf;
44. $t->process( "hello_world.ezt" );
45. }
46. catch( Exception $e )
47. {
48. echo $e->getMessage() . "\n\n";
49. }
50. ?>
And you'll get the following output:
The requested template file <html/hello_world.ezt> does not exist.
The requested template file <printer/hello_world.ezt> does not exist.
The requested template file <pdf/hello_world.ezt> does not exist.
As demonstrated, the Template configuration can be set in the 'configuration' property,
given as second parameter in the process method, or use the 'default'
getInstance configuration.
The following template code uses the variable: $quote and returns the number
6. Copy/paste this example and save it as 'send_receive.ezt'.
{use $quote}
{$quote}
{var $number = 6}
{return $number}
The template code that sends $quote and receive $number is as follows:
1. <?php
2. require_once 'tutorial_autoload.php';
3.
4. $t = new ezcTemplate();
5.
6. // Send the variable: $quote to the template.
7. $t->send->quote = "I am not a number, I am a free man.";
8.
9. // Process it.
10. $t->process( "send_receive.ezt" );
11.
12. // Retrieve the $number variable from the template.
13. echo "You are number " . $t->receive->number . "\n";
14.
15. // Show the output.
16. echo $t->output;
17. ?>
The output for this template is:
You are number 6
I am not a number, I am a free man.
