Web   ·   Wiki   ·   Activities   ·   Blog   ·   Lists   ·   Chat   ·   Meeting   ·   Bugs   ·   Git   ·   Translate   ·   Archive   ·   People   ·   Donate
summaryrefslogtreecommitdiffstats
path: root/app/static/doc/flask-docs/blueprints.html
blob: 271aa3d1bf976c9cec769f33b10f4301e90752f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306

<!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>Modular Applications with Blueprints &mdash; 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="Flask Extensions" href="extensions.html" />
    <link rel="prev" title="The Request Context" href="reqcontext.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="extensions.html" title="Flask Extensions"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="reqcontext.html" title="The Request Context"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Flask 0.8 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="modular-applications-with-blueprints">
<span id="blueprints"></span><h1>Modular Applications with Blueprints<a class="headerlink" href="#modular-applications-with-blueprints" title="Permalink to this headline">¶</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version 0.7.</span></p>
<p>Flask uses a concept of <em>blueprints</em> for making application components and
supporting common patterns within an application or across applications.
Blueprints can greatly simplify how large applications work and provide a
central means for Flask extensions to register operations on applications.
A <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt> object works similarly to a <tt class="xref py py-class docutils literal"><span class="pre">Flask</span></tt>
application object, but it is not actually an application.  Rather it is a
<em>blueprint</em> of how to construct or extend an application.</p>
<div class="section" id="why-blueprints">
<h2>Why Blueprints?<a class="headerlink" href="#why-blueprints" title="Permalink to this headline">¶</a></h2>
<p>Blueprints in Flask are intended for these cases:</p>
<ul class="simple">
<li>Factor an application into a set of blueprints.  This is ideal for
larger applications; a project could instantiate an application object,
initialize several extensions, and register a collection of blueprints.</li>
<li>Register a blueprint on an application at a URL prefix and/or subdomain.
Parameters in the URL prefix/subdomain become common view arguments
(with defaults) across all view functions in the blueprint.</li>
<li>Register a blueprint multiple times on an application with different URL
rules.</li>
<li>Provide template filters, static files, templates, and other utilities
through blueprints.  A blueprint does not have to implement applications
or view functions.</li>
<li>Register a blueprint on an application for any of these cases when
initializing a Flask extension.</li>
</ul>
<p>A blueprint in Flask is not a pluggable app because it is not actually an
application &#8211; it&#8217;s a set of operations which can be registered on an
application, even multiple times.  Why not have multiple application
objects?  You can do that (see <a class="reference internal" href="patterns/appdispatch.html#app-dispatch"><em>Application Dispatching</em></a>), but your applications
will have separate configs and will be managed at the WSGI layer.</p>
<p>Blueprints instead provide separation at the Flask level, share
application config, and can change an application object as necessary with
being registered. The downside is that you cannot unregister a blueprint
once an application was created without having to destroy the whole
application object.</p>
</div>
<div class="section" id="the-concept-of-blueprints">
<h2>The Concept of Blueprints<a class="headerlink" href="#the-concept-of-blueprints" title="Permalink to this headline">¶</a></h2>
<p>The basic concept of blueprints is that they record operations to execute
when registered on an application.  Flask associates view functions with
blueprints when dispatching requests and generating URLs from one endpoint
to another.</p>
</div>
<div class="section" id="my-first-blueprint">
<h2>My First Blueprint<a class="headerlink" href="#my-first-blueprint" title="Permalink to this headline">¶</a></h2>
<p>This is what a very basic blueprint looks like.  In this case we want to
implement a blueprint that does simple rendering of static templates:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Blueprint</span><span class="p">,</span> <span class="n">render_template</span><span class="p">,</span> <span class="n">abort</span>
<span class="kn">from</span> <span class="nn">jinja2</span> <span class="kn">import</span> <span class="n">TemplateNotFound</span>

