]> git.mxchange.org Git - friendica.git/blob - doc/themes.md
Merge pull request #13146 from MrPetovan/bug/deprecated
[friendica.git] / 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.