Flask Extras

Assorted useful flask views, blueprints, Jinja2 template filters, and templates/macros.

Overall setup

As of 3.4.0, filters and templates will automatically be registered and available through the following simple command:

from flask_extras import FlaskExtras
app = Flask('myapp')
FlaskExtras(app)

For the old way, check out this page

Available features

Views

Import them like usual:

from flask_extras.views import (
    statuses,
)

Note: each view must have a valid template in your apps templates dir. See each view for the required names and locations.

Note: each view has configuration helpers to inject or configure your app. See source for details.

Macros

All macro DEMOS are available by cloning this repo and firing up the flask test server, e.g:

git clone https://github.com/christabor/flask_extras
cd flask_extras
virtualenv env
source env/bin/active
python setup.py install
cd test_app
python app.py
open http://localhost:5014

Philosophy

Many macros leverage the structure of data to find a common mapping. For example, a dictionary looks a lot like a definition list (dl), and a list looks really like a ...list, in html terms. But stepping even further into things, more complex data structures can have fairly elegant mappings when using macros to hide away a lot of html cruft.

This makes rendering complex server side data easy, without having to do lots of transformation. This won't work for cases where every last DOM element need to be stylized, but many users will find incredibly powerful tools available to make UI development much easier.

Many more macros are available. You can use them like so:

{% from 'macros.html' import list_group, objects2table %}

For the most comprehensive docs, check out each macro. Comment "docstrings" are inline using jinja2 comments (these are not rendered in your html).

Also, check the source and/or output to see what classes are available for style overrides.

Statuses

Provides views for common status codes. Usage:

app = statuses.inject_error_views(app)

See source for more.

Decorators

See the source for more. Usage example:

from flask_extras.decorators import require_headers

app.route('/')
@require_headers(['X-Foo'])
def foo():
    pass

Forms

WTForm Multi-step wizard

A WTForm extension for handling an arbitrary number of separate forms as a single, multi-step, multi-POST wizard. All state and data are handled by apps' session backend. Building forms is just like you're used to -- simple and intuitive. Just inherit the MultiStepWizard class and put a __forms__ key on it, which is just a list of all the forms you want to use. Note: list order matters for your form steps.

Usage example:

from flask.ext.wtf import FlaskForm

from flask_extras.forms.wizard import MultiStepWizard


class MultiStepTest1(FlaskForm):
    field1 = StringField(validators=[validators.DataRequired()],)
    field2 = IntegerField(validators=[validators.DataRequired()],)


class MultiStepTest2(FlaskForm):
    field3 = StringField(validators=[validators.DataRequired()],)
    field4 = IntegerField(validators=[validators.DataRequired()],)


class MyCoolForm(MultiStepWizard):
    __forms__ = [
        MultiStepTest1,
        MultiStepTest2,
    ]

and an example route:

from forms import MyCoolForm

@app.route('/', methods=['GET', 'POST'])
def index():
    curr_step = request.args.get('curr_step')
    form_kwargs = dict(session_key='mycustomkey')
    if curr_step is not None:
        form_kwargs.update(curr_step=curr_step)
    form = forms.MyCoolForm(**form_kwargs)
    kwargs = dict(form=form)
    if request.method == 'POST':
        if form.validate_on_submit():
            if form.is_complete():
                data = form.alldata(combine_fields=True, flush_after=True)
                flash('Form validated and complete! data = {}'.format(data),
                      'success')
                return jsonify(data)
            else:
                flash('Great job, but not done yet ({} steps remain!).'.format(form.remaining))
        else:
            flash('Invalid form data.', 'error')
    return render_template('index.html', **kwargs)

and an example html page (using the wtform_form macro also available):

{% if form.is_complete() %}
    <span class="well">Complete!</span>
{% else %}
    <ul class="list-inline">
        {% for step in form.steps %}
            <li>
                {% if step == form.curr_step %}
                    <strong class="lead label label-info">current {{ step }}</strong>
                {% else %}
                    <a href="{{ url_for('app.index') }}?curr_step={{ step }}">{{ step }}</a>
                {% endif %}
                {% if not loop.last %}
                    &nbsp;&nbsp;/
                {% endif %}
            </li>
        {% endfor %}
    </ul>
    {{ wtform_form(form,
        classes=['form', 'form-horizontal'],
        btn_classes=['btn btn-primary', 'btn-lg'],
        align='right',
        action=url_for('app.index'),
        method='POST',
        reset_btn=False,
        horizontal=True,
    ) }}
{% endif %}