forked from orbit-oss/flask
use Jinja name consistently
This commit is contained in:
parent
38b4c1e19b
commit
d8259eb119
9 changed files with 31 additions and 31 deletions
|
|
@ -1376,7 +1376,7 @@ Released 2011-09-29, codename Rakija
|
||||||
of Flask itself and no longer of the test client. This cleaned up
|
of Flask itself and no longer of the test client. This cleaned up
|
||||||
some internal logic and lowers the odds of runaway request contexts
|
some internal logic and lowers the odds of runaway request contexts
|
||||||
in unittests.
|
in unittests.
|
||||||
- Fixed the Jinja2 environment's ``list_templates`` method not
|
- Fixed the Jinja environment's ``list_templates`` method not
|
||||||
returning the correct names when blueprints or modules were
|
returning the correct names when blueprints or modules were
|
||||||
involved.
|
involved.
|
||||||
|
|
||||||
|
|
@ -1462,7 +1462,7 @@ Released 2010-12-31
|
||||||
|
|
||||||
- Fixed an issue where the default ``OPTIONS`` response was not
|
- Fixed an issue where the default ``OPTIONS`` response was not
|
||||||
exposing all valid methods in the ``Allow`` header.
|
exposing all valid methods in the ``Allow`` header.
|
||||||
- Jinja2 template loading syntax now allows "./" in front of a
|
- Jinja template loading syntax now allows "./" in front of a
|
||||||
template load path. Previously this caused issues with module
|
template load path. Previously this caused issues with module
|
||||||
setups.
|
setups.
|
||||||
- Fixed an issue where the subdomain setting for modules was ignored
|
- Fixed an issue where the subdomain setting for modules was ignored
|
||||||
|
|
|
||||||
|
|
@ -96,10 +96,10 @@ is ambiguous.
|
||||||
One Template Engine
|
One Template Engine
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
Flask decides on one template engine: Jinja2. Why doesn't Flask have a
|
Flask decides on one template engine: Jinja. Why doesn't Flask have a
|
||||||
pluggable template engine interface? You can obviously use a different
|
pluggable template engine interface? You can obviously use a different
|
||||||
template engine, but Flask will still configure Jinja2 for you. While
|
template engine, but Flask will still configure Jinja for you. While
|
||||||
that limitation that Jinja2 is *always* configured will probably go away,
|
that limitation that Jinja is *always* configured will probably go away,
|
||||||
the decision to bundle one template engine and use that will not.
|
the decision to bundle one template engine and use that will not.
|
||||||
|
|
||||||
Template engines are like programming languages and each of those engines
|
Template engines are like programming languages and each of those engines
|
||||||
|
|
@ -107,7 +107,7 @@ has a certain understanding about how things work. On the surface they
|
||||||
all work the same: you tell the engine to evaluate a template with a set
|
all work the same: you tell the engine to evaluate a template with a set
|
||||||
of variables and take the return value as string.
|
of variables and take the return value as string.
|
||||||
|
|
||||||
But that's about where similarities end. Jinja2 for example has an
|
But that's about where similarities end. Jinja for example has an
|
||||||
extensive filter system, a certain way to do template inheritance,
|
extensive filter system, a certain way to do template inheritance,
|
||||||
support for reusable blocks (macros) that can be used from inside
|
support for reusable blocks (macros) that can be used from inside
|
||||||
templates and also from Python code, supports iterative template
|
templates and also from Python code, supports iterative template
|
||||||
|
|
@ -118,8 +118,8 @@ other hand treats templates similar to Python modules.
|
||||||
|
|
||||||
When it comes to connecting a template engine with an application or
|
When it comes to connecting a template engine with an application or
|
||||||
framework there is more than just rendering templates. For instance,
|
framework there is more than just rendering templates. For instance,
|
||||||
Flask uses Jinja2's extensive autoescaping support. Also it provides
|
Flask uses Jinja's extensive autoescaping support. Also it provides
|
||||||
ways to access macros from Jinja2 templates.
|
ways to access macros from Jinja templates.
|
||||||
|
|
||||||
A template abstraction layer that would not take the unique features of
|
A template abstraction layer that would not take the unique features of
|
||||||
the template engines away is a science on its own and a too large
|
the template engines away is a science on its own and a too large
|
||||||
|
|
@ -150,7 +150,7 @@ authentication technologies, and more. Flask may be "micro", but it's ready for
|
||||||
production use on a variety of needs.
|
production use on a variety of needs.
|
||||||
|
|
||||||
Why does Flask call itself a microframework and yet it depends on two
|
Why does Flask call itself a microframework and yet it depends on two
|
||||||
libraries (namely Werkzeug and Jinja2). Why shouldn't it? If we look
|
libraries (namely Werkzeug and Jinja). Why shouldn't it? If we look
|
||||||
over to the Ruby side of web development there we have a protocol very
|
over to the Ruby side of web development there we have a protocol very
|
||||||
similar to WSGI. Just that it's called Rack there, but besides that it
|
similar to WSGI. Just that it's called Rack there, but besides that it
|
||||||
looks very much like a WSGI rendition for Ruby. But nearly all
|
looks very much like a WSGI rendition for Ruby. But nearly all
|
||||||
|
|
@ -208,7 +208,7 @@ What Flask is, What Flask is Not
|
||||||
|
|
||||||
Flask will never have a database layer. It will not have a form library
|
Flask will never have a database layer. It will not have a form library
|
||||||
or anything else in that direction. Flask itself just bridges to Werkzeug
|
or anything else in that direction. Flask itself just bridges to Werkzeug
|
||||||
to implement a proper WSGI application and to Jinja2 to handle templating.
|
to implement a proper WSGI application and to Jinja to handle templating.
|
||||||
It also binds to a few common standard library packages such as logging.
|
It also binds to a few common standard library packages such as logging.
|
||||||
Everything else is up for extensions.
|
Everything else is up for extensions.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -29,7 +29,7 @@ debug environments with profilers and other things you might have enabled.
|
||||||
Streaming from Templates
|
Streaming from Templates
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
The Jinja2 template engine supports rendering a template piece by
|
The Jinja template engine supports rendering a template piece by
|
||||||
piece, returning an iterator of strings. Flask provides the
|
piece, returning an iterator of strings. Flask provides the
|
||||||
:func:`~flask.stream_template` and :func:`~flask.stream_template_string`
|
:func:`~flask.stream_template` and :func:`~flask.stream_template_string`
|
||||||
functions to make this easier to use.
|
functions to make this easier to use.
|
||||||
|
|
|
||||||
|
|
@ -99,7 +99,7 @@ WTForm's field function, which renders the field for us. The keyword
|
||||||
arguments will be inserted as HTML attributes. So, for example, you can
|
arguments will be inserted as HTML attributes. So, for example, you can
|
||||||
call ``render_field(form.username, class='username')`` to add a class to
|
call ``render_field(form.username, class='username')`` to add a class to
|
||||||
the input element. Note that WTForms returns standard Python strings,
|
the input element. Note that WTForms returns standard Python strings,
|
||||||
so we have to tell Jinja2 that this data is already HTML-escaped with
|
so we have to tell Jinja that this data is already HTML-escaped with
|
||||||
the ``|safe`` filter.
|
the ``|safe`` filter.
|
||||||
|
|
||||||
Here is the :file:`register.html` template for the function we used above, which
|
Here is the :file:`register.html` template for the function we used above, which
|
||||||
|
|
|
||||||
|
|
@ -352,7 +352,7 @@ Rendering Templates
|
||||||
|
|
||||||
Generating HTML from within Python is not fun, and actually pretty
|
Generating HTML from within Python is not fun, and actually pretty
|
||||||
cumbersome because you have to do the HTML escaping on your own to keep
|
cumbersome because you have to do the HTML escaping on your own to keep
|
||||||
the application secure. Because of that Flask configures the `Jinja2
|
the application secure. Because of that Flask configures the `Jinja
|
||||||
<https://palletsprojects.com/p/jinja/>`_ template engine for you automatically.
|
<https://palletsprojects.com/p/jinja/>`_ template engine for you automatically.
|
||||||
|
|
||||||
Templates can be used to generate any type of text file. For web applications, you'll
|
Templates can be used to generate any type of text file. For web applications, you'll
|
||||||
|
|
@ -392,8 +392,8 @@ package it's actually inside your package:
|
||||||
/templates
|
/templates
|
||||||
/hello.html
|
/hello.html
|
||||||
|
|
||||||
For templates you can use the full power of Jinja2 templates. Head over
|
For templates you can use the full power of Jinja templates. Head over
|
||||||
to the official `Jinja2 Template Documentation
|
to the official `Jinja Template Documentation
|
||||||
<https://jinja.palletsprojects.com/templates/>`_ for more information.
|
<https://jinja.palletsprojects.com/templates/>`_ for more information.
|
||||||
|
|
||||||
Here is an example template:
|
Here is an example template:
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,21 @@
|
||||||
Templates
|
Templates
|
||||||
=========
|
=========
|
||||||
|
|
||||||
Flask leverages Jinja2 as its template engine. You are obviously free to use
|
Flask leverages Jinja as its template engine. You are obviously free to use
|
||||||
a different template engine, but you still have to install Jinja2 to run
|
a different template engine, but you still have to install Jinja to run
|
||||||
Flask itself. This requirement is necessary to enable rich extensions.
|
Flask itself. This requirement is necessary to enable rich extensions.
|
||||||
An extension can depend on Jinja2 being present.
|
An extension can depend on Jinja being present.
|
||||||
|
|
||||||
This section only gives a very quick introduction into how Jinja2
|
This section only gives a very quick introduction into how Jinja
|
||||||
is integrated into Flask. If you want information on the template
|
is integrated into Flask. If you want information on the template
|
||||||
engine's syntax itself, head over to the official `Jinja2 Template
|
engine's syntax itself, head over to the official `Jinja Template
|
||||||
Documentation <https://jinja.palletsprojects.com/templates/>`_ for
|
Documentation <https://jinja.palletsprojects.com/templates/>`_ for
|
||||||
more information.
|
more information.
|
||||||
|
|
||||||
Jinja Setup
|
Jinja Setup
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
Unless customized, Jinja2 is configured by Flask as follows:
|
Unless customized, Jinja is configured by Flask as follows:
|
||||||
|
|
||||||
- autoescaping is enabled for all templates ending in ``.html``,
|
- autoescaping is enabled for all templates ending in ``.html``,
|
||||||
``.htm``, ``.xml``, ``.xhtml``, as well as ``.svg`` when using
|
``.htm``, ``.xml``, ``.xhtml``, as well as ``.svg`` when using
|
||||||
|
|
@ -25,13 +25,13 @@ Unless customized, Jinja2 is configured by Flask as follows:
|
||||||
- a template has the ability to opt in/out autoescaping with the
|
- a template has the ability to opt in/out autoescaping with the
|
||||||
``{% autoescape %}`` tag.
|
``{% autoescape %}`` tag.
|
||||||
- Flask inserts a couple of global functions and helpers into the
|
- Flask inserts a couple of global functions and helpers into the
|
||||||
Jinja2 context, additionally to the values that are present by
|
Jinja context, additionally to the values that are present by
|
||||||
default.
|
default.
|
||||||
|
|
||||||
Standard Context
|
Standard Context
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
The following global variables are available within Jinja2 templates
|
The following global variables are available within Jinja templates
|
||||||
by default:
|
by default:
|
||||||
|
|
||||||
.. data:: config
|
.. data:: config
|
||||||
|
|
@ -140,7 +140,7 @@ using in this block.
|
||||||
Registering Filters
|
Registering Filters
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
If you want to register your own filters in Jinja2 you have two ways to do
|
If you want to register your own filters in Jinja you have two ways to do
|
||||||
that. You can either put them by hand into the
|
that. You can either put them by hand into the
|
||||||
:attr:`~flask.Flask.jinja_env` of the application or use the
|
:attr:`~flask.Flask.jinja_env` of the application or use the
|
||||||
:meth:`~flask.Flask.template_filter` decorator.
|
:meth:`~flask.Flask.template_filter` decorator.
|
||||||
|
|
@ -157,7 +157,7 @@ The two following examples work the same and both reverse an object::
|
||||||
|
|
||||||
In case of the decorator the argument is optional if you want to use the
|
In case of the decorator the argument is optional if you want to use the
|
||||||
function name as name of the filter. Once registered, you can use the filter
|
function name as name of the filter. Once registered, you can use the filter
|
||||||
in your templates in the same way as Jinja2's builtin filters, for example if
|
in your templates in the same way as Jinja's builtin filters, for example if
|
||||||
you have a Python list in context called `mylist`::
|
you have a Python list in context called `mylist`::
|
||||||
|
|
||||||
{% for x in mylist | reverse %}
|
{% for x in mylist | reverse %}
|
||||||
|
|
@ -211,7 +211,7 @@ strings. This can be used for streaming HTML in chunks to speed up
|
||||||
initial page load, or to save memory when rendering a very large
|
initial page load, or to save memory when rendering a very large
|
||||||
template.
|
template.
|
||||||
|
|
||||||
The Jinja2 template engine supports rendering a template piece
|
The Jinja template engine supports rendering a template piece
|
||||||
by piece, returning an iterator of strings. Flask provides the
|
by piece, returning an iterator of strings. Flask provides the
|
||||||
:func:`~flask.stream_template` and :func:`~flask.stream_template_string`
|
:func:`~flask.stream_template` and :func:`~flask.stream_template_string`
|
||||||
functions to make this easier to use.
|
functions to make this easier to use.
|
||||||
|
|
|
||||||
|
|
@ -51,12 +51,12 @@ tags. For more information on that have a look at the Wikipedia article
|
||||||
on `Cross-Site Scripting
|
on `Cross-Site Scripting
|
||||||
<https://en.wikipedia.org/wiki/Cross-site_scripting>`_.
|
<https://en.wikipedia.org/wiki/Cross-site_scripting>`_.
|
||||||
|
|
||||||
Flask configures Jinja2 to automatically escape all values unless
|
Flask configures Jinja to automatically escape all values unless
|
||||||
explicitly told otherwise. This should rule out all XSS problems caused
|
explicitly told otherwise. This should rule out all XSS problems caused
|
||||||
in templates, but there are still other places where you have to be
|
in templates, but there are still other places where you have to be
|
||||||
careful:
|
careful:
|
||||||
|
|
||||||
- generating HTML without the help of Jinja2
|
- generating HTML without the help of Jinja
|
||||||
- calling :class:`~markupsafe.Markup` on data submitted by users
|
- calling :class:`~markupsafe.Markup` on data submitted by users
|
||||||
- sending out HTML from uploaded files, never do that, use the
|
- sending out HTML from uploaded files, never do that, use the
|
||||||
``Content-Disposition: attachment`` header to prevent that problem.
|
``Content-Disposition: attachment`` header to prevent that problem.
|
||||||
|
|
@ -65,7 +65,7 @@ careful:
|
||||||
trick a browser to execute HTML.
|
trick a browser to execute HTML.
|
||||||
|
|
||||||
Another thing that is very important are unquoted attributes. While
|
Another thing that is very important are unquoted attributes. While
|
||||||
Jinja2 can protect you from XSS issues by escaping HTML, there is one
|
Jinja can protect you from XSS issues by escaping HTML, there is one
|
||||||
thing it cannot protect you from: XSS by attribute injection. To counter
|
thing it cannot protect you from: XSS by attribute injection. To counter
|
||||||
this possible attack vector, be sure to always quote your attributes with
|
this possible attack vector, be sure to always quote your attributes with
|
||||||
either double or single quotes when using Jinja expressions in them:
|
either double or single quotes when using Jinja expressions in them:
|
||||||
|
|
|
||||||
|
|
@ -521,7 +521,7 @@ class App(Scaffold):
|
||||||
return os.path.join(prefix, "var", f"{self.name}-instance")
|
return os.path.join(prefix, "var", f"{self.name}-instance")
|
||||||
|
|
||||||
def create_global_jinja_loader(self) -> DispatchingJinjaLoader:
|
def create_global_jinja_loader(self) -> DispatchingJinjaLoader:
|
||||||
"""Creates the loader for the Jinja2 environment. Can be used to
|
"""Creates the loader for the Jinja environment. Can be used to
|
||||||
override just the loader and keeping the rest unchanged. It's
|
override just the loader and keeping the rest unchanged. It's
|
||||||
discouraged to override this function. Instead one should override
|
discouraged to override this function. Instead one should override
|
||||||
the :meth:`jinja_loader` function instead.
|
the :meth:`jinja_loader` function instead.
|
||||||
|
|
|
||||||
|
|
@ -37,7 +37,7 @@ def _default_template_ctx_processor() -> dict[str, t.Any]:
|
||||||
|
|
||||||
|
|
||||||
class Environment(BaseEnvironment):
|
class Environment(BaseEnvironment):
|
||||||
"""Works like a regular Jinja2 environment but has some additional
|
"""Works like a regular Jinja environment but has some additional
|
||||||
knowledge of how Flask's blueprint works so that it can prepend the
|
knowledge of how Flask's blueprint works so that it can prepend the
|
||||||
name of the blueprint to referenced templates if necessary.
|
name of the blueprint to referenced templates if necessary.
|
||||||
"""
|
"""
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue