Documentation update

doc/api/index.rst

@@ -8,6 +8,7 @@ API
    mod_model
    mod_form
    mod_tools
+   mod_actions
 
    mod_contrib_sqlamodel
    mod_contrib_mongoengine

doc/api/mod_actions.rst

+``flask.ext.admin.actions``
+===========================
+
+.. automodule:: flask.ext.admin.actions
+
+    .. autofunction:: action
+
+    .. autoclass:: ActionsMixin
+        :members:

doc/django_migration.rst

+Migrating from Django
+=====================
+
+If you used `Django <https://www.djangoproject.com/>`_ before, you might find Flask-Admin work slightly different than you expect.
+
+This guide will help you to get acquainted with the Flask-Admin library. Some prior Flask knowledge will be required.
+
+Architecture
+------------
+
+Django does lots of things automatically. For example, it is importing models from the `models.py`, administrative interface
+declarations from `admin.py` and so on.
+
+Flask philosophy is slightly different - explicit is better than implicit. If something should be initialized, it should be
+initialized by the developer.
+
+Flask-Admin follows this convention. It is up for you, as a developer, to tell Flask-Admin what should be displayed and how.
+
+Sometimes this will require writing a bit of boilerplate code, but it will pay off in the future, especially if you
+will have to implement some custom logic.
+
+All Flask-Admin functionality is incapsulated into classes with view methods. Class should be instantiated and plugged to the
+administrative framework for its views to be accessible by the users. Nothing prevents from creating more than one instance
+of the class and plug them using different base URL - it will work as expected.
+
+Another big difference - Flask-Admin is not built around model CRUD interface. CRUD is just extension of the base administrative
+framework. In a nutshell, it is just a class which accepts model in its constructor and exposes few views (list, create, edit, etc).
+And as Flask-Admin supports more than one ORM (SQLAlchemy, MongoEngine, Peewee, raw pymongo), developer can mix different model
+types in one application by instantiating appropriate CRUD classes.
+
+Getting started
+---------------
+
+Lets write a bit of code to create CRUD interface for `Post` SQLAlchemy model. This example uses Flask-SQLAlchemy extension,
+but you don't have to use it, Flask-Admin will work with SQLAlchemy declarative extension too. To the code::
+
+    from flask import Flask
+    from flask.ext.admin import Admin
+    from flask.ext.admin.contrib.sqlamodel import ModelView
+    from flask.ext.sqlalchemy import SQLAlchemy
+
+    app = Flask(__name__)
+    db = SQLAlchemy(app)
+
+    class Post(db.Model):
+        id = db.Column(db.Integer, primary_key=True)
+        title = db.Column(db.Unicode(120))
+        text = db.Column(db.UnicodeText, nullable=False)
+
+    admin = Admin(app)
+    admin.add_view(ModelView(Post, db.session))
+
+You can customize behavior of CRUD interface by using special properties, like Django does::
+
+    # ... imports
+
+    class PostView(ModelView):
+        list_columns = ('title',)
+
+        def __init__(self):
+            super(PostView, self).__init__(Post, db.session)
+
+    # ... initialization
+
+    admin.add_view(PostView())
+
+But because administrative interface is implemented as class, you can customize it in constructor as well::
+
+    class PostView(ModelView):
+        list_columns = ('title',)
+
+        def __init__(self, include_id=False):
+            if include_id:
+                self.list_columns = ('id', 'title')
+
+            super(PostView, self).__init__(Post, db.session)
+
+Here is comparison table between some Django configuration properties and Flask-Admin SQLAlchemy backend properties:
+
+=========================================== ==============================================
+Django                                      Flask-Admin
+=========================================== ==============================================
+actions										:doc:`api/mod_actions`
+exclude										:attr:`~flask.ext.admin.model.BaseModelView.form_excluded_columns`
+fields										:attr:`~flask.ext.admin.model.BaseModelView.form_columns`
+form 										:attr:`~flask.ext.admin.model.BaseModelView.form`
+formfield_overrides 						:attr:`~flask.ext.admin.model.BaseModelView.form_args`
+inlines										:attr:`~flask.ext.admin.contrib.sqlalchemy.ModelView.inline_models`
+list_display 								:attr:`~flask.ext.admin.model.BaseModelView.column_list`
+list_filter									:attr:`~flask.ext.admin.contrib.sqlalchemy.ModelView.column_filters`
+list_per_page 								:attr:`~flask.ext.admin.model.BaseModelView.page_size`
+search_fields								:attr:`~flask.ext.admin.model.BaseModelView.column_searchable_list`
+add_form_template							:attr:`~flask.ext.admin.model.BaseModelView.create_template`
+change_form_template						:attr:`~flask.ext.admin.model.BaseModelView.change_form_template`
+=========================================== ==============================================
+
+You might want to check :doc:`api/mod_model` for basic model configuration options (reused by all model
+backends) and specific backend documentation, for example :doc:`api/mod_contrib_sqlamodel`. There's much more
+than displayed in this table.
+
+Authentication
+--------------
+
+If you need to restrict access to the administrative interface, you need to override `is_accessible` method. For example::
+
+    class MyModelView(ModelView):
+        def is_accessible(self):
+            return login.current_user.is_authenticated()
+
+If administrative piece is not accessible by the user, it won't be displayed in the menu as well.
+
+Templates
+---------
+
+Flask-Admin uses Jinja2 templating engine. Jinja2 is pretty advanced templating engine and Flask-Admin templates were made
+to be easily extensible.
+
+For example, if you need to include javascript snippet on edit page for your model, it is easy to do::
+
+    {% extends 'admin/model/edit.html' %}
+
+    {% block tail %}
+        {{ super() }}
+        <script language="javascript">alert('Hello World!')</script>
+    {% endblock %}
+
+And then point your class to this new template::
+
+    class MyModelView(ModelView):
+        edit_template = 'my_edit_template.html'
+
+For list of template blocks, check :doc:`templates`.
+
+Tips and hints
+--------------
+
+ 1. Programming with Flask-Admin is not very different from normal application development - write some views, expose
+    them to the user in constistent user interface.
+
+ 2. If you're missing some functionality which can be used more than once, you can create your own "base" class and use
+    it instead of default implementation
+
+ 3. Due to more advanced templating engine, you can easily extend existing templates. You can even change look and feel
+    of the administrative UI completely, if you want to. Check `this example <https://github.com/mrjoes/flask-admin/tree/master/examples/layout>`_.
+
+ 4. You're not limited to CRUD interface. Want to add some kind of realtime monitoring via websockets? No problem at all
+
+ 5. There's so called "index view". By default it is empty, but you can put any information you need there. It is displayed
+    under Home menu option.
+

