Commit 7a5f88db authored by Serge S. Koval's avatar Serge S. Koval

More documentation.

parent 0e0dd4e8
[submodule "doc/_themes"]
path = doc/_themes
url = https://github.com/mitsuhiko/flask-sphinx-themes.git
Subproject commit 0269f3d188eaff07c44a800f35f7351f9e0aefb0
API
===
.. toctree::
:maxdepth: 2
mod_base
mod_model
mod_form
mod_tools
mod_ext_sqlamodel
...@@ -91,7 +91,10 @@ pygments_style = 'sphinx' ...@@ -91,7 +91,10 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # a list of builtin themes.
html_theme = 'default' sys.path.append(os.path.abspath('_themes'))
html_theme = 'flask'
html_theme_path = ['_themes']
# Theme options are theme-specific and customize the look and feel of a theme # Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
......
...@@ -10,6 +10,7 @@ Topics ...@@ -10,6 +10,7 @@ Topics
:maxdepth: 2 :maxdepth: 2
quickstart quickstart
api
Indices and tables Indices and tables
......
``flask.ext.adminex.base``
==========================
.. automodule:: flask.ext.adminex.base
Base View
---------
.. autofunction:: expose
.. autoclass:: BaseView
.. automethod:: BaseView.__init__
.. automethod:: BaseView.is_accessible
.. automethod:: BaseView.render
Internal
--------
.. automethod:: BaseView.create_blueprint
Default view
------------
.. autoclass:: AdminIndexView
.. automethod:: __init__
Admin
-----
.. autoclass:: Admin
.. automethod:: __init__
.. automethod:: add_view
.. automethod:: setup_app
.. automethod:: menu
``flask.ext.adminex.ext.sqlamodel``
===================================
.. automodule:: flask.ext.adminex.ext.sqlamodel
.. autoclass:: ModelView
Permissions
-----------
.. autoattribute:: BaseModelView.can_create
.. autoattribute:: BaseModelView.can_edit
.. autoattribute:: BaseModelView.can_delete
Templates
---------
.. autoattribute:: BaseModelView.list_template
.. autoattribute:: BaseModelView.edit_template
.. autoattribute:: BaseModelView.create_template
Customizations
--------------
.. autoattribute:: BaseModelView.list_columns
.. autoattribute:: BaseModelView.rename_columns
.. autoattribute:: BaseModelView.sortable_columns
.. autoattribute:: BaseModelView.form_columns
.. autoattribute:: BaseModelView.form_args
.. autoattribute:: ModelView.hide_backrefs
.. autoattribute:: BaseModelView.page_size
Constructor
-----------
.. automethod:: ModelView.__init__
Scaffolding
-----------
.. automethod:: ModelView.scaffold_list_columns
.. automethod:: ModelView.scaffold_sortable_columns
.. automethod:: ModelView.scaffold_form
Configuration
-------------
.. automethod:: ModelView.get_list_columns
.. automethod:: ModelView.get_sortable_columns
.. automethod:: ModelView.get_create_form
.. automethod:: ModelView.get_edit_form
Data
----
.. automethod:: ModelView.get_list
.. automethod:: ModelView.get_one
.. automethod:: ModelView.create_model
.. automethod:: ModelView.update_model
.. automethod:: ModelView.delete_model
Helpers
-------
.. automethod:: ModelView.create_form
.. automethod:: ModelView.edit_form
.. automethod:: ModelView.is_sortable
.. automethod:: ModelView.prettify_name
Views
-----
.. automethod:: ModelView.index_view
.. automethod:: ModelView.create_view
.. automethod:: ModelView.edit_view
.. automethod:: ModelView.delete_view
Internal API
------------
.. automethod:: ModelView._get_url
``flask.ext.adminex.form``
==========================
.. automodule:: flask.ext.adminex.form
.. autoclass:: AdminForm
.. automethod:: has_file_field
``flask.ext.adminex.model``
===========================
.. automodule:: flask.ext.adminex.model
.. autoclass:: BaseModelView
Permissions
-----------
.. autoattribute:: BaseModelView.can_create
.. autoattribute:: BaseModelView.can_edit
.. autoattribute:: BaseModelView.can_delete
Templates
---------
.. autoattribute:: BaseModelView.list_template
.. autoattribute:: BaseModelView.edit_template
.. autoattribute:: BaseModelView.create_template
Customizations
--------------
.. autoattribute:: BaseModelView.list_columns
.. autoattribute:: BaseModelView.rename_columns
.. autoattribute:: BaseModelView.sortable_columns
.. autoattribute:: BaseModelView.form_columns
.. autoattribute:: BaseModelView.form_args
.. autoattribute:: BaseModelView.page_size
Constructor
-----------
.. automethod:: BaseModelView.__init__
Scaffolding
-----------
.. automethod:: BaseModelView.scaffold_list_columns
.. automethod:: BaseModelView.scaffold_sortable_columns
.. automethod:: BaseModelView.scaffold_form
Configuration
-------------
.. automethod:: BaseModelView.get_list_columns
.. automethod:: BaseModelView.get_sortable_columns
.. automethod:: BaseModelView.get_create_form
.. automethod:: BaseModelView.get_edit_form
Data
----
.. automethod:: BaseModelView.get_list
.. automethod:: BaseModelView.get_one
.. automethod:: BaseModelView.create_model
.. automethod:: BaseModelView.update_model
.. automethod:: BaseModelView.delete_model
Helpers
-------
.. automethod:: BaseModelView.create_form
.. automethod:: BaseModelView.edit_form
.. automethod:: BaseModelView.is_sortable
.. automethod:: BaseModelView.prettify_name
Views
-----
.. automethod:: BaseModelView.index_view
.. automethod:: BaseModelView.create_view
.. automethod:: BaseModelView.edit_view
.. automethod:: BaseModelView.delete_view
Internal API
------------
.. automethod:: BaseModelView._get_url
``flask.ext.adminex.tools``
===========================
.. automodule:: flask.ext.adminex.tools
.. autofunction:: import_module
.. autofunction:: import_attribute
.. autofunction:: module_not_found
.. autofunction:: rec_getattr
...@@ -2,20 +2,16 @@ Quick Start ...@@ -2,20 +2,16 @@ Quick Start
=========== ===========
This page gives quick introduction to Flask-AdminEx library. It is assumed that reader has some prior This page gives quick introduction to Flask-AdminEx library. It is assumed that reader has some prior
knowledge of Flask framework. knowledge of `Flask <http://flask.pocoo.org/>`_ framework.
Introduction Introduction
------------ ------------
While developing the library, I had set of goals which should make it very easy to use and won't While developing the library, I attempted to make it as flexible as possible, so you don't have
require monkey patching to achieve desired functionality. Here they are: to monkey patch, if you wanted to extend or change existing functionality.
1. It should be flexible Library uses one simple, but powerful concept - administrative pieces are built as classes with
2. It should be reusable view methods.
3. It should look nice
Library uses one simple, but powerful concept - administrative pieces are grouped by functionality
into classes with their own view methods.
Here is absolutely valid administrative piece:: Here is absolutely valid administrative piece::
...@@ -28,14 +24,18 @@ Here is absolutely valid administrative piece:: ...@@ -28,14 +24,18 @@ Here is absolutely valid administrative piece::
def test(self): def test(self):
return render_template('admin/test.html', view=self) return render_template('admin/test.html', view=self)
So, how does it help structuring administrative interface? With such building blocks, you're
implementing reusable functional pieces that are highly customizable.
With this approach, all of OOP concepts apply. You can derive, you can modify behavior, you can do For example, Flask-AdminEx provides ready-to-use SQLAlchemy model interface. It is implemented as a
whatever you want. class which accepts two parameters: model and a database session. While it exposes some
class-level variables which change behavior of the interface (somewhat similar to django.contrib.admin),
nothing prohibits you from overriding form creation or database access methods or adding more views.
Initialization Initialization
-------------- --------------
You must create `Admin` class and associate it with the `Flask` application:: To start using Admin, you have to create `Admin` class instance and associate it with Flask application::
from flask import Flask from flask import Flask
from flask.ext.adminex import Admin from flask.ext.adminex import Admin
...@@ -48,18 +48,20 @@ You must create `Admin` class and associate it with the `Flask` application:: ...@@ -48,18 +48,20 @@ You must create `Admin` class and associate it with the `Flask` application::
app.run() app.run()
If you will run this application and will navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_, If you will run this application and will navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_,
you should see lonely Home page with a navigation bar on top. you should see empty "Home" page with a navigation bar on top.
You can change application name by passing `name` parameter to the `Admin` class constructor:: You can change application name by passing `name` parameter to the `Admin` class constructor::
admin = Admin(name='My App') admin = Admin(name='My App')
admin.setup_app(app) admin.setup_app(app)
Name is displayed in the menu section.
Adding first view Adding view
----------------- -----------
Now, lets add custom view:: Now, lets add a view. To do this, you need to derive from `BaseView` class::
from flask import Flask from flask import Flask
from flask.ext.adminex import Admin, BaseView from flask.ext.adminex import Admin, BaseView
...@@ -94,24 +96,26 @@ If you will refresh 'Hello' administrative page again you should see greeting in ...@@ -94,24 +96,26 @@ If you will refresh 'Hello' administrative page again you should see greeting in
Authentication Authentication
-------------- --------------
By default, administrative interface will be visible to everyone, as Flask-AdminEx does not make By default, administrative interface is visible to everyone, as Flask-AdminEx does not make
any assumptions about authentication system you're using. any assumptions about authentication system you're using.
If you want to control who can access administrative views and who can not, derive from the If you want to control who can access administrative views and who can not, derive from the
administrative view class and implement `is_accessible` method:: administrative view class and implement `is_accessible` method. So, if you use Flask-Login and
want to expose administrative interface only to logged in users, you can do something like
this::
class MyView(BaseView): class MyView(BaseView):
def is_accessible(self): def is_accessible(self):
return login.current_user.is_authenticated() return login.current_user.is_authenticated()
Menu is generated dynamically, so you can implement policy based security, so some users will see Menu is generated dynamically, so you can implement policy-based security and conditionally
some of the administrative interface, others won't be able to, etc. allow or disallow access to parts of the administrative interface.
Generating URLs Generating URLs
--------------- ---------------
Internally, these view classes work on top of Flask blueprints, so you can use `url_for` with a dot Internally, view classes work on top of Flask blueprints, so you can use `url_for` with a dot
prefix to get URL to a local view:: prefix to get URL to a local view::
class MyView(BaseView): class MyView(BaseView):
...@@ -158,15 +162,15 @@ Flask-AdminEx comes with built-in SQLAlchemy model administrative interface. It ...@@ -158,15 +162,15 @@ Flask-AdminEx comes with built-in SQLAlchemy model administrative interface. It
# Flask and Flask-SQLAlchemy initialization here # Flask and Flask-SQLAlchemy initialization here
admin = Admin() admin = Admin()
admin.add_view(ModelBase(User, db.session, name='Users')) admin.add_view(ModelBase(User, db.session))
admin.setup_app(app) admin.setup_app(app)
This will create administrative interface for `User` model with default settings. This will create administrative interface for `User` model with default settings.
If you want to customize model views, you have two options: If you want to customize model views, you have two options:
1. Change behavior by overriding public properties that control how these views work 1. Change behavior by overriding public properties that control how view works
2. Change behavior by overriding view methods 2. Change behavior by overriding methods
For example, if you want to disable model creation, show only 'login' and 'email' columns in the list view, For example, if you want to disable model creation, show only 'login' and 'email' columns in the list view,
you can do something like this:: you can do something like this::
...@@ -185,6 +189,7 @@ you can do something like this:: ...@@ -185,6 +189,7 @@ you can do something like this::
admin.add_view(UserView(db.session)) admin.add_view(UserView(db.session))
admin.setup_app(app) admin.setup_app(app)
It is very easy to add support for different database backends (Mongo, etc) by inheriting from `BaseModelView` It is very easy to add support for different database backends (Mongo, etc) by inheriting from `BaseModelView`
class and implementing database-related methods. class and implementing database-related methods.
...@@ -195,6 +200,6 @@ Examples ...@@ -195,6 +200,6 @@ Examples
Flask-AdminEx comes with three samples: Flask-AdminEx comes with three samples:
- Simple administrative interface with custom administrative views - `Simple administrative interface <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/simple>`_ with custom administrative views
- Sample model view interface - `SQLAlchemy model example <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/sqla>`_
- Flask-Login integration sample - `Flask-Login integration example <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/auth>`_
...@@ -7,6 +7,7 @@ from flask import Blueprint, render_template, url_for, abort ...@@ -7,6 +7,7 @@ from flask import Blueprint, render_template, url_for, abort
def expose(url='/', methods=('GET',)): def expose(url='/', methods=('GET',)):
""" """
Use this decorator to expose views in your view classes. Use this decorator to expose views in your view classes.
`url` `url`
Relative URL for the view Relative URL for the view
`methods` `methods`
......
...@@ -65,7 +65,8 @@ class ModelView(BaseModelView): ...@@ -65,7 +65,8 @@ class ModelView(BaseModelView):
Usage sample:: Usage sample::
admin = ModelView(User, db.session) admin = Admin()
admin.add_view(ModelView(User, db.session))
""" """
hide_backrefs = True hide_backrefs = True
......
...@@ -2,8 +2,15 @@ from flask.ext import wtf ...@@ -2,8 +2,15 @@ from flask.ext import wtf
class AdminForm(wtf.Form): class AdminForm(wtf.Form):
"""
Customized form class.
"""
@property @property
def has_file_field(self): def has_file_field(self):
"""
Return True if form contains at least one FileField.
"""
# TODO: Optimize me # TODO: Optimize me
for f in self: for f in self:
if isinstance(f, wtf.FileField): if isinstance(f, wtf.FileField):
......
...@@ -112,7 +112,7 @@ class BaseModelView(BaseView): ...@@ -112,7 +112,7 @@ class BaseModelView(BaseView):
# Various settings # Various settings
page_size = 20 page_size = 20
""" """
Page size. You can change it to something you want. Default page size.
""" """
def __init__(self, model, def __init__(self, model,
...@@ -147,11 +147,18 @@ class BaseModelView(BaseView): ...@@ -147,11 +147,18 @@ class BaseModelView(BaseView):
self.model = model self.model = model
# Scaffolding # Scaffolding
self._refresh_cache()
# Caching
def _refresh_cache(self):
"""
Refresh various cached variables.
"""
self._list_columns = self.get_list_columns() self._list_columns = self.get_list_columns()
self._sortable_columns = self.get_sortable_columns() self._sortable_columns = self.get_sortable_columns()
self._create_form_class = self.scaffold_create_form() self._create_form_class = self.get_create_form()
self._edit_form_class = self.scaffold_edit_form() self._edit_form_class = self.get_edit_form()
# Public API # Public API
def scaffold_list_columns(self): def scaffold_list_columns(self):
...@@ -225,7 +232,7 @@ class BaseModelView(BaseView): ...@@ -225,7 +232,7 @@ class BaseModelView(BaseView):
""" """
raise NotImplemented('Please implement scaffold_form method') raise NotImplemented('Please implement scaffold_form method')
def scaffold_create_form(self): def get_create_form(self):
""" """
Create form class for model creation view. Create form class for model creation view.
...@@ -233,7 +240,7 @@ class BaseModelView(BaseView): ...@@ -233,7 +240,7 @@ class BaseModelView(BaseView):
""" """
return self.scaffold_form() return self.scaffold_form()
def scaffold_edit_form(self): def get_edit_form(self):
""" """
Create form class for model editing view. Create form class for model editing view.
......
import sys, traceback import sys
import traceback
def import_module(name, required=True): def import_module(name, required=True):
......
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