Introduction To eZ Components part 1
eZ Components From go to WHOA!Part 1
Contents
Abstract
eZ Components is, as the name suggests, a component library which rapidly increases speed of development. During this tutorial we will look at how this is done, from a simple page, to building a CMS, and developing our own custom component. The code base is object oriented which allows for greater re-use of code. If you are reading this tutorial a pre-requisite is a basic understanding of PHP classes. If you need to get up to speed on PHP classes, a tutorial exists at http://phpro.org/tutorials/Object-Oriented-Programming-with-PHP.html to help get you up to speed. This series is not meant as an alternative to the exhaustive documentation available from the eZ Componts web site, but as a guide to help you get started programming the eZ way.
In Part one of this series, we will show how to set up your environment, and how to get a simple site in place using eZ Components. It really is eZier than you think.
Download
Before we can build our site or application, we need to install eZ Components. There are two methods of doing this. The first is with PEAR and the second is by downloading the package directly. Of course, a SVN repository exists for those requiring the latest and greatest features, but it is recommended to stick with the latest stable release for development in a production environment. In this tutorial we will be using the download method of installation.
To download eZ components, simply point your browser at http://www.eZ.no and click on the downloads link. When you have the compressed archive you can unpack it and build our development directory structure
|
+ html
|
+ ezcomponents
This style of directory structure allows us access to the component library whilst keeping it out of the DocumentRoot html directory. With the directory structure in place, we can begin our first page. We will be using a template to create our index page so we need to add another directory to our tree structure to hold the templates. Our directory tree should now look like this:
|
+ html
|
+ ezcomponents
|
+ templates
Hello World
What programming tutorial would be complete without a "Hello World" script. In the html directory we will create an index.php page. The first task is to make the eZ Component library available to our site. This is quite simple with an include. As we will be using a template, we need to make a file called "hello_world.ezt (ez template). Inside this file we will put the following.
Now we make a script that includes the ez base, autoloads our classes and calls the template we created above.
<?php
/*** path to the base file ***/
$ezBase = '/www/ezcomponents/trunk/Base/src/base.php';
if(!file_exists($ezBase))
{
echo 'Could not find base file in '.$ezBase;
}
else
{
/*** include the base file ***/
include $ezBase;
/*** Autoload the ezcomponent classes. ***/
function __autoload( $className ){
ezcBase::autoload($className);
}
/*** Use the default configuration. ***/
$template = new ezcTemplate();
/*** Compile the template and return the result. ***/
echo $template->process('hello_world.ezt');
}
?>
The first surprise you will get from running the code above, is that it has thrown an Exception like this:
'The requested template file './compiled_templates/xhtml-updqr0' is not writeable.'
in /www/ezcomponents/trunk/Template/src/template.php:383
Stack trace: #0 /www/ezcomponents/trunk/Template/src/template.php(319):
ezcTemplate->createDirectory('./compiled_temp...')
#1 /www/html/index.php(25): ezcTemplate->process('hello_world.ezt')
#2 {main} thrown in /www/ezcomponents/trunk/Template/src/template.php on line 383
This is because the template engine has tried to write the compiled template to the ./compiled_templates directory which does not exist. You will need to create this directory and make sure it is writable by the current running PHP process. iWe could simply create the compiled_templates directory within the html directory, or, we could create it in /tmp or whatever your operating systems temporary directory is named. For the purposes of this tutorial, we will create the compiled_templates directory along side the others we have made. This will keep the files out of the web tree, so they will not be accessable via the web. Similarly, we would like to keep them out of /tmp because, in a shared hosting environment, other users may gain access to this directory. Rather than directly create the directory /www/compiled_templates we will later use a configuration option to set the directory in which it can be created. The directory MUST be writable by the running PHP process or an Exception will be thrown. When it is created by the template engine, the directory structure will look like this:
|
+ html
|
+ ezcomponents
|
+ templates
|
+ compiled_templates
As we saw above, the template engine default is to search for the compiled_templates directory in the current directory relative to index.php. Similarly, the template engine, by default, will search the current directory for template files. To tell the template where to look for these directories, a configuration class is supplied called ezcTemplateConfiguration. In this next example, multiple configuration options are used to set the compiled_templates directory and the templates directory.
<?php
/*** path to the base file ***/
$ezBase = '/www/ezcomponents/trunk/Base/src/base.php';
if(!file_exists($ezBase))
{
echo 'Could not find base file in '.$ezBase;
}
else
{
/*** include the base file ***/
include $ezBase;
/*** Autoload the ezcomponent classes. ***/
function __autoload( $className ){
ezcBase::autoload( $className );
}
/*** set some config options ***/
$config = ezcTemplateConfiguration::getInstance();
/*** set the template path ***/
$config->templatePath = '/www/templates';
/*** set the compiled_templates path ***/
$config->compilePath = '/www';
/*** Use the default configuration. ***/
$template = new ezcTemplate();
try {
/*** Compiles the template and returns the result. ***/
echo $template->process( "hello_world.ezt" );
}
catch(Exception $e)
{
echo $e->getMessage();
}
}
?>
If all is well, when the above code is run, you will see the contents of the hello_world.ezt template.
Hello World!
If the compiled_templates directory cannot be created, or cannot be written to, an exception is thrown and needs to be caught so that the error can be handled. This may look like this:
Assuming the best, that all your permissions are correct and that the response from the browser was what you were expecting, you will now also have a compiled template with a path something like:
/www/compiled_templates/xhtml-updqr0/hello_world-a15f3ddbccbf800f9b3b364a9a262eec.php
The contents of this file will look like this:
<?php
// Generated PHP file from template code.
// If you modify this file your changes will be lost when it is regenerated.
$this->checkRequirements(1,array("disableCache" => false));
$i_output = "";
$i_output .= "<p>Hello World</p>\n";
return $i_output;
?>
This is the file that the eZ system will now use to produce output. As you can see in the comments within the file, it is pointless to edit this file as any alterations would be lost at the next access.
Template Variables
With the a basic template in place, variables can now be sent to the template engine from our site. To continue with the above template, a heading variable can be set in our PHP code and sent to the template. To send a variable to the template engine the send method is is used. On the template side, the use keyword is used to declare the variable. Our Template can now be changed to look like this:
<h1>{$heading}</h2>
<p>Hello World</p>
The index.php will now be changed to send the heading variable:
<?php
/*** path to the base file ***/
$ezBase = '/www/ezcomponents/trunk/Base/src/base.php';
if(!file_exists($ezBase))
{
echo 'Could not find base file in '.$ezBase;
}
else
{
/*** include the base file ***/
include $ezBase;
/*** Autoload the ezcomponent classes. ***/
function __autoload( $className ){
ezcBase::autoload( $className );
}
/*** set some config options ***/
$config = ezcTemplateConfiguration::getInstance();
/*** set the template path ***/
$config->templatePath = '/www/templates';
/*** set the compiled_templates path ***/
$config->compilePath = '/www';
/*** Use the default configuration. ***/
$template = new ezcTemplate();
/*** send heading variable to the template engine ***/
$template->send->heading = 'My eZ Site';
try {
/*** Compiles the template and returns the result. ***/
echo $template->process('hello_world.ezt');
}
catch(Exception $e)
{
echo $e->getMessage();
}
}
?>
The result will look like this:
My eZ Site
Hello World
Of course, multiple variables can be sent and we can really begin to flesh out template. Lets change the name of the "hello_world.ezt to main.ezt and send multiple variables. The new main.ezt will look like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>{$title}</title>
</head>
<body>
<h1>{$heading}</h1>
<p>{$content}</p>
</body>
</html>
The changes to the index.php file are minimal, and only two extra variables are added. Don't forget to change the name of the hello_world.ezt to main.ezt to reflect the new name of the template.
<?php
/*** path to the base file ***/
$ezBase = '/www/ezcomponents/trunk/Base/src/base.php';
if(!file_exists($ezBase))
{
echo 'Could not find base file in '.$ezBase;
}
else
{
/*** include the base file ***/
include $ezBase;
/*** Autoload the ezcomponent classes. ***/
function __autoload( $className ){
ezcBase::autoload( $className );
}
/*** set some config options ***/
$config = ezcTemplateConfiguration::getInstance();
/*** set the template path ***/
$config->templatePath = '/www/templates';
/*** set the compiled_templates path ***/
$config->compilePath = '/www';
/*** Use the default configuration. ***/
$template = new ezcTemplate();
/*** send the first variable called title ***/
$template->send->title = 'My eZ Site';
/*** send heading variable to the template engine ***/
$template->send->heading = 'Welcome to my site!';
/*** send a third content variable ***/
$template->send->content = 'This is the page content';
try {
/*** Compiles the template and returns the result. ***/
echo $template->process( 'main.ezt' );
}
catch(Exception $e)
{
echo $e->getMessage();
}
}
?>
Sending an Object
We saw above how easy it is to send a variable to the template. There is another method of sending variables that makes for less code. We could send an array, more on that later, but we could also send an object that contains our variables. We still send the object in the same manner as previously described. All we need do is create it. The content of the main.ezt will need to be changed to use the object variables.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>{$object->title}</title>
</head>
<body>
<h1>{$object->heading}</h1>
<p>{$object->content}</p>
</body>
</html>
The PHP code to send the object variable to the template engine looks like this:
<?php
/*** path to the base file ***/
$ezBase = '/www/ezcomponents/trunk/Base/src/base.php';
if(!file_exists($ezBase))
{
echo 'Could not find base file in '.$ezBase;
}
else
{
/*** include the base file ***/
include $ezBase;
/*** Autoload the ezcomponent classes. ***/
function __autoload( $className ){
ezcBase::autoload( $className );
}
/*** set some config options ***/
$config = ezcTemplateConfiguration::getInstance();
/*** set the template path ***/
$config->templatePath = '/www/templates';
/*** set the compiled_templates path ***/
$config->compilePath = '/www';
/*** Use the default configuration. ***/
$template = new ezcTemplate();
/*** create an object instance ***/
$object = new stdClass();
/*** page title ***/
$object->title = 'My eZ Site';
/*** page heading ***/
$object->heading = 'Welcome to my site!';
/*** send a third content variable ***/
$object->content = 'This is the page content';
/*** send the object to the template engine ***/
$template->send->object = $object;
try {
/*** Compiles the template and returns the result. ***/
echo $template->process( 'main.ezt' );
}
catch(Exception $e)
{
echo $e->getMessage();
}
}
?>
When the above code is run, the output will look like this:
Welcome to my site!
This is the page content
You will also note that the title field is filled an the page title in your web browser now reads
My eZ Site
The results are similar to that of the previous method of sending variable individually, however, when sending large groups of varibles to the template engine, this is a great advantage requiring much less code.
From here on, adding a second, third or more pages is as simple as creating new PHP files, there is no need to change the template so we can use the same template, for all our pages. Lets make a second PHP file to demonstrate. We will call this page2.php and the contents will look like this:
<?php
/*** path to the base file ***/
$ezBase = '/www/ezcomponents/trunk/Base/src/base.php';
if(!file_exists($ezBase))
{
echo 'Could not find base file in '.$ezBase;
}
else
{
/*** include the base file ***/
include $ezBase;
/*** Autoload the ezcomponent classes. ***/
function __autoload( $className ){
ezcBase::autoload( $className );
}
/*** set some config options ***/
$config = ezcTemplateConfiguration::getInstance();
/*** set the template path ***/
$config->templatePath = '/www/templates';
/*** set the compiled_templates path ***/
$config->compilePath = '/www';
/*** Use the default configuration. ***/
$template = new ezcTemplate();
/*** create an object instance ***/
$object = new stdClass();
/*** page title ***/
$object->title = 'My eZ Site';
/*** page heading ***/
$object->heading = 'Welcome to Page2!';
/*** send a third content variable ***/
$object->content = 'This is the page2 content';
/*** send the object to the template engine ***/
$template->send->object = $object;
try {
/*** Compiles the template and returns the result. ***/
echo $template->process( 'main.ezt' );
}
catch(Exception $e)
{
echo $e->getMessage();
}
}
?>
When viewed, the above script shows the change in the heading and in the content. The benifit of this is that the programming logic, and the display logic are completely seperate. This opens up great flexibility for allowing HTML designers to weave thier magic on a single template, whilst allowing the backend developer to freely create the logic needed to run an enterprise ready site or application.
Going Forward
Of course, many sites are more than just a few static pages as we have seen here. Although, for many this is all that is required. But, most sites will have more needs and many will need dynamic content from databases or other sources. At the very least, most will have a contact form. In part two of this tutorial, we will follow the creation of a form to send an email. This will entail a template, securing the form, validation and sanitization of variables from the form, and sending an email. All this with the ready built compontents availabe from eZ.