doc/smarty3-templates.md

   1 Friendica Templating Documentation
   2 ==================================
   3
   4 * [Home](help)
   5
   6 Friendica uses [Smarty 3](http://www.smarty.net/) as PHP templating engine. The main templates are found in
   7
   8                 /view/templates
   9
  10 theme authors may overwrite the default templates by putting a files with the same name into the
  11
  12                 /view/themes/$themename/templates
  13
  14 directory.
  15
  16 Templates that are only used by addons shall be placed in the
  17
  18                 /addon/$addonname/templates
  19
  20 directory.
  21
  22 To render a template use the function *get_markup_template* to load the template and *replace_macros* to replace the macros/variables in the just loaded template file.
  23
  24                 $tpl = get_markup_template('install_settings.tpl');
  25         $o .= replace_macros($tpl, array( ... ));
  26
  27 the array consists of an association of an identifier and the value for that identifier, i.e.
  28
  29                 '$title' => $install_title,
  30
  31 where the value may as well be an array by its own.
  32
  33 Form Templates
  34 --------------
  35
  36 To guarantee a consistent look and feel for input forms, i.e. in the settings sections, there are templates for the basic form fields. They are initialized with an array of data, depending on the tyle of the field.
  37
  38 All of these take an array for holding the values, i.e. for an one line text input field, which is required and should be used to type email addesses use something along
  39
  40                 '$adminmail' => array('adminmail', t('Site administrator email address'), $adminmail, t('Your account email address must match this in order to use the web admin panel.'), 'required', '', 'email'),
  41
  42 To evaluate the input value, you can then use the $_POST array, more precisely the $_POST['adminemail'] variable.
  43
  44 Listed below are the template file names, the general purpose of the template and their field parameters.
  45
  46 ### field_checkbox.tpl
  47
  48 A checkbox. If the checkbox is checked its value is **1**. Field parameter:
  49
  50 0. Name of the checkbox,
  51 1. Label for the checkbox,
  52 2. State checked? if true then the checkbox will be marked as checked,
  53 3. Help text for the checkbox.
  54
  55 ### field_combobox.tpl
  56
  57 A combobox, combining a pull down selection and a textual input field. Field parameter:
  58
  59 0. Name of the combobox,
  60 1. Label for the combobox,
  61 2. Current value of the variable,
  62 3. Help text for the combobox,
  63 4. Array holding the possible values for the textual input,
  64 5. Array holding the possible values for the pull down selection.
  65
  66 ### field_custom.tpl
  67
  68 A customizeable template to include a custom element in the form with the usual surroundings, Field parameter:
  69
  70 0. Name of the field,
  71 1. Label for the field,
  72 2. the field,
  73 3. Help text for the field.
  74
  75 ### field_input.tpl
  76
  77 A single line input field for textual input. Field parameter:
  78
  79 0. Name of the field,
  80 1. Label for the input box,
  81 2. Current value of the variable,
  82 3. Help text for the input box,
  83 4. if set to "required" modern browser will check that this input box is filled when submitting the form,
  84 5. if set to "autofocus" modern browser will put the cursur into this box once the page is loaded,
  85 6. if set to "email" or "url" modern browser will check that the filled in value corresponds to an email address or URL.
  86
  87 ### field_intcheckbox.tpl
  88
  89 A checkbox (see above) but you can define the value of it. Field parameter:
  90
  91 0. Name of the checkbox,
  92 1. Label for the checkbox,
  93 2. State checked? if true then the checkbox will be marked as checked,
  94 3. Value of the checkbox,
  95 4. Help text for the checkbox.
  96
  97 ### field_openid.tpl
  98
  99 An input box (see above) but prepared for special CSS styling for openID input. Field parameter:
 100
 101 0. Name of the field,
 102 1. Label for the input box,
 103 2. Current value of the variable,
 104 3. Help text for the input field.
 105
 106 ### field_password.tpl
 107
 108 A single line input field (see above) for textual input. The characters typed in will not be shown by the browser. Field parameter:
 109
 110 0. Name of the field,
 111 1. Label for the field,
 112 2. Value for the field, e.g. the old password,
 113 3. Help text for the input field,
 114 4. if set to "required" modern browser will check that this field is filled out,
 115 5. if set to "autofocus" modern browser will put the cursor automatically into this input field.
 116
 117 ### field_radio.tpl
 118
 119 A radio button. Field parameter:
 120
 121 0. Name of the radio button,
 122 1. Label for the radio button,
 123 2. Current value of the variable,
 124 3. Help text for the button,
 125 4. if set, the radio button will be checked.
 126
 127 ### field_richtext.tpl
 128
 129 A multi-line input field for *rich* textual content. Field parameter:
 130
 131 0. Name of the input field,
 132 1. Label for the input box,
 133 2. Current text for the box,
 134 3. Help text for the input box.
 135
 136 ### field_select.tpl
 137
 138 A drop down selection box. Field parameter:
 139
 140 0. Name of the field,
 141 1. Label of the selection box,
 142 2. Current selected value,
 143 3. Help text for the selection box,
 144 4. Array holding the possible values of the selection drop down.
 145
 146 ### field_select_raw.tpl
 147
 148 A drop down selection box (see above) but you have to prepare the values yourself. Field parameter:
 149
 150 0. Name of the field,
 151 1. Label of the selection box,
 152 2. Current selected value,
 153 3. Help text for the selection box,
 154 4. Possible values of the selection drop down.
 155
 156 ### field_textarea.tpl
 157
 158 A multi-line input field for (plain) textual content. Field parameter:
 159
 160 0. Name of the input field,
 161 1. Label for the input box,
 162 2. Current text for the box,
 163 3. Help text for the input box.
 164
 165 ### field_yesno.tpl
 166
 167 A button that has two states *yes* or *no*. Field parameter:
 168
 169 0. Name of the input field,
 170 1. Label for the button,
 171 2. Current value,
 172 3. Help text for the button
 173 4. if set to an array of two values, these two will be used, otherwise "off" and "on".