diff --git a/docs/blueprints.rst b/docs/blueprints.rst index 9d429df1..8a83128d 100644 --- a/docs/blueprints.rst +++ b/docs/blueprints.rst @@ -57,6 +57,94 @@ implement a blueprint that does simple rendering of static templates:: @simple_page.route('/') def show(page): try: - return render_template('simple_pages/%s.html' % page) + return render_template('pages/%s.html' % page) except TemplateNotFound: abort(404) + +When you bind a function with the help of the ``@simple_page.route`` +decorator the blueprint will record the intention of registering the +function `show` on the application when it's later registered. +Additionally it will prefix the endpoint of the function with the +name of the blueprint which was given to the :class:`Blueprint` +constructor (in this case also ``simple_page``). + +So how do you register that blueprint? Like this:: + + from flask import Flask + from yourapplication.simple_page import simple_page + + app = Flask(__name__) + app.register_blueprint(simple_page) + +If you check the rules registered on the application, you will find +these:: + + [' (HEAD, OPTIONS, GET) -> static>, + ' (HEAD, OPTIONS, GET) -> simple_page.show>, + simple_page.show>] + +The first one is obviously from the application ifself for the static +files. The other two are for the `show` function of the ``simple_page`` +blueprint. As you can see, they are also prefixed with the name of the +blueprint and separated by a dot (``.``). + +Blueprint Resources +------------------- + +Blueprints can provide resources as well. Sometimes you might want to +introduce a blueprint only for the resources it provides. + +Blueprint Resource Folder +````````````````````````` + +Like for regular applications, blueprints are considered to be contained +in a folder. While multiple blueprints can origin from the same folder, +it does not have to be the case and it's usually not recommended. + +The folder is infered from the second argument to :class:`Blueprint` which +is ususally `__name__`. 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's a module, the package the module is contained in +will be the resource folder. You can access the +:attr:`Blueprint.root_path` property to see what's the resource folder:: + + >>> simple_page.root_path + '/Users/username/TestProject/yourapplication' + +To quickly open sources from this folder you can use the +:meth:`~Blueprint.open_resource` function:: + + with simple_page.open_resource('static/style.css') as f: + code = f.read() + +Static Files +```````````` + +A blueprint can expose a folder with static files by providing a path to a +folder on the filesystem via the `static_folder` keyword argument. It can +either be an absolute path or one relative to the folder of the +blueprint:: + + admin = Blueprint('admin', __name__, static_folder='static') + +By default the rightmost part of the path is where it is exposed on the +web. Because the folder is called ``static`` here it will be available at +the location of the blueprint + ``/static``. Say the blueprint is +registered for ``/admin`` the static folder will be at ``/admin/static``. + +The endpoint is named `blueprint_name.static` so you can generate URLs to +it like you would do to the static folder of the application:: + + url_for('admin.static', filename='style.css') + +Templates +````````` + +If you want the blueprint to expose templates you can do that by providing +the `template_folder` parameter to the :class:`Blueprint` constructor:: + + admin = Blueprint('admin', __name__, template_folder='templates') + +As for static files, the path can be absolute or relative to the blueprint +resource folder.