Upades to 'templates' page.

doc/templates.rst

@@ -5,7 +5,7 @@ One great advantage of building an extension on top of Flask, is the great templ
 comes with the package. Jinja2 allows you to use most of the Python syntax that you are used to, inside
 of your templates, helping you generate either text or code in a powerful, yet flexible way.
 
-To get explore some more of what Jinja2 can offer you, head over to their documentation at
+To explore some more of what Jinja2 can offer you, head over to their documentation at
 `http://jinja.pocoo.org/docs/ <http://jinja.pocoo.org/docs/>`_. But the most important features for you to
 understand in order to get started with Flask-Admin are given below.
 
@@ -38,7 +38,11 @@ When a block is defined in a parent template, it can already be given some conte
 will be rendered in that place, even if a child template chooses to ignore that block completely.
 
 If content is defined in a child template, you have the option of also rendering the code that the parent template
-may have defined in that block. But the default behaviour is to simply override the block completely.
+may have defined in that block by calling::
+
+ {{ super() }}
+
+anywhere inside that block. But the default behaviour is to simply override the block entirely.
 
 Since these template blocks are defined by name, you have a lot of freedom in how you decide to arrange / nest them
 in your code.
@@ -67,38 +71,52 @@ body           Content (that's where your view will be displayed)
 tail           Empty area below content
 ============== ========================================================================
 
-Index Page
-----------
+Adding an Index Page
+--------------------
 
 You'll notice that the 'Home' page that is created by Flask-Admin at `/admin` is largely empty. By default, the
 only content on the page is a set of controls for navigating to the views that you have defined. You can change this by
 creating a template at `admin/index.html` in your `templates` directory.
 
-Models
-------
+Working with your Models
+------------------------
 
-There are 3 main templates that are used to display models:
+By default, Flask-Admin uses three pre-defined templates for displaying your models in the admin-interface:
 
-`admin/model/list.html` is list view template and contains following blocks:
+* `admin/model/list.html`
+* `admin/model/create.html`
+* `admin/model/edit.html`
 
-======================= ============================================
-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
-======================= ============================================
+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`.
 
-`admin/model/create.html` and `admin/model/edit.html` are used to display model creation editing forms respectively. They don't contain any custom
-blocks and if you want to change something, you can do it using any of the blocks found in `admin/master.html`.
 
 Environment variables
 ---------------------
 
-There are few variables and methods that are always accessible in administrative templates:
+While working in any of the templates that extend `admin/master.html`, you have access to a small number of
+environment variables:
 
+==================== ================================
+Variable Name        Description
 ==================== ================================
 admin_view           Current administrative view
 admin_base_template  Base template name
@@ -111,10 +129,25 @@ h                    Helpers from :mod:`~flask.ext.admin.helpers` module
 Customizing templates
 ---------------------
 
-You can override any used template in your Flask application by creating template with same name and relative path in your main `templates` directory.
+As noted earlier, you can override any default Flask-Admin template by creating your own template with same name and
+relative path inside your own `templates` directory.
 
-If you need to override master template, you can pass template name to the `Admin` constructor::
+You can also override the master template, but then you need to pass your own template name to the `Admin`
+constructor::
 
     admin = Admin(app, base_template='my_master.html')
 
-For model views, use `list_template`, `create_template` and `edit_template` properties to use non-default template.
+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
+======================= ============================================
\ No newline at end of file