From 0313c8b24a40d016e6b64495ce72ed912ce0fc24 Mon Sep 17 00:00:00 2001 From: Ron DuPlain Date: Wed, 8 Jun 2011 08:20:42 -0400 Subject: [PATCH] Expand documentation on blueprints. --- docs/blueprints.rst | 61 ++++++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/docs/blueprints.rst b/docs/blueprints.rst index 9d429df1..04ab0d8b 100644 --- a/docs/blueprints.rst +++ b/docs/blueprints.rst @@ -5,42 +5,51 @@ Modular Applications with Blueprints .. versionadded:: 0.7 -Flask knows a concept known as “blueprints” which can greatly simplify how -large applications work. A blueprint is an object works similar to an -actual :class:`Flask` application object, but it is not actually an -application. Rather it is the blueprint of how to create an application. -Think of it like that: you might want to have an application that has a -wiki. So what you can do is creating the blueprint for a wiki and then -let the application assemble the wiki on the application object. +Flask uses a concept of *blueprints* 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 :class:`Blueprint` object works similarly to a :class:`Flask` +application object, but it is not actually an application. Rather it is a +*blueprint* of how to construct or extend an application. Why Blueprints? --------------- -Why have blueprints and not multiple application objects? The utopia of -pluggable applications are different WSGI applications and merging them -together somehow. You can do that (see :ref:`app-dispatch`) but it's not -the right tool for every case. Having different applications means having -different configs. Applications are also separated on the WSGI layer -which is a lot lower level than the level that Flask usually operates on -where you have request and response objects. +Blueprints in Flask are intended for these cases: -Blueprints do not necessarily have to implement applications. They could -only provide filters for templates, static files, templates or similar -things. They share the same config as the application and can change the -application as necessary when being registered. +* 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. +* Register a blueprint on an application at a URL prefix and/or subdomain. + Paremeters in the URL prefix/subdomain become common view arguments + (with defaults) across all view functions in the blueprint. +* Register a blueprint multiple times on an application with different URL + rules. +* Provide template filters, static files, templates, and other utilities + through blueprints. A blueprint does not have to implement applications + or view functions. +* Register a blueprint on an application for any of these cases when + initializing a Flask extension. -The downside is that you cannot unregister a blueprint once application -without having to destroy the whole application object. +A blueprint in Flask is not a pluggable app because it is not actually an +application -- it'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 :ref:`app-dispatch`), but your applications +will have separate configs and will be managed at the WSGI layer. + +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 application without having to destroy the whole application object. The Concept of Blueprints ------------------------- -The basic concept of blueprints is that they record operations that should -be executed when the blueprint is registered on the application. However -additionally each time a request gets dispatched to a view that was -declared to a blueprint Flask will remember that the request was -dispatched to that blueprint. That way it's easier to generate URLs from -one endpoint to another in the same module. +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. My First Blueprint ------------------