Commit 971bea12 authored by Serge S. Koval's avatar Serge S. Koval

Documentation changes

parent 04879b2e
include LICENSE include LICENSE
recursive-include flask_adminex/static * recursive-include flask_admin/static *
recursive-include flask_adminex/templates * recursive-include flask_admin/templates *
recursive-include flask_adminex/translations * recursive-include flask_admin/translations *
Flask-AdminEx Flask-Admin
============= ===========
Contributors Contributors
------------ ------------
...@@ -11,7 +11,7 @@ Introduction ...@@ -11,7 +11,7 @@ Introduction
This is library for building adminstrative interface on top of Flask framework. This is library for building adminstrative interface on top of Flask framework.
Instead of providing simple scaffolding for the SQLAlchemy models, Flask-AdminEx Instead of providing simple scaffolding for the SQLAlchemy models, Flask-Admin
provides tools that can be used to build adminstrative interface of any complexity, provides tools that can be used to build adminstrative interface of any complexity,
using consistent look and feel. using consistent look and feel.
...@@ -24,16 +24,17 @@ Small example (Flask initialization omitted):: ...@@ -24,16 +24,17 @@ Small example (Flask initialization omitted)::
admin.add_view(GalleryManager(name='Photos', category='Cats')) admin.add_view(GalleryManager(name='Photos', category='Cats'))
admin.setup_app(app) admin.setup_app(app)
If you're looking for 0.x version of the Flask-Admin written by Andy Wilson, check `here <https://github.com/wilsaj/flask-admin>`_
Documentation Documentation
------------- -------------
Flask-AdminEx is extensively documented, you can find documentation `here <http://readthedocs.org/docs/flask-adminex>`_. Flask-Admin is extensively documented, you can find documentation `here <http://readthedocs.org/docs/flask-admin>`_.
3rd Party Stuff 3rd Party Stuff
--------------- ---------------
Flask-AdminEx is built with help of `Twitter Bootstrap <http://twitter.github.com/bootstrap/>`_ and `Chosen <http://harvesthq.github.com/chosen/>`_. Flask-Admin is built with help of `Twitter Bootstrap <http://twitter.github.com/bootstrap/>`_ and `Chosen <http://harvesthq.github.com/chosen/>`_.
Kudos Kudos
----- -----
......
pybabel extract -F babel.ini -k _gettext -k _ngettext -k lazy_gettext -o admin.pot --project Flask-AdminEx ..\flask_adminex pybabel extract -F babel.ini -k _gettext -k _ngettext -k lazy_gettext -o admin.pot --project Flask-Admin ..\flask_admin
#!/bin/sh #!/bin/sh
pybabel extract -F babel.ini -k _gettext -k _ngettext -k lazy_gettext -o admin.pot --project Flask-AdminEx ../flask_adminex pybabel extract -F babel.ini -k _gettext -k _ngettext -k lazy_gettext -o admin.pot --project Flask-Admin ../flask_admin
Flask-AdminEx Flask-Admin
============= ===========
Flask-AdminEx is simple and extensible administrative interface framework for `Flask <http://flask.pocoo.org/>`_. Flask-Admin is simple and extensible administrative interface framework for `Flask <http://flask.pocoo.org/>`_.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
......
``flask.ext.adminex.base`` ``flask.ext.admin.base``
========================== ========================
.. automodule:: flask.ext.adminex.base .. automodule:: flask.ext.admin.base
Base View Base View
--------- ---------
......
``flask.ext.adminex.ext.fileadmin`` ``flask.ext.admin.ext.fileadmin``
=================================== =================================
.. automodule:: flask.ext.adminex.ext.fileadmin .. automodule:: flask.ext.admin.ext.fileadmin
.. autoclass:: FileAdmin .. autoclass:: FileAdmin
:members: :members:
......
``flask.ext.adminex.ext.sqlamodel`` ``flask.ext.admin.ext.sqlamodel``
=================================== =================================
.. automodule:: flask.ext.adminex.ext.sqlamodel .. automodule:: flask.ext.admin.ext.sqlamodel
.. autoclass:: ModelView .. autoclass:: ModelView
:members: :members:
...@@ -9,7 +9,7 @@ ...@@ -9,7 +9,7 @@
:exclude-members: hide_backrefs, auto_select_related, list_select_related, :exclude-members: hide_backrefs, auto_select_related, list_select_related,
searchable_columns, filter_converter searchable_columns, filter_converter
Class inherits configuration options from :class:`~flask.ext.adminex.model.BaseModelView` and they're not displayed here. Class inherits configuration options from :class:`~flask.ext.admin.model.BaseModelView` and they're not displayed here.
.. autoattribute:: hide_backrefs .. autoattribute:: hide_backrefs
.. autoattribute:: auto_select_related .. autoattribute:: auto_select_related
......
``flask.ext.adminex.form`` ``flask.ext.admin.form``
========================== ========================
.. automodule:: flask.ext.adminex.form .. automodule:: flask.ext.admin.form
.. autoclass:: BaseForm .. autoclass:: BaseForm
:members: :members:
``flask.ext.adminex.model`` ``flask.ext.admin.model``
=========================== =========================
.. automodule:: flask.ext.adminex.model .. automodule:: flask.ext.admin.model
.. autoclass:: BaseModelView .. autoclass:: BaseModelView
:members: :members:
......
``flask.ext.adminex.tools`` ``flask.ext.admin.tools``
=========================== =========================
.. automodule:: flask.ext.adminex.tools .. automodule:: flask.ext.admin.tools
.. autofunction:: import_module .. autofunction:: import_module
.. autofunction:: import_attribute .. autofunction:: import_attribute
......
...@@ -16,7 +16,7 @@ There are few assumptions about models: ...@@ -16,7 +16,7 @@ There are few assumptions about models:
Steps to add new model backend: Steps to add new model backend:
1. Create new class and derive it from :class:`~flask.ext.adminex.model.BaseModelView`:: 1. Create new class and derive it from :class:`~flask.ext.admin.model.BaseModelView`::
class MyDbModel(BaseModelView): class MyDbModel(BaseModelView):
pass pass
...@@ -26,11 +26,11 @@ Steps to add new model backend: ...@@ -26,11 +26,11 @@ Steps to add new model backend:
2. Implement following scaffolding methods:: 2. Implement following scaffolding methods::
- :meth:`~flask.ext.adminex.model.BaseModelView.get_pk_value` - :meth:`~flask.ext.admin.model.BaseModelView.get_pk_value`
This method will return primary key value from This method will return primary key value from
the model. For example, in SQLAlchemy backend, the model. For example, in SQLAlchemy backend,
it gets primary key from the model (:meth:`~flask.ext.adminex.ext.sqla.ModelView.scaffold_pk), caches it it gets primary key from the model (:meth:`~flask.ext.admin.ext.sqla.ModelView.scaffold_pk), caches it
and returns actual value from the model from ``get_pk_value`` when requested. and returns actual value from the model from ``get_pk_value`` when requested.
For example:: For example::
...@@ -39,7 +39,7 @@ Steps to add new model backend: ...@@ -39,7 +39,7 @@ Steps to add new model backend:
def get_pk_value(self, model): def get_pk_value(self, model):
return self.model.id return self.model.id
- :meth:`~flask.ext.adminex.model.BaseModelView.scaffold_list_columns` - :meth:`~flask.ext.admin.model.BaseModelView.scaffold_list_columns`
Returns list of columns to be displayed in a list view. Returns list of columns to be displayed in a list view.
Make sure you exclude columns if `self.excluded_list_columns` was set. Make sure you exclude columns if `self.excluded_list_columns` was set.
...@@ -59,7 +59,7 @@ Steps to add new model backend: ...@@ -59,7 +59,7 @@ Steps to add new model backend:
return columns return columns
- :meth:`~flask.ext.adminex.model.BaseModelView.scaffold_sortable_columns` - :meth:`~flask.ext.admin.model.BaseModelView.scaffold_sortable_columns`
Returns dictionary of sortable columns. Key in a dictionary is field name. Value - implementation Returns dictionary of sortable columns. Key in a dictionary is field name. Value - implementation
specific, value that will be used by you backend implementation to do actual sort operation. specific, value that will be used by you backend implementation to do actual sort operation.
...@@ -72,7 +72,7 @@ Steps to add new model backend: ...@@ -72,7 +72,7 @@ Steps to add new model backend:
If your backend does not support sorting, return If your backend does not support sorting, return
`None` or empty dictionary. `None` or empty dictionary.
- :meth:`~flask.ext.adminex.model.BaseModelView.init_search` - :meth:`~flask.ext.admin.model.BaseModelView.init_search`
Initialize search functionality. If your backend supports Initialize search functionality. If your backend supports
full-text search, do initializations and return `True`. full-text search, do initializations and return `True`.
...@@ -84,7 +84,7 @@ Steps to add new model backend: ...@@ -84,7 +84,7 @@ Steps to add new model backend:
it will add a join, etc) and caches this information for it will add a join, etc) and caches this information for
future use. future use.
- :meth:`~flask.ext.adminex.model.BaseModelView.is_valid_filter` - :meth:`~flask.ext.admin.model.BaseModelView.is_valid_filter`
Verify if provided object is a valid filter. Verify if provided object is a valid filter.
...@@ -94,16 +94,16 @@ Steps to add new model backend: ...@@ -94,16 +94,16 @@ Steps to add new model backend:
This also means that different backends might have This also means that different backends might have
different set of available filters. different set of available filters.
Filter is a class derived from :class:`~flask.ext.adminex.model.filters.BaseFilter` which implements at least two methods: Filter is a class derived from :class:`~flask.ext.admin.model.filters.BaseFilter` which implements at least two methods:
1. :meth:`~flask.ext.adminex.model.filters.BaseFilter.apply` 1. :meth:`~flask.ext.admin.model.filters.BaseFilter.apply`
2. :meth:`~flask.ext.adminex.model.filters.BaseFilter.operation` 2. :meth:`~flask.ext.admin.model.filters.BaseFilter.operation`
`apply` method accepts two parameters: `query` object and a value from the client. Here you will add `apply` method accepts two parameters: `query` object and a value from the client. Here you will add
filtering logic for this filter type. filtering logic for this filter type.
Lets take SQLAlchemy model backend as an example. Lets take SQLAlchemy model backend as an example.
All SQLAlchemy filters derive from :class:`~flask.ext.adminex.ext.sqla.filters.BaseSQLAFilter` class. All SQLAlchemy filters derive from :class:`~flask.ext.admin.ext.sqla.filters.BaseSQLAFilter` class.
Each filter implements one simple filter SQL operation Each filter implements one simple filter SQL operation
(like, not like, greater, etc) and accepts column as (like, not like, greater, etc) and accepts column as
...@@ -139,7 +139,7 @@ Steps to add new model backend: ...@@ -139,7 +139,7 @@ Steps to add new model backend:
def clean(self, value): def clean(self, value):
return value return value
- :meth:`~flask.ext.adminex.model.BaseModelView.scaffold_filters` - :meth:`~flask.ext.admin.model.BaseModelView.scaffold_filters`
Return list of filter objects for one model field. Return list of filter objects for one model field.
...@@ -158,7 +158,7 @@ Steps to add new model backend: ...@@ -158,7 +158,7 @@ Steps to add new model backend:
if isinstance(attr, MyDbTextField): if isinstance(attr, MyDbTextField):
return [MyEqualFilter(name, name)] return [MyEqualFilter(name, name)]
- :meth:`~flask.ext.adminex.model.BaseModelView.scaffold_form` - :meth:`~flask.ext.admin.model.BaseModelView.scaffold_form`
Generate `WTForms` form class from the model. Generate `WTForms` form class from the model.
...@@ -172,7 +172,7 @@ Steps to add new model backend: ...@@ -172,7 +172,7 @@ Steps to add new model backend:
# Do something # Do something
return MyForm return MyForm
- :meth:`~flask.ext.adminex.model.BaseModelView.get_list` - :meth:`~flask.ext.admin.model.BaseModelView.get_list`
This method should return list of models with paging, This method should return list of models with paging,
sorting, etc applied. sorting, etc applied.
...@@ -202,19 +202,19 @@ Steps to add new model backend: ...@@ -202,19 +202,19 @@ Steps to add new model backend:
6. Return count, list as a tuple 6. Return count, list as a tuple
- :meth:`~flask.ext.adminex.model.BaseModelView.get_one` - :meth:`~flask.ext.admin.model.BaseModelView.get_one`
Return one model by its primary key. Return one model by its primary key.
- :meth:`~flask.ext.adminex.model.BaseModelView.create_model` - :meth:`~flask.ext.admin.model.BaseModelView.create_model`
Create new model from the `Form` object. Create new model from the `Form` object.
- :meth:`~flask.ext.adminex.model.BaseModelView.update_model` - :meth:`~flask.ext.admin.model.BaseModelView.update_model`
Update provided model with the data from the form. Update provided model with the data from the form.
- :meth:`~flask.ext.adminex.model.BaseModelView.delete_model` - :meth:`~flask.ext.admin.model.BaseModelView.delete_model`
Delete provided model from the data store. Delete provided model from the data store.
......
Quick Start 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-Admin library. It is assumed that reader has some prior
knowledge of the `Flask <http://flask.pocoo.org/>`_ framework. knowledge of the `Flask <http://flask.pocoo.org/>`_ framework.
Introduction Introduction
...@@ -27,7 +27,7 @@ Here is absolutely valid administrative piece:: ...@@ -27,7 +27,7 @@ Here is absolutely valid administrative piece::
So, how does it help structuring administrative interface? With such building blocks, you're So, how does it help structuring administrative interface? With such building blocks, you're
implementing reusable functional pieces that are highly customizable. implementing reusable functional pieces that are highly customizable.
For example, Flask-AdminEx provides ready-to-use SQLAlchemy model interface. It is implemented as a For example, Flask-Admin provides ready-to-use SQLAlchemy model interface. It is implemented as a
class which accepts two parameters: model and a database session. While it exposes some 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), class-level variables which change behavior of the interface (somewhat similar to django.contrib.admin),
nothing prohibits you from overriding form creation logic, database access methods or adding more views. nothing prohibits you from overriding form creation logic, database access methods or adding more views.
...@@ -35,10 +35,10 @@ nothing prohibits you from overriding form creation logic, database access metho ...@@ -35,10 +35,10 @@ nothing prohibits you from overriding form creation logic, database access metho
Initialization Initialization
-------------- --------------
To start using Flask-AdminEx, you have to create `Admin` class instance and associate it with Flask application:: To start using Flask-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.admin import Admin
app = Flask(__name__) app = Flask(__name__)
...@@ -71,7 +71,7 @@ Adding view ...@@ -71,7 +71,7 @@ Adding view
Now, lets add a view. To do this, you need to derive from `BaseView` class:: 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, expose from flask.ext.admin import Admin, BaseView, expose
class MyView(BaseView): class MyView(BaseView):
@expose('/') @expose('/')
...@@ -113,7 +113,7 @@ You're not limited to top level menu. It is possible to pass category name and i ...@@ -113,7 +113,7 @@ You're not limited to top level menu. It is possible to pass category name and i
top menu item. For example:: top menu item. For example::
from flask import Flask from flask import Flask
from flask.ext.adminex import Admin, BaseView, expose from flask.ext.admin import Admin, BaseView, expose
class MyView(BaseView): class MyView(BaseView):
@expose('/') @expose('/')
...@@ -137,7 +137,7 @@ Will look like this: ...@@ -137,7 +137,7 @@ Will look like this:
Authentication Authentication
-------------- --------------
By default, administrative interface is visible to everyone, as Flask-AdminEx does not make By default, administrative interface is visible to everyone, as Flask-Admin 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
...@@ -194,9 +194,9 @@ is not provided. Model-based views will be explained in the next section. ...@@ -194,9 +194,9 @@ is not provided. Model-based views will be explained in the next section.
Model Views Model Views
----------- -----------
Flask-AdminEx comes with built-in SQLAlchemy model administrative interface. It is very easy to use:: Flask-Admin comes with built-in SQLAlchemy model administrative interface. It is very easy to use::
from flask.ext.adminex.ext.sqlamodel import ModelView from flask.ext.admin.ext.sqlamodel import ModelView
from flask.ext.sqlalchemy import db from flask.ext.sqlalchemy import db
# Flask and Flask-SQLAlchemy initialization here # Flask and Flask-SQLAlchemy initialization here
...@@ -236,16 +236,16 @@ you can do something like this:: ...@@ -236,16 +236,16 @@ you can do something like this::
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.
Please refer to :mod:`flask.ext.adminex.ext.sqlamodel` documentation on how to customize behavior of model-based administrative views. Please refer to :mod:`flask.ext.admin.ext.sqlamodel` documentation on how to customize behavior of model-based administrative views.
File Admin File Admin
---------- ----------
Flask-AdminEx comes with another handy battery - file admin. It gives you ability to manage files on your server (upload, delete, rename, etc). Flask-Admin comes with another handy battery - file admin. It gives you ability to manage files on your server (upload, delete, rename, etc).
Here is simple example:: Here is simple example::
from flask.ext.adminex.ext.fileadmin import FileAdmin from flask.ext.admin.ext.fileadmin import FileAdmin
import os.path as op import os.path as op
...@@ -263,14 +263,14 @@ Sample screenshot: ...@@ -263,14 +263,14 @@ Sample screenshot:
:target: ../_images/quickstart_5.png :target: ../_images/quickstart_5.png
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.ext.adminex.ext.fileadmin` documentation on how to do it. Check :mod:`flask.ext.admin.ext.fileadmin` documentation on how to do it.
Examples Examples
-------- --------
Flask-AdminEx comes with four samples: Flask-Admin comes with four samples:
- `Simple administrative interface <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/simple>`_ with custom administrative views - `Simple administrative interface <https://github.com/MrJoes/Flask-Admin/tree/master/examples/simple>`_ with custom administrative views
- `SQLAlchemy model example <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/sqla>`_ - `SQLAlchemy model example <https://github.com/MrJoes/Flask-Admin/tree/master/examples/sqla>`_
- `Flask-Login integration example <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/auth>`_ - `Flask-Login integration example <https://github.com/MrJoes/Flask-Admin/tree/master/examples/auth>`_
- `File management interface <https://github.com/MrJoes/Flask-AdminEx/tree/master/examples/file>`_ - `File management interface <https://github.com/MrJoes/Flask-Admin/tree/master/examples/file>`_
...@@ -2,4 +2,4 @@ ...@@ -2,4 +2,4 @@
detailed-errors=1 detailed-errors=1
with-coverage=0 with-coverage=0
debug=nose.loader debug=nose.loader
tests=flask_adminex/tests/test_base.py tests=flask_admin/tests/test_base.py
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