2. Installation
2.1. Standard installation
2. Installation
« Previous
2.2. PHAR installation
Next »

2.1. Standard installation

This chapter describes the installation as a set of PHP files.

Directory structure

In the downloaded archive you can find a directory called /lib with all the necessary OPT and OPL source code. Create in your project directory tree a new directory and copy there the contents of /lib. If you already use other OPL libraries, copy OPT into the existing directory. Do not be afraid to overwrite the files if you are asked to do so. Unless they are modified, there is nothing to worry.

In case of OPT, you must also create two directories for your templates. Let assume that the first one is called /templates and the second one - /templates_c. You can choose any other name, if you want.

Be sure that PHP has write access to /templates_c and read access to /templates.

PHP code and the configuration

In the beginning, you must load the OPL core, configure the path to the libraries and set the autoloader. The following code is used then:

<?php
require('./libs/Opl/Base.php'); // 1
Opl_Loader::setDirectory('./libs/'); // 2
Opl_Loader::register(); // 3
 
$tpl = new Opt_Class; // 4
// your script
  1. We load the OPL core.
  2. We set the library path. It should end with /, but it is not necessary. We recommend to set the absolute path, because OPL does not use include_path by default. In case of PHP 5.2 this method is required, because it also loads the emulation code for some extra classes from PHP 5.3.
  3. We register the autoloader that will automatically locate and load the classes.
  4. We create the main parser object.

All the OPL libraries report the errors as exceptions. For OPL, the base exception class is Opl_Exception and for OPT - Opt_Exception. OPT contains a very convenient error handler that shows some extra information that should help to solve the problem, and adds additional explanations, why you see it and where to look for mistakes.

Once we created the object, the library must be configured. We do it by setting the values of some fields in $tpl object. The most important are:

sourceDir
Path to the /templates/ directory.
compileDir
Path to the /templates_c/ directory.
contentType
Content type. We can use one of predefined values or enter the MIME type manually.
charset
Used output encoding.

Before we definitely start, we must also call Opt_Class::setup(). Do not forget about it, because it plays a very important role:

<?php
require('./libs/Opl/Base.php');
Opl_Loader::setDirectory('./libs/');
spl_autoload_register(array('Opl_Loader', 'autoload'));
 
try
{
    $tpl = new Opt_Class;
    $tpl->sourceDir = './templates/';
    $tpl->compileDir = './templates_c/';
    $tpl->contentType = Opt_Output_Http::XHTML;
    $tpl->charset = 'utf-8';
    $tpl->setup();
 
    $view = new Opt_View('template.tpl');
    $view->hello = 'Hello, world!';
 
    $out = new Opt_Output_Http;
    $out->setContentType();
    $out->render($view);
}
catch(Opt_Exception $exception)
{
    Opt_Error_Handler($exception);
}

Finally, to work with OPT, we need two types of objects:

  1. Views - they represent a template with some script data assigned to it, as well as other rules, such as format definitions or inheritance lists. In the script, they are objects of Opt_View class and one object should match exactly one top template (possibly accompanied with dependent templates).
  2. Outputs - they decide, where to send the processed view results.

Using a view is very easy. In the constructor, we specify the template assigned to the view, and later we simply assign the data to template variables using the syntax $view->variableName = value. There are several other data assignment methods which are described deeper in the API reference. As our view is ready, we need to create an output. We are going to use Opt_Output_Http, a standard OPT class that is responsible for HTTP header management and sending the templates to the browser. Once it is initialized, we call Opt_Output_Http::setContentType() to create the headers for the specified content type. The method supports full content negotiation, when connected with Open Power Classes library. Finally, we call Opt_Output_Http::render() on our view object to send the results to the browser.

Note that different output systems may have some requirements. For example, the HTTP output assumes that all the templates are valid XML files. This means that you cannot open a tag in one template and close it in another. So, to be sure that the script output will be also a valid XML document, we can parse only one template. But do not worry - OPT provides several better solutions to make a template modularization. They are explained in the next chapters.

The templates

We save the templates in ./templates/ directory. To speed up the task, OPT compiles them to the PHP code every time they are changed. The compiled versions are stored in ./templates_c/ whose content is managed by OPT and you do not have to do there anything. You can delete the contents in this folder anytime you want. OPT will recompile all the templates then.

This is an example template in /templates/template.tpl:

<?xml version="1.0" ?>
<opt:root>
<opt:prolog />
<opt:dtd template="xhtml10transitional"/>
<html>
<head>
    <title>My first OPT template</title>
</head>
<body>
    <p>My first OPT template</p>
    <p>Script message: {$hello}</p>
</body>
</html>
</opt:root>

The third and fourth line expand the output XML prolog and the DTD for XHTML 1.0 Transitional, because the prolog we can see in the template is for internal use only. In the line four from the end, we specify an expression in curly brackets. It displays the content of the variable $hello in the specified place. When you run the example, instead of curly brackets we see there "Hello world!".

The details concerning creating templates and using OPT are described later.

See also:

2.1. Standard installation
2. Installation
« Previous
2. Installation
Next »
2.2. PHAR installation