<bp:$works/>

====== 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///:

<bp:$works/>
Congratulation, it

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

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. ===== Using Beilpuz ===== ==== Signatures ==== === What are signatures === 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//:



<bp:example/>

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



<bp:example foo="bar"/>

The example signature got the attribute //foo// with the value //bar//. === Inline templates === Signature can also contain further template code.




    
    Hello

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.


<bp:$title/>

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('Iam a template');

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]].

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.

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.

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