If you are using the MongoEngine backend, Flask-Admin supports GridFS-backed image- and file uploads, done through WTForms fields. Documentation can be found
at :mod:`flask_admin.contrib.mongoengine.fields`.
If you just want to manage static files in a directory, without tying them to a database model, then
rather use the handy :ref:`File-Admin<file-admin>` plugin.
Initialisation
Initialisation
---------------
---------------
****
As an alternative to passing a Flask application object to the Admin constructor, you can also call the
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::
:meth:`~flask_admin.base.Admin.init_app` function, after the Admin instance has been initialized::
...
@@ -10,10 +112,11 @@ As an alternative to passing a Flask application object to the Admin constructor
...
@@ -10,10 +112,11 @@ As an alternative to passing a Flask application object to the Admin constructor
# Add views here
# Add views here
admin.init_app(app)
admin.init_app(app)
****
Localization with Flask-Babelex
Localization with Flask-Babelex
------------------------------------------
------------------------------------------
****
Enabling localization is relatively simple.
Enabling localization is relatively simple.
#. Install `Flask-BabelEx <http://github.com/mrjoes/flask-babelex/>`_ to do the heavy
#. Install `Flask-BabelEx <http://github.com/mrjoes/flask-babelex/>`_ to do the heavy
...
@@ -49,11 +152,12 @@ Enabling localization is relatively simple.
...
@@ -49,11 +152,12 @@ Enabling localization is relatively simple.
If the builtin translations are not enough, look at the `Flask-BabelEx documentation <https://pythonhosted.org/Flask-BabelEx/>`_
If the builtin translations are not enough, look at the `Flask-BabelEx documentation <https://pythonhosted.org/Flask-BabelEx/>`_
to see how you can add your own.
to see how you can add your own.
****
Handling Foreign Key relations inline
Handling Foreign Key relations inline
--------------------------------------------
--------------------------------------------
****
Many-to-many relations
Many-to-many relations
----------------------------------
----------------------------------
...
@@ -64,6 +168,8 @@ Many-to-many relations
...
@@ -64,6 +168,8 @@ Many-to-many relations
Managing Files & Folders
Managing Files & Folders
--------------------------------
--------------------------------
****
Flask-Admin comes with another handy battery - file admin. It gives you the ability to manage files on your server
Flask-Admin comes with another handy battery - file admin. It gives you the ability to manage files on your server
(upload, delete, rename, etc).
(upload, delete, rename, etc).
...
@@ -89,11 +195,11 @@ Sample screenshot:
...
@@ -89,11 +195,11 @@ Sample screenshot:
You can disable uploads, disable file or directory deletion, restrict file uploads to certain types and so on.
You can disable uploads, disable file or directory deletion, restrict file uploads to certain types and so on.
Check :mod:`flask_admin.contrib.fileadmin` documentation on how to do it.
Check :mod:`flask_admin.contrib.fileadmin` documentation on how to do it.
****
Managing geographical models
Managing geographical models
--------------------------------------
--------------------------------------
****
GeoAlchemy backend
GeoAlchemy backend
If you want to store spatial information in a GIS database, Flask-Admin has
If you want to store spatial information in a GIS database, Flask-Admin has
...
@@ -173,11 +279,11 @@ If you have any ideas or suggestions, make a pull request!
...
@@ -173,11 +279,11 @@ If you have any ideas or suggestions, make a pull request!
Adding CSRF validation will require overriding the :class:`flask_admin.form.BaseForm` by using :attr:`flask_admin.model.BaseModelView.form_base_class`.
Adding CSRF validation will require overriding the :class:`flask_admin.form.BaseForm` by using :attr:`flask_admin.model.BaseModelView.form_base_class`.
WTForms >=2::
WTForms >=2::
...
@@ -298,11 +405,14 @@ For WTForms 1, you can use use Flask-WTF's Form class::
...
@@ -298,11 +405,14 @@ For WTForms 1, you can use use Flask-WTF's Form class::
app.run(debug=True)
app.run(debug=True)
****
Using different database backends
.. _database-backends:
Using Different Database Backends
----------------------------------------
----------------------------------------
****
The purpose of Flask-Admin is to help you manage your data. For this, it needs some database backend in order to be
The purpose of Flask-Admin is to help you manage your data. For this, it needs some database backend in order to be
able to access that data in the first place. At present, there are five different backends for you to choose
able to access that data in the first place. At present, there are five different backends for you to choose
from, depending on which database you would like to use for your application.
from, depending on which database you would like to use for your application.
...
@@ -335,11 +445,11 @@ are dedicated to helping you through this process. See :doc:`model_guidelines`.
...
@@ -335,11 +445,11 @@ are dedicated to helping you through this process. See :doc:`model_guidelines`.
.. _MongoEngine: http://mongoengine.org/
.. _MongoEngine: http://mongoengine.org/
.. _MongoDB: http://www.mongodb.org/
.. _MongoDB: http://www.mongodb.org/
****
Migrating from Django
Migrating from Django
-------------------------
-------------------------
****
If you are used to `Django <https://www.djangoproject.com/>`_ and the *django-admin* package, you will find
If you are used to `Django <https://www.djangoproject.com/>`_ and the *django-admin* package, you will find
Flask-Admin to work slightly different from what you would expect.
Flask-Admin to work slightly different from what you would expect.
...
@@ -469,5 +579,28 @@ and then point your class to this new template::
...
@@ -469,5 +579,28 @@ and then point your class to this new template::
For list of available template blocks, check :doc:`templates`.
For list of available template blocks, check :doc:`templates`.
Adding a Redis console
--------------------------
****
Overriding the Form Scaffolding
---------------------------------
****
If you don't want to the use the built-in Flask-Admin form scaffolding logic, you are free to roll your own
by simply overriding :meth:`~flask_admin.model.base.scaffold_form`. For example, if you use
`WTForms-Alchemy <https://github.com/kvesteri/wtforms-alchemy>`_, you could put your form generation code
into a `scaffold_form` method in your `ModelView` class.
For SQLAlchemy, if the `synonym_property` does not return a SQLAlchemy field, then Flask-Admin won't be able to figure out what to
do with it, so it won't generate a form field. In this case, you would need to manually contribute your own field::
@@ -6,33 +6,38 @@ It offers freedom for you, the designer, to implement your project in a way that
...
@@ -6,33 +6,38 @@ It offers freedom for you, the designer, to implement your project in a way that
particular application.
particular application.
**Why Flask-Admin?** In a world of micro-services and APIs, Flask-Admin solves
**Why Flask-Admin?** In a world of micro-services and APIs, Flask-Admin solves
the really boring problem of letting you quickly build an admin interface on top
the boring problem of building an admin interface on top
of an existing data model. With little effort, it makes it possible for
of an existing data model. With little effort, it lets
you to manage your web service's data through a user-friendly interface.
you manage your web service's data through a user-friendly interface.
Examples
**How does it work?** The basic concept behind Flask-Admin, is that it lets you
==========
build complicated interfaces by grouping individual views
Flask-Admin comes with several examples that will help you get a grip on what's possible.
Have a look at http://examples.flask-admin.org/ to see them in action, or browse through the `examples` directory in the GitHub repository.
****
Getting Started
=================
Flask-Admin lets you build complicated interfaces by grouping individual views
together in classes: Each web page you see on the frontend, represents a
together in classes: Each web page you see on the frontend, represents a
method on a class that has explicitly been added to the interface.
method on a class that has explicitly been added to the interface.
These view classes are especially helpful when they are tied to particular
These view classes are especially helpful when they are tied to particular
database models,
database models,
because they let you group together all of the usual
because they let you group together all of the usual
**Create, Read, Update, Delete** (CRUD) view logic into a single, self-contained
*Create, Read, Update, Delete* (CRUD) view logic into a single, self-contained
class for each of your models.
class for each of your models.
**What does it look like?** Have a look at http://examples.flask-admin.org/ to 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>`_.
.. toctree::
:maxdepth: 2
Index <index>
Getting Started
================
****
Initialization
Initialization
--------------
-------------------
To get started, the first step, is to initialise an empty admin interface on your Flask app::
To get started, the first step, is to initialise an empty admin interface on your Flask app::
...
@@ -54,7 +59,7 @@ you should see an empty page with a navigation bar on top.
...
@@ -54,7 +59,7 @@ you should see an empty page with a navigation bar on top.
Adding Model Views
Adding Model Views
----------------------
----------------------
Model views allow you to add a dedicated set of admin pages for any model in your database. Do this by creating
Model views allow you to add a dedicated set of admin pages for managing any model in your database. Do this by creating
instances of the *ModelView* class, which you can import from one of Flask-Admin's built-in ORM backends. An example
instances of the *ModelView* class, which you can import from one of Flask-Admin's built-in ORM backends. An example
is the SQLAlchemy backend, which you can use as follows::
is the SQLAlchemy backend, which you can use as follows::
...
@@ -71,8 +76,9 @@ Straight out of the box, this gives you a set of fully featured *CRUD* views for
...
@@ -71,8 +76,9 @@ Straight out of the box, this gives you a set of fully featured *CRUD* views for
* A `create` view for adding new records.
* A `create` view for adding new records.
* An `edit` view for updating existing records.
* An `edit` view for updating existing records.
There are many options available for customizing the display and functionality of these builtin view.
There are many options available for customizing the display and functionality of these builtin views.
For more details on that, see :ref:`customising-builtin-views`.
For more details on that, see :ref:`customising-builtin-views`. For more details on the other
ORM backends that are available, see :ref:`database-backends`.
Adding Content to the Index Page
Adding Content to the Index Page
------------------------------------
------------------------------------
...
@@ -85,12 +91,14 @@ is that it's just an empty page with a navigation menu. To add some content to t
...
@@ -85,12 +91,14 @@ is that it's just an empty page with a navigation menu. To add some content to t
<p>Hello world</p>
<p>Hello world</p>
{% endblock %}
{% endblock %}
This will override the default index template, but still give you the navigation menu. So, now you can add any content to the index page that makes sense for your app.
This will override the default index template, but still give you the builtin navigation menu.
So, now you can add any content to the index page, while maintaining a consistent user experience.
****
Authorisation & Permissions
Authorisation & Permissions
=================================
=================================
****
When setting up an admin interface for your application, one of the first problems
When setting up an admin interface for your application, one of the first problems
you'll want to solve is how to keep unwanted users out. With Flask-Admin there
you'll want to solve is how to keep unwanted users out. With Flask-Admin there
are a few different ways of approaching this.
are a few different ways of approaching this.
...
@@ -110,7 +118,7 @@ interface.
...
@@ -110,7 +118,7 @@ interface.
Rolling Your Own
Rolling Your Own
--------------------------------
--------------------------------
For a finer-grained solution, Flask-Admin lets you define access control rules
For a more flexible solution, Flask-Admin lets you define access control rules
on each of your admin view classes by simply overriding the `is_accessible` method.
on each of your admin view classes by simply overriding the `is_accessible` method.
How you implement the logic is up to you, but if you were to use a low-level library like
How you implement the logic is up to you, but if you were to use a low-level library like
`Flask-Login <https://flask-login.readthedocs.org/>`_, then restricting access
`Flask-Login <https://flask-login.readthedocs.org/>`_, then restricting access