Documentation update

doc/api/index.rst

@@ -12,4 +12,5 @@ API
    mod_contrib_sqlamodel
    mod_contrib_mongoengine
    mod_contrib_peeweemodel
+   mod_contrib_pymongo
    mod_contrib_fileadmin
\ No newline at end of file

doc/api/mod_contrib_mongoengine.rst

@@ -8,14 +8,13 @@ MongoEngine model backend implementation.
     .. autoclass:: ModelView
         :members:
         :inherited-members:
-        :exclude-members: hide_backrefs, auto_select_related, list_select_related,
-                          searchable_columns, filter_converter, fast_mass_delete,
-                          inline_model_form_converter, inline_models, model_form_conveter,
-                          list_type_formatters
+        :exclude-members: column_filters, column_type_formatter,
+                          filter_converter, model_form_converter
 
-        Class inherits configuration options from :class:`~flask.ext.admin.model.BaseModelView` and they're not displayed here.
 
-        .. autoattribute:: searchable_columns
+		Class inherits configuration options from :class:`~flask.ext.admin.model.BaseModelView` and they're not displayed here.
+
+        .. autoattribute:: column_filters
+        .. autoattribute:: column_type_formatters
         .. autoattribute:: filter_converter
         .. autoattribute:: model_form_converter
-        .. autoattribute:: list_type_formatters
\ No newline at end of file

doc/api/mod_contrib_peeweemodel.rst

@@ -8,15 +8,14 @@ Peewee model backend implementation.
     .. autoclass:: ModelView
         :members:
         :inherited-members:
-        :exclude-members: hide_backrefs, auto_select_related, list_select_related,
-                          searchable_columns, filter_converter, fast_mass_delete,
-                          inline_model_form_converter, inline_models, model_form_conveter
+        :exclude-members: column_filters, filter_converter, model_form_converter,
+                          inline_model_form_converter, fast_mass_delete, inline_models
 
         Class inherits configuration options from :class:`~flask.ext.admin.model.BaseModelView` and they're not displayed here.
 
-        .. autoattribute:: searchable_columns
+        .. autoattribute:: column_filters
         .. autoattribute:: filter_converter
+        .. autoattribute:: model_form_converter
+        .. autoattribute:: inline_model_form_converter
         .. autoattribute:: fast_mass_delete
         .. autoattribute:: inline_models
-        .. autoattribute:: inline_model_form_converter
-        .. autoattribute:: model_form_converter

doc/api/mod_contrib_pymongo.rst

+``flask.ext.admin.contrib.pymongo``
+===================================
+
+PyMongo model backend implementation.
+
+.. automodule:: flask.ext.admin.contrib.pymongo
+
+    .. autoclass:: ModelView
+        :members:
+        :inherited-members:
+        :exclude-members: column_filters
+
+		Class inherits configuration options from :class:`~flask.ext.admin.model.BaseModelView` and they're not displayed here.
+
+        .. autoattribute:: column_filters

doc/api/mod_contrib_sqlamodel.rst

@@ -8,21 +8,21 @@ SQLAlchemy model backend implementation.
     .. autoclass:: ModelView
         :members:
         :inherited-members:
-        :exclude-members: hide_backrefs, auto_select_related, list_select_related,
-                          searchable_columns, filter_converter,
-                          fast_mass_delete, inline_models, column_filters,
-                          inline_model_form_converter, model_form_converter
-
+        :exclude-members: column_hide_backrefs, column_auto_select_related,
+                          column_select_related_list, column_searchable_list,
+                          column_filters, filter_converter, model_form_converter,
+                          inline_model_form_converter, fast_mass_delete,
+                          inline_models
 
         Class inherits configuration options from :class:`~flask.ext.admin.model.BaseModelView` and they're not displayed here.
 
