OrderBlocks Extension for Jinja2
================================
Introduction
------------
This is an extension for the `Jinja2 <https://palletsprojects.com/p/jinja/>`_
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 %}
<ul>
<li>Some introductory information</li>
<li>E.g. date, author, …</li>
</ul>
{% endblock %}
{% block story %}
<p>Article story goes here …</p>
{% endblock %}
{% block images %}
<p>
<img src="..." />
</p>
{% 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 %}
<!-- Placeholder for fancy image display! -->
<big>{{ super() }}</big>
{% 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>
<h2>Section X</h2>
<p>…</p>
</section>
{% endblock %}
{% block y %}
<section>
<h2>Section Y</h2>
<p>…</p>
</section>
{% endblock %}
{% block z %}
<section>
<h2>Section Z</h2>
<p>…</p>
</section>
{% 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 %}
<p>X</p>
{% endblock %}
{% block y %}
<p>Y</p>
{% endblock %}
{% endorderblocks %}
into a for loop of if blocks such as::
{% for block_name in block_order %}
{% if block_name == 'x' %}
{% block x %}
<p>X</p>
{% endblock %}
{% endif %}
{% if block_name == 'y' %}
{% block y %}
<p>Y</p>
{% 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 <http://www.gnu.org/licenses/>.
Raw data
{
"_id": null,
"home_page": "http://github.com/grahambell/jinja2-orderblocks",
"name": "jinja2-orderblocks",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Graham Bell",
"author_email": "graham.s.bell@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7f/39/4d845b134bd85379ac86d4d747ed26fc28b69ce0aa4686521d06b44eadd8/jinja2_orderblocks-0.1.1.tar.gz",
"platform": null,
"description": "OrderBlocks Extension for Jinja2\n================================\n\nIntroduction\n------------\n\nThis is an extension for the `Jinja2 <https://palletsprojects.com/p/jinja/>`_\ntemplate engine which allows you to select and reorder inheritance blocks.\n\n\nExample 1: Ordering Specified by Child Template\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIn this example, a website might wish to publish a number of articles.\nEach article shows some basic information about the article, the main\nstory itself and perhaps some images.\nThis could be done with a template `\"article.html\"` which\ninherits from the website's main `\"layout.html\"` template and\noverrides the `content` block to contain three new blocks:\n`introduction`, `story` and `images`::\n\n {% extends 'layout.html' %}\n\n {% block content %}\n {% orderblocks article_order %}\n {% block introduction %}\n <ul>\n <li>Some introductory information</li>\n <li>E.g. date, author, …</li>\n </ul>\n {% endblock %}\n\n {% block story %}\n <p>Article story goes here …</p>\n {% endblock %}\n\n {% block images %}\n <p>\n <img src=\"...\" />\n </p>\n {% endblock %}\n {% endorderblocks %}\n {% endblock %}\n\nNote that the blocks are enclosed in the `orderblocks` tag.\nThis takes one argument, specifying the order in which to show the\ncontained blocks.\n(Any non-block contents are ignored.)\nIn this case this argument is given by the `article_order` parameter.\nWhen this is undefined, as it is here, (or None) the blocks are shown in their\noriginal ordering.\n\nHowever there might also be some special kinds of articles, such as\nan image feature article.\nHere the images should appear in a special display before the story text.\nThe template for this kind of article can inherit from the `\"article.html\"`\ntemplate but specify a value for the `article_order` parameter::\n\n {% extends 'article.html' %}\n\n {% set article_order = ('introduction', 'images', 'story') %}\n\n {% block images %}\n <!-- Placeholder for fancy image display! -->\n <big>{{ super() }}</big>\n {% endblock %}\n\nExample 2: Dynamically-specified Ordering\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe block ordering parameter can of course also be specified by\na template context parameter.\nHere a page allows the user to specify which sections\nthey wish to see, and their ordering, via a request argument::\n\n from flask import Flask, render_template, request\n\n app = Flask(__name__)\n\n if 'extensions' not in app.jinja_options:\n app.jinja_options['extensions'] = []\n app.jinja_options['extensions'].append(\n 'jinja2_orderblocks.OrderBlocks')\n\n @app.route('/example/')\n def example_page():\n return render_template(\n 'example_template.html',\n article_order=request.args['order'].split(','))\n\nIt could be used with a template which included a number of sections,\nsuch as the following fragment::\n\n {% orderblocks article_order %}\n {% block x %}\n <section>\n <h2>Section X</h2>\n <p>…</p>\n </section>\n {% endblock %}\n\n {% block y %}\n <section>\n <h2>Section Y</h2>\n <p>…</p>\n </section>\n {% endblock %}\n\n {% block z %}\n <section>\n <h2>Section Z</h2>\n <p>…</p>\n </section>\n {% endblock %}\n {% endorderblocks %}\n\nThe sections could be requested in reverse order via\n`http://.../example/?order=z,y,x`\nor a single section could be requested using\n`http://.../example/?order=y`.\n\nNote on Implementation\n~~~~~~~~~~~~~~~~~~~~~~\n\nThis extension, as currently implemented, works by replacing the\n`orderblocks` tag with a for loop which iterates over the list of\nrequested block names, and includes blocks which match the requested\nnames.\nIn other words it converts a structure like this::\n\n {% orderblocks block_order %}\n {% block x %}\n <p>X</p>\n {% endblock %}\n\n {% block y %}\n <p>Y</p>\n {% endblock %}\n {% endorderblocks %}\n\ninto a for loop of if blocks such as::\n\n {% for block_name in block_order %}\n {% if block_name == 'x' %}\n {% block x %}\n <p>X</p>\n {% endblock %}\n {% endif %}\n\n {% if block_name == 'y' %}\n {% block y %}\n <p>Y</p>\n {% endblock %}\n {% endif %}\n {% endfor %}\n\nInstallation\n------------\n\nThe extension can be installed using the ``setup.py`` script::\n\n python setup.py install\n\nBefore doing that, you might like to run the unit tests::\n\n PYTHONPATH=lib python -m unittest discover\n\nLicense\n-------\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see <http://www.gnu.org/licenses/>.",
"bugtrack_url": null,
"license": "",
"summary": "OrderBlocks Extension for Jinja2",
"version": "0.1.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f394d845b134bd85379ac86d4d747ed26fc28b69ce0aa4686521d06b44eadd8",
"md5": "4b130d661f4ff6bf87f5cc12beacaa83",
"sha256": "acc25ad04f2ca093377a6fcd12a699c14b5fca3dde28b6144bde75a4677e6922"
},
"downloads": -1,
"filename": "jinja2_orderblocks-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4b130d661f4ff6bf87f5cc12beacaa83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16972,
"upload_time": "2023-04-15T21:29:40",
"upload_time_iso_8601": "2023-04-15T21:29:40.700133Z",
"url": "https://files.pythonhosted.org/packages/7f/39/4d845b134bd85379ac86d4d747ed26fc28b69ce0aa4686521d06b44eadd8/jinja2_orderblocks-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-15 21:29:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "grahambell",
"github_project": "jinja2-orderblocks",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jinja2-orderblocks"
}
JSON
