Flask-Milligram

Milligram — a minimalist CSS framework — helper for Jinja2 template engine in Flask.

Contents

Basic

Installation

Install Flask-Milligram from PyPI:

$ pip install flask-milligram

Initialization

from flask_milligram import Milligram
from flask import Flask

app = Flask(__name__)

milligram = Milligram(app)

Flask-Milligram also supports factory pattern. For example:

def create_app(config_filename):
    app = Flask(__name__)
    app.config.from_pyfile(config_filename)

    # import Milligram instance from another file like extensions.py
    milligram.init_app(app)

Read Flask documentation for more details.

Load Resources

Flask-Milligram provides two methods to load related resources in the template: load_css() and load_js().

Call them in your base template first:

<head>
....
{{ milligram.load_css() }}
</head>
<body>
...
{{ milligram.load_js() }}
</body>

By default, normalize.css and milligram.css will be loaded from CDN. You can also set MILLIGRAM_SERVE_LOCAL to True to use built-in local files. Please note that these two methods are not optional, that is to say, Flask-Milligram won’t work without the specific resources — milligram-extensions.css and milligram-extensions.js. However, you can customize them anytime you want.

Base Template

Here is an example base template you can use:

<!doctype html>
<html lang="en">
    <head>
        {% block head %}
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

        {% block styles %}
        {{ milligram.load_css() }}
        {% endblock %}

        <title>Page title</title>
        {% endblock %}
    </head>
    <body>
        {% block content %}{% endblock %}

        {% block scripts %}
        {{ milligram.load_js() }}
        {% endblock %}
    </body>
</html>

Macros

Macro

Templates Path

Description

render_navbar()

milligram/nav.html

Render a navigation header

render_breadcrumb()

milligram/nav.html

Render a navigation breadcrumb

render_pagination()

milligram/pagination.html

Render a Flask-SQLAlchemy pagniantion

render_badge()

milligram/utilities.html

Render a badge

Import the macros above from the corresponding path and call them in template engine:

{% from 'milligram/pagination.html' import render_pagination %}

{{ render_pagination(pagination) }}

Go to the Macros page to see more details.

Configurations

Configuration Variable

Default Value

Description

MILLIGRAM_SERVE_LOCAL

False

If set to True, local resources will be used for load_css methods.

Macros

render_navbar()

Render a navigation header

Example
{% from 'milligram/nav.html' import render_navbar %}

{{ render_navbar([('index', 'Home'), ('other', 'Other'), ('about', 'About')])}}
API
render_navbar(navigation)
Parameters

navigation – An array-like object contains at least one sub array-like object whose first element is the endpoint used to generate URL and second is the text displayed.

render_breadcrumb()

Render a navigation breadcrumb.

Example
{% from 'milligram/nav.html' import render_breadcrumb %}

{{ render_breadcrumb([('index', 'Home'), ('other', 'Other'), ('about', 'About')], use_ol=True)}}
API
render_breadcrumb(navigation, use_ol=False)
Parameters

  • navigation – An array-like object contains at least one sub array-like object whose first element is the endpoint used to generate URL and second is the text displayed.

  • use_ol – Default to generate <ul></ul>, if set to True, it will generate <ol></ol>.

render_pagination()

Render a Flask-SQLAlchemy pagniantion.

Example
{% from 'milligram/pagination.html' import render_pagination %}

{{ render_pagination(pagination) }}
API
render_pagination(pagination, fragment='', endpoint=None, ellipses='…')
Parameters

  • pagination – A Flask-SQLAlchemy Pagination instance.

  • fragment – URL fragment added into link.

  • endpoint – Endpoint to call when a page number is clicked.

  • ellipses – Symbol to use to indicate that pages have been skipped.

render_badge()

Render a badge.

Example
{% from 'milligram/utilities.html' import render_badge %}

{{ render_badge('Badge') }}
API
render_badge(text, small=False)
Parameters

  • text – Text displayed in the badge.

  • small – Default to generate a normal size badge, if set to True, it will generate a small size badge.

Run the example application

Input these commands in the terminal to run the example application:

$ git clone https://github.com/ImJuanan/flask-milligram.git
$ cd flask-milligram/examples
$ pipenv install
$ pipenv run python app.py

Now go to http://localhost:5000.

Changelog

Flask-Milligram Changelog

0.1.0

Release date: 2021/10/07

  • Initial release.

Development

All kinds of contributions are meaningful. You can build the development environment locally and run tests using tox with the following commands:

$ git clone https://github.com/ImJuanan/flask-milligram.git
$ cd flask-milligram
$ pipenv install
$ pipenv run pip install ".[dev]"
$ pipenv run tox

If you are not familiar with Pipenv, this way is gonna work as well:

$ git clone https://github.com/ImJuanan/flask-milligram.git
$ cd flask-milligram
$ python -m venv env
$ env/Scripts/activate
$ pip install ".[dev]"
$ tox

Authors

Maintainer: Juan An

License

This project is licensed under the MIT License (see the LICENSE file for details).