Quick Template Guide

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. OBSOLETE###

Friendica default template engine is now Smarty3. Refer to smarty3 documentation

###Variables###

Variables starts with $

Welcome $name

Is possible to pass an array to template. Refer to array items with the form $varname.key

in php: 
    $user = Array( 'name'=>'John', 'enabled'=>false)
in template:
    Welcome $user.name

###Logic blocks###

Logic block are in the form {{ name opts }}...{{ endname }}

####Conditional: IF####

syntax:

{{ if <$var> }}...[{{ else }} ...] {{ endif }}
{{ if <$var>==<$var|str> }}...[{{ else }} ...]{{ endif }}
{{ if <$var>!=<$var|str> }}...[{{ else }} ...]{{ endif }}

examples:

{{ if $user.enabled }} Ok. {{ endif }}

{{ if $user.enabled }}
     <span>$user.name</span>
{{ else }}
    <span>$user.name</span>
{{ endif }}

####Loop: FOR####

syntax:

{{ for <$var> as $name }}...{{ endfor }}
{{ for <$var> as $key=>$name }}...{{ endfor }}

example:

 {{ for $items as $item}}
     < h1 >$item.title< /h1 >;
     $item.body
 {{ endfor }}

####Include: INC####

syntax:

{{ inc  [with $var1=$var2] }}{{ endinc }}

example:

 file: field_text.tpl
 < label for="id_$field.name">$field.label< /label >
 < input id="id_$field.name" name="$field.name" value="$field_value" />
 
 file: form.tpl
 < form >
     {{ inc field_text.tpl with $field=$username }}{{ endinc }}
     {{ inc field_text.tpl with $field=$useremail }}{{ endinc }}
 < /form >

##2 - PHP side##

In friendica, templates are used with two functions:

get_markup_template($templatename, [$root]);
replace_macro($tpl, $array);

get_markup_template() 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_yesno.tpl: a javascript-enanched checkbox. Show a slider button with "ON/OFF" or custom labels
• 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 prebuild html string
• field_openid.tpl: a text input styled with openid icon
• field_custom.tpl: field template without input tag. Is passed as prebuild html string

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

{{ inc field_input.tpl with $field=$myvar }}{{ endinc }}

The $field var is an array:

$field = array('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_custon expects this to be the prebuild imput html string
• 'optional text help' is a text printed under input to give more detail on what he shoud 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: prebuild html string of < option > tags
• field_yesno: custom labels for OFF and ON in array ("label off","label on"