Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #4

Merged
merged 1 commit into from
Jul 27, 2016
Merged

Update README.md #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update README.md
  • Loading branch information
@sneksik
sneksik authored Jul 27, 2016
commit cbd1725caed6e9cf1d1de835da04d7e3b312fbbb
82 changes: 41 additions & 41 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
# GodMode 2

GodMode is a semi-automatic customizable admin interface generator that lets you add admin interface to any SQL database.
Written in Python 3.x and Flask, with superpower of WTForms and SQLAlchemy reflections.
GodMode is customizable semi-automatic admin interface generator that lets you to add an admin interface to any SQL database.
It was written in Python 3.x and Flask, with superpower of WTForms and SQLAlchemy reflections.

Automatically creates CRUD pages for any table in your database with ability to customize rows and views, create filters,
GodMode automatically creates CRUD pages for any table in your database with an ability to customize rows and views, create filters,
batch actions and manage access policies for users and groups.

Inspired by Django Admin Interface and Flask-Admin extension, but designed to be a standalone application.
So you don't need to have you app written using Django, Flask or even in Python at all. All you need is a SQL database.
Tested on several pet-projects and medium startups. Good for a quick start because you can make a simple CRUD using a few
lines of code and may add additional functionality as your product grows.
Inspired by Django Admin Interface and Flask-Admin extension, it has been designed as standalone application.
It's not necessary to have your app written using Django, Flask or even in Python at all. All you need is SQL database.
GodMode has been tested at several pet projects and projects of medium startups. Interface is good for a quick start since you can make a simple CRUD using just a few
lines of code and add additional functionality with the growth of your product.

Best for PostgreSQL, MySQL and SQLite. Also supports other SQLAlchemy drivers: Firebird, Microsoft SQL Server,
Oracle and Sybase but they were not officially tested (welcome to pull-requests and issues).
GodMode is best for PostgreSQL, MySQL and SQLite. It also supports other SQLAlchemy drivers such as Firebird, Microsoft SQL Server,
Oracle and Sybase. They were not officially tested though, so pull-requests and issue reports are welcome.

![Screenshot](static/screenshot.png?raw=true)

## Installation

**Demo user and password: demo/demo.**

Make sure that you have a Python 3.x. Python 2.x is not supported.
Make sure that you have Python 3.x. Python 2.x is not supported.

Clone this repository, install all requirements and run app.py.
Clone this repository, install all the requirements and run app.py.

```
$ git clone https://github.com/vas3k/GodMode2.git
Expand All @@ -36,11 +36,11 @@ Then open your browser at [localhost:1488](http://localhost:1488), enter demo/de
## Quick Start

For example your PostgreSQL database on `localhost` called `dbname`
and you have the `users` table in your database that you want to manage.
and you have the `users` table in the database you want to manage.
So your DSN is `postgresql+psycopg2://username:password@localhost/dbname`.
Check that you have an access to the database from your computer before the first step.
Check if you have an access to the database from your computer before you move to the first step.

**First step:** create new file in `db` directory and name it for example `my.py`.
**First step:** create new file in `db` directory and name it `my.py`, for example.
You can use `demo.py` as an example.
If you're familiar with SQLAlchemy it will be easy.

Expand All @@ -61,7 +61,7 @@ class User(MyDatabase.TableBase):
# you can declare your table columns here, but autoload=True will try to do it for you
```

**Second step:** create new model file for users admin in `models` directory. For example `users.py`.
**Second step:** create new model file for user administration in `models` directory. For example `users.py`.

```python
from base.model import BaseAdminModel
Expand Down Expand Up @@ -98,7 +98,7 @@ Now run `$ python3 app.py` and open [localhost:1488](http://localhost:1488). You

Great, you've just created your first simple CRUD for `users` table. Check the Usage section to learn how to configure it.

Maybe one day all these steps will be automated by the one script.
Probably, all these steps will be automated with the script one day.

## Usage

Expand All @@ -116,13 +116,13 @@ class FirstDatabase(BaseDatabase):
# bind your database class with engine (call it before any table declaration!)
FirstDatabase.bind()

# you even can have multiple databases (but better to describe them in separate files)
# you can even have multiple databases (it's better to describe them in separate files though)
class SecondDatabase(BaseDatabase):
dsn = "postgresql+psycopg2://username:password@postgres.example.com/dbname"

SecondDatabase.bind()

# describe couple of tables
# describe a couple of tables
class User(FirstDatabase.TableBase):
__table__ = sa.Table('users', FirstDatabase.metadata, autoload=True)

Expand All @@ -134,7 +134,7 @@ class Post(FirstDatabase.TableBase):
user = relationship('User')
```

Now tell GodMode about all your databases by editing `app.py`.
Now, tell GodMode about all your databases by editing `app.py`.

```python
app = GodModeApp(
Expand Down Expand Up @@ -193,7 +193,7 @@ class YourAdminModel(BaseAdminModel):
details_view = CustomDetailsView # see Views section for more info
```

Now return to the `app.py` file to specify new models for your app.
Now return to `app.py` file to specify new models for your app.


```python
Expand All @@ -210,8 +210,8 @@ class MyListView(BaseListView):
acl = ACL.MODERATOR # lowest ACL group who has access to this view
title = "My List" # title for HTML
template = "list.html" # you can specify your template for this view
fields = [...] # like "fields" in model, but specific for this view
sorting = ["id", "name"] # fields which allowed to sorting (default = None — all fields)
fields = [...] # same to "fields" in model, but specific for this view
sorting = ["id", "name"] # fields allowed for sorting (default = None — all fields)
batch_actions = [MyBatchAction] # see screenshot above
object_actions = [MyObjectAction]
max_per_page = 100
Expand All @@ -235,7 +235,7 @@ class MyAction(BaseAction):
def render_form(self, *args, **kwargs):
return render_template("actions/button_action.html", url=self.name, button_label="Submit")

# some code then action is executed, kwargs have all request parameters
# some code, triggered with action; kwargs have all request parameters
# but all you usually need is kwargs["id"]
def do_item_action(self, *args, **kwargs):
user_id = kwargs.pop("id")
Expand All @@ -245,11 +245,11 @@ class MyAction(BaseAction):

### Widgets

Widgets are using great [WTForms](https://github.com/wtforms/wtforms) library for form parsing, validation and rendering.
But they are responsible for rendering in all views — create, list, details, delete.
If you're familiar with WTForms, you have all the superpowers in your hand. Otherwise check it's documentation.
Widgets use great [WTForms](https://github.com/wtforms/wtforms) library for form parsing, validation and rendering.
They are responsible for rendering in all views — create, list, details, delete.
If you're familiar with WTForms, you have all the superpowers in your hand. Otherwise, check the documentation.

However you can create widgets that are completely independent from WTForms. Check `widgets/polygon.py` for example.
You can also create widgets which are completely independent from WTForms. Check `widgets/polygon.py` for example.

```python
class MyWidget(BaseWidget):
Expand All @@ -274,29 +274,29 @@ class MyWidget(BaseWidget):

### Groups

Groups allows you to combine models into logical sets in sidebar.
Models without group have a higher priority and displayed at the top of sidebar.
Groups allow you to combine models into logical sets in sidebar.
Models without group have higher priority and displayed at the top of sidebar.

```python
class MyGroup(BaseGroup):
acl = ACL.MODERATOR # you can hide whole group from users lower than MODERATOR level
acl = ACL.MODERATOR # you can hide the whole group from users lower than MODERATOR level
name = "Group name" # title to display in sidebar
index = 1000 # higher index -> higher position
```

### ACL's and policies
### ACLs and policies

ACL's and their priorities are defined in `common/acl.py` file: `PRIORITY = [SUPERUSER, ADMIN, MODERATOR, ALL]`.
ACLs and their priorities are defined in `common/acl.py` file: `PRIORITY = [SUPERUSER, ADMIN, MODERATOR, ALL]`.
You can create any group for yourself but don't forget to put it into PRIORITY list.

* SUPERUSER is a group of users with the highest privileges. They have permission to do everything in GodMode.
* SUPERUSER is a group of users with highest privileges. They have permission to do everything in GodMode.
Use carefully. Usually 1 superuser per project is enough.
* ADMIN's have all permissions to edit all databases but can't create and manage other GodMode users.
* MODERATOR's are read-only users by default. You're able to hide some models, views, groups and actions from moderators.
* ALL specifies that module is public even for unauthorized users. Made for login screen, don't know why they can be useful for you.
* ADMINs have all permissions to edit the databases but they cannot create and manage other GodMode users.
* MODERATORs are read-only users by default. You can hide any models, views, groups and actions from moderators.
* ALL specifies that module is visible even for unauthorized users. It was made for login screen — don't know how it can be useful for you.

Policies are written in a very bad and unoptimized way, so they really need a huge refactoring.
**Don't use it for now.**
Policies are written in a bad and unoptimized way, so large refactoring is needed.
**Do not use it for now.**

## Future Plans

Expand All @@ -305,14 +305,14 @@ Policies are written in a very bad and unoptimized way, so they really need a hu
* Make Widgets Great Again (+sexy appearance)
* Support default values from more databases
* Rewrite policies
* Security test for XSS and injections (be careful with that, check all models you create and send me pull requests)
* Security test for XSS and injections (be careful with that; check all the models you create and send me pull requests)
* Think about better filtering/sorting interface
* Make an install~~.php~~ file for easier cold start
* Maybe more AJAX for validation and inline editing
* More AJAX for validation and inline editing, probably

## Similar Projects

Other great projects for automatic admin interfaces:
Other great projects of automatic admin interfaces:

* [Django Admin Module (Python)](https://docs.djangoproject.com/en/dev/ref/contrib/admin/)
* [Flask-Admin (Python)](https://github.com/flask-admin/flask-admin)
Expand Down