Customizing Templates

Customizing the appearance of the Php Reports framework is easy due to the Twig templating engine.

Everything that is output to the screen is rendered by Twig and completely customizable. All of the default templates are located in templates/default. Anything you place in templates/local will be used instead of the default one.

Most templates define one or more blocks that can be over-ridden individually. This provides tremendous flexibility while also allowing you to update the core framework without worrying about overwriting local changes.

Let's start by changing the "Configure Report" title in the variable form. It often helps to look at the default template and see what blocks are available to override. The default template for the variable form is located at templates/default/html/variable_form.twig. It contains the following:

<form method='get' id='variable_form'>
	{% block variable_form_title %}
	<h2>Configure Report</h2>
	{% endblock %}
	
	<input type='hidden' name='report' value='{{report}}' />
	...

While you are free to replace the entire variable_form.twig file with a local version, it's often easier to extend the default template and just modify the blocks that you want.

Create the file templates/local/html/variable_form.twig and put in the following contents:

{% extends "default/html/variable_form.twig" %}

{% block variable_form_title %}
<h2>Report Configuration</h2>
{% endblock %}

Now, just refresh the report to see your changes take effect.

If you want to add extra css or javascript files to every page, create the file templates/local/html/page.twig and put in the following contents:

{% extends "default/html/page.twig" %}

{% block stylesheets %}
    {{ parent() }}
    <link rel='stylesheet' href='{{base}}/public/css/custom_styles.css' />
{% endblock %}

{% block javascripts %}
    {{ parent() }}
    <script src='{{base}}/public/js/custom_javascript.js'></script>
{% endblock %}

The "{{ parent() }}" tag will render everything in the default block. The "{{base}}" variable contains the root url of the report framework. It is important to always prefix internal links with "{{base}}" so your links don't break if you install in a subdirectory.

To find out more about Twig, check out their excellent documentation.