Merge pull request pallets-eco#1 from flask-admin/master

pull master

Author: bekab95

.travis.yml

@@ -33,11 +33,13 @@ addons:
 services:
   - postgresql
   - mongodb
+  - docker
 
 before_script:
   - psql -U postgres -c 'CREATE DATABASE flask_admin_test;'
   - psql -U postgres -c 'CREATE EXTENSION postgis;' flask_admin_test
   - psql -U postgres -c 'CREATE EXTENSION hstore;' flask_admin_test
+  - docker run --restart always -d -e executable=blob -p 10000:10000 --tmpfs /opt/azurite/folder arafato/azurite:2.6.5
 
 install:
   - pip install tox

README.rst

@@ -38,14 +38,28 @@ Flask-Admin is an active project, well-tested and production ready.
 
 Examples
 --------
-Several usage examples are included in the */examples* folder. Please feel free to add your own examples, or improve
-on some of the existing ones, and then submit them via GitHub as a *pull-request*.
+Several usage examples are included in the */examples* folder. Please add your own, or improve
+on the existing examples, and submit a *pull-request*.
 
-You can see some of these examples in action at `http://examples.flask-admin.org <http://examples.flask-admin.org/>`_.
-To run the examples on your local environment, one at a time, do something like::
+To run the examples in your local environment::
 
-    cd flask-admin
-    python examples/simple/app.py
+  1. Clone the repository::
+
+        git clone https://github.com/flask-admin/flask-admin.git
+        cd flask-admin
+
+  2. Create and activate a virtual environment::
+
+        virtualenv env -p python3
+        source env/bin/activate
+
+  3. Install requirements::
+
+        pip install -r 'examples/sqla/requirements.txt'
+
+  4. Run the application::
+
+        python examples/sqla/app.py
 
 Documentation
 -------------
@@ -91,7 +105,11 @@ You should see output similar to::
 
 For all the tests to pass successfully, you'll need Postgres & MongoDB to be running locally. For Postgres::
 
+    > psql postgres
     CREATE DATABASE flask_admin_test;
+    \q
+
+    > psql flask_admin_test
     CREATE EXTENSION postgis;
     CREATE EXTENSION hstore;
 
@@ -100,7 +118,8 @@ You can also run the tests on multiple environments using *tox*.
 3rd Party Stuff
 ---------------
 
-Flask-Admin is built with the help of `Bootstrap <http://getbootstrap.com/>`_ and `Select2 <https://github.com/ivaynberg/select2>`_.
+Flask-Admin is built with the help of `Bootstrap <http://getbootstrap.com/>`_,  `Select2 <https://github.com/ivaynberg/select2>`_
+and `Bootswatch <http://bootswatch.com/>`_.
 
 If you want to localize your application, install the `Flask-BabelEx <https://pypi.python.org/pypi/Flask-BabelEx>`_ package.
 

doc/_templates/sidebarintro.html

@@ -2,7 +2,6 @@ <h3>Useful Links</h3>
 <ul>
   <li><a href="http://flask.pocoo.org/" target="_blank">Flask</a></li>
   <li><a href="http://github.com/flask-admin/flask-admin" target="_blank">Flask-Admin @ github</a></li>
-  <li><a href="http://examples.flask-admin.org/" target="_blank">Flask-Admin Examples</a></li>
 </ul>
 
 <a class="github" href="http://github.com/flask-admin/flask-admin" target="_blank"><img style="position: fixed; top: 0; right: 0; border: 0;"

doc/advanced.rst

@@ -34,7 +34,7 @@ Enabling localization is simple:
 
 #. Initialize Flask-BabelEx by creating instance of `Babel` class::
 
-        from flask import app
+        from flask import Flask
         from flask_babelex import Babel
 
         app = Flask(__name__)
@@ -164,7 +164,7 @@ Image handling also requires you to have `Pillow <https://pypi.python.org/pypi/P
 installed if you need to do any processing on the image files.
 
 Have a look at the example at
-https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms.
+https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms-files-images.
 
 If you are using the MongoEngine backend, Flask-Admin supports GridFS-backed image and file uploads through WTForms fields. Documentation can be found at :mod:`flask_admin.contrib.mongoengine.fields`.
 
@@ -544,4 +544,3 @@ While the wrapped function should accept only one parameter - `ids`::
                     raise
 
                 flash(gettext('Failed to approve users. %(error)s', error=str(ex)), 'error')
-

doc/api/index.rst

@@ -15,6 +15,7 @@ API
    mod_actions
 
    mod_contrib_sqla
+   mod_contrib_sqla_fields
    mod_contrib_mongoengine
    mod_contrib_mongoengine_fields
    mod_contrib_peewee

doc/api/mod_contrib_sqla_fields.rst

@@ -0,0 +1,13 @@
+``flask_admin.contrib.sqla.fields``
+===================================
+
+.. automodule:: flask_admin.contrib.sqla.fields
+
+	.. autoclass:: QuerySelectField
+		:members:
+
+	.. autoclass:: QuerySelectMultipleField
+		:members:
+
+	.. autoclass:: CheckboxListField
+		:members:

doc/changelog.rst

@@ -1,6 +1,45 @@
 Changelog
 =========
 
+1.5.3
+-----
+
+* Fixed XSS vulnerability
+* Support nested categories in the navbar menu
+* SQLAlchemy
+    * sort on multiple columns with `column_default_sort`
+    * sort on related models in `column_sortable_list`
+    * fix: inline model forms can now also be used for models with multiple primary keys
+    * support for using mapped `column_property`
+* Upgrade Leaflet and Leaflet.draw plugins, used for geoalchemy integration
+* Specify `minimum_input_length` for ajax widget
+* Peewee: support composite keys
+* MongoEngine: when searching/filtering the input is now regarded as case-insensitive by default
+* FileAdmin
+    * handle special characters in filename
+    * fix a bug with listing directories on Windows
+    * avoid raising an exception when unknown sort parameter is encountered
+* WTForms 3 support
+
+1.5.2
+-----
+
+* Fixed XSS vulnerability
+* Fixed Peewee support
+* Added detail view column formatters
+* Updated Flask-Login example to work with the newer version of the library
+* Various SQLAlchemy-related fixes
+* Various Windows related fixes for the file admin
+
+1.5.1
+-----
+
+* Dropped Python 2.6 support
+* Fixed SQLAlchemy >= 1.2 compatibility
+* Fixed Pewee 3.0 compatibility
+* Fixed max year for a combo date inline editor
+* Lots of small bug fixes
+
 1.5.0
 -----
 
@@ -13,7 +52,7 @@ Changelog
   - Added support for association proxies
   - Added support for remote hybrid properties filters
   - Added support for ARRAY column type
-* Localization-related fixes 
+* Localization-related fixes
 * MongoEngine backend is now properly formats model labels
 * Improved Google App Engine support:
   - Added TextProperty, KeyProperty and SelectField support

doc/index.rst

@@ -23,9 +23,9 @@ because they let you group together all of the usual
 *Create, Read, Update, Delete* (CRUD) view logic into a single, self-contained
 class for each of your models.
 
-**What does it look like?** At http://examples.flask-admin.org/ you can see
-some examples of Flask-Admin in action, or browse through the `examples/`
-directory in the `GitHub repository <https://github.com/flask-admin/flask-admin>`_.
+**What does it look like?** Clone the `GitHub repository <https://github.com/flask-admin/flask-admin>`_
+and run the provided examples locally to get a feel for Flask-Admin. There are several to choose from
+in the `examples` directory.
 
 .. toctree::
    :maxdepth: 2

doc/introduction.rst

@@ -18,6 +18,9 @@ The first step is to initialize an empty admin interface for your Flask app::
 
     app = Flask(__name__)
 
+    # set optional bootswatch theme
+    app.config['FLASK_ADMIN_SWATCH'] = 'cerulean'
+
     admin = Admin(app, name='microblog', template_mode='bootstrap3')
     # Add administrative views here
 
@@ -27,7 +30,8 @@ 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.
+you should see an empty page with a navigation bar on top. Customize the look by
+specifying a Bootswatch theme that suits your needs (see http://bootswatch.com/3/ for available swatches).
 
 Adding Model Views
 ------------------
@@ -156,12 +160,9 @@ Customizing Built-in Views
 
 ****
 
-The built-in `ModelView` class is great for getting started quickly. But, you'll want
-to configure its functionality to suit your particular models. This is done by setting
-values for the configuration attributes that are made available in the `ModelView` class.
-
-To specify some global configuration parameters, you can subclass `ModelView` and use that
-subclass when adding your models to the interface::
+When inheriting from `ModelView`, values can be specified for numerous
+configuration parameters. Use these to customize the views to suit your
+particular models::
 
     from flask_admin.contrib.sqla import ModelView
 
@@ -287,6 +288,28 @@ To **enable csv export** of the model view::
 
 This will add a button to the model view that exports records, truncating at :attr:`~flask_admin.model.BaseModelView.export_max_rows`.
 
+
+Grouping Views
+==============
+When adding a view, specify a value for the `category` parameter
+to group related views together in the menu::
+
+    admin.add_view(UserView(User, db.session, category="Team"))
+    admin.add_view(ModelView(Role, db.session, category="Team"))
+    admin.add_view(ModelView(Permission, db.session, category="Team"))
+
+This will create a top-level menu item named 'Team', and a drop-down containing
+links to the three views.
+
+To nest related views within these drop-downs, use the `add_sub_category` method::
+
+    admin.add_sub_category(name="Links", parent_name="Team")
+
+And to add arbitrary hyperlinks to the menu::
+
+  admin.add_link(MenuLink(name='Home Page', url='/', category='Links'))
+
+
 Adding Your Own Views
 =====================
 
@@ -440,7 +463,7 @@ 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
+Have a look at the `layout` example at https://github.com/flask-admin/flask-admin/tree/master/examples/custom-layout
 to see how you can take full stylistic control over the admin interface.
 
 Environment Variables

examples/layout/README.rst renamed to examples/custom-layout/README.rst

@@ -14,11 +14,11 @@ To run this example:
 
 3. Install requirements::
 
-    pip install -r 'examples/layout/requirements.txt'
+    pip install -r 'examples/custom-layout/requirements.txt'
 
 4. Run the application::
 
-    python examples/layout/app.py
+    python examples/custom-layout/app.py
 
 The first time you run this example, a sample sqlite database gets populated automatically. To suppress this behaviour,
 comment the following lines in app.py:::

examples/__init__.py renamed to examples/custom-layout/__init__.py

@@ -7,7 +7,7 @@
 {% endblock %}
 
 {% block page_body %}
-<div class="container">
+<div class="container-fluid">
   <div class="row">
     <div class="col-md-2" role="navigation">
       <ul class="nav nav-pills nav-stacked">

examples/layout_bootstrap3/app.py renamed to examples/custom-layout/app.py

@@ -1,4 +1,11 @@
-Example of custom filters for the SQLAlchemy backend.
+This example shows how you can::
+
+    * define your own custom forms by using form rendering rules
+    * handle generic static file uploads
+    * handle image uploads
+    * turn a TextArea field into a rich WYSIWYG editor using WTForms and CKEditor
+    * set up a Flask-Admin view as a Redis terminal
+
 
 To run this example:
 
@@ -14,11 +21,11 @@ To run this example:
 
 3. Install requirements::
 
-    pip install -r 'examples/sqla-custom-filter/requirements.txt'
+    pip install -r 'examples/forms-files-images/requirements.txt'
 
 4. Run the application::
 
-    python examples/sqla-custom-filter/app.py
+    python examples/forms-files-images/app.py
 
 The first time you run this example, a sample sqlite database gets populated automatically. To suppress this behaviour,
 comment the following lines in app.py:::