<commit_before>Renderers for application developers
====================================

You are an application developer? Here is what you need to know to use the rendering system efficiently.

The rendering system provides an easy way to render in HTML your objects. This is a 3 steps process:

1. Your class should implement the <code>HtmlElementInterface</code> (optional)
2. Your class should use the <code>Renderable</code> trait
3. You should add a template file in the *src/templates* directory

Then you can render your class using the <code>toHtml()</code> method provided by the <code>Renderable</code> trait.

Here is a minimalistic sample:

```php
namespace MyNamespace;

use Mouf\Html\HtmlElement\HtmlElementInterface;
use Mouf\Html\Renderer\Renderable;

// My class implements the HtmlElementInterface interface
class MyClass implements HtmlElementInterface {
	// My class uses the Renderable trait
	use Renderable;

	public $myValue;
}
```

Now, I need to provide a template file. The template file should be named after the PSR-0 convention and 
placed in the *src/templates* directory. It can have the ".php" or ".twig" extension.

In this example, if we are using Twig as a templating engine, the file name should 
be **src/templates/MyNamespace/MyClass.twig**

```twig
<h1>Sample class</h1>
{{ this.myValue }}
```

We could also use the PHP templating engine. In that case, the file name would  
be **src/templates/MyNamespace/MyClass.php**

```php
<h1>Sample class</h1>
<?php echo $object->myValue ?>
```

About Twig templates
--------------------

[Twig](http://twig.sensiolabs.org/) is a templating engine for PHP. The main reason to use Twig is that Twig
automatically protects you from XSS by escaping HTML strings (unless you tell it not to espace the string). It has 
also a very concise syntax making it pleasant to use.

When you are working with Twig, your object is accessible using the "this" variable.

<table class="table table-bordered">
	<tr>
		<th>In your class</th>
		<th>In Twig</th>
	</tr>
	<tr>
		<td><code>public $myVar</code></td>
		<td><code>{{ this.myVar }}</code> or <code>{{ myVar }}</code> (public properties can be accessed without the <code>this</code> keyword.</td>
	</tr>
	<tr>
		<td><code>public function getVar2() { ... }</code></td>
		<td><code>{{ this.var2 }}</code> or <code>{{ this.getVar2 }}</code></td>
	</tr>
</table>

Please note you cannot access *protected* or *private* properties.

Autoescaping is enabled by default.
Performance-wise, templates are compiled as PHP files and cached. When a template file is modified, Twig detects the
change and recompiles the template.

About PHP templates
-------------------

Plain PHP files can also be used as template files.
This is way more flexible than Twig, but there are also way more ways to make errors.
The $object variable is a pointer to the object you are rendering.

<table class="table table-bordered">
	<tr>
		<th>In your class</th>
		<th>In your PHP template</th>
	</tr>
	<tr><commit_msg>Adding special Twig functions<commit_after>Renderers for application developers
====================================

You are an application developer? Here is what you need to know to use the rendering system efficiently.

The rendering system provides an easy way to render in HTML your objects. This is a 3 steps process:

1. Your class should implement the <code>HtmlElementInterface</code> (optional)
2. Your class should use the <code>Renderable</code> trait
3. You should add a template file in the *src/templates* directory

Then you can render your class using the <code>toHtml()</code> method provided by the <code>Renderable</code> trait.

Here is a minimalistic sample:

```php
namespace MyNamespace;

use Mouf\Html\HtmlElement\HtmlElementInterface;
use Mouf\Html\Renderer\Renderable;

// My class implements the HtmlElementInterface interface
class MyClass implements HtmlElementInterface {
	// My class uses the Renderable trait
	use Renderable;

	public $myValue;
}
```

Now, I need to provide a template file. The template file should be named after the PSR-0 convention and 
placed in the *src/templates* directory. It can have the ".php" or ".twig" extension.

In this example, if we are using Twig as a templating engine, the file name should 
be **src/templates/MyNamespace/MyClass.twig**

```twig
<h1>Sample class</h1>
{{ this.myValue }}
```

We could also use the PHP templating engine. In that case, the file name would  
be **src/templates/MyNamespace/MyClass.php**

```php
<h1>Sample class</h1>
<?php echo $object->myValue ?>
```

About Twig templates
--------------------

[Twig](http://twig.sensiolabs.org/) is a templating engine for PHP. The main reason to use Twig is that Twig
automatically protects you from XSS by escaping HTML strings (unless you tell it not to espace the string). It has 
also a very concise syntax making it pleasant to use.

When you are working with Twig, your object is accessible using the "this" variable.

<table class="table table-bordered">
	<tr>
		<th>In your class</th>
		<th>In Twig</th>
	</tr>
	<tr>
		<td><code>public $myVar</code></td>
		<td><code>{{ this.myVar }}</code> or <code>{{ myVar }}</code> (public properties can be accessed without the <code>this</code> keyword.</td>
	</tr>
	<tr>
		<td><code>public function getVar2() { ... }</code></td>
		<td><code>{{ this.var2 }}</code> or <code>{{ this.getVar2 }}</code></td>
	</tr>
</table>

Please note you cannot access *protected* or *private* properties.

Autoescaping is enabled by default.
Performance-wise, templates are compiled as PHP files and cached. When a template file is modified, Twig detects the
change and recompiles the template.

The rendering engines comes with a set of functions dedicated to Mouf. You can check it out on the
[Mouf's Twig extensions](twig_extensions.md) page.

About PHP templates
-------------------

Plain PHP files can also be used as template files.
This is way more flexible than Twig, but there are also way more ways to make errors.
The $object variable is a pointer to the object you are rendering.

<table class="table table-bordered">
	<tr>
		<th>In your class</th>
		<th>In your PHP template</th>
	</tr>
	<tr>
{'fraction_non_alphanumeric': 0.12477775981897526, 'fraction_numerical': 0.0038791013415225475, 'mean_word_length': 4.135269709543569, 'pattern_counts': {'":': 0, '<': 113, '<?xml version=': 0, '>': 115, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4102181', 'n_tokens_mistral': 1859, 'n_tokens_neox': 1806, 'n_words': 809}