Quick Template Guide

fabrixxm edited this page Apr 24, 2013 · 2 revisions

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"
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.