3 Quick Template Guide
Hypolite Petovan edited this page 2020-02-05 21:04:43 -05:00

friendica has a template system. We are trying to separate html from php (wich is also a good think if we want a mobile teme). This template system allows variables substitution, a minimal logic and possibility to include a template in another template. In 'view/templates' folder there are some template for form fields, ready to be included, so that every form looks the same throughout the site.

A quick guide

1 - Template syntax

Friendica uses the Smarty 3 template engine, please refer to the official Smarty 3 manual.

2 - PHP side

In Friendica, templates are used with two functions:

Friendica\Core\Renderer::getMarkupTemplate($templatename, [$root]);
Friendica\Core\Renderer::replaceMacros($tpl, $array);

Renderer::getMarkupTemplate() search $templatename in $root/theme/templates/$currenttheme and $root/templates and return its content. If $root is not defined, defaults to view/

Addons can load custom templates saving template files in templates/ subfolder, and calling get_markup_template() with plugin relative path as $root:

$tpl = get_markup_template("mytemplate.tpl", "addon/myplugin/");

replace_macro() replace $array in template content.

file: test.tpl
Hello $name! {{ if $isback }} Welcome back! {{ endif }}

file: test.php
<?php ...
$tpl = get_markup_template('test.tpl');
echo replace_macro($tpl, array(
    '$name' => 'Anna',
    '$isback' => false));

result:

Hello Anna!

Form fields templates

In view/template folder there are many template for form fields.

  • field_input.tpl: prints a text input
  • field_password.tpl: prints a password input
  • field_textarea.tpl: prints a textarea element
  • field_richtext.tpl: prints a tinymce rich text area
  • field_radio.tpl: prints a radio input
  • field_checkbox.tpl: prints a checkbox input with value=1
  • field_intcheckbox.tpl: prints a checkbox input with a custom value
  • field_select.tpl: prints a select input. options are passed as key=>value array.
  • field_select_raw.tpl: a select input, but options are passed as prebuilt html string
  • field_openid.tpl: a text input styled with openid icon
  • field_custom.tpl: field template without input tag. Is passed as prebuilt html string

Every field_* template expect a var called $field. A field template is included like this:

{{include file=field_input.tpl field=$myvar}}

The $field var is an array:

$field = ['name', 'Label', value, '[optional help text]', <extra data>]
  • 'name' is the name assigned to html element
  • 'Label' is the string printed for element label
  • value is the value of field
  • field_checkbox want a value that can be evaluated to 'true' or 'false' to set the field checked or not (usually 1 or 0).
  • field_select use this to find the currently selected option
  • field_custom expects this to be the prebuilt input html string
  • 'optional text help' is a text printed under input to give more detail on what he should input. Could be an empty string.
  • extra data is data needed by some templates
  • field_select: array(key=>value,..) to use in < option > tags as value=>label
  • field_intcheckbox: value of input element
  • field_select_raw: prebuilt HTML string of < option > tags