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, 0 insertions, 293 deletions
diff --git a/app/static/doc/flask-docs/templating.html b/app/static/doc/flask-docs/templating.html deleted file mode 100644 index 4aedfbe..0000000 --- a/app/static/doc/flask-docs/templating.html +++ /dev/null @@ -1,293 +0,0 @@ - -<!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 |