]> git.mxchange.org Git - friendica.git/blob - doc/themes.md
typo
[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 [duepunto zero](https://github.com/friendica/friendica/tree/master/view/theme/duepuntozero) 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 There are several ways to change a theme.
9 You can either directly work on an existing theme.
10 But you might loose your changes when the theme is updated by the friendica team.
11 In cases where 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.
12 The beloow for a more detailed description of theme heritage.
13
14 Some themes also allow users to select *variants* of the theme.
15 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.
16 From the themes in the main repository *duepunto zero* and *vier* are using this methods for variations.
17
18 Third you can start your theme from scratch.
19 Which is the most complex way to change friendicas look.
20 But it leaves you the most freedom.
21 So below for a detailed description and the meaning of some special files.
22
23 ## Styling
24
25 If you want to change the styling of a theme, have a look at the themes CSS file.
26 In most cases, you can found these in
27
28     /view/theme/<your-theme-name>/style.css
29
30 sometimes, there is also a file called style.php in the theme directory.
31 This is only needed if the theme allowes the user to change certain things of the theme dynamically.
32 Say the font size or set a background image.
33
34 If you want to change the structure of the theme, you need to change the templates used by the theme.
35 Friendica themes are using [SMARTY3](http://www.smarty.net/) for templating.
36 The default template can be found in
37
38     /view/templates
39
40 if you want to override any template within your theme create your version of the template in
41
42     /view/theme/<your-theme-name>/templates
43
44 any template that exists there will be used instead of the default one.
45 The same rule applies to the JavaScript files found in
46
47     /js
48
49 they will be overwritten by files in
50
51     /view/theme/<your-theme-name>/js.
52
53 ## Expand an existing Theme
54
55 ### A new Variation for duepuntozero
56
57 In
58
59     /view/theme/duepuntozero/deriv
60
61 you find a couple of CSS files that define color derivations from the duepunto theme.
62 These resemble some of the now as unsupported marked themes, that were inherited by the duepunto theme.
63 Darkzero and Easter Bunny for example.
64
65 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.
66 The template (theme_settings.tpl)
67
68     <script src="{{$baseurl}}/view/theme/quattro/jquery.tools.min.js"></script>
69     {{include file="field_select.tpl" field=$colorset}} 
70     <div class="settings-submit-wrapper">
71         <input type="submit" value="{{$submit}}" class="settings-submit" name="duepuntozero-settings-submit" />
72     </div>
73
74 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.
75 See the documentation about [SMARTY3 templates](/help/snarty3-templates.md) for a summary of friendica specific blocks other then the select element.
76
77 The template alone wont work.
78 You make friendica aware of its existance and tell it how to use the template file, by defining a config.php file.
79 It needs to define at lest the following functions
80 * theme_content
81 * theme_post
82
83 and may also define functions for the admin interface
84
85 * theme_admin
86 * theme_admin_post.
87
88 theme_content and theme_admin are used to make the form available in the settings, repectively the admin panel.
89 The _post functions handle the processing of the send form, in this case they save to selected variand in friendicas database.
90
91 To make your own variation 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:
92
93     $colorset = array(
94         'default'=>t('default'), 
95         'greenzero'=>t('greenzero'),
96         'purplezero'=>t('purplezero'),
97         'easterbunny'=>t('easterbunny'),
98         'darkzero'=>t('darkzero'),
99         'comix'=>t('comix'),
100         'slackr'=>t('slackr'),
101     );
102
103 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.
104 The selected 1st part will be saved in the database by the theme_post function.
105
106     function theme_post(&$a){
107         // non local users shall not pass
108         if(! local_user())
109             return;
110         // if the one specific submit button was pressed then proceed
111         if (isset($_POST['duepuntozero-settings-submit'])){
112             // and save the selection key into the personal config of the user
113             set_pconfig(local_user(), 'duepuntozero', 'colorset', $_POST['duepuntozero_colorset']);
114         }
115     }
116
117 Now that this information is set in the databes, what should friendica do with it?
118 For this, have a look at the theme.php file of the theme.
119 There you'll find somethink alike
120
121         $colorset = get_pconfig( local_user(), 'duepuntozero','colorset');
122         if (!$colorset)
123             $colorset = get_config('duepuntozero', 'colorset');
124         if ($colorset) {
125             if ($colorset == 'greenzero')
126                 $a->page['htmlhead'] .= '<link rel="stylesheet" href="view/theme/duepuntozero/deriv/greenzero.css" type="text/css" media="screen" />'."\n";
127             /* some more variants */
128         }
129
130 so you'll just need to add a if selection, fitting your variant keyword and link to the CSS file of it.
131
132 Done.
133 Now you can use the variant on your system.
134 But remember once the theme.php or the config.php you have to readd your variant to them.
135
136 *More or less the same procedure works for the vier theme.*
137
138 ### Inheritation
139
140 Say, you like the duepuntozero but you want to have the content of the outer columns  left and right exchanged.
141 That would be not a color variation as shown above.
142 Instead we will create a new theme, duepuntozero_lr, inherit the properties of duepuntozero and make small changes to the underlying php files.
143
144 So create a directory called duepunto_lr and create a file called theme.php with your favorite text editor.
145 The content of this file should be something like
146
147     <?php
148     /* meta informations for the theme, see below */
149     function duepuntozero_lr_init(&$a) {
150         $a-> theme_info = array(
151             'extends' => 'duepuntozero'.
152         );
153         set_template_engine($a, 'smarty3');
154         /* and more stuff e.g. the JavaScript function for the header */
155     }
156
157 Next take the default.php file found in the /view direcotry and exchange the aside and right_aside elements.
158 So the central part of the file now looks like this:
159
160     <body>
161         <?php if(x($page,'nav')) echo $page['nav']; ?>
162         <aside><?php if(x($page,'right_aside')) echo $page['right_aside']; ?></aside>
163         <section><?php if(x($page,'content')) echo $page['content']; ?>
164                 <div id="page-footer"></div>
165         </section>
166         <right_aside><?php if(x($page,'aside')) echo $page['aside']; ?></right_aside>
167         <footer><?php if(x($page,'footer')) echo $page['footer']; ?></footer>
168     </body>
169
170 Finally we need a style.css file, inheriting the definitions from the parent theme and containing out changes for the new theme.
171
172     @import url('../duepuntozero/style.css');
173
174 Done.
175 But I agree it is not really useful at this state.
176 Nevertheless, to use it, you just neet to activate in the admin panel.
177 That done, you can select it in the settings like any other activated theme.
178
179 ## Creating a Theme from Scratch
180
181 Keep patient.
182 Basically what you have to do is identifying which template you have to change so it looks more like what you want.
183 Adopt the CSS of the theme accordingly.
184 And iterate the process until you have the theme the way you want it.
185
186 ## Special Files
187
188 ### unsupported
189
190 If a file (which might be empty) exists in the theme directory, the theme is marked as *unsupported*.
191 An unsupported theme may not be selected by a user in the settings.
192 Users who are already using it wont notice anything.
193
194 ### README(.md)
195
196 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.
197
198 This file should contain information you want to let others know about your theme.
199
200 ### screenshot.[png|jpg]
201
202 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.
203 Supported formats are PNG and JPEG.
204
205 ### theme.php
206
207 This is the main definition file of the theme.
208 In the header of that file, some meta information are stored.
209 For example, have a look at the theme.php of the *quattro* theme:
210
211     <?php
212     /**
213      * Name: Quattro
214      * Version: 0.6
215      * Author: Fabio <http://kirgroup.com/profile/fabrixxm>
216      * Maintainer: Fabio <http://kirgroup.com/profile/fabrixxm>
217      * Maintainer: Tobias <https://f.diekershoff.de/profile/tobias>
218      */
219
220 You see the definition of the themes name, it's version and the initial author of the theme.
221 These three information should be listed.
222 If the original author is not anymore working on the theme, but a maintainer has taken over, the maintainer should be listed as well.
223 The information from the theme header will be displayed in the admin panelö.
224
225 Next crucial part of the theme.php file is a definition of an init function.
226 The name of the function is <theme-name>_init.
227 So in the case of quattro it is
228
229     function quattro_init(&$a) {
230       $a->theme_info = array();
231       set_template_engine($a, 'smarty3');
232     }
233
234 Here we have set the basic theme information, in this case they are empthy.
235 But the array needs to be set.
236 And we have set the template engine that should be used by friendica for this theme.
237 At the moment you should use the *smarty3* engine.
238 There once was a friendica specific templating engine as well but that is not used anymore.
239 If you like to use another templating engine, please implement it.
240
241 When you want to inherit stuff from another theme you have to *announce* this in the theme_info:
242
243     $a->theme_info = array(
244       'extends' => 'duepuntozero',
245     );
246
247 which declares *duepuntozero* as parent of the theme.
248
249 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.
250 To do so, add something alike
251
252     $a->page['htmlhead'] .= <<< EOT
253     /* stuff you want to add to the header */
254     EOT;
255
256 The $a variable holds the friendica application.
257 So you can access the properties of this friendica session from the theme.php file as well.
258
259 ### default.php
260
261 This file covers the structure of the underlying HTML layout.
262 The default file is in
263
264     /view/default.php
265
266 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.