From 650aa089d90f90462443dfae16ccf19a00fb2890 Mon Sep 17 00:00:00 2001 From: foss- Date: Wed, 13 Mar 2024 12:17:27 +0100 Subject: [PATCH] Re-wrote themes.md - rewrite to reflect new default theme frio and describe settings options - old information was obsolete and replaced (please double check) --- doc/themes.md | 151 ++------------------------------------------------ 1 file changed, 4 insertions(+), 147 deletions(-) diff --git a/doc/themes.md b/doc/themes.md index 8d85dce2a9..5804868836 100644 --- a/doc/themes.md +++ b/doc/themes.md @@ -2,153 +2,10 @@ * [Home](help) -To change the look of friendica you have to touch the themes. -The current default theme is [Vier](https://github.com/friendica/friendica/tree/stable/view/theme/vier) but there are numerous others. -Have a look at [github.com/bkil/friendica-themes](https://github.com/bkil/friendica-themes) for an overview of the existing themes. -In case none of them suits your needs, there are several ways to change a theme. +The default Theme in Friendica is called [frio](https://github.com/friendica/friendica/tree/stable/view/theme/frio). -So, how to work on the UI of friendica. +Open `Settings > Display > Custom Theme Settings` adjust the Theme to your liking. Select your preferred Appearance - light, dark or black - and your favorite Accent color. Click `Submit` to save your changes. -You can either directly edit an existing theme. -But you might loose your changes when the theme is updated by the friendica team. +The `Custom` Appearance allows to tweak the themes CSS and set colors for UI elements. So called `schemestrings` can be shared between users. -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. -The below 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 *vier* and *vier* are using this methods for variations. -Quattro is using a slightly different approach. - -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/**your-theme-name**/style.css - -sometimes, there is also a file called style.php in the theme directory. -This is only needed if the theme allows the user to change certain things of the theme dynamically. -Say the font size or set a background image. - -### Templates - -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/**your-theme-name**/templates - -any template that exists there will be used instead of the default one. - -### JavaScript - -The same rule applies to the JavaScript files found in - - /js - -they will be overwritten by files in - - /view/theme/**your-theme-name**/js. - -## Creating a Theme from Scratch - -Keep patient. -Basically what you have to do is identify 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. - -*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). - -## Special Files - -### unsupported - -If a file with this name (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 is stored. -For example, have a look at the theme.php of the *vier* theme: - - - * Author: Ike - * Author: Beanow - * Maintainer: Ike - * Description: "Vier" is a very compact and modern theme. It uses the font awesome font library: http://fortawesome.github.com/Font-Awesome/ - */ - -You see the definition of the theme's name, it's version and the initial author of the theme. -These three pieces of information should be listed. -If the original author is no longer 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. - -The first thing in file is to import the `App` class from `\Friendica\` namespace. - - use Friendica\App; - -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. - -The 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 vier it is - - function vier_init(App $a) { - $a->theme_info = array(); - $a->set_template_engine('smarty3'); - } - -Here we have set the basic theme information, in this case they are empty. -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. - -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 - - DI::page()['htmlhead'] .= <<< EOT - /* stuff you want to add to the header */ - EOT; - -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. -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. +In the `General Theme Settings` you can also find the [vier](https://github.com/friendica/friendica/tree/stable/view/theme/vier) Theme, which precedes frio and is no longer officially maintained.