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/stable/view/theme/vier) but there are numerous others.
   7 Have a look at [github.com/bkil/friendica-themes](https://github.com/bkil/friendica-themes) 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
  10 So, how to work on the UI of friendica.
  11
  12 You can either directly edit an existing theme.
  13 But you might loose your changes when the theme is updated by the friendica team.
  14
  15 If you are almost happy with an existing theme, the easiest way to cover your needs is to create a new theme, inheriting most of the properties of the parent theme and change just minor stuff.
  16 The below for a more detailed description of theme heritage.
  17
  18 Some themes also allow users to select *variants* of the theme.
  19 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.
  20 From the themes in the main repository *vier* and *vier* are using this methods for variations.
  21 Quattro is using a slightly different approach.
  22
  23 Third you can start your theme from scratch.
  24 Which is the most complex way to change friendicas look.
  25 But it leaves you the most freedom.
  26 So below for a *detailed* description and the meaning of some special files.
  27
  28 ### Styling
  29
  30 If you want to change the styling of a theme, have a look at the themes CSS file.
  31 In most cases, you can found these in
  32
  33     /view/theme/**your-theme-name**/style.css
  34
  35 sometimes, there is also a file called style.php in the theme directory.
  36 This is only needed if the theme allows the user to change certain things of the theme dynamically.
  37 Say the font size or set a background image.
  38
  39 ### Templates
  40
  41 If you want to change the structure of the theme, you need to change the templates used by the theme.
  42 Friendica themes are using [SMARTY3](http://www.smarty.net/) for templating.
  43 The default template can be found in
  44
  45     /view/templates
  46
  47 if you want to override any template within your theme create your version of the template in
  48
  49     /view/theme/**your-theme-name**/templates
  50
  51 any template that exists there will be used instead of the default one.
  52
  53 ### JavaScript
  54
  55 The same rule applies to the JavaScript files found in
  56
  57     /js
  58
  59 they will be overwritten by files in
  60
  61     /view/theme/**your-theme-name**/js.
  62
  63 ## Creating a Theme from Scratch
  64
  65 Keep patient.
  66 Basically what you have to do is identify which template you have to change so it looks more like what you want.
  67 Adopt the CSS of the theme accordingly.
  68 And iterate the process until you have the theme the way you want it.
  69
  70 *Use the source Luke.* and don't hesitate to ask in @[developers](https://forum.friendi.ca/profile/developers) or @[helpers](https://forum.friendi.ca/profile/helpers).
  71
  72 ## Special Files
  73
  74 ### unsupported
  75
  76 If a file with this name (which might be empty) exists in the theme directory, the theme is marked as *unsupported*.
  77 An unsupported theme may not be selected by a user in the settings.
  78 Users who are already using it wont notice anything.
  79
  80 ### README(.md)
  81
  82 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.
  83
  84 This file should contain information you want to let others know about your theme.
  85
  86 ### screenshot.[png|jpg]
  87
  88 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.
  89 Supported formats are PNG and JPEG.
  90
  91 ### theme.php
  92
  93 This is the main definition file of the theme.
  94 In the header of that file, some meta information is stored.
  95 For example, have a look at the theme.php of the *vier* theme:
  96
  97     <?php
  98     /**
  99      * [Licence]
 100      *
 101      * Name: Vier
 102      * Version: 1.2
 103      * Author: Fabio <http://kirgroup.com/profile/fabrixxm>
 104      * Author: Ike <http://pirati.ca/profile/heluecht>
 105      * Author: Beanow <https://fc.oscp.info/profile/beanow>
 106      * Maintainer: Ike <http://pirati.ca/profile/heluecht>
 107      * Description: "Vier" is a very compact and modern theme. It uses the font awesome font library: http://fortawesome.github.com/Font-Awesome/
 108      */
 109
 110 You see the definition of the theme's name, it's version and the initial author of the theme.
 111 These three pieces of information should be listed.
 112 If the original author is no longer working on the theme, but a maintainer has taken over, the maintainer should be listed as well.
 113 The information from the theme header will be displayed in the admin panel.
 114
 115 The first thing in file is to import the `App` class from `\Friendica\` namespace.
 116
 117     use Friendica\App;
 118
 119 This will make our job a little easier, as we don't have to specify the full name every time we need to use the `App` class.
 120
 121 The next crucial part of the theme.php file is a definition of an init function.
 122 The name of the function is <theme-name>_init.
 123 So in the case of vier it is
 124
 125     function vier_init(App $a) {
 126                 $a->theme_info = array();
 127                 $a->set_template_engine('smarty3');
 128     }
 129
 130 Here we have set the basic theme information, in this case they are empty.
 131 But the array needs to be set.
 132 And we have set the template engine that should be used by friendica for this theme.
 133 At the moment you should use the *smarty3* engine.
 134 There once was a friendica specific templating engine as well but that is not used anymore.
 135 If you like to use another templating engine, please implement it.
 136
 137 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.
 138 To do so, add something alike
 139
 140     DI::page()['htmlhead'] .= <<< EOT
 141     /* stuff you want to add to the header */
 142     EOT;
 143
 144 So you can access the properties of this friendica session from the theme.php file as well.
 145
 146 ### default.php
 147
 148 This file covers the structure of the underlying HTML layout.
 149 The default file is in
 150
 151     /view/default.php
 152
 153 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.
 154 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.