Skip to content

Commit

Permalink
Clean up 'Extending the Builtin Templates' and move it to 'index' page.
Browse files Browse the repository at this point in the history
  • Loading branch information
@petrus-jvrensburg
petrus-jvrensburg committed Jul 5, 2015
1 parent 1084cfb commit e8f585d
Show file tree
Hide file tree
Showing 2 changed files with 85 additions and 97 deletions.
86 changes: 0 additions & 86 deletions doc/advanced.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,81 +3,6 @@ Advanced Functionality

.. _extending-builtin-templates:

Extending the Builtin Templates
---------------------------------

****

By default, Flask-Admin uses three pre-defined templates for displaying your models in the admin-interface:

* `admin/model/list.html`
* `admin/model/create.html`
* `admin/model/edit.html`

All three of these extend the `admin/master.html` template, and you can override them by defining your own templates,
with the same path relative to your `templates` folder.

You could also choose to extend these templates, rather than overriding them. In this case you will need to
point your classes at your own templates, rather than letting them use the defaults. For example, your own template
for the *edit* views could be defined in `templates/my_edit_template.html` to look something like::

{% extends 'admin/model/edit.html' %}

{% block tail %}
{{ super() }}
...
{% endblock %}

And your classes could be made to use this template by setting the appropriate class property::

class MyModelView(ModelView):
edit_template = 'my_edit_template.html'

The three available properties are simply called `list_template`, `create_template` and `edit_template`.

If you want to use your own base template, then pass the name of the template to
the admin constructor during initialization::

admin = Admin(app, base_template='my_master.html')

Available Template Blocks
****************************

Flask-Admin defines one *base* template at `admin/master.html` that all the other admin templates are derived
from. This template is a proxy which points to `admin/base.html`, which defines
the following blocks:

============== ========================================================================
Block Name Description
============== ========================================================================
head_meta Page metadata in the header
title Page title
head_css Various CSS includes in the header
head Empty block in HTML head, in case you want to put something there
page_body Page layout
brand Logo in the menu bar
main_menu Main menu
menu_links Links menu
access_control Section to the right of the menu (can be used to add login/logout buttons)
messages Alerts and various messages
body Content (that's where your view will be displayed)
tail Empty area below content
============== ========================================================================

In addition to all of the blocks that are inherited from `admin/master.html`, the `admin/model/list.html` template
also contains the following blocks:

======================= ============================================
Block Name Description
======================= ============================================
model_menu_bar Menu bar
model_list_table Table container
list_header Table header row
list_row_actions_header Actions header
list_row Single row
list_row_actions Row action cell with edit/remove/etc buttons
empty_list_message Message that will be displayed if there are no models found
======================= ============================================

Replacing Individual Form Fields
------------------------------------------
Expand Down Expand Up @@ -660,14 +585,3 @@ do with it, so it won't generate a form field. In this case, you would need to m
form_class.extra = TextField('Extra')
return form_class

Usage Tips
---------------

****

Initialisation: As an alternative to passing a Flask application object to the Admin constructor, you can also call the
:meth:`~flask_admin.base.Admin.init_app` function, after the Admin instance has been initialized::

admin = Admin(name='microblog', template_mode='bootstrap3')
# Add views here
admin.init_app(app)
96 changes: 85 additions & 11 deletions doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,8 @@ The first step, is to initialise an empty admin interface on your Flask app::

app.run()

Here, both the *name* and *template_mode* parameters are optional.
Here, both the *name* and *template_mode* parameters are optional. Alternatively,
you could use the :meth:`~flask_admin.base.Admin.init_app` method.

If you start this application and navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_,
you should see an empty page with a navigation bar on top.
Expand Down Expand Up @@ -380,6 +381,9 @@ Working with the builtin templates

Flask-Admin uses the `Jinja2 <http://jinja.pocoo.org/docs/>`_ templating engine.

Overriding the Builtin Templates
---------------------------------

To take full control over the style and layout of the admin interface, you can override
all of the builtin templates. Just keep in mind that the templates will change slightly
from one version of Flask-Admin to the next, so once you start overriding them, you
Expand All @@ -390,12 +394,83 @@ the Flask-Admin source into your project's `templates/admin/` directory.
As long as the filenames stay the same, the templates in your project directory should
automatically take precedence over the builtin ones.

Extending the Builtin Templates
---------------------------------

Rather than overriding the builtin templates completely, you could extend them. This
could make it simpler for you to upgrade to new Flask Admin versions in future.

Internally, the Flask-Admin templates are derived from the `admin/master.html` template.
The three most interesting templates for you to extend are probably:

* `admin/model/list.html`
* `admin/model/create.html`
* `admin/model/edit.html`

To extend the default *edit* template with your own functionality, create a template in
`templates/microblog_edit.html` to look something like::

{% extends 'admin/model/edit.html' %}

{% block body %}
<h1>MicroBlog Edit View</h1>
{{ super() }}
{% endblock %}

Now, to make your view classes use this template, set the appropriate class property::

class MicroBlogModelView(ModelView):
edit_template = 'microblog_edit.html'
# create_template = 'microblog_create.html'
# list_template = 'microblog_list.html'

If you want to use your own base template, then pass the name of the template to
the admin constructor during initialization::

admin = Admin(app, base_template='microblog_master.html')

Available Template Blocks
****************************

Flask-Admin defines one *base* template at `admin/master.html` that all the other admin templates are derived
from. This template is a proxy which points to `admin/base.html`, which defines
the following blocks:

============== ========================================================================
Block Name Description
============== ========================================================================
head_meta Page metadata in the header
title Page title
head_css Various CSS includes in the header
head Empty block in HTML head, in case you want to put something there
page_body Page layout
brand Logo in the menu bar
main_menu Main menu
menu_links Links menu
access_control Section to the right of the menu (can be used to add login/logout buttons)
messages Alerts and various messages
body Content (that's where your view will be displayed)
tail Empty area below content
============== ========================================================================

In addition to all of the blocks that are inherited from `admin/master.html`, the `admin/model/list.html` template
also contains the following blocks:

======================= ============================================
Block Name Description
======================= ============================================
model_menu_bar Menu bar
model_list_table Table container
list_header Table header row
list_row_actions_header Actions header
list_row Single row
list_row_actions Row action cell with edit/remove/etc buttons
empty_list_message Message that will be displayed if there are no models found
======================= ============================================

Have a look at the `layout` example at https://github.com/flask-admin/flask-admin/tree/master/examples/layout
to see how you can take full stylistic control over the admin interface.

See :ref:`extending-builtin-templates` for an alternative approach, that could make
life easier for you when upgrading to future versions of Flask-Admin.

Environment variables
---------------------

Expand All @@ -412,12 +487,10 @@ _ngettext Babel ngettext
h Helpers from :mod:`~flask_admin.helpers` module
==================== ================================

****

Generating URLs
------------------

To get the URL for a specific view, use *url_for* with a dot prefix::
To generate the URL for a specific view, use *url_for* with a dot prefix::

from flask import url_for

Expand All @@ -435,13 +508,14 @@ A specific record can also be referenced with::

When referencing ModelView instances, use the lowercase name of the model as the
prefix when calling *url_for*. Other views can be referenced by specifying a
unique endpoint for each, and using that as the prefix. So, to referece::
unique endpoint for each, and using that as the prefix. So, you could use::

admin.add_view(CustomView(name='Analytics', endpoint='analytics'))
url_for('analytics.index')

Use::
If your view endpoint was defined like::

admin.add_view(CustomView(name='Analytics', endpoint='analytics'))

url_for('analytics.index')

Further Reading
==================
Expand Down

0 comments on commit e8f585d

Please sign in to comment.