Documentation

Documentation

This is the documentation section of Beilpuz 0.3.

Installation

Extract the Beilpuz ZIP archive.
Upload the bp/ directory to your webserver into any directory you want.
Create the following directories as siblings of bp.
- templates: That directory will contain your templates.
- compiled: Directory to be used from Beilpuz for compiled templates.
- cache: Directory for cached templates (not used at the moment).
Make the compiled and cache directories writable for your PHP (or Apache) user.

Upgrade instructions

If you want to upgrade from a older Beilpuz 0.3 version, you must empty both compiled and cache directories before overwrite the existing bp directory with the new version.

Quickstart

Create a new HTML file with the following content and save it as quickstart.html into templates/:

<html><head><title><bp:$works/></title></head>
<body><h3>Congratulation, it <bp:$works/></h3></body>
</html>

Create a new PHP file with the following content and save it as test.php and as sibling of bp/:

<?php
include('bp/Beilpuz.php');
$tpl = new BpTemplate('quickstart.html');
$tpl->assign('works', 'works!');
echo $tpl->render();
?>

You must have a directory structure like that:
- httpdocs
  - bp/
  - cache/
  - compiled/
  - images/
  - templates/
    - quickstart.html
  - gallery.php
  - index.html
  - test.php
Now type the URL of test.php into a browser. Thats it.

Signatures are nothing else than tags in a XML syntax and an own, but unspecified, namespace for Beilpuz. These tags are marks in templates, which can be found and compiled from the the Beilpuz compiler.
Here is an example for a simple non-existent signature named example:

<html>
<title><bp:example/></title>
</html>

As in HTML or XML, Beilpuz signatures can have attributes. Let me extend this example:

<html>
<title><bp:example foo="bar"/></title>
</html>

The example signature got the attribute foo with the value bar.

Inline templates

Signature can also contain further template code.

<html>
<bp:example>
    <body>
    <h3>Hello</h3>
    </body>
</bp:example>
</html>

The template code between the opening and closing tags of example will be removed and is only visible when the signature is able to handle inline templates.

Value signature

It is not really a signature, but a placeholder for values assigned to the template.

<html><title><bp:$title/></title></html>

If the template contains a value named title, this special type of signature will be replaced by the value.

Pre-defined signatures

Beilpuz comes with a few base signatures to be able to create dynamic content.

include

Includes another template into the current.

template: Path of the template to include.
shared_values (optional): Makes the values of the parent template available in the included.

foreach

Renders the inner template in a loop.

in: Array to loop.
as: Variable name for each item of the array.
index (optional): Variable name for the key of each array item.

if, elseif, else

Renders the inline template if the condition expression is true.

value: Variable name.
is (optional): Comparative value.

value

Renders the value of an assigned variable.

name: Variable name.

This signature is only useful, if you want to cache the value. Otherwise, use the simple Value signature.

Templates

This section is too simple to describe. You should know what templates are, there is nothing left to say.

Location

The default location of templates is the templates/ directory. You can change the directory by setting the Beilpuz configuration variable before loading a template.

include('bp/Beilpuz.php');
Beilpuz::$templates = 'projects/test/templates';

Load a template

You can load a template from a path.

$template = new BpTemplate('test.html');
echo $template->render();
$template = new BpTemplate('subdirectory/test.html');
echo $template->render();

You dont need a file to render dynamic content, you can just create a template from a static string.

$template = new BpTemplate();
$template->fromString('<h5>Iam a template</h5>');

You should avoid using this feature, because this makes Beilpuz slow. Beilpuz is going to recompile this static template every first call of the render method.

Assign values

If you want to fill the template with dynamic content, use the assign method.

$template = new BpTemplate('test.html');
$template->assign('variablename', 'value');
echo $template->render();

Its also possible to assign more complex data structures like arrays.

$template = new BpTemplate('test.html');
$template->assign('myarray', array('one','two','three'));
echo $template->render();

Or objects

$template = new BpTemplate('test.html');
$template->assign('myobject', new FooBar());
echo $template->render();

For large data structures, its recommended to use the assignRef method. That creates a reference of the data structure and prevents PHP to copy its contents.

$template = new BpTemplate('test.html');
$template->assignRef('server', $_SERVER);
echo $template->render();

Output assigned values

If you want to output previous assigned values, use the following signatures.
For single values, use the special Value signature.

<html><bp:$variablename/></html>

This is a short form of a signature which doesnt support attributes. If you want to use attributes, you can use the built-in value signature.

<html><bp:value name="variablename"/></html>

This calls a method and is slightly slower than the short form, but its supports attributes and caching.
The notation for accessing elements of an array is nearly the same as in PHP.

<html><bp:$myarray[0]/> - <bp:$myarray[1]/></html>

Use the dot (.) operator to access properties or methods of object instances.

<html><bp:$myobject.name/> - <bp:$myobject.runMethod()/></html>