Skip to content

F
flask-admin
Commit d6b72422 authored by Petrus J.v.Rensburg's avatar Petrus J.v.Rensburg
Browse files
Options

Improve language in all sections of the index page.

parent 9ed589d1
Hide whitespace changes
Inline Side-by-side
Showing with 72 additions and 66 deletions
doc/index.rst
View file @ d6b72422
......@@ -22,7 +22,7 @@ Getting Started
=================
Flask-Admin lets you build complicated interfaces by grouping individual views
together in classes: Each view that 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.
These view classes are especially helpful when they are tied to particular
......@@ -34,7 +34,7 @@ class for each of your models.
Initialization
--------------
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::
from flask import Flask
from flask_admin import Admin
......@@ -46,8 +46,10 @@ The first step, is to initialise an empty admin interface on your Flask app::
app.run()
Here, both the *name* and *template_mode* parameters are optional. If you start this application and navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_,
you should see an empty "Home" page with a navigation bar on top, and the *name* that you specified.
Here, both the *name* and *template_mode* parameters are optional.
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.
Adding Model Views
----------------------
......@@ -72,10 +74,10 @@ Straight out of the box, this gives you a set of fully featured *CRUD* views for
There are many options available for customizing the display and functionality of these builtin view.
For more details on that, see :ref:`customising-builtin-views`.
Customising the index page
Adding Content to the Index Page
------------------------------------
The first thing you'll notice when you visit `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_
is that it's just an empty page with a navigation menu. To add some content to this page, save the following text to a file in `my_app/templates/admin/index.html`::
is that it's just an empty page with a navigation menu. To add some content to this page, save the following text as `admin/index.html` in your project's `templates` directory::
{% extends 'admin/master.html' %}
......@@ -83,7 +85,7 @@ is that it's just an empty page with a navigation menu. To add some content to t
<p>Hello world</p>
{% endblock %}
This will override the builtin index template, but still give you the builtin 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 navigation menu. So, now you can add any content to the index page that makes sense for your app.
****
......@@ -114,16 +116,15 @@ How you implement the logic is up to you, but if you were to use a low-level lib
`Flask-Login <https://flask-login.readthedocs.org/>`_, then restricting access
could be as simple as::
class MyModelView(sqla.ModelView):
class BaseModelView(sqla.ModelView):
def is_accessible(self):
return login.current_user.is_authenticated()
However, you would still need to implement all of the relevant login /
registration views yourself.
However, you would still need to implement all of the relevant login,
registration and account management views yourself.
If you like this approach, then have a look at the example at
https://github.com/flask-admin/Flask-Admin/tree/master/examples/auth-flask-login.
For a basic example of this, have a look at https://github.com/flask-admin/Flask-Admin/tree/master/examples/auth-flask-login.
Using Flask-Security
--------------------------------
......@@ -131,10 +132,10 @@ Using Flask-Security
If you want to get started quicker, you could
use `Flask-Security <https://pythonhosted.org/Flask-Security/>`_,
which is a higher-level library. It comes with lots of builtin views for doing
common things like registration, login, email address confirmation, password resets, etc.
common things like user registration, login, email address confirmation, password resets, etc.
The complicated bit, is making the builtin Flask-Security views work together with the
Flask-Admin templates, to create a consistent experience for your users. To
The only complicated bit, is making the builtin Flask-Security views integrate smoothly with the
Flask-Admin templates to create a consistent user experience. To
do this, you will need to override the builtin Flask-Security templates and have them
extend the Flask-Admin base template by adding the following to the top
of each file::
......@@ -166,9 +167,9 @@ Customising Builtin Views
=================================
The builtin `ModelView` class is great for getting started quickly. But you'll want
to adapt it's functionality
to suit your particular models. To do this, there's a whole host of configuration
attributes that you can set either globally, or just for specific models.
to configure its functionality
to suit your particular models. This is done by setting values for the configuration
attributes that are made available on the `ModelView` class.
To specify some global configuration parameters, you can subclass `ModelView`, and then use that
subclass when adding your models to the interface::
......@@ -196,12 +197,12 @@ Or, in much the same way, you can specify options for a single model at a time::
admin.add_view(PostView(Post, db.session))
View configuration attributes
-----------------------------
`ModelView` Configuration Attributes
-----------------------------------
For a complete list of all the options that are available, have a look at the
API documentation for :meth:`~flask_admin.model.BaseModelView`. Here we are
just highlighting some of the most useful ones.
For a complete list of the attributes that are defined, have a look at the
API documentation for :meth:`~flask_admin.model.BaseModelView`. But, here follows
some of the most commonly used ones:
To disable some of the basic CRUD operations, set any of these boolean parameters::
......@@ -210,15 +211,15 @@ To disable some of the basic CRUD operations, set any of these boolean parameter
can_delete = True
Common List view options
**************************
Configuring the List View
****************************
Removing some columns from the list view is easy, just use something like::
column_exclude_list = ['password', ]
To make some of your columns searchable, or to use them for filtering, specify
a list of column names, e.g.::
a list of column names::
column_searchable_list = ['name', 'email']
column_filters = ['country', ]
......@@ -227,10 +228,10 @@ For a faster editing experience, make some of the columns editable in the list v
column_editable_list = ['name', 'last_name']
Common Form view options
**************************
Configuring the Create & Edit Views
************************************
You can restrict the values of a text-field by specifying a list of choices::
You can restrict the possible values for a text-field by specifying a list of choices::
form_choices = {
'title': [
......@@ -242,11 +243,11 @@ You can restrict the values of a text-field by specifying a list of choices::
]
}
To remove some fields from the forms::
To remove some fields from the create and edit forms::
form_excluded_columns = ('last_name', 'email')
form_excluded_columns = ['last_name', 'email']
To specify arguments for rendering the WTForms fields::
To specify arguments to the WTForms fields when they are being rendered::
form_args = {
'name': {
......@@ -255,8 +256,8 @@ To specify arguments for rendering the WTForms fields::
}
}
Or, to go one level deeper, you can specify arguments for the widgets used to
render those fields. For example::
And, to go one level deeper, you can specify arguments to the widgets used to
render those fields::
form_widget_args = {
'description': {
......@@ -270,23 +271,27 @@ related models loaded via ajax, using::
form_ajax_refs = {
'user': {
'fields': ('first_name', 'last_name', 'email')
'fields': ['first_name', 'last_name', 'email']
'page_size': 10
}
}
Overriding the default templates
Changing the Look & Feel
---------------------------------
You can override any of the builtin Flask-Admin templates by simply copying them
into `templates/admin/` in your project directory. This gives you absolute
control over the look & feel of the admin interface, but with one drawback: it
can make life difficult for you when you eventually want to upgrade the version
of Flask-Admin that you are using.
To take full control over the look & feel of the admin interface, you can override
all of the builtin templates. Just keep in mind that the templates will change slightly
from one Flask-Admin version to the next, so once you start overriding them, you
need to take care when upgrade your package version.
To override any of the builtin templates, simply copy them from
the Flask-Admin source into `templates/admin/` in your project directory.
As long as the filenames stay the same, the templates in your project directory should
automatically take precedence over the builtin ones.
If you want to keep your custom templates in some other location, then you need
to remember to reference them from the ModelView classes where you intend to
use them, e.g.::
use them, for example::
class BaseModelView(ModelView):
list_template = 'base_list.html'
......@@ -294,16 +299,16 @@ use them, e.g.::
edit_template = 'base_edit.html'
Have a look at the `layout` example at https://github.com/flask-admin/flask-admin/tree/master/examples/layout
if you want to see how to take full stylistic control.
to see how you can take full stylistic control over the admin interface.
Replacing specific form fields
Replacing Individual Form Fields
------------------------------------------
Individual form fields can be replaced completely by specifying the `form_overrides` attribute.
You can use this to add a rich text editor, or to handle
file / image uploads that need to be tied to a field in one of your models.
The `form_overrides` attribute allows you to replace individual fields within a form.
A comon use-case for this would be to add a rich text editor, or to handle
file / image uploads that need to be tied to a field in your model.
Rich-text fields
Rich-Text Fields
**********************
To handle complicated text content, use `CKEditor <http://ckeditor.com/>`_ by subclassing some of the builtin WTForms classes as follows::
......@@ -330,7 +335,7 @@ To handle complicated text content, use `CKEditor <http://ckeditor.com/>`_ by su
For this to work, you would also need to create a template that extends the default
functionality by including the necessary CKEditor javascript on the `create` and
`edit` pages. Save this in `templates/ckeditor.html::
`edit` pages. Save this in `templates/ckeditor.html`::
{% extends 'admin/model/edit.html' %}
......@@ -339,27 +344,28 @@ functionality by including the necessary CKEditor javascript on the `create` and
<script src="http://cdnjs.cloudflare.com/ajax/libs/ckeditor/4.0.1/ckeditor.js"></script>
{% endblock %}
File & Image fields
File & Image Fields
*******************
For handling File & Image fields, have a look a the example at
https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms.
Flask-Admin comes with a builtin `FileUploadField` and `ImageUploadField`. To make use
of them, you'll need to specify an upload directory, and add them to the forms in question.
Image handling also requires you to have `Pillow <https://pypi.python.org/pypi/Pillow/2.8.2>`_ installed.
You'll need to specify an upload directory, and then use either `FileUploadField` or
`ImageUploadField` to override the field in question.
Have a look a the example at
https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms.
If you just want to manage static files, without tying them to a database model, then
rather use the :ref:`File-Admin<file-admin>` plugin.
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.
****
Adding your own views
Adding Your Own Views
======================
For situations where your requirements are really specific, and you struggle to meet
them with the builtin :class:`~flask_admin.model.ModelView` class: Flask-Admin makes it really easy for you to
take full control and ass some views yourself.
them with the builtin :class:`~flask_admin.model.ModelView` class: Flask-Admin makes it easy for you to
take full control and add your own views to the interface.
Standalone views
Standalone Views
------------------
To add a set of standalone views, that are not tied to any particular model, you can extend the
:class:`~flask_admin.base.BaseView` class, and define your own view methods on it. For
......@@ -375,8 +381,8 @@ example, to add a page that displays some analytics data from a 3rd-party API::
admin.add_view(CustomView(name='Analytics'))
This will add a link to the navbar, from where your view can be accessed. Notice that
it is served at the root URL, '/'. This is a restriction on standalone views: each view class needs
to serve a view at its root.
it is served at '/', the root URL. This is a restriction on standalone views: at the very minimum, each view class needs
at least one method, that serves a view at the root URL.
The `analytics_index.html` template for the example above, could look something like::
......@@ -388,12 +394,12 @@ The `analytics_index.html` template for the example above, could look something
By extending the *admin/master.html* template, you can maintain a consistent user experience,
even while having tight control over your page's content.
Overriding the builtin views
Overriding the Builtin Views
------------------------------------
If you want most of the builtin ModelView functionality, but you want to have your own view
in place of the default `create`, `edit`, or `list` view. Then you can simply
override the view in question, and all the links to it will still function as you would expect::
There may be some scenarios where you want most of the builtin ModelView
functionality, but you want to replace one of the default `create`, `edit`, or `list` views.
For this you could override only the view in question, and all the links to it will still function as you would expect::
from flask_admin.contrib.sqla import ModelView
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment