Welcome to FlaskBB¶

FlaskBB is a classic forum software in a modern and fresh look. It is written in Python using the web framework Flask. FlaskBB is being distributed under the BSD 3-Clause License.

Links¶

website | documentation | source code

User Documentation¶

Installation¶

Basic Setup
Configuration
Deploying
Deploying to PythonAnywhere

Basic Setup¶

We recommend installing FlaskBB in an isolated Python environment. This can be achieved with virtualenv. In our little guide we will use a wrapper around virtualenv - the virtualenvwrapper. In addition to virtualenv, we will also use the package manager pip to install the dependencies for FlaskBB.

Virtualenv Setup¶

Linux: The easiest way to install virtualenv and virtualenvwrapper is, to use the package manager on your system (if you are running Linux) to install them.

Windows: Take a look at the flask documentation (then skip ahead to dependencies).

For example, on archlinux you can install them with:

$ sudo pacman -S python2-virtualenvwrapper

or, on macOS, you can install them with:

$ sudo pip install virtualenvwrapper

It’s sufficient to just install the virtualenvwrapper because it depends on virtualenv and the package manager will resolve all the dependencies for you.

After that, you can create your virtualenv with:

$ mkvirtualenv -a /path/to/flaskbb -p $(which python2) flaskbb

This will create a virtualenv named flaskbb using the python interpreter in version 2 and it will set your project directory to /path/to/flaskbb. This comes handy when typing workon flaskbb as it will change your current directory automatically to /path/to/flaskbb. To deactivate it you just have to type deactivate and if you want to work on it again, just type workon flaskbb.

It is also possible to use virtualenv without the virtualenvwrapper. For this you have to use the virtualenv command and pass the name of the virtualenv as an argument. In our example, the name of the virtualenv is .venv.

$ virtualenv .venv

and finally activate it

$ source .venv/bin/activate

If you want to know more about those isolated python environments, checkout the virtualenv and virtualenvwrapper docs.

Dependencies¶

Now that you have set up your environment, you are ready to install the dependencies.

$ pip install -r requirements.txt

Alternatively, you can use the make command to install the dependencies.

$ make dependencies

The development process requires a few extra dependencies which can be installed with the provided requirements-dev.txt file.

$ pip install -r requirements-dev.txt

Optional Dependencies¶

We have one optional dependency, redis (the python package is installed automatically). If you want to use it, make sure that a redis-server is running. Redis will be used as the default result and caching backend for celery (celery is a task queue which FlaskBB uses to send non blocking emails). The feature for tracking the online guests and online users do also require redis (although online users works without redis as well). To install redis, just use your distributions package manager. For Arch Linux this is pacman and for Debian/Ubuntu based systems this is apt-get.

# Installing redis using 'pacman':
$ sudo pacman -S redis
# Installing redis using 'apt-get':
$ sudo apt-get install redis-server

# Check if redis is already running.
$ systemctl status redis

# If not, start it.
$ sudo systemctl start redis

# Optional: Lets start redis everytime you boot your machine
$ sudo systemctl enable redis

Configuration¶

Production¶

FlaskBB already sets some sane defaults, so you shouldn’t have to change much. To make this whole process a little bit easier for you, we have created a little wizard which will ask you some questions and with the answers you provide it will generate a configuration for you. You can of course further adjust the generated configuration.

The setup wizard can be started with:

flaskbb makeconfig

These are the only settings you have to make sure to setup accordingly if you want to run FlaskBB in production:

SERVER_NAME = "example.org"
PREFERRED_URL_SCHEME = "https"
SQLALCHEMY_DATABASE_URI = 'sqlite:///path/to/flaskbb.sqlite'
SECRET_KEY = "secret key"
WTF_CSRF_SECRET_KEY = "secret key"

By default it will try to save the configuration file with the name flaskbb.cfg in FlaskBB’s root folder.

Finally to get going – fire up FlaskBB!

flaskbb --config flaskbb.cfg run

[+] Using config from: /path/to/flaskbb/flaskbb.cfg
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Development¶

To get started with development you have to generate a development configuration first. You can use the CLI for this, as explained in Configuration:

flaskbb makeconfig -d

flaskbb makeconfig –development

Now you can either use make to run the development server:

make run

or if you like to type a little bit more, the CLI:

flaskbb --config flaskbb.cfg run

You can either pass an import string to the path to the (python) config file you’ve just created, or a default config object. (Most users will follow the example above, which uses the generated file). This is how you do it by using an import string. Be sure that it is importable from within FlaskBB:

flaskbb –config flaskbb.configs.default.DefaultConfig run

Redis¶

If you have decided to use redis as well, which we highly recommend, then the following services and features can be enabled and configured to use redis.

Before you can start using redis, you have to enable and configure it. This is quite easy just set REDIS_ENABLE to True and adjust the REDIS_URL if needed.

REDIS_ENABLED = True
REDIS_URL = "redis://localhost:6379"  # or with a password: "redis://:password@localhost:6379"
REDIS_DATABASE = 0

The other services are already configured to use the REDIS_URL configuration variable.

Celery

CELERY_BROKER_URL = REDIS_URL
CELERY_RESULT_BACKEND = REDIS_URL

Caching

CACHE_TYPE = "redis"
CACHE_REDIS_URL = REDIS_URL

Rate Limiting

RATELIMIT_ENABLED = True
RATELIMIT_STORAGE_URL = REDIS_URL

Mail Examples¶

Both methods are included in the example configs.

Google Mail

MAIL_SERVER = "smtp.gmail.com"
MAIL_PORT = 465
MAIL_USE_SSL = True
MAIL_USERNAME = "your_username@gmail.com"
MAIL_PASSWORD = "your_password"
MAIL_DEFAULT_SENDER = ("Your Name", "your_username@gmail.com")

Local SMTP Server

MAIL_SERVER = "localhost"
MAIL_PORT = 25
MAIL_USE_SSL = False
MAIL_USERNAME = ""
MAIL_PASSWORD = ""
MAIL_DEFAULT_SENDER = "noreply@example.org"

Installation¶

MySQL users: Make sure that you create the database using the utf8 charset:

CREATE DATABASE flaskbb CHARACTER SET utf8;

Even though the utf8mb4 charset is prefered today (see this SO answer), we have to create our database using the utf8 charset. A good explanation about this issue can be found here.

For a guided install, run:

$ make install

or:

flaskbb install

During the installation process you are asked about your username, your email address and the password for your administrator user. Using the make install command is recommended as it checks that the dependencies are also installed.

Upgrading¶

If the database models changed after a release, you have to run the upgrade command:

flaskbb db upgrade

Deploying¶

This chapter will describe how to set up Supervisor + uWSGI + nginx for FlaskBB as well as document how to use the built-in WSGI server (gunicorn) that can be used in a productive environment.

Supervisor¶

Supervisor is a client/server system that allows its users to monitor and control a number of processes on UNIX-like operating systems.

To install supervisor on Debian, you need to fire up this command:

$ sudo apt-get install supervisor

There are two ways to configure supervisor. The first one is, you just put the configuration to the end in the /etc/supervisor/supervisord.conf file.

The second way would be to create a new file in the /etc/supervisor/conf.d/ directory. For example, such a file could be named uwsgi.conf.

After you have choosen the you way you like, simply put the snippet below in the configuration file.

[program:uwsgi]
command=/usr/bin/uwsgi --emperor /etc/uwsgi/apps-enabled
user=apps
stopsignal=QUIT
autostart=true
autorestart=true
redirect_stderr=true

uWSGI¶

uWSGI is a web application solution with batteries included.

To get started with uWSGI, you need to install it first. You’ll also need the python plugin to serve python apps. This can be done with:

$ sudo apt-get install uwsgi uwsgi-plugin-python

For the configuration, you need to create a file in the /etc/uwsgi/apps-available directory. In this example, I will call the file flaskbb.ini. After that, you can start with configuring it. My config looks like this for flaskbb.org (see below). As you might have noticed, I’m using a own user for my apps whose home directory is located at /var/apps/. In this directory there are living all my Flask apps.

[uwsgi]
base = /var/apps/flaskbb
home = /var/apps/.virtualenvs/flaskbb/
pythonpath = %(base)
socket = 127.0.0.1:30002
module = wsgi
callable = flaskbb
uid = apps
gid = apps
logto = /var/apps/flaskbb/logs/uwsgi.log
plugins = python

base	/path/to/flaskbb	The folder where your flaskbb application lives
home	/path/to/virtualenv/folder	The virtualenv folder for your flaskbb application
pythonpath	/path/to/flaskbb	The same as base
socket	socket	This can be either a ip or the path to a socket (don’t forget to change that in your nginx config)
module	wsgi.py	This is the file located in the root directory from flaskbb (where manage.py lives).
callable	flaskbb	The callable is application you have created in the `wsgi.py` file
uid	your_user	The user who should be used. NEVER use root!
gid	your_group	The group who should be used.
logto	/path/to/log/file	The path to your uwsgi logfile
plugins	python	We need the python plugin

Don’t forget to create a symlink to /etc/uwsgi/apps-enabled.

ln -s /etc/uwsgi/apps-available/flaskbb /etc/uwsgi/apps-enabled/flaskbb

gunicorn¶

Gunicorn ‘Green Unicorn’ is a Python WSGI HTTP Server for UNIX.

It’s a pre-fork worker model ported from Ruby’s Unicorn project. The Gunicorn server is broadly compatible with various web frameworks, simply implemented, light on server resources, and fairly speedy.

This is probably the easiest way to run a FlaskBB instance. Just install gunicorn via pip inside your virtualenv:

pip install gunicorn

FlaskBB has an built-in command to gunicorn:

flaskbb start

To see a full list of options either type flaskbb start --help or visit the cli docs.

nginx¶

nginx [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev.

The nginx config is pretty straightforward. Again, this is how I use it for FlaskBB. Just copy the snippet below and paste it to, for example /etc/nginx/sites-available/flaskbb. The only thing left is, that you need to adjust the server_name to your domain and the paths in access_log, error_log. Also, don’t forget to adjust the paths in the alias es, as well as the socket address in uwsgi_pass.

server {
    listen 80;
    server_name forums.flaskbb.org;

    access_log /var/log/nginx/access.forums.flaskbb.log;
    error_log /var/log/nginx/error.forums.flaskbb.log;

    location / {
        try_files $uri @flaskbb;
    }

    # Static files
    location /static {
       alias /var/apps/flaskbb/flaskbb/static/;
    }

    location ~ ^/_themes/([^/]+)/(.*)$ {
        alias /var/apps/flaskbb/flaskbb/themes/$1/static/$2;
    }

    # robots.txt
    location /robots.txt {
        alias /var/apps/flaskbb/flaskbb/static/robots.txt;
    }

    location @flaskbb {
        uwsgi_pass 127.0.0.1:30002;
        include uwsgi_params;
    }
}

If you wish to use gunicorn instead of uwsgi just replace the location @flaskbb with this:

location @flaskbb {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    #proxy_set_header SCRIPT_NAME /forums;  # This line will make flaskbb available on /forums;
    proxy_redirect off;
    proxy_buffering off;

    proxy_pass http://127.0.0.1:8000;
}

Don’t forget to adjust the proxy_pass address to your socket address.

Like in the uWSGI chapter, don’t forget to create a symlink to /etc/nginx/sites-enabled/.

User Contributed Deployment Guides¶

We do not maintain these deployment guides. They have been submitted by users and we thought it is nice to include them in docs. If something is missing, or doesn’t work - please open a new pull request on GitHub.

Deploying to PythonAnywhere¶

PythonAnywhere is a platform-as-a-service, which basically means they have a bunch of servers pre-configured with Python, nginx and uWSGI. You can run a low-traffic website with them for free, so it’s an easy way to get quickly FlaskBB running publicly.

Here’s what to do:

Sign up for a PythonAnywhere account at https://www.pythonanywhere.com/.
On the “Consoles” tab, start a Bash console and install/configure FlaskBB like this

git clone https://github.com/sh4nks/flaskbb.git
cd flaskbb
pip3.5 install --user -r requirements.txt
pip3.5 install --user -e .
flaskbb makeconfig
flaskbb install

Click the PythonAnywhere logo to go back to the dashboard, then go to the “Web” tab, and click the “Add a new web app” button.
Just click “Next” on the first page.
On the next page, click “Flask”
On the next page, click “Python 3.5”
On the next page, just accept the default and click next
Wait while the website is created.
Click on the “Source code” link, and in the input that appears, replace the mysite at the end with flaskbb
Click on the “WSGI configuration file” filename, and wait for an editor to load.
Change the line that sets project_home to replace mysite with flaskbb again.
Change the line that says

from flask_app import app as application

to say

from flaskbb import create_app
application = create_app("/path/to/your/configuration/file")

Click the green “Save” button near the top right.
Go back to the “Web” tab.
Click the green “Reload…” button.
Click the link to visit the site – you’ll have a new FlaskBB install!

Command Line Interface¶

Here you can find the documentation about FlaskBB’s Command Line Interface.

To get help for a commands, just type flaskbb COMMAND --help. If no command options or arguments are used it will display all available commands.

Usage: flaskbb [OPTIONS] COMMAND [ARGS]...

  This is the commandline interface for flaskbb.

Options:
  --config CONFIG  Specify the config to use in dotted module notation e.g.
                   flaskbb.configs.default.DefaultConfig
  --version        Show the FlaskBB version.
  --help           Show this message and exit.

Commands:
  celery           Preconfigured wrapper around the 'celery' command.
  db               Perform database migrations.
  download-emojis  Downloads emojis from emoji-cheat-sheet.com.
  install          Installs flaskbb.
  makeconfig       Generates a FlaskBB configuration file.
  plugins          Plugins command sub group.
  populate         Creates the necessary tables and groups for FlaskBB.
  reindex          Reindexes the search index.
  run              Runs a development server.
  shell            Runs a shell in the app context.
  start            Starts a production ready wsgi server.
  themes           Themes command sub group.
  translations     Translations command sub group.
  upgrade          Updates the migrations and fixtures.
  urls             Show routes for the app.
  users            Create, update or delete users.

Commands¶

Here you will find a detailed description of every command including all of their options and arguments.

flaskbb install

Installs flaskbb. If no arguments are used, an interactive setup will be run.

--welcome, -w: Disables the generation of the welcome forum.

--force, -f: Doesn’t ask for confirmation if the database should be deleted or not.

--username USERNAME, -u USERNAME: The username of the user.

--email EMAIL, -e EMAIL: The email address of the user.

--password PASSWORD, -p PASSWORD: The password of the user.

--group GROUP, -g GROUP: The primary group of the user. The group GROUP has to be one of admin, super_mod, mod or member.

flaskbb upgrade

Updates the migrations and fixtures.

--all, -a: Upgrades migrations AND fixtures to the latest version.

--fixture FIXTURE, -f FIXTURE: The fixture which should be upgraded or installed. All fixtures have to be places inside flaskbb/fixtures/

--force-fixture, -ff: Forcefully upgrades the fixtures. WARNING: This will also overwrite any settings.

flaskbb populate

Creates the necessary tables and groups for FlaskBB.

--test-data, -t: Adds some test data.

--bulk-data, -b: Adds a lot of test data. Has to be used in combination with --posts and --topics.

--posts: Number of posts to create in each topic (default: 100).

--topics: Number of topics to create (default: 100).

--force, -f: Will delete the database without asking before populating it.

--initdb, -i: Initializes the database before populating it.

flaskbb runserver: Starts the development server

flaskbb start

Starts a production ready wsgi server. Other versions of starting FlaskBB are still supported!

--server SERVER, -s SERVER

Defaults to gunicorn. The following WSGI Servers are supported:

gunicorn (default)
gevent

--host HOST, -h HOST: The interface to bind FlaskBB to. Defaults to 127.0.0.1.

--port PORT, -p PORT: The port to bind FlaskBB to. Defaults to 8000.

--workers WORKERS, -w WORKERS: The number of worker processes for handling requests. Defaults to 4.

--daemon, -d: Starts gunicorn in daemon mode.

--config, -c: The configuration file to use for the FlaskBB WSGI Application.

flaskbb celery CELERY_ARGS

Starts celery. This is just a preconfigured wrapper around the celery command. Additional arguments are directly passed to celery.

--help-celery: Shows the celery help message.

flaskbb shell: Creates a python shell with an app context.

flaskbb urls

Lists all available routes.

--route, -r: Order by route.

--endpoint, -e: Order by endpoint

--methods, -m: Order by methods

flaskbb makeconfig

Generates a FlaskBB configuration file.

--development, -d: Creates a development config with DEBUG set to True.

--output, -o: The path where the config file will be saved at. Defaults to the flaskbb’s root folder.

--force, -f: Overwrites any existing config file, if one exsits, WITHOUT asking.

flaskbb reindex: Reindexes the search index.

flaskbb translations

Translations command sub group.

new LANGUAGE_CODE

Adds a new language to FlaskBB’s translations. The LANGUAGE_CODE is the short identifier for the language i.e. ‘en’, ‘de’, ‘de_AT’, etc.

--plugin PLUGIN_NAME, --p PLUGIN_NAME: Adds a new language to a plugin.

update

Updates the translations.

--all, -a: Updates all translations, including the ones from the plugins.

--plugin PLUGIN_NAME, --p PLUGIN_NAME: Update the language of the given plugin.

compile

Compiles the translations.

--all, -a: Compiles all translations, including the ones from the plugins.

--plugin PLUGIN_NAME, --p PLUGIN_NAME: Compiles only the given plugin translation.

flaskbb plugins

Plugins command sub group.

new PLUGIN_IDENTIFIER: Creates a new plugin based on the cookiecutter plugin template. Defaults to this template: https://github.com/sh4nks/cookiecutter-flaskbb-plugin. It will either accept a valid path on the filesystem or a URL to a Git repository which contains the cookiecutter template.

install PLUGIN_IDENTIFIER: Installs a plugin by using the plugin’s identifier.

uninstall PLUGIN_IDENTIFIER: Uninstalls a plugin by using the plugin’s identifier.

remove PLUGIN_IDENTIFIER

Removes a plugin from the filesystem by using the plugin’s identifier.

describe:: –force, -f

Removes the plugin without asking for confirmation first.

list: Lists all installed plugins.

flaskbb themes

Themes command sub group.

new THEME_IDENTIFIER: Creates a new theme based on the cookiecutter theme template. Defaults to this template: https://github.com/sh4nks/cookiecutter-flaskbb-theme. It will either accept a valid path on the filesystem or a URL to a Git repository which contains the cookiecutter template.

remove THEME_IDENTIFIER: Removes a theme from the filesystem by the theme’s identifier.

list: Lists all installed themes.

flaskbb users

Creates a new user. If an option is missing, you will be interactivly prompted to type it.

new

Creates a new user.

--username USERNAME, -u USERNAME: The username of the user.

--email EMAIL, -e EMAIL: The email address of the user.

--password PASSWORD, -p PASSWORD: The password of the user.

--group GROUP, -g GROUP: The primary group of the user. The group GROUP has to be one of admin, super_mod, mod or member.

update

Updates an user.

--username USERNAME, -u USERNAME: The username of the user.

--email EMAIL, -e EMAIL: The email address of the user.

--password PASSWORD, -p PASSWORD: The password of the user.

--group GROUP, -g GROUP: The primary group of the user. The group GROUP has to be one of admin, super_mod, mod or member.

delete

--username USERNAME, -u USERNAME: The username of the user.

--force, -f: Removes the user without asking for confirmation first.

Plugins¶

FlaskBB provides a full featured plugin system. This system allows you to easily extend or modify FlaskBB without touching any FlaskBB code. Under the hood it uses the pluggy plugin system which does most of the heavy lifting for us. A list of available plugins can be found at the GitHub Wiki. A proper index for FlaskBB Plugins and Themes still have to be built.

If you are interested in creating new plugins, checkout out the Developing new Plugins page.

Management¶

Before plugins can be used in FlaskBB, they have to be downloaded, installed and activated. Plugins can be very minimalistic with nothing to install at all (just enabling and disabling) to be very complex where you have to run migrations and add some additional settings.

Download¶

Downloading a Plugin is as easy as:

$ pip install flaskbb-plugin-MYPLUGIN

if the plugin has been uploaded to PyPI. If you haven’t uploaded your plugin to PyPI or are in the middle of developing one, you can just:

$ pip install -e .

in your plugin’s package directory to install it.

Remove¶

Removing a plugin is a little bit more tricky. By default, FlaskBB does not remove the settings of a plugin by itself because this could lead to some unwanted dataloss.

Disable and Uninstall the plugin first before continuing.

After taking care of this and you are confident that you won’t need the plugin anymore you can finally remove it:

$ pip uninstall flaskbb-plugin-MYPLUGIN

There is a setting in FlaskBB which lets you control the deletion of settings of a plugin. If REMOVE_DEAD_PLUGINS is set to True, all not available plugins (not available on the filesystem) are constantly removed. Only change this if you know what you are doing.

Install¶

In our context, by installing a plugin, we mean, to install the settings and apply the migrations. Personal Note: I can’t think of a better name and I am open for suggestions.

The plugin can be installed via the Admin Panel (in tab ‘Plugins’) or by running:

flaskbb plugins install <plugin_name>

Make sure to to apply the migrations of the plugin as well (if any, check the plugins docs):

flaskbb db upgrade <plugin_name>@head

Uninstall¶

Removing a plugin involves two steps. The first one is to check if the plugin has applied any migrations on FlaskBB and if so you can undo them via:

$ flaskbb db downgrade <plugin_name>@base

The second step is to wipe the settings from FlaskBB which can be done in the Admin Panel or by running:

$ flaskbb plugins uninstall <plugin_name>

Disable¶

Disabling a plugin has the benefit of keeping all the data of the plugin but not using the functionality it provides. A plugin can either be deactivated via the Admin Panel or by running:

flaskbb plugins disable <plugin_name>

Important

Restart the server.

You must restart the wsgi/in-built server in order to make the changes effect your forum.

Enable¶

All plugins are activated by default. To activate a deactivated plugin you either have to activate it via the Admin Panel again or by running the activation command:

flaskbb plugins enable <plugin_name>

Database¶

Upgrading, downgrading and generating database revisions is all handled via alembic. We make use of alembic’s branching feature to manage seperate migrations for the plugins. Each plugin will have it’s own branch in alembic where migrations can be managed. Following commands are used for generaring, upgrading and downgrading your plugins database migrations:

(Auto-)Generating revisions

flaskbb db revision --branch <plugin_name> "<YOUR_MESSAGE>"

Replace <YOUR_MESSAGE> with something like “initial migration” if it’s the first migration or with just a few words that will describe the changes of the revision.
Applying revisions

flaskbb db upgrade <plugin_name>@head

If you want to upgrade to specific revision, replace head with the revision id.
Downgrading revisions

flaskbb db downgrade <plugin_name>@-1

If you just want to revert the latest revision, just use -1. To downgrade all database migrations, use base.

FAQ - Frequently Asked Questions¶

Here we try to answer some common questions and pitfalls about FlaskBB.

Why do I get a AttributeError: 'NullTranslations' object has no attribute 'add' exception?

This usually happens when you forgot to compile the translations. To compile them, just run:
```
$ flaskbb translations compile
```
Relevant issue: #389
Why isn’t the cache (Flask-Caching) using the configured REDIS_URL?

You have to set the CACHE_REDIS_HOST to the REDIS_URL. This is inconvenience is caused because you are not limited to redis as the caching backend. See the Flask-Caching documentation for a full list of caching backends.

Relevant issue: #372

Developer Documentation¶

Theming¶

FlaskBB uses the Flask-Themes2 extension for theming.

Quickstart¶

Create a new folder within the themes/ folder and give it the name of your theme.
Copy the content of the aurora/ folder into your folder theme’s folder.
Create 2 new folders called static/ and templates/ in your themes folder.
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.
Add some information about your theme using the info.json file.
Edit the package.json to your needs.
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

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:

{
    "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 templating engine, so you should read its documentation 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 own theme, you have to create a templates/ folder in your themes directory and optionally also copy the layout.html file from FlaskBB’s template folder over to yours. This layout.html file is your starting point. Every template 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 loaded template 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:

{% 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.

{# 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.

{% from 'macros.html' import topnav %}

You can also get the URL for the theme’s media files with the theme_static function:

<link rel=stylesheet href="{{ theme_static('style.css') }}">

To include the static files that FlaskBB ships with, you just proceed as normal:

<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:

This theme is <a href="{{ theme_get_info('website'}}">
  <b>{{ theme_get_info('name') }}</b>
</a>

Advanced Example¶

A more advanced example of a theme, is our own default theme called Aurora. We do not have a layout.html file because we want to avoid code duplication and are just falling back to the one that FlaskBB ships with in its templates/ folder. In order to use your own stylesheets you have to create a layout.html file. It’s probably the easiest to just copy the layout.html from FlaskBB’s templates/ folder into your themes templates/ folder.

For example, the forums on FlaskBB are using a slightly modified version of the Aurora theme. It is available on GitHub here: Aurora Mod. The modified version just adds a top navigation and uses a different footer.

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.

The theme also uses SASS, a CSS preprocessor, to make development easier. If you are not familar with SASS but want to use it, which I can really recommend, follow this guide to get a basic understanding of it.

As explained in 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 file 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 just run the npm install command in the directory where the package.json file is located. 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.

Hooks¶

In FlaskBB we distinguish from Python Hooks and Template Hooks. Python Hooks are prefixed with flaskbb_ and called are called in Python files whereas Template Hooks have to be prefixed with flaskbb_tpl_ and are executed in the templates.

If you miss a hook, feel free to open a new issue or create a pull request. The pull request should always contain a entry in this document with a small example.

A hook needs a hook specification which are defined in flaskbb.plugins.spec. All hooks have to be prefixed with flaskbb_ and template hooks with flaskbb_tpl_.

Be sure to also check out the API documentation for interfaces that interact with these plugins in interesting ways.

Application Startup Hooks¶

Application startup hooks are called when the application is created, either through a WSGI server (uWSGI or gunicorn for example) or by the flaskbb command.

Unless noted, all FlaskBB hooks are called after the relevant builtin FlaskBB setup has run (e.g. flaskbb_load_blueprints is called after all standard FlaskBB blueprints have been loaded).

The hooks below are listed in the order they are called.

flaskbb.plugins.spec.flaskbb_extensions(app)¶: Hook for initializing any plugin loaded extensions.

flaskbb.plugins.spec.flaskbb_load_blueprints(app)¶

Hook for registering blueprints.

Parameters:	app – The application object.

flaskbb.plugins.spec.flaskbb_jinja_directives(app)¶

Hook for registering jinja filters, context processors, etc.

Parameters:	app – The application object.

flaskbb.plugins.spec.flaskbb_request_processors(app)¶

Hook for registering pre/post request processors.

Parameters:	app – The application object.

flaskbb.plugins.spec.flaskbb_errorhandlers(app)¶

Hook for registering error handlers.

Parameters:	app – The application object.

flaskbb.plugins.spec.flaskbb_load_migrations()¶: Hook for registering additional migrations.

flaskbb.plugins.spec.flaskbb_load_translations()¶: Hook for registering translation folders.

flaskbb.plugins.spec.flaskbb_load_post_markdown_class(app)¶

Hook for loading a mistune renderer child class in order to render markdown on posts and user signatures. All classes returned by this hook will be composed into a single class to render markdown for posts.

Since all classes will be composed together, child classes should call super as appropriate and not add any new arguments to __init__ since the class will be insantiated with predetermined arguments.

Example:

class YellingRenderer(mistune.Renderer):
    def paragraph(self, text):
        return super(YellingRenderer, self).paragraph(text.upper())

@impl
def flaskbb_load_post_markdown_class():
    return YellingRenderer

Parameters:	app (Flask) – The application object associated with the class if needed

flaskbb.plugins.spec.flaskbb_load_nonpost_markdown_class(app)¶

Hook for loading a mistune renderer child class in order to render markdown in locations other than posts, for example in category or forum descriptions. All classes returned by this hook will be composed into a single class to render markdown for nonpost content (e.g. forum and category descriptions).

Since all classes will be composed together, child classes should call super as appropriate and not add any new arguments to __init__ since the class will be insantiated with predetermined arguments.

Example:

class YellingRenderer(mistune.Renderer):
    def paragraph(self, text):
        return super(YellingRenderer, self).paragraph(text.upper())

@impl
def flaskbb_load_nonpost_markdown_class():
    return YellingRenderer

Parameters:	app (Flask) – The application object associated with the class if needed

flaskbb.plugins.spec.flaskbb_additional_setup(app, pluggy)¶

Hook for any additional setup a plugin wants to do after all other application setup has finished.

For example, you could apply a WSGI middleware:

@impl
def flaskbb_additional_setup(app):
    app.wsgi_app = ProxyFix(app.wsgi_app)

Parameters:	app – The application object. pluggy – The pluggy object.

FlaskBB CLI Hooks¶

These hooks are only invoked when using the flaskbb CLI.

flaskbb.plugins.spec.flaskbb_cli(cli, app)¶

Hook for registering CLI commands.

For example:

@impl
def flaskbb_cli(cli):
    @cli.command()
    def testplugin():
        click.echo("Hello Testplugin")

    return testplugin

Parameters:	app – The application object. cli – The FlaskBBGroup CLI object.

flaskbb.plugins.spec.flaskbb_shell_context()¶: Hook for registering shell context handlers Expected to return a single callable function that returns a dictionary or iterable of key value pairs.

FlaskBB Event Hooks¶

flaskbb.plugins.spec.flaskbb_event_post_save_before(post)¶

Hook for handling a post before it has been saved.

Parameters:	post (flaskbb.forum.models.Post) – The post which triggered the event.

flaskbb.plugins.spec.flaskbb_event_post_save_after(post, is_new)¶

Hook for handling a post after it has been saved.

Parameters:	post (flaskbb.forum.models.Post) – The post which triggered the event. is_new (bool) – True if the post is new, False if it is an edit.

flaskbb.plugins.spec.flaskbb_event_topic_save_before(topic)¶

Hook for handling a topic before it has been saved.

Parameters:	topic (flaskbb.forum.models.Topic) – The topic which triggered the event.

flaskbb.plugins.spec.flaskbb_event_topic_save_after(topic, is_new)¶

Hook for handling a topic after it has been saved.

Parameters:	topic (flaskbb.forum.models.Topic) – The topic which triggered the event. is_new (bool) – True if the topic is new, False if it is an edit.

flaskbb.plugins.spec.flaskbb_event_user_registered(username)¶

Hook for handling events after a user is registered

Parameters:	username – The username of the newly registered user.

flaskbb.plugins.spec.flaskbb_authenticate(identifier, secret)¶

Hook for authenticating users in FlaskBB. This hook should return either an instance of flaskbb.user.models.User or None.

If a hook decides that all attempts for authentication should end, it may raise a flaskbb.core.exceptions.StopAuthentication and include a reason why authentication was stopped.

Only the first User result will used and the default FlaskBB authentication is tried last to give others an attempt to authenticate the user instead.

FlaskBB Form Hooks¶

flaskbb.plugins.spec.flaskbb_form_new_post_save(form)¶

Hook for modifying the ReplyForm.

This hook is called while populating the post object with the data from the form. The post object will be saved after the hook call.

Parameters:	form – The form object. post – The post object.

flaskbb.plugins.spec.flaskbb_form_new_post(form)¶

Hook for modifying the ReplyForm.

For example:

@impl
def flaskbb_form_new_post(form):
    form.example = TextField("Example Field", validators=[
        DataRequired(message="This field is required"),
        Length(min=3, max=50)])

Parameters:	form – The `ReplyForm` class.

flaskbb.plugins.spec.flaskbb_form_new_topic(form)¶

Hook for modifying the NewTopicForm

Parameters:	form – The `NewTopicForm` class.

flaskbb.plugins.spec.flaskbb_form_new_topic_save(form, topic)¶

Hook for modifying the NewTopicForm.

This hook is called while populating the topic object with the data from the form. The topic object will be saved after the hook call.

Parameters:	form – The form object. topic – The topic object.

flaskbb.plugins.spec.flaskbb_form_registration(form)¶

Hook for modifying the RegisterForm.

Parameters:	form – The form class

Template Hooks¶

Note

Template hooks, which are used in forms, are usually rendered after the hidden CSRF token field and before an submit field.

flaskbb.plugins.spec.flaskbb_tpl_navigation_before()¶

Hook for registering additional navigation items.

in templates/layout.html.

flaskbb.plugins.spec.flaskbb_tpl_navigation_after()¶

Hook for registering additional navigation items.

in templates/layout.html.

flaskbb.plugins.spec.flaskbb_tpl_user_nav_loggedin_before()¶

Hook for registering additional user navigational items which are only shown when a user is logged in.

in templates/layout.html.

flaskbb.plugins.spec.flaskbb_tpl_user_nav_loggedin_after()¶

Hook for registering additional user navigational items which are only shown when a user is logged in.

in templates/layout.html.

flaskbb.plugins.spec.flaskbb_tpl_form_registration_before(form)¶

This hook is emitted in the Registration form before the first input field but after the hidden CSRF token field.

in templates/auth/register.html.

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_registration_after(form)¶

This hook is emitted in the Registration form after the last input field but before the submit field.

in templates/auth/register.html.

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_user_details_before(form)¶

This hook is emitted in the Change User Details form before an input field is rendered.

in templates/user/change_user_details.html.

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_user_details_after(form)¶

This hook is emitted in the Change User Details form after the last input field has been rendered but before the submit field.

in templates/user/change_user_details.html.

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_new_post_before(form)¶

Hook for inserting a new form field before the first field is rendered.

For example:

@impl
def flaskbb_tpl_form_new_post_after(form):
    return render_template_string(
        """
        <div class="form-group">
            <div class="col-md-12 col-sm-12 col-xs-12">
                <label>{{ form.example.label.text }}</label>

                {{ form.example(class="form-control",
                                placeholder=form.example.label.text) }}

                {%- for error in form.example.errors -%}
                <span class="help-block">{{error}}</span>
                {%- endfor -%}
            </div>
        </div>
        """

in templates/forum/new_post.html

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_new_post_after(form)¶

Hook for inserting a new form field after the last field is rendered (but before the submit field).

in templates/forum/new_post.html

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_new_topic_before(form)¶

Hook for inserting a new form field before the first field is rendered (but before the CSRF token).

in templates/forum/new_topic.html

Parameters:	form – The form object.

flaskbb.plugins.spec.flaskbb_tpl_form_new_topic_after(form)¶

Hook for inserting a new form field after the last field is rendered (but before the submit button).

in templates/forum/new_topic.html :param form: The form object.

flaskbb.plugins.spec.flaskbb_tpl_profile_settings_menu()¶

This hook is emitted on the user settings page in order to populate the side bar menu. Implementations of this hook should return a list of tuples that are view name and display text. The display text will be provided to the translation service so it is unnecessary to supply translated text.

A plugin can declare a new block by setting the view to None. If this is done, consider marking the hook implementation with trylast=True to avoid capturing plugins that do not create new blocks.

For example:

@impl(trylast=True)
def flaskbb_tpl_profile_settings_menu():
    return [
        (None, 'Account Settings'),
        ('user.settings', 'General Settings'),
        ('user.change_user_details', 'Change User Details'),
        ('user.change_email', 'Change E-Mail Address'),
        ('user.change_password', 'Change Password')
    ]

Hookwrappers for this spec should not be registered as FlaskBB supplies its own hookwrapper to flatten all the lists into a single list.

in templates/user/settings_layout.html

flaskbb.plugins.spec.flaskbb_tpl_profile_sidebar_stats(user)¶

This hook is emitted on the users profile page below the standard information. For example, it can be used to add additional items such as a link to the profile.

in templates/user/profile_layout.html

Parameters:	user – The user object for whom the profile is currently visited.

flaskbb.plugins.spec.flaskbb_tpl_post_author_info_before(user, post)¶

This hook is emitted before the information about the author of a post is displayed (but after the username).