Quick Template Guide - adamhesim/friendica GitHub Wiki

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

###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);
replace_macro($tpl, $array);

The first function search $templatename in view/theme/$currenttheme and view/ and return its content.

The second 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/ 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"

A trick in addons to load a template from addon folder:

in addon/myaddon/myaddon.php
$tpl = file_get_content(dirname(__file__)."/mytemplate.tpl";
⚠️ **GitHub.com Fallback** ⚠️