diff options
Diffstat (limited to 'app/static/doc/flask-docs/templating.html')
| -rw-r--r-- | app/static/doc/flask-docs/templating.html | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/app/static/doc/flask-docs/templating.html b/app/static/doc/flask-docs/templating.html new file mode 100644 index 0000000..4aedfbe --- /dev/null +++ b/app/static/doc/flask-docs/templating.html @@ -0,0 +1,293 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Templates — Flask 0.8 documentation</title> + + <link rel="stylesheet" href="_static/flasky.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '', + VERSION: '0.8', + COLLAPSE_INDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/underscore.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="Flask 0.8 documentation" href="index.html" /> + <link rel="next" title="Testing Flask Applications" href="testing.html" /> + <link rel="prev" title="Bonus: Testing the Application" href="tutorial/testing.html" /> + + + <link rel="apple-touch-icon" href="_static/touch-icon.png" /> + + <link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" /> + + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="testing.html" title="Testing Flask Applications" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="tutorial/testing.html" title="Bonus: Testing the Application" + accesskey="P">previous</a> |</li> + <li><a href="index.html">Flask 0.8 documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="templates"> +<h1>Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h1> +<p>Flask leverages Jinja2 as template engine. You are obviously free to use +a different template engine, but you still have to install Jinja2 to run +Flask itself. This requirement is necessary to enable rich extensions. +An extension can depend on Jinja2 being present.</p> +<p>This section only gives a very quick introduction into how Jinja2 +is integrated into Flask. If you want information on the template +engine’s syntax itself, head over to the official <a class="reference external" href="http://jinja.pocoo.org/2/documentation/templates">Jinja2 Template +Documentation</a> for +more information.</p> +<div class="section" id="jinja-setup"> +<h2>Jinja Setup<a class="headerlink" href="#jinja-setup" title="Permalink to this headline">¶</a></h2> +<p>Unless customized, Jinja2 is configured by Flask as follows:</p> +<ul class="simple"> +<li>autoescaping is enabled for all templates ending in <tt class="docutils literal"><span class="pre">.html</span></tt>, +<tt class="docutils literal"><span class="pre">.htm</span></tt>, <tt class="docutils literal"><span class="pre">.xml</span></tt> as well as <tt class="docutils literal"><span class="pre">.xhtml</span></tt></li> +<li>a template has the ability to opt in/out autoescaping with the +<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">autoescape</span> <span class="pre">%}</span></tt> tag.</li> +<li>Flask inserts a couple of global functions and helpers into the +Jinja2 context, additionally to the values that are present by +default.</li> +</ul> +</div> +<div class="section" id="standard-context"> +<h2>Standard Context<a class="headerlink" href="#standard-context" title="Permalink to this headline">¶</a></h2> +<p>The following global variables are available within Jinja2 templates +by default:</p> +<dl class="data"> +<dt> +<tt class="descname">config</tt></dt> +<dd><p>The current configuration object (<tt class="xref py py-data docutils literal"><span class="pre">flask.config</span></tt>)</p> +<p class="versionadded"> +<span class="versionmodified">New in version 0.6.</span></p> +</dd></dl> + +<dl class="data"> +<dt> +<tt class="descname">request</tt></dt> +<dd><p>The current request object (<a class="reference internal" href="api.html#flask.request" title="flask.request"><tt class="xref py py-class docutils literal"><span class="pre">flask.request</span></tt></a>)</p> +</dd></dl> + +<dl class="data"> +<dt> +<tt class="descname">session</tt></dt> +<dd><p>The current session object (<a class="reference internal" href="api.html#flask.session" title="flask.session"><tt class="xref py py-class docutils literal"><span class="pre">flask.session</span></tt></a>)</p> +</dd></dl> + +<dl class="data"> +<dt> +<tt class="descname">g</tt></dt> +<dd><p>The request-bound object for global variables (<a class="reference internal" href="api.html#flask.g" title="flask.g"><tt class="xref py py-data docutils literal"><span class="pre">flask.g</span></tt></a>)</p> +</dd></dl> + +<dl class="function"> +<dt> +<tt class="descname">url_for</tt><big>(</big><big>)</big></dt> +<dd><p>The <a class="reference internal" href="api.html#flask.url_for" title="flask.url_for"><tt class="xref py py-func docutils literal"><span class="pre">flask.url_for()</span></tt></a> function.</p> +</dd></dl> + +<dl class="function"> +<dt> +<tt class="descname">get_flashed_messages</tt><big>(</big><big>)</big></dt> +<dd><p>The <a class="reference internal" href="api.html#flask.get_flashed_messages" title="flask.get_flashed_messages"><tt class="xref py py-func docutils literal"><span class="pre">flask.get_flashed_messages()</span></tt></a> function.</p> +</dd></dl> + +<div class="admonition-the-jinja-context-behaviour admonition "> +<p class="first admonition-title">The Jinja Context Behaviour</p> +<p>These variables are added to the context of variables, they are not +global variables. The difference is that by default these will not +show up in the context of imported templates. This is partially caused +by performance considerations, partially to keep things explicit.</p> +<p>What does this mean for you? If you have a macro you want to import, +that needs to access the request object you have two possibilities:</p> +<ol class="arabic simple"> +<li>you explicitly pass the request to the macro as parameter, or +the attribute of the request object you are interested in.</li> +<li>you import the macro “with context”.</li> +</ol> +<p>Importing with context looks like this:</p> +<div class="last highlight-jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">from</span> <span class="s1">'_helpers.html'</span> <span class="k">import</span> <span class="nv">my_macro</span> <span class="k">with context</span> <span class="cp">%}</span><span class="x"></span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="standard-filters"> +<h2>Standard Filters<a class="headerlink" href="#standard-filters" title="Permalink to this headline">¶</a></h2> +<p>These filters are available in Jinja2 additionally to the filters provided +by Jinja2 itself:</p> +<dl class="function"> +<dt> +<tt class="descname">tojson</tt><big>(</big><big>)</big></dt> +<dd><p>This function converts the given object into JSON representation. This +is for example very helpful if you try to generate JavaScript on the +fly.</p> +<p>Note that inside <cite>script</cite> tags no escaping must take place, so make +sure to disable escaping with <tt class="docutils literal"><span class="pre">|safe</span></tt> if you intend to use it inside +<cite>script</cite> tags:</p> +<div class="highlight-html+jinja"><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">text/javascript</span><span class="nt">></span> + <span class="nx">doSomethingWith</span><span class="p">(</span><span class="cp">{{</span> <span class="nv">user.username</span><span class="o">|</span><span class="nf">tojson</span><span class="o">|</span><span class="nf">safe</span> <span class="cp">}}</span><span class="p">);</span> +<span class="nt"></script></span> +</pre></div> +</div> +<p>That the <tt class="docutils literal"><span class="pre">|tojson</span></tt> filter escapes forward slashes properly for you.</p> +</dd></dl> + +</div> +<div class="section" id="controlling-autoescaping"> +<h2>Controlling Autoescaping<a class="headerlink" href="#controlling-autoescaping" title="Permalink to this headline">¶</a></h2> +<p>Autoescaping is the concept of automatically escaping special characters +of you. Special characters in the sense of HTML (or XML, and thus XHTML) +are <tt class="docutils literal"><span class="pre">&</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">"</span></tt> as well as <tt class="docutils literal"><span class="pre">'</span></tt>. Because these characters +carry specific meanings in documents on their own you have to replace them +by so called “entities” if you want to use them for text. Not doing so +would not only cause user frustration by the inability to use these +characters in text, but can also lead to security problems. (see +<a class="reference internal" href="security.html#xss"><em>Cross-Site Scripting (XSS)</em></a>)</p> +<p>Sometimes however you will need to disable autoescaping in templates. +This can be the case if you want to explicitly inject HTML into pages, for +example if they come from a system that generate secure HTML like a +markdown to HTML converter.</p> +<p>There are three ways to accomplish that:</p> +<ul class="simple"> +<li>In the Python code, wrap the HTML string in a <a class="reference internal" href="api.html#flask.Markup" title="flask.Markup"><tt class="xref py py-class docutils literal"><span class="pre">Markup</span></tt></a> +object before passing it to the template. This is in general the +recommended way.</li> +<li>Inside the template, use the <tt class="docutils literal"><span class="pre">|safe</span></tt> filter to explicitly mark a +string as safe HTML (<tt class="docutils literal"><span class="pre">{{</span> <span class="pre">myvariable|safe</span> <span class="pre">}}</span></tt>)</li> +<li>Temporarily disable the autoescape system altogether.</li> +</ul> +<p>To disable the autoescape system in templates, you can use the <tt class="docutils literal"><span class="pre">{%</span> +<span class="pre">autoescape</span> <span class="pre">%}</span></tt> block:</p> +<div class="highlight-html+jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">autoescape</span> <span class="kp">false</span> <span class="cp">%}</span> + <span class="nt"><p></span>autoescaping is disabled here + <span class="nt"><p></span><span class="cp">{{</span> <span class="nv">will_not_be_escaped</span> <span class="cp">}}</span> +<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span> +</pre></div> +</div> +<p>Whenever you do this, please be very cautious about the variables you are +using in this block.</p> +</div> +<div class="section" id="registering-filters"> +<h2>Registering Filters<a class="headerlink" href="#registering-filters" title="Permalink to this headline">¶</a></h2> +<p>If you want to register your own filters in Jinja2 you have two ways to do +that. You can either put them by hand into the +<a class="reference internal" href="api.html#flask.Flask.jinja_env" title="flask.Flask.jinja_env"><tt class="xref py py-attr docutils literal"><span class="pre">jinja_env</span></tt></a> of the application or use the +<a class="reference internal" href="api.html#flask.Flask.template_filter" title="flask.Flask.template_filter"><tt class="xref py py-meth docutils literal"><span class="pre">template_filter()</span></tt></a> decorator.</p> +<p>The two following examples work the same and both reverse an object:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.template_filter</span><span class="p">(</span><span class="s">'reverse'</span><span class="p">)</span> +<span class="k">def</span> <span class="nf">reverse_filter</span><span class="p">(</span><span class="n">s</span><span class="p">):</span> + <span class="k">return</span> <span class="n">s</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> + +<span class="k">def</span> <span class="nf">reverse_filter</span><span class="p">(</span><span class="n">s</span><span class="p">):</span> + <span class="k">return</span> <span class="n">s</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> +<span class="n">app</span><span class="o">.</span><span class="n">jinja_env</span><span class="o">.</span><span class="n">filters</span><span class="p">[</span><span class="s">'reverse'</span><span class="p">]</span> <span class="o">=</span> <span class="n">reverse_filter</span> +</pre></div> +</div> +<p>In case of the decorator the argument is optional if you want to use the +function name as name of the filter.</p> +</div> +<div class="section" id="context-processors"> +<h2>Context Processors<a class="headerlink" href="#context-processors" title="Permalink to this headline">¶</a></h2> +<p>To inject new variables automatically into the context of a template +context processors exist in Flask. Context processors run before the +template is rendered and have the ability to inject new values into the +template context. A context processor is a function that returns a +dictionary. The keys and values of this dictionary are then merged with +the template context:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="nd">@app.context_processor</span> +<span class="k">def</span> <span class="nf">inject_user</span><span class="p">():</span> + <span class="k">return</span> <span class="nb">dict</span><span class="p">(</span><span class="n">user</span><span class="o">=</span><span class="n">g</span><span class="o">.</span><span class="n">user</span><span class="p">)</span> +</pre></div> +</div> +<p>The context processor above makes a variable called <cite>user</cite> available in +the template with the value of <cite>g.user</cite>. This example is not very +interesting because <cite>g</cite> is available in templates anyways, but it gives an +idea how this works.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"><p class="logo"><a href="index.html"> + <img class="logo" src="_static/flask.png" alt="Logo"/> +</a></p> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Templates</a><ul> +<li><a class="reference internal" href="#jinja-setup">Jinja Setup</a></li> +<li><a class="reference internal" href="#standard-context">Standard Context</a></li> +<li><a class="reference internal" href="#standard-filters">Standard Filters</a></li> +<li><a class="reference internal" href="#controlling-autoescaping">Controlling Autoescaping</a></li> +<li><a class="reference internal" href="#registering-filters">Registering Filters</a></li> +<li><a class="reference internal" href="#context-processors">Context Processors</a></li> +</ul> +</li> +</ul> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="tutorial/testing.html" title="previous chapter">Bonus: Testing the Application</a></li> + <li>Next: <a href="testing.html" title="next chapter">Testing Flask Applications</a></li> + </ul></li> +</ul> + <h3>This Page</h3> + <ul class="this-page-menu"> + <li><a href="_sources/templating.txt" + rel="nofollow">Show Source</a></li> + </ul> +<div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + © Copyright 2010, Armin Ronacher. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. + </div> + </body> +</html>
\ No newline at end of file |