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