-        .. autoattribute:: hide_backrefs
-        .. autoattribute:: auto_select_related
-        .. autoattribute:: list_select_related
-        .. autoattribute:: searchable_columns
+        .. autoattribute:: column_hide_backrefs
+        .. autoattribute:: column_auto_select_related
+        .. autoattribute:: column_select_related_list
+        .. autoattribute:: column_searchable_list
+        .. autoattribute:: column_filters
         .. autoattribute:: filter_converter
         .. autoattribute:: model_form_converter
         .. autoattribute:: inline_model_form_converter
         .. autoattribute:: fast_mass_delete
         .. autoattribute:: inline_models
-        .. autoattribute:: column_filters

doc/api/mod_model.rst

@@ -6,10 +6,11 @@
     .. autoclass:: BaseModelView
         :members:
         :exclude-members: can_create, can_edit, can_delete, list_template, edit_template,
-                          create_template, list_columns, excluded_list_columns, rename_columns, list_formatters,
-                          sortable_columns, searchable_columns, column_filters, form, form_columns,
-                          excluded_form_columns, form_args, form_overrides, page_size,
-                          disallowed_actions, list_display_pk, list_type_formatters
+                          create_template, column_list, column_exclude_list, column_labels,
+                          column_formatters, column_type_formatters, column_display_pk,
+                          column_sortable_list, column_searchable_list, column_filters,
+                          form, form_columns, form_excluded_columns, form_args,
+                          form_overrides, action_disallowed_list, page_size
 
         .. autoattribute:: can_create
         .. autoattribute:: can_edit
@@ -19,25 +20,24 @@
         .. autoattribute:: edit_template
         .. autoattribute:: create_template
 
-        .. autoattribute:: list_columns
-        .. autoattribute:: excluded_list_columns
-        .. autoattribute:: rename_columns
-        .. autoattribute:: list_formatters
-        .. autoattribute:: list_display_pk
-        .. autoattribute:: list_type_formatters
+        .. autoattribute:: column_list
+        .. autoattribute:: column_exclude_list
+        .. autoattribute:: column_labels
+        .. autoattribute:: column_formatters
+        .. autoattribute:: column_type_formatters
+        .. autoattribute:: column_display_pk
 
-        .. autoattribute:: sortable_columns
-
-        .. autoattribute:: searchable_columns
+        .. autoattribute:: column_sortable_list
+        .. autoattribute:: column_searchable_list
 
         .. autoattribute:: column_filters
 
         .. autoattribute:: form
         .. autoattribute:: form_columns
-        .. autoattribute:: excluded_form_columns
+        .. autoattribute:: form_excluded_columns
         .. autoattribute:: form_args
         .. autoattribute:: form_overrides
 
-        .. autoattribute:: disallowed_actions
+        .. autoattribute:: action_disallowed_list
 
         .. autoattribute:: page_size

doc/changelog.rst

 Changelog
 =========
 
+1.0.4
+-----
+
+* MongoEngine support
+* Raw PyMongo support
+* Model property names are more consistent now
+* Revamped InlineForm implementation
+* Proper support of SQLAlchemy model inheritance
+* Updated to bootstrap 2.2.1
+
 1.0.3
 -----
 
@@ -11,7 +21,7 @@ General:
 * Inline model forms are much more customizable now
 * List view type-based formatters
 * Database ``NULL`` will be displayed in list view as empty string by default. Use type-based formatter if you want to show something else.
-* Use `Select2`_ instead of Chosen
+* `Use Select2 <http://ivaynberg.github.com/select2/>`_ instead of Chosen
 * List view formatting callbacks. See `example <https://gist.github.com/3714266>`_.
 * ``_template_args`` property is now available in all views
 * ``on_model_change`` and ``on_model_delete`` callbacks

doc/db.rst

@@ -7,3 +7,4 @@ Database backends
    db_sqla
    db_mongoengine
    db_peewee
+   db_pymongo

doc/db_mongoengine.rst

@@ -16,7 +16,9 @@ MongoEngine models without any problems.
 Known issues:
 
  - There's no way to configure EmbeddedDocument display options
- - Search functionality can't split query into multiple terms
-
+ - Search functionality can't split query into multiple terms due to
+   MongoEngine query language limitations
 
 For more documentation, check :doc:`api/mod_contrib_mongoengine` documentation.
+
+MongoEngine integration example is `here <https://github.com/mrjoes/flask-admin/tree/master/examples/mongoengine>`_.

doc/db_peewee.rst

 Peewee backend
 ==============
 
-Flask-Admin provides Peewee ORM backend.
-
-Peewee is a small ORM and some people showed interest in
-
 Features:
 
  - Peewee 2.x+ support;
@@ -17,5 +13,6 @@ Known issues:
 
  - Many-to-Many model relations are not supported: there's no built-in way to express M2M relation in Peewee
 
-
 For more documentation, check :doc:`api/mod_contrib_peeweemodel` documentation.
+
+Peewee example is `here <https://github.com/mrjoes/flask-admin/tree/master/examples/peewee>`_.

doc/db_pymongo.rst

+PyMongo backend
+===============
+
+Pretty simple PyMongo backend.
+
+Flask-Admin does not make assumptions about document structure, so you
+will have to configure ModelView to do what you need it to do.
+
+This is bare minimum you have to provide for Flask-Admin view to work
+with PyMongo:
+
+ 1. Provide list of columns by setting `column_list` property
+ 2. Provide form to use by setting `form` property
+ 3. When instantiating :class:`flask.ext.admin.contrib.pymongo.ModelView` class, you have to provide PyMongo collection object
+
+This is minimal PyMongo view::
+
+  class UserForm(wtf.Form):
+      name = wtf.TextForm('Name')
+      email = wtf.TextForm('Email')
+
+  class UserView(ModelView):
+      column_list = ('name', 'email')
+      form = UserForm
+
+  if __name__ == '__main__':
+      admin = Admin(app)
+
+      # 'db' is PyMongo database object
+      admin.add_view(UserView(db['users']))
+
+On top of that you can add sortable columns, filters, text search, etc.
+
+For more documentation, check :doc:`api/mod_contrib_pymongo` documentation.
+
+PyMongo integration example is `here <https://github.com/mrjoes/flask-admin/tree/master/examples/pymongo>`_.

doc/db_sqla.rst

@@ -10,5 +10,101 @@ Notable features:
  - Proper model relationship handling;
  - Inline editing of related models.
 
+Getting Started
+---------------
 
-For more documentation, check :doc:`api/mod_contrib_sqlamodel` documentation.
+In order to use SQLAlchemy model scaffolding, you need to have:
+
+ 1. SQLAlchemy ORM `model <http://docs.sqlalchemy.org/en/rel_0_8/orm/tutorial.html#declare-a-mapping>`_
+ 2. Initialized database `session <http://docs.sqlalchemy.org/en/rel_0_8/orm/tutorial.html#creating-a-session>`_
+
+If you use Flask-SQLAlchemy, this is how you initialize Flask-Admin
+and get session from the `SQLAlchemy` object::
+
+    from flask import Flask
+    from flask.ext.sqlalchemy import SQLAlchemy
+    from flask.ext.admin import Admin
+    from flask.ext.admin.contrib.sqlamodel import ModelView
+
+    app = Flask(__name__)
+    # .. read settings
+    db = SQLAlchemy(app)
+
+    # .. model declarations here
+
+    if __name__ == '__main__':
+        admin = Admin(app)
+        # .. add ModelViews
+        # admin.add_view(ModelView(SomeModel, db.session))
+
+Creating simple model
+---------------------
+
+Using previous template, lets create simple model::
+
+    # .. flask initialization
+    db = SQLAlchemy(app)
+
+    class User(db.Model):
+        id = db.Column(db.Integer, primary_key=True)
+        name = db.Column(db.String(64), unique=True)
+        email = db.Column(db.String(128))
+
+    if __name__ == '__main__':
+        admin = Admin(app)
+        admin.add_view(ModelView(User, db.session))
+
+        db.create_all()
+        app.run('0.0.0.0', 8000)
+
+If you will run this example and open `http://localhost:8000/ <http://localhost:8000/>`_,
+you will see that Flask-Admin generated administrative page for the
+model:
+
+    .. image:: images/sqla/sqla_1.png
+        :width: 640
+        :target: ../_images/sqla_1.png
+
+You can add new models, edit existing, etc.
+
+Customizing administrative interface
+------------------------------------
+
+List view can be customized in different ways.
+
+First of all, you can use various class-level properties to configure
+what should be displayed and how. For example, :attr:`~flask.ext.admin.contrib.sqlamodel.ModelView.column_list` can be used to show some of
+the column or include extra columns from related models.
+
+For example::
+
+    class UserView(ModelView):
+        # Show only name and email columns in list view
+        column_list = ('name', 'email')
+
+        # Enable search functionality - it will search for terms in
+        # name and email fields
+        column_searchable_list = ('name', 'email')
+
+        # Add filters for name and email columns
+        column_filters = ('name', 'email')
+
+Alternatively, you can override some of the :class:`~flask.ext.admin.contrib.sqlamodel.ModelView` methods and implement your custom logic.
+
+For example, if you need to contribute additional field to the generated form,
+you can do something like this::
+
+    class UserView(ModelView):
+        def scaffold_form(self):
+            form_class = super(UserView, self).scaffold_form()
+            form_class.extra = wtf.TextField('Extra')
+            return form_class
+
+Check :doc:`api/mod_contrib_sqlamodel` documentation for list of
+configuration properties and methods.
+
+Example
+-------
+
+Flask-Admin comes with relatively advanced example, which you can
+see `here <https://github.com/mrjoes/flask-admin/tree/master/examples/sqla>`_.
\ No newline at end of file

doc/index.rst

@@ -8,10 +8,12 @@ Flask-Admin is simple and extensible administrative interface framework for `Fla
 
    quickstart
    templates
+   tips
    db
    model_guidelines
    api/index
    changelog
+   renamed_columns
 
 
 Indices and tables

doc/model_guidelines.rst

@@ -42,20 +42,17 @@ Steps to add new model backend:
     - :meth:`~flask.ext.admin.model.BaseModelView.scaffold_list_columns`
 
     Returns list of columns to be displayed in a list view.
-    Make sure you exclude columns if `self.excluded_list_columns` was set.
 
     For example::
 
         class MyDbModel(BaseModelView):
             def scaffold_list_columns(self):
                 columns = []
-                exclude = self.excluded_list_columns or []
 
                 for p in dir(self.model):
-                    if p not in exclude:
-                        attr = getattr(self.model)
-                        if isinstance(attr, MyDbColumn):
-                            columns.append(p)
+                    attr = getattr(self.model)
+                    if isinstance(attr, MyDbColumn):
+                        columns.append(p)
 
                 return columns
 

doc/renamed_columns.rst

+Renamed Columns
+---------------
+
+Starting from version 1.0.4, Flask-Admin uses different configuration
+property names.
+
+Please update your sources as support for old property names will be
+removed in future Flask-Admin versions.
+
+=========================== =============================
+**Old Name**                **New name**
+--------------------------- -----------------------------
+list_columns                column_list
+excluded_list_columns       column_exclude_list
+list_formatters             column_formatters
+list_type_formatters        column_type_formatters
+rename_columns              column_labels
+sortable_columns            column_sortable_list
+searchable_columns          column_searchable_list
+list_display_pk             column_display_pk
+hide_backrefs               column_hide_backrefs
+auto_select_related         column_auto_select_related
+list_select_related         column_select_related_list
+list_display_all_relations  column_display_all_relations
+excluded_form_columns       form_excluded_columns
+disallowed_actions          action_disallowed_list
+=========================== =============================

doc/tips.rst

+Usage Tips
+==========
+
+General tips
+------------
+
+1. Use class inheritance. If your models share common functionality,
+create base class which will be responsible for this functionality.
+
+For example - permissions. Don't implement `is_accessible` in  every administrative view. Create your own base class,
+implement is_accessible there and use it instead.
+
+2. You can override templates either by using `ModelView` properties or
+putting customized version into your `templates/admin/` directory
+
+
+SQLAlchemy
+----------
+
+1. If `synonym_property` does not return SQLAlchemy field, Flask-Admin
+won't be able to figure out what to do with it and won't generate form
+field. In this case, you need to manually contribute field::
+
+    class MyView(ModelView):
+        def scaffold_form(self):
+            form_class = super(UserView, self).scaffold_form()
+            form_class.extra = wtf.TextField('Extra')
+            return form_class

examples/doc.py

+from flask import Flask
+from flask.ext.sqlalchemy import SQLAlchemy
+from flask.ext.admin import Admin
+from flask.ext.admin.contrib.sqlamodel import ModelView
+
+app = Flask(__name__)
+app.config['SECRET_KEY'] = '123456790'
+app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite://'
+app.config['SQLALCHEMY_ECHO'] = True
+
+# .. read settings
+db = SQLAlchemy(app)
+
+
+# .. model declarations here
+class User(db.Model):
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String(64), unique=True)
+    email = db.Column(db.String(128))
+
+if __name__ == '__main__':
+    admin = Admin(app)
+    admin.add_view(ModelView(User, db.session))
+
+    db.create_all()
+    app.run('0.0.0.0', 8000)

flask_admin/contrib/pymongo/view.py

@@ -33,8 +33,8 @@ class ModelView(BaseModelView):
                 column_filters = (BooleanEqualFilter(User.name, 'Name'),)
     """
 
-    def __init__(self, coll, name,
-                 category=None, endpoint=None, url=None):
+    def __init__(self, coll,
+                 name=None, category=None, endpoint=None, url=None):
         """
             Constructor
 
@@ -51,6 +51,9 @@ class ModelView(BaseModelView):
         """
         self._search_fields = []
 
+        if name is None:
+            name = self._prettify_name(coll.name)
+
         if endpoint is None:
             endpoint = ('%sview' % coll.name).lower()
 

flask_admin/contrib/sqlamodel/view.py

@@ -45,9 +45,9 @@ class ModelView(BaseModelView):
         will still make separate database call.
     """
 
-    column_select_related = ObsoleteAttr('column_select_related',
-                                         'list_select_related',
-                                         None)
+    column_select_related_list = ObsoleteAttr('column_select_related',
+                                             'list_select_related',
+                                              None)
     """
         List of parameters for SQLAlchemy `subqueryload`. Overrides `column_auto_select_related`
         property.
@@ -55,12 +55,12 @@ class ModelView(BaseModelView):
         For example::
 
             class PostAdmin(ModelAdmin):
-                column_select_related = ('user', 'city')
+                column_select_related_list = ('user', 'city')
 
         You can also use properties::
 
             class PostAdmin(ModelAdmin):
-                column_select_related = (Post.user, Post.city)
+                column_select_related_list = (Post.user, Post.city)
 
         Please refer to the `subqueryload` on list of possible values.
     """
@@ -229,10 +229,10 @@ class ModelView(BaseModelView):
             raise Exception('Model %s does not have primary key.' % self.model.__name__)
 
         # Configuration
-        if not self.column_select_related:
+        if not self.column_select_related_list:
             self._auto_joins = self.scaffold_auto_joins()
         else:
-            self._auto_joins = self.column_select_related
+            self._auto_joins = self.column_select_related_list
 
     # Internal API
     def _get_model_iterator(self, model=None):