doc/themes.md

   1 # Themes
   2
   3 * [Home](help)
   4
   5 To change the look of friendica you have to touch the themes.
   6 The current default theme is [Vier](https://github.com/friendica/friendica/tree/master/view/theme/vier) but there are numerous others.
   7 Have a look at [friendica-themes.com](http://friendica-themes.com) for an overview of the existing themes.
   8 In case none of them suits your needs, there are several ways to change a theme.
   9 If you need help theming, there is a forum @[ftdevs@friendica.eu](https://friendica.eu/profile/ftdevs) where you can ask theme specific questions and present your themes.
  10
  11 So, how to work on the UI of friendica.
  12
  13 You can either directly edit an existing theme.
  14 But you might loose your changes when the theme is updated by the friendica team.
  15
  16 If you are almost happy with an existing theme, the easiest way to cover your needs is to create a new theme, inheritating most of the properties of the parent theme and change just minor stuff.
  17 The below for a more detailed description of theme heritage.
  18
  19 Some themes also allow users to select *variants* of the theme.
  20 Those theme variants most often contain an additional [CSS](https://en.wikipedia.org/wiki/CSS) file to override some styling of the default theme values.
  21 From the themes in the main repository *duepunto zero* and *vier* are using this methods for variations.
  22 Quattro is using a slightly different approach.
  23
  24 Third you can start your theme from scratch.
  25 Which is the most complex way to change friendicas look.
  26 But it leaves you the most freedom.
  27 So below for a *detailed* description and the meaning of some special files.
  28
  29 ### Styling
  30
  31 If you want to change the styling of a theme, have a look at the themes CSS file.
  32 In most cases, you can found these in
  33
  34     /view/theme/**your-theme-name**/style.css
  35
  36 sometimes, there is also a file called style.php in the theme directory.
  37 This is only needed if the theme allowes the user to change certain things of the theme dynamically.
  38 Say the font size or set a background image.
  39
  40 ### Templates
  41
  42 If you want to change the structure of the theme, you need to change the templates used by the theme.
  43 Friendica themes are using [SMARTY3](http://www.smarty.net/) for templating.
  44 The default template can be found in
  45
  46     /view/templates
  47
  48 if you want to override any template within your theme create your version of the template in
  49
  50     /view/theme/**your-theme-name**/templates
  51
  52 any template that exists there will be used instead of the default one.
  53
  54 ### Javascript
  55
  56 The same rule applies to the JavaScript files found in
  57
  58     /js
  59
  60 they will be overwritten by files in
  61
  62     /view/theme/**your-theme-name**/js.
  63
  64 ## Expand an existing Theme
  65
  66 ### Theme Variations
  67
  68 Many themes are more *theme families* than only one theme.
  69 *duepunto zero* and *vier* allow easily to add new theme variation.
  70 We will go through the process of creating a new variation for *duepunto zero*.
  71 The same  (well almost, some names change) procedure applies to the *vier* theme.
  72 And similar steps are needed for *quattro* but this theme is using [lesscss](http://lesscss.org/#docs) to maintain the CSS files..
  73
  74 In
  75
  76     /view/theme/duepuntozero/deriv
  77
  78 you find a couple of CSS files that define color derivations from the duepunto theme.
  79 These resemble some of the now as unsupported marked themes, that were inherited by the duepunto theme.
  80 Darkzero and Easter Bunny for example.
  81
  82 The selection of the colorset is done in a combination of a template for a new form in the settings and aome functions in the theme.php file.
  83 The template (theme_settings.tpl)
  84
  85     {{include file="field_select.tpl" field=$colorset}}
  86     <div class="settings-submit-wrapper">
  87         <input type="submit" value="{{$submit}}" class="settings-submit" name="duepuntozero-settings-submit" />
  88     </div>
  89
  90 defines a formular consisting of a [select](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) pull-down which contains all aviable variants and s submit button.
  91 See the documentation about [SMARTY3 templates](/help/snarty3-templates.md) for a summary of friendica specific blocks other than the select element.
  92 But we don't really need to change anything at the template itself.
  93
  94 The template alone wont work though.
  95 You make friendica aware of its existance and tell it how to use the template file, by defining a config.php file.
  96 It needs to define at least the following functions
  97
  98 * theme_content
  99 * theme_post
 100
 101 and may also define functions for the admin interface
 102
 103 * theme_admin
 104 * theme_admin_post.
 105
 106 theme_content and theme_admin are used to make the form available in the settings, repectively the admin panel.
 107 The _post functions handle the processing of the send form, in this case they save to selected variand in friendicas database.
 108
 109 To make your own variation appear in the menu, all you need to do is to create a new CSS file in the deriv directoy and include it in the array in the config.php:
 110
 111     $colorset = array(
 112         'default'=>L10n::t('default'),
 113         'greenzero'=>L10n::t('greenzero'),
 114         'purplezero'=>L10n::t('purplezero'),
 115         'easterbunny'=>L10n::t('easterbunny'),
 116         'darkzero'=>L10n::t('darkzero'),
 117         'comix'=>L10n::t('comix'),
 118         'slackr'=>L10n::t('slackr'),
 119     );
 120
 121 the 1st part of the line is the name of the CSS file (without the .css) the 2nd part is the common name of the variant.
 122 Calling the L10n::t() function with the common name makes the string translateable.
 123 The selected 1st part will be saved in the database by the theme_post function.
 124
 125     function theme_post(App $a){
 126         // non local users shall not pass
 127         if (! local_user()) {
 128             return;
 129         }
 130         // if the one specific submit button was pressed then proceed
 131         if (isset($_POST['duepuntozero-settings-submit'])){
 132             // and save the selection key into the personal config of the user
 133             PConfig::set(local_user(), 'duepuntozero', 'colorset', $_POST['duepuntozero_colorset']);
 134         }
 135     }
 136
 137 Now that this information is set in the database, what should friendica do with it?
 138 For this, have a look at the theme.php file of the *duepunto zero*.
 139 There you'll find somethink alike
 140
 141         $colorset = PConfig::get( local_user(), 'duepuntozero','colorset');
 142         if (!$colorset)
 143             $colorset = Config::get('duepuntozero', 'colorset');
 144         if ($colorset) {
 145             if ($colorset == 'greenzero')
 146                 $a->page['htmlhead'] .= '<link rel="stylesheet" href="view/theme/duepuntozero/deriv/greenzero.css" type="text/css" media="screen" />'."\n";
 147             /* some more variants */
 148         }
 149
 150 which tells friendica to get the personal config of a user.
 151 Check if it is set and if not look for the global config.
 152 And finally if a config for the colorset was found, apply it by adding a link to the CSS file into the HTML header of the page.
 153 So you'll just need to add a if selection, fitting your variant keyword and link to the CSS file of it.
 154
 155 Done.
 156 Now you can use the variant on your system.
 157 But remember once the theme.php or the config.php you have to readd your variant to them.
 158 If you think your color variation could be benifical for other friendica users as well, feel free to generate a pull request at github so we can include your work into the repository.
 159
 160 ### Inheritation
 161
 162 Say, you like the duepuntozero but you want to have the content of the outer columns left and right exchanged.
 163 That would be not a color variation as shown above.
 164 Instead we will create a new theme, duepuntozero_lr, inherit the properties of duepuntozero and make small changes to the underlying php files.
 165
 166 So create a directory called duepunto_lr and create a file called theme.php with your favorite text editor.
 167 The content of this file should be something like
 168
 169     <?php
 170     /* meta informations for the theme, see below */
 171     function duepuntozero_lr_init(App $a) {
 172         $a-> theme_info = array(
 173             'extends' => 'duepuntozero'.
 174         );
 175         $a->set_template_engine('smarty3');
 176         /* and more stuff e.g. the JavaScript function for the header */
 177     }
 178
 179 Next take the default.php file found in the /view direcotry and exchange the aside and right_aside elements.
 180 So the central part of the file now looks like this:
 181
 182     <body>
 183         <?php if(x($page,'nav')) echo $page['nav']; ?>
 184         <aside><?php if(x($page,'right_aside')) echo $page['right_aside']; ?></aside>
 185         <section><?php if(x($page,'content')) echo $page['content']; ?>
 186                 <div id="page-footer"></div>
 187         </section>
 188         <right_aside><?php if(x($page,'aside')) echo $page['aside']; ?></right_aside>
 189         <footer><?php if(x($page,'footer')) echo $page['footer']; ?></footer>
 190     </body>
 191
 192 Finally we need a style.css file, inheriting the definitions from the parent theme and containing out changes for the new theme.
 193 ***Note***:You need to create the style.css and at lest import the base CSS file from the parent theme.
 194
 195     @import url('../duepuntozero/style.css');
 196
 197 Done.
 198 But I agree it is not really useful at this state.
 199 Nevertheless, to use it, you just need to activate in the admin panel.
 200 That done, you can select it in the settings like any other activated theme.
 201
 202 ## Creating a Theme from Scratch
 203
 204 Keep patient.
 205 Basically what you have to do is identify which template you have to change so it looks more like what you want.
 206 Adopt the CSS of the theme accordingly.
 207 And iterate the process until you have the theme the way you want it.
 208
 209 *Use the source Luke.* and don't hesitate to ask in @[ftdevs](https://friendica.eu/profile/ftdevs) or @[helpers](https://forum.friendi.ca/profile/helpers).
 210
 211 ## Special Files
 212
 213 ### unsupported
 214
 215 If a file with this name (which might be empty) exists in the theme directory, the theme is marked as *unsupported*.
 216 An unsupported theme may not be selected by a user in the settings.
 217 Users who are already using it wont notice anything.
 218
 219 ### README(.md)
 220
 221 The contents of this file, with or without the .md which indicates [Markdown](https://daringfireball.net/projects/markdown/) syntax, will be displayed at most repository hosting services and in the theme page within the admin panel of friendica.
 222
 223 This file should contain information you want to let others know about your theme.
 224
 225 ### screenshot.[png|jpg]
 226
 227 If you want to have a preview image of your theme displayed in the settings you should take a screenshot and save it with this name.
 228 Supported formats are PNG and JPEG.
 229
 230 ### theme.php
 231
 232 This is the main definition file of the theme.
 233 In the header of that file, some meta information is stored.
 234 For example, have a look at the theme.php of the *quattro* theme:
 235
 236     <?php
 237     /**
 238      * Name: Quattro
 239      * Version: 0.6
 240      * Author: Fabio <http://kirgroup.com/profile/fabrixxm>
 241      * Maintainer: Fabio <http://kirgroup.com/profile/fabrixxm>
 242      * Maintainer: Tobias <https://f.diekershoff.de/profile/tobias>
 243      */
 244
 245 You see the definition of the theme's name, it's version and the initial author of the theme.
 246 These three pieces of information should be listed.
 247 If the original author is no longer working on the theme, but a maintainer has taken over, the maintainer should be listed as well.
 248 The information from the theme header will be displayed in the admin panel.
 249
 250 The next crucial part of the theme.php file is a definition of an init function.
 251 The name of the function is <theme-name>_init.
 252 So in the case of quattro it is
 253
 254     function quattro_init(App $a) {
 255       $a->theme_info = array();
 256       $a->set_template_engine('smarty3');
 257     }
 258
 259 Here we have set the basic theme information, in this case they are empty.
 260 But the array needs to be set.
 261 And we have set the template engine that should be used by friendica for this theme.
 262 At the moment you should use the *smarty3* engine.
 263 There once was a friendica specific templating engine as well but that is not used anymore.
 264 If you like to use another templating engine, please implement it.
 265
 266 When you want to inherit stuff from another theme you have to *announce* this in the theme_info:
 267
 268     $a->theme_info = array(
 269       'extends' => 'duepuntozero',
 270     );
 271
 272 which declares *duepuntozero* as parent of the theme.
 273
 274 If you want to add something to the HTML header of the theme, one way to do so is by adding it to the theme.php file.
 275 To do so, add something alike
 276
 277     $a->page['htmlhead'] .= <<< EOT
 278     /* stuff you want to add to the header */
 279     EOT;
 280
 281 The $a variable holds the friendica application.
 282 So you can access the properties of this friendica session from the theme.php file as well.
 283
 284 ### default.php
 285
 286 This file covers the structure of the underlying HTML layout.
 287 The default file is in
 288
 289     /view/default.php
 290
 291 if you want to change it, say adding a 4th column for banners of your favourite FLOSS projects, place a new default.php file in your theme directory.
 292 As with the theme.php file, you can use the properties of the $a variable with holds the friendica application to decide what content is displayed.