<span class="n">simple_page</span> <span class="o">=</span> <span class="n">Blueprint</span><span class="p">(</span><span class="s">&#39;simple_page&#39;</span><span class="p">,</span> <span class="n">__name__</span><span class="p">)</span>

<span class="nd">@simple_page.route</span><span class="p">(</span><span class="s">&#39;/&#39;</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;page&#39;</span><span class="p">:</span> <span class="s">&#39;index&#39;</span><span class="p">})</span>
<span class="nd">@simple_page.route</span><span class="p">(</span><span class="s">&#39;/&lt;page&gt;&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">show</span><span class="p">(</span><span class="n">page</span><span class="p">):</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">render_template</span><span class="p">(</span><span class="s">&#39;pages/</span><span class="si">%s</span><span class="s">.html&#39;</span> <span class="o">%</span> <span class="n">page</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">TemplateNotFound</span><span class="p">:</span>
        <span class="n">abort</span><span class="p">(</span><span class="mi">404</span><span class="p">)</span>
</pre></div>
</div>
<p>When you bind a function with the help of the <tt class="docutils literal"><span class="pre">&#64;simple_page.route</span></tt>
decorator the blueprint will record the intention of registering the
function <cite>show</cite> on the application when it&#8217;s later registered.
Additionally it will prefix the endpoint of the function with the
name of the blueprint which was given to the <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt>
constructor (in this case also <tt class="docutils literal"><span class="pre">simple_page</span></tt>).</p>
</div>
<div class="section" id="registering-blueprints">
<h2>Registering Blueprints<a class="headerlink" href="#registering-blueprints" title="Permalink to this headline">¶</a></h2>
<p>So how do you register that blueprint?  Like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flask</span> <span class="kn">import</span> <span class="n">Flask</span>
<span class="kn">from</span> <span class="nn">yourapplication.simple_page</span> <span class="kn">import</span> <span class="n">simple_page</span>

<span class="n">app</span> <span class="o">=</span> <span class="n">Flask</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">register_blueprint</span><span class="p">(</span><span class="n">simple_page</span><span class="p">)</span>
</pre></div>
</div>
<p>If you check the rules registered on the application, you will find
these:</p>
<div class="highlight-python"><pre>[&lt;Rule '/static/&lt;filename&gt;' (HEAD, OPTIONS, GET) -&gt; static&gt;,
 &lt;Rule '/&lt;page&gt;' (HEAD, OPTIONS, GET) -&gt; simple_page.show&gt;,
 &lt;Rule '/' (HEAD, OPTIONS, GET) -&gt; simple_page.show&gt;]</pre>
</div>
<p>The first one is obviously from the application ifself for the static
files.  The other two are for the <cite>show</cite> function of the <tt class="docutils literal"><span class="pre">simple_page</span></tt>
blueprint.  As you can see, they are also prefixed with the name of the
blueprint and separated by a dot (<tt class="docutils literal"><span class="pre">.</span></tt>).</p>
<p>Blueprints however can also be mounted at different locations:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">register_blueprint</span><span class="p">(</span><span class="n">simple_page</span><span class="p">,</span> <span class="n">url_prefix</span><span class="o">=</span><span class="s">&#39;/pages&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>And sure enough, these are the generated rules:</p>
<div class="highlight-python"><pre>[&lt;Rule '/static/&lt;filename&gt;' (HEAD, OPTIONS, GET) -&gt; static&gt;,
 &lt;Rule '/pages/&lt;page&gt;' (HEAD, OPTIONS, GET) -&gt; simple_page.show&gt;,
 &lt;Rule '/pages/' (HEAD, OPTIONS, GET) -&gt; simple_page.show&gt;]</pre>
</div>
<p>On top of that you can register blueprints multiple times though not every
blueprint might respond properly to that.  In fact it depends on how the
blueprint is implemented if it can be mounted more than once.</p>
</div>
<div class="section" id="blueprint-resources">
<h2>Blueprint Resources<a class="headerlink" href="#blueprint-resources" title="Permalink to this headline">¶</a></h2>
<p>Blueprints can provide resources as well.  Sometimes you might want to
introduce a blueprint only for the resources it provides.</p>
<div class="section" id="blueprint-resource-folder">
<h3>Blueprint Resource Folder<a class="headerlink" href="#blueprint-resource-folder" title="Permalink to this headline">¶</a></h3>
<p>Like for regular applications, blueprints are considered to be contained
in a folder.  While multiple blueprints can originate from the same folder,
it does not have to be the case and it&#8217;s usually not recommended.</p>
<p>The folder is inferred from the second argument to <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt> which
is usually <cite>__name__</cite>.  This argument specifies what logical Python
module or package corresponds to the blueprint.  If it points to an actual
Python package that package (which is a folder on the filesystem) is the
resource folder.  If it&#8217;s a module, the package the module is contained in
will be the resource folder.  You can access the
<tt class="xref py py-attr docutils literal"><span class="pre">Blueprint.root_path</span></tt> property to see what the resource folder is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">simple_page</span><span class="o">.</span><span class="n">root_path</span>
<span class="go">&#39;/Users/username/TestProject/yourapplication&#39;</span>
</pre></div>
</div>
<p>To quickly open sources from this folder you can use the
<tt class="xref py py-meth docutils literal"><span class="pre">open_resource()</span></tt> function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">simple_page</span><span class="o">.</span><span class="n">open_resource</span><span class="p">(</span><span class="s">&#39;static/style.css&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
    <span class="n">code</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="static-files">
<h3>Static Files<a class="headerlink" href="#static-files" title="Permalink to this headline">¶</a></h3>
<p>A blueprint can expose a folder with static files by providing a path to a
folder on the filesystem via the <cite>static_folder</cite> keyword argument.  It can
either be an absolute path or one relative to the folder of the
blueprint:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">admin</span> <span class="o">=</span> <span class="n">Blueprint</span><span class="p">(</span><span class="s">&#39;admin&#39;</span><span class="p">,</span> <span class="n">__name__</span><span class="p">,</span> <span class="n">static_folder</span><span class="o">=</span><span class="s">&#39;static&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>By default the rightmost part of the path is where it is exposed on the
web.  Because the folder is called <tt class="docutils literal"><span class="pre">static</span></tt> here it will be available at
the location of the blueprint + <tt class="docutils literal"><span class="pre">/static</span></tt>.  Say the blueprint is
registered for <tt class="docutils literal"><span class="pre">/admin</span></tt> the static folder will be at <tt class="docutils literal"><span class="pre">/admin/static</span></tt>.</p>
<p>The endpoint is named <cite>blueprint_name.static</cite> so you can generate URLs to
it like you would do to the static folder of the application:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">&#39;admin.static&#39;</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s">&#39;style.css&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="templates">
<h3>Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h3>
<p>If you want the blueprint to expose templates you can do that by providing
the <cite>template_folder</cite> parameter to the <tt class="xref py py-class docutils literal"><span class="pre">Blueprint</span></tt> constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">admin</span> <span class="o">=</span> <span class="n">Blueprint</span><span class="p">(</span><span class="s">&#39;admin&#39;</span><span class="p">,</span> <span class="n">__name__</span><span class="p">,</span> <span class="n">template_folder</span><span class="o">=</span><span class="s">&#39;templates&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>As for static files, the path can be absolute or relative to the blueprint
resource folder.  The template folder is added to the searchpath of
templates but with a lower priority than the actual application&#8217;s template
folder.  That way you can easily override templates that a blueprint
provides in the actual application.</p>
<p>So if you have a blueprint in the folder <tt class="docutils literal"><span class="pre">yourapplication/admin</span></tt> and you
want to render the template <tt class="docutils literal"><span class="pre">'admin/index.html'</span></tt> and you have provided
<tt class="docutils literal"><span class="pre">templates</span></tt> as a <cite>template_folder</cite> you will have to create a file like
this: <tt class="docutils literal"><span class="pre">yourapplication/admin/templates/admin/index.html</span></tt>.</p>
</div>
</div>
<div class="section" id="building-urls">
<h2>Building URLs<a class="headerlink" href="#building-urls" title="Permalink to this headline">¶</a></h2>
<p>If you want to link from one page to another you can use the
<tt class="xref py py-func docutils literal"><span class="pre">url_for()</span></tt> function just like you normally would do just that you
prefix the URL endpoint with the name of the blueprint and a dot (<tt class="docutils literal"><span class="pre">.</span></tt>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">&#39;admin.index&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Additionally if you are in a view function of a blueprint or a rendered
template and you want to link to another endpoint of the same blueprint,
you can use relative redirects by prefixing the endpoint with a dot only:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url_for</span><span class="p">(</span><span class="s">&#39;.index&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>This will link to <tt class="docutils literal"><span class="pre">admin.index</span></tt> for instance in case the current request
was dispatched to any other admin blueprint endpoint.</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="#">Modular Applications with Blueprints</a><ul>
<li><a class="reference internal" href="#why-blueprints">Why Blueprints?</a></li>
<li><a class="reference internal" href="#the-concept-of-blueprints">The Concept of Blueprints</a></li>
<li><a class="reference internal" href="#my-first-blueprint">My First Blueprint</a></li>
<li><a class="reference internal" href="#registering-blueprints">Registering Blueprints</a></li>
<li><a class="reference internal" href="#blueprint-resources">Blueprint Resources</a><ul>
<li><a class="reference internal" href="#blueprint-resource-folder">Blueprint Resource Folder</a></li>
<li><a class="reference internal" href="#static-files">Static Files</a></li>
<li><a class="reference internal" href="#templates">Templates</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-urls">Building URLs</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="reqcontext.html" title="previous chapter">The Request Context</a></li>
      <li>Next: <a href="extensions.html" title="next chapter">Flask Extensions</a></li>
  </ul></li>
</ul>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/blueprints.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">
      &copy; Copyright 2010, Armin Ronacher.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>