doc/index.rst

@@ -7,6 +7,7 @@ Flask-Admin is simple and extensible administrative interface framework for `Fla
    :maxdepth: 2
 
    quickstart
+   django_migration
    templates
    tips
    db

doc/quickstart.rst

@@ -203,7 +203,9 @@ is not provided. Model-based views will be explained in the next section.
 Model Views
 -----------
 
-Flask-Admin comes with built-in SQLAlchemy model administrative interface. It is very easy to use::
+Flask-Admin comes with built-in few ORM backends.
+
+Lets pick SQLAlchemy backend. It is very easy to use::
 
     from flask.ext.admin.contrib.sqlamodel import ModelView
 

doc/templates.rst

@@ -16,10 +16,11 @@ Flask Core
 
 All Flask-Admin templates should derive from `admin/master.html`.
 
-`admin/master.html` contains following blocks:
+`admin/master.html` is a proxy which points to `admin/base.html`. It contains following blocks:
 
 ============= ========================================================================
 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
@@ -38,6 +39,8 @@ There are 3 main templates that are used to display models:
 `admin/model/list.html` is list view template and contains following blocks:
 
 ================= ============================================
+model_menu_bar    Menu bar
+model_list_table  Table container
 list_header       Table header row
 list_row          Row block
 list_row_actions  Row action cell with edit/remove/etc buttons
@@ -51,8 +54,8 @@ 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.
 
-For example, if you want to override `admin/master.html`, create `admin/templates/admin/master.html` in your application and it will be used instead of
-original `admin/master.html` found in Flask-Admin package.
+If you need to override master template, you can pass template name to the `Admin` constructor::
 
-If you don't want to replace template completely, you can create new template, derive it from existing template, override one or more blocks and
-tell Flask-Admin to use it. For model view, there is `list_template` and related properties.
+    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.