|
|
@@ -1,4 +1,281 @@
|
|
|
.. _theming:
|
|
|
|
|
|
-Theming (WIP)
|
|
|
-=============
|
|
|
+Theming
|
|
|
+=======
|
|
|
+
|
|
|
+FlaskBB uses the `Flask-Themes2`_ extension for theming.
|
|
|
+
|
|
|
+
|
|
|
+Getting Started
|
|
|
+---------------
|
|
|
+
|
|
|
+A theme is simply a folder containing static media (like CSS files, images,
|
|
|
+and JavaScript) and Jinja2 templates, with some metadata.
|
|
|
+A theme folder should look something like this::
|
|
|
+
|
|
|
+ my_theme
|
|
|
+ ├── info.json
|
|
|
+ ├── LICENSE
|
|
|
+ ├── static
|
|
|
+ │ └── style.css
|
|
|
+ └── templates
|
|
|
+ └── layout.html
|
|
|
+
|
|
|
+Every theme needs to have a file called **info.json**. The info.json file
|
|
|
+contains the theme’s metadata, so that the application can provide a nice
|
|
|
+switching interface if necessary. For example, the info.json file for the
|
|
|
+aurora theme looks like this:
|
|
|
+
|
|
|
+.. sourcecode:: json
|
|
|
+
|
|
|
+ {
|
|
|
+ "application": "flaskbb",
|
|
|
+ "identifier": "aurora",
|
|
|
+ "name": "Aurora",
|
|
|
+ "author": "Peter Justin",
|
|
|
+ "license": "BSD 3-Clause",
|
|
|
+ "website": "https://flaskbb.org",
|
|
|
+ "description": "The default theme for FlaskBB.",
|
|
|
+ "preview": "preview.png",
|
|
|
+ "version": "1.0.0"
|
|
|
+ }
|
|
|
+
|
|
|
+Field Explanation
|
|
|
+~~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+**application**
|
|
|
+ The name of the application, in our case this should always be **flaskbb**.
|
|
|
+
|
|
|
+**identifier**
|
|
|
+ The unique name of your theme. This identifier should match the themes
|
|
|
+ folder name!
|
|
|
+
|
|
|
+**name**
|
|
|
+ Human readable name of the theme.
|
|
|
+
|
|
|
+**author**
|
|
|
+ The name of the author.
|
|
|
+
|
|
|
+**license**
|
|
|
+ A short phrase describing the license, like "GPL", "BSD", "Public Domain",
|
|
|
+ or "Creative Commons BY-SA 3.0". Every theme should define a license
|
|
|
+ under which terms the theme can be used. You should also put a copy
|
|
|
+ of the license in your themes directory (e.g. in a LICENSE file).
|
|
|
+
|
|
|
+**description**
|
|
|
+ A short description about your theme.
|
|
|
+ For example: "A minimalistic blue theme".
|
|
|
+
|
|
|
+**website**
|
|
|
+ The URL of the theme’s Web site. This can be a Web site specifically
|
|
|
+ for this theme, Web site for a collection of themes that includes
|
|
|
+ this theme, or just the author’s Web site.
|
|
|
+
|
|
|
+**preview**
|
|
|
+ The theme's preview image, within the static folder.
|
|
|
+
|
|
|
+**version**
|
|
|
+ The version of the theme.
|
|
|
+
|
|
|
+
|
|
|
+Templates
|
|
|
+~~~~~~~~~
|
|
|
+
|
|
|
+`Flask`_ and therefore also FlaskBB uses the `Jinja2`_ template engine,
|
|
|
+so you should read `its documentation <http://jinja.pocoo.org/docs/templates>`_
|
|
|
+to learn about the actual syntax of the templates.
|
|
|
+
|
|
|
+All templates are by default loaded from FlaskBB's ``templates/`` folder. In
|
|
|
+order to create your theme, you have to create a ``templates/`` folder in your
|
|
|
+themes directory and preferably copy the ``layout.html`` file from FlaskBBs
|
|
|
+template folder over to yours. This ``layout.html`` file is your starting
|
|
|
+point. Every template is will extend it. If you want to overwrite other
|
|
|
+templates, just copy them over from the templates folder and modify them
|
|
|
+to your liking.
|
|
|
+
|
|
|
+Each template loaded will have a global function named `theme`
|
|
|
+available to look up the theme's templates. For example, if you want to
|
|
|
+extend, import, or include another template from your theme, you can use
|
|
|
+``theme(template_name)``, like this:
|
|
|
+
|
|
|
+.. sourcecode:: html+jinja
|
|
|
+
|
|
|
+ {% extends theme('layout.html') %}
|
|
|
+ {% from theme('macros.html') import horizontal_field %}
|
|
|
+
|
|
|
+.. note::
|
|
|
+
|
|
|
+ If the template you requested **doesn't** exist within the theme, it will
|
|
|
+ **fallback** to using the application's template.
|
|
|
+
|
|
|
+If you pass `false` as the second parameter, it will only return the theme's template.
|
|
|
+
|
|
|
+.. sourcecode:: html+jinja
|
|
|
+
|
|
|
+ {# This template, for example, does not exist in FlaskBB #}
|
|
|
+ {% include theme('header.html', false) %}
|
|
|
+
|
|
|
+You can also explicitly import/include templates from FlaskBB. Just use the
|
|
|
+tag without calling `theme`.
|
|
|
+
|
|
|
+.. sourcecode:: html+jinja
|
|
|
+
|
|
|
+ {% from 'macros.html' import topnav %}
|
|
|
+
|
|
|
+You can also get the URL for the theme's media files with the `theme_static`
|
|
|
+function:
|
|
|
+
|
|
|
+.. sourcecode:: html+jinja
|
|
|
+
|
|
|
+ <link rel=stylesheet href="{{ theme_static('style.css') }}">
|
|
|
+
|
|
|
+To include the static files that FlaskBB ships with, you just use
|
|
|
+the usual way of including them:
|
|
|
+
|
|
|
+.. sourcecode:: html+jinja
|
|
|
+
|
|
|
+ <link rel="stylesheet" href="{{ url_for('static', filename='css/pygments.css') }}">
|
|
|
+
|
|
|
+If you want to get information about the currently active theme, you can do
|
|
|
+that with the `theme_get_info` function:
|
|
|
+
|
|
|
+.. sourcecode:: html+jinja
|
|
|
+
|
|
|
+ This theme is <a href="{{ theme_get_info('website'}}">
|
|
|
+ <b>{{ theme_get_info('name') }}</b>
|
|
|
+ </a>
|
|
|
+
|
|
|
+
|
|
|
+Advanced Example
|
|
|
+-----------------
|
|
|
+
|
|
|
+A more advanced example is our own default theme called **Aurora**. It does
|
|
|
+not provide an ``layout.html`` because I want to avoid code duplication (and
|
|
|
+it is easier to maintain as well). For your own theme, please copy the
|
|
|
+``layout.html`` from FlaskBB's templates fodler into your themes templates
|
|
|
+folder.
|
|
|
+
|
|
|
+
|
|
|
+Prerequisites
|
|
|
+~~~~~~~~~~~~~
|
|
|
+
|
|
|
+To use the same build tools, which we also use to develop the Aurora theme,
|
|
|
+you have to make sure that you have npm installed. You can install npm by
|
|
|
+following the official
|
|
|
+`installation guide <https://docs.npmjs.com/getting-started/installing-node>`_.
|
|
|
+
|
|
|
+The theme also uses `SASS <https://sass-lang.com/libsass>`_,
|
|
|
+a CSS preprocessor, to make development easier. If you are not familar with
|
|
|
+SASS and want to use SASS (which I really recommend), follow this basic
|
|
|
+`guide <http://sass-lang.com/guide>`__ to get a basic understanding of it.
|
|
|
+
|
|
|
+As explained in `Field Explanation <#field-explanation>`_, each theme must
|
|
|
+have a unique theme **identifier** - so open up ``info.json`` (from your
|
|
|
+themes folder) with your favorite editor and adjust all the fields properly.
|
|
|
+
|
|
|
+Next, do the same thing for the ``package.json`` file (this one is used by
|
|
|
+npm to install some libraries like Bootstrap). A detailed explanation about
|
|
|
+all the fields is available from `package.json documentation page`_.
|
|
|
+
|
|
|
+To install the stated requirements in ``package.json`` like, Bootstrap,
|
|
|
+JQuery and some other libraries just run the ``npm install`` command in the directory where the ``package.json`` file lies. Now you have set up the
|
|
|
+toolchain which is used for the Aurora theme.
|
|
|
+
|
|
|
+
|
|
|
+Toolchain Commands
|
|
|
+~~~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+For the build, minify, etc. process we use npm's task runner. Just hit up
|
|
|
+``npm run`` to get a list with all available commands. Following commands are
|
|
|
+used::
|
|
|
+
|
|
|
+ Usage
|
|
|
+ npm run [TASK]
|
|
|
+
|
|
|
+ Available tasks
|
|
|
+ clean
|
|
|
+ rm -f node_modules
|
|
|
+ autoprefixer
|
|
|
+ postcss -u autoprefixer -r static/css/*
|
|
|
+ scss
|
|
|
+ ./tools/build_css
|
|
|
+ uglify
|
|
|
+ ./tools/build_js
|
|
|
+ imagemin
|
|
|
+ imagemin src/img/* -o static/img
|
|
|
+ fonts
|
|
|
+ ./tools/build_fonts
|
|
|
+ build:css
|
|
|
+ npm run scss && npm run autoprefixer
|
|
|
+ build:js
|
|
|
+ npm run uglify
|
|
|
+ build:images
|
|
|
+ npm run imagemin && npm run fonts
|
|
|
+ build:all
|
|
|
+ npm run build:css && npm run build:js && npm run build:images
|
|
|
+ watch:css
|
|
|
+ onchange 'src/scss' -- npm run build:css
|
|
|
+ watch:js
|
|
|
+ onchange 'src/js' -- npm run build:js
|
|
|
+ watch:all
|
|
|
+ npm-run-all -p watch:css watch:js
|
|
|
+
|
|
|
+
|
|
|
+For example, to watch for changes in our JS and SCSS files,
|
|
|
+you just have to run::
|
|
|
+
|
|
|
+ npm run watch:all
|
|
|
+
|
|
|
+and upon changes it will automatically rebuild the files.
|
|
|
+
|
|
|
+
|
|
|
+TL;DR
|
|
|
+-----
|
|
|
+
|
|
|
+1. Create a new folder within the ``themes/`` folder and give it the name
|
|
|
+ of your theme.
|
|
|
+2. Copy the content of the ``aurora/`` folder into your folder theme's folder.
|
|
|
+3. Create **2** new folders called ``static/`` and ``templates`` in your
|
|
|
+ themes folder.
|
|
|
+4. Copy ``layout.html`` from FlaskBB's ``templates/`` into your themes
|
|
|
+ ``templates/`` folder and modified to your liking. Feel free to copy
|
|
|
+ other templates over into your themes. Just make sure that they have the
|
|
|
+ same name and directory structure to overwrite them.
|
|
|
+5. Add some information about your theme using the ``info.json`` file.
|
|
|
+6. Edit the ``package.json`` to your needs.
|
|
|
+7. Happy theming!
|
|
|
+
|
|
|
+In the end your folder structure should look like this::
|
|
|
+
|
|
|
+ ── example_theme/
|
|
|
+ ├── node_modules
|
|
|
+ │ └── ...
|
|
|
+ ├── src
|
|
|
+ │ ├── img
|
|
|
+ │ │ └── ...
|
|
|
+ │ ├── js
|
|
|
+ │ │ └── ...
|
|
|
+ │ └── scss
|
|
|
+ │ └── ...
|
|
|
+ ├── static
|
|
|
+ │ ├── img
|
|
|
+ │ ├── css
|
|
|
+ │ ├── fonts
|
|
|
+ │ └── js
|
|
|
+ ├── templates
|
|
|
+ │ ├── ...
|
|
|
+ │ └── layout.html
|
|
|
+ ├── tools
|
|
|
+ │ ├── build_css
|
|
|
+ │ ├── build_fonts
|
|
|
+ │ └── build_js
|
|
|
+ ├── info.json
|
|
|
+ ├── LICENSE
|
|
|
+ ├── package.json
|
|
|
+ └── README.md
|
|
|
+
|
|
|
+
|
|
|
+.. _Jinja2: http://jinja.pocoo.org/
|
|
|
+.. _Flask: http://flask.pocoo.org/
|
|
|
+.. _Flask-Themes2: https://flask-themes2.readthedocs.io/en/latest/
|
|
|
+.. _package.json documentation page: https://docs.npmjs.com/files/package.json
|
sh4nks