From 3855648c3d008bd752a5db76cc308ca9972e6958 Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Sun, 16 Aug 2015 18:08:46 +0200 Subject: [PATCH] 0th iteration of the theming documentation --- doc/themes.md | 266 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 doc/themes.md diff --git a/doc/themes.md b/doc/themes.md new file mode 100644 index 0000000000..1e15b3df81 --- /dev/null +++ b/doc/themes.md @@ -0,0 +1,266 @@ +# Themes + +* [Home](help) + +To change the look of friendica you have to touch the themes. +The current default theme is [duepunto zero](https://github.com/friendica/friendica/tree/master/view/theme/duepuntozero) but there are numerous others. +Have a look at [friendica-themes.com](http://friendica-themes.com) for an overview of the existing themes. +There are several ways to change a theme. +You can either directly work on an existing theme. +But you might loose your changes when the theme is updated by the friendica team. +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. +The beloow for a more detailed description of theme heritage. + +Some themes also allow users to select *variants* of the theme. +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. +From the themes in the main repository *duepunto zero* and *vier* are using this methods for variations. + +Third you can start your theme from scratch. +Which is the most complex way to change friendicas look. +But it leaves you the most freedom. +So below for a detailed description and the meaning of some special files. + +## Styling + +If you want to change the styling of a theme, have a look at the themes CSS file. +In most cases, you can found these in + + /view/theme//style.css + +sometimes, there is also a file called style.php in the theme directory. +This is only needed if the theme allowes the user to change certain things of the theme dynamically. +Say the font size or set a background image. + +If you want to change the structure of the theme, you need to change the templates used by the theme. +Friendica themes are using [SMARTY3](http://www.smarty.net/) for templating. +The default template can be found in + + /view/templates + +if you want to override any template within your theme create your version of the template in + + /view/theme//templates + +any template that exists there will be used instead of the default one. +The same rule applies to the JavaScript files found in + + /js + +they will be overwritten by files in + + /view/theme//js. + +## Expand an existing Theme + +### A new Variation for duepuntozero + +In + + /view/theme/duepuntozero/deriv + +you find a couple of CSS files that define color derivations from the duepunto theme. +These resemble some of the now as unsupported marked themes, that were inherited by the duepunto theme. +Darkzero and Easter Bunny for example. + +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. +The template (theme_settings.tpl) + + + {{include file="field_select.tpl" field=$colorset}} +
+ +
+ +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. +See the documentation about [SMARTY3 templates](/help/snarty3-templates.md) for a summary of friendica specific blocks other then the select element. + +The template alone wont work. +You make friendica aware of its existance and tell it how to use the template file, by defining a config.php file. +It needs to define at lest the following functions +* theme_content +* theme_post + +and may also define functions for the admin interface + +* theme_admin +* theme_admin_post. + +theme_content and theme_admin are used to make the form available in the settings, repectively the admin panel. +The _post functions handle the processing of the send form, in this case they save to selected variand in friendicas database. + +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: + + $colorset = array( + 'default'=>t('default'), + 'greenzero'=>t('greenzero'), + 'purplezero'=>t('purplezero'), + 'easterbunny'=>t('easterbunny'), + 'darkzero'=>t('darkzero'), + 'comix'=>t('comix'), + 'slackr'=>t('slackr'), + ); + +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. +The selected 1st part will be saved in the database by the theme_post function. + + function theme_post(&$a){ + // non local users shall not pass + if(! local_user()) + return; + // if the one specific submit button was pressed then proceed + if (isset($_POST['duepuntozero-settings-submit'])){ + // and save the selection key into the personal config of the user + set_pconfig(local_user(), 'duepuntozero', 'colorset', $_POST['duepuntozero_colorset']); + } + } + +Now that this information is set in the databes, what should friendica do with it? +For this, have a look at the theme.php file of the theme. +There you'll find somethink alike + + $colorset = get_pconfig( local_user(), 'duepuntozero','colorset'); + if (!$colorset) + $colorset = get_config('duepuntozero', 'colorset'); + if ($colorset) { + if ($colorset == 'greenzero') + $a->page['htmlhead'] .= ''."\n"; + /* some more variants */ + } + +so you'll just need to add a if selection, fitting your variant keyword and link to the CSS file of it. + +Done. +Now you can use the variant on your system. +But remember once the theme.php or the config.php you have to readd your variant to them. + +*More of less the same procedure works for the vier theme.* + +### Inheritation + +Say, you like the duepuntozero but you want to have the content of the outer columns left and right exchanged. +That would be not a color variation as shown above. +Instead we will create a new theme, duepuntozero_lr, inherit the properties of duepuntozero and make small changes to the underlying php files. + +So create a directory called duepunto_lr and create a file called theme.php with your favorite text editor. +The content of this file should be something like + + theme_info = array( + 'extends' => 'duepuntozero'. + ); + set_template_engine($a, 'smarty3'); + /* and more stuff e.g. the JavaScript function for the header */ + } + +Next take the default.php file found in the /view direcotry and exchange the aside and right_aside elements. +So the central part of the file now looks like this: + + + + +
+
+
+ +
+ + +Finally we need a style.css file, inheriting the definitions from the parent theme and containing out changes for the new theme. + + @import url('../duepuntozero/style.css'); + +Done. +But I agree it is not really useful at this state. +Nevertheless, to use it, you just neet to activate in the admin panel. +That done, you can select it in the settings like any other activated theme. + +## Creating a Theme from Scratch + +Keep patient. +Basically what you have to do is identifying which template you have to change so it looks more like what you want. +Adopt the CSS of the theme accordingly. +And iterate the process until you have the theme the way you want it. + +## Special Files + +### unsupported + +If a file (which might be empty) exists in the theme directory, the theme is marked as *unsupported*. +An unsupported theme may not be selected by a user in the settings. +Users who are already using it wont notice anything. + +### README(.md) + +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. + +This file should contain information you want to let others know about your theme. + +### screenshot.[png|jpg] + +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. +Supported formats are PNG and JPEG. + +### theme.php + +This is the main definition file of the theme. +In the header of that file, some meta information are stored. +For example, have a look at the theme.php of the *quattro* theme: + + + * Maintainer: Fabio + * Maintainer: Tobias + */ + +You see the definition of the themes name, it's version and the initial author of the theme. +These three information should be listed. +If the original author is not anymore working on the theme, but a maintainer has taken over, the maintainer should be listed as well. +The information from the theme header will be displayed in the admin panelö. + +Next crucial part of the theme.php file is a definition of an init function. +The name of the function is _init. +So in the case of quattro it is + + function quattro_init(&$a) { + $a->theme_info = array(); + set_template_engine($a, 'smarty3'); + } + +Here we have set the basic theme information, in this case they are empthy. +But the array needs to be set. +And we have set the template engine that should be used by friendica for this theme. +At the moment you should use the *smarty3* engine. +There once was a friendica specific templating engine as well but that is not used anymore. +If you like to use another templating engine, please implement it. + +When you want to inherit stuff from another theme you have to *announce* this in the theme_info: + + $a->theme_info = array( + 'extends' => 'duepuntozero', + ); + +which declares *duepuntozero* as parent of the theme. + +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. +To do so, add something alike + + $a->page['htmlhead'] .= <<< EOT + /* stuff you want to add to the header */ + EOT; + +The $a variable holds the friendica application. +So you can access the properties of this friendica session from the theme.php file as well. + +### default.php + +This file covers the structure of the underlying HTML layout. +The default file is in + + /view/default.php + +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. \ No newline at end of file