https://github.com/grahambell/jinja2-orderblocks
OrderBlocks Extension for Jinja2
https://github.com/grahambell/jinja2-orderblocks
jinja2-extension
Last synced: about 1 month ago
JSON representation
OrderBlocks Extension for Jinja2
- Host: GitHub
- URL: https://github.com/grahambell/jinja2-orderblocks
- Owner: grahambell
- License: gpl-3.0
- Created: 2016-08-21T00:14:23.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-08-02T16:46:44.000Z (10 months ago)
- Last Synced: 2025-03-26T20:22:16.403Z (about 2 months ago)
- Topics: jinja2-extension
- Language: Python
- Homepage:
- Size: 20.5 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.txt
- License: COPYING
Awesome Lists containing this project
README
OrderBlocks Extension for Jinja2
================================
Introduction
------------
This is an extension for the `Jinja2 `_
template engine which allows you to select and reorder inheritance blocks.
Example 1: Ordering Specified by Child Template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this example, a website might wish to publish a number of articles.
Each article shows some basic information about the article, the main
story itself and perhaps some images.
This could be done with a template `"article.html"` which
inherits from the website's main `"layout.html"` template and
overrides the `content` block to contain three new blocks:
`introduction`, `story` and `images`::
{% extends 'layout.html' %}
{% block content %}
{% orderblocks article_order %}
{% block introduction %}
- Some introductory information
- E.g. date, author, …
{% endblock %}
{% block story %}
Article story goes here …
{% endblock %}
{% block images %}
{% endblock %}
{% endorderblocks %}
{% endblock %}
Note that the blocks are enclosed in the `orderblocks` tag.
This takes one argument, specifying the order in which to show the
contained blocks.
(Any non-block contents are ignored.)
In this case this argument is given by the `article_order` parameter.
When this is undefined, as it is here, (or None) the blocks are shown in their
original ordering.
However there might also be some special kinds of articles, such as
an image feature article.
Here the images should appear in a special display before the story text.
The template for this kind of article can inherit from the `"article.html"`
template but specify a value for the `article_order` parameter::
{% extends 'article.html' %}
{% set article_order = ('introduction', 'images', 'story') %}
{% block images %}
{{ super() }}
{% endblock %}
Example 2: Dynamically-specified Ordering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The block ordering parameter can of course also be specified by
a template context parameter.
Here a page allows the user to specify which sections
they wish to see, and their ordering, via a request argument::
from flask import Flask, render_template, request
app = Flask(__name__)
if 'extensions' not in app.jinja_options:
app.jinja_options['extensions'] = []
app.jinja_options['extensions'].append(
'jinja2_orderblocks.OrderBlocks')
@app.route('/example/')
def example_page():
return render_template(
'example_template.html',
article_order=request.args['order'].split(','))
It could be used with a template which included a number of sections,
such as the following fragment::
{% orderblocks article_order %}
{% block x %}
Section X
…
{% endblock %}
{% block y %}
Section Y
…
{% endblock %}
{% block z %}
Section Z
…
{% endblock %}
{% endorderblocks %}
The sections could be requested in reverse order via
`http://.../example/?order=z,y,x`
or a single section could be requested using
`http://.../example/?order=y`.
Note on Implementation
~~~~~~~~~~~~~~~~~~~~~~
This extension, as currently implemented, works by replacing the
`orderblocks` tag with a for loop which iterates over the list of
requested block names, and includes blocks which match the requested
names.
In other words it converts a structure like this::
{% orderblocks block_order %}
{% block x %}
X
{% endblock %}
{% block y %}
Y
{% endblock %}
{% endorderblocks %}
into a for loop of if blocks such as::
{% for block_name in block_order %}
{% if block_name == 'x' %}
{% block x %}
X
{% endblock %}
{% endif %}
{% if block_name == 'y' %}
{% block y %}
Y
{% endblock %}
{% endif %}
{% endfor %}
Installation
------------
The extension can be installed using the ``setup.py`` script::
python setup.py install
Before doing that, you might like to run the unit tests::
PYTHONPATH=lib python -m unittest discover
License
-------
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .