jazzband / django-admin2

Extendable, adaptable rewrite of django.contrib.admin

django-admin2

One of the most useful parts of django.contrib.admin is the ability to configure various views that touch and alter data. django-admin2 is a complete rewrite of that library using modern Class-Based Views and enjoying a design focused on extendibility and adaptability. By starting over, we can avoid the legacy code and make it easier to write extensions and themes.

Full Documentation at: https://django-admin2.readthedocs.io/

Features

• Rewrite of the Django Admin backend
• Drop-in themes
• Built-in RESTful API

Screenshots

Requirements

• Django 2.2+
• Python 3.5+
• django-braces
• django-extra-views
• django-rest-framework
• django-filter
• Sphinx (for documentation)

Installation

Use pip to install from PyPI:

pip install django-admin2

Add djadmin2 and rest_framework to your settings file:

INSTALLED_APPS = (
    ...
    'djadmin2',
    'rest_framework', # for the browsable API templates
    ...
)

Add setting for apps and the default theme in your settings file:

# In settings.py
INSTALLED_APPS += ('djadmin2.themes.djadmin2theme_bootstrap3',)
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}
ADMIN2_THEME_DIRECTORY = "djadmin2theme_bootstrap3"

Add djadmin2 urls to your URLconf:

# urls.py
from django.conf.urls import include

from djadmin2.site import djadmin2_site

djadmin2_site.autodiscover()

urlpatterns = [
  ...
  url(r'^admin2/', include(djadmin2_site.urls)),
]

How to write django-admin2 modules

# myapp/admin2.py
# Import your custom models
from django.contrib.auth.forms import UserCreationForm, UserChangeForm
from django.contrib.auth.models import User
from djadmin2.site import djadmin2_site
from djadmin2.types import ModelAdmin2

from .models import Post, Comment


class UserAdmin2(ModelAdmin2):
    # Replicates the traditional admin for django.contrib.auth.models.User
    create_form_class = UserCreationForm
    update_form_class = UserChangeForm


#  Register each model with the admin
djadmin2_site.register(Post)
djadmin2_site.register(Comment)
djadmin2_site.register(User, UserAdmin2)

Migrating from 0.6.x

• The default theme has been updated to bootstrap3, be sure to replace your reference to the new one.
• Django rest framework also include multiple pagination system, the only one supported now is the PageNumberPagination.

Therefore, your settings need to include this:

# In settings.py
INSTALLED_APPS += ('djadmin2.themes.djadmin2theme_bootstrap3',)
ADMIN2_THEME_DIRECTORY = "djadmin2theme_bootstrap3"

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

The default admin2 site has move into djadmin2.site make sure your use the news djadmin2_site in your urls.py:

# urls.py
from django.conf.urls import include

from djadmin2.site import djadmin2_site

djadmin2_site.autodiscover()

urlpatterns = [
  ...
  url(r'^admin2/', include(djadmin2_site.urls)),
]

Migrating from 0.5.x

Themes are now defined explicitly, including the default theme. Therefore, your settings need to include this:

# In settings.py
INSTALLED_APPS += ('djadmin2.themes.djadmin2theme_default',)
ADMIN2_THEME_DIRECTORY = "djadmin2theme_default"

Drop-In Themes

The default theme is whatever bootstrap is most current. Specifically:

# In settings.py
INSTALLED_APPS += ('djadmin2.themes.djadmin2theme_bootstrap3',)
ADMIN2_THEME_DIRECTORY = "djadmin2theme_bootstrap3"

If you create a new theme, you define it thus:

# In settings.py
# Mythical theme! This does not exit... YET!
INSTALLED_APPS += ('djadmin2theme_foundation',)
ADMIN2_THEME_DIRECTORY = "djadmin2theme_foundation"

Code of Conduct

Everyone interacting in the django-admin2 project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the Jazzband Code of Conduct.

Follows Best Practices

This project follows best practices as espoused in Two Scoops of Django: Best Practices for Django 1.8.

django-admin2's Issues

Implement action dropdown in ModelListView

Stubbed out the UI quickly to roughly match the existing Django admin:

Generate test coverage reports

Change password page

Copy/edit contributor documentation from OpenComparison

This: https://github.com/opencomparison/opencomparison/blob/master/docs/contributing.rst

Needs to be brought into our documentation directory.

Delete confirmation form UI improvements

Permissions need to be granular

This either needs to be made to function, or documented so it's understandable how to implement the following use cases

Use Case 0: (Django default)

• Admins have full control
• Admins can assigned controls to Staff level users.
• No one else can see anything

Use case 1:

• I am an admin. I have full controls.
• You are an authenticated or unauthenticated user. You are allowed to read data

Use case 2

• I am an admin. I have full controls.
• You are an authenticated user, you are allowed to read data.
• You are an unauthenticated user, you are not allowed to see anything

Get admin2.views.ModelDetailView functioning

Stub out tests!

Get admin2.views.ModelEditFormView functioning

Fix URLs in HTML theme to use proper {% url %} tag

Convert modeladmin to be 'model_admin'

We have a mix of modeladmin and model_admin. We really need to be consistent.

Views method: get_form_class()

• For add/edit model views
• Needs to create a ModelView with the correct models.Model.Meta.model attribute assigned

Support for inlines

Just like the old admin. I've got a branch with this implemented, I just need to get the formset rendering working in a readable fashion. Putting this here so you know it's being worked on

https://github.com/AndrewIngram/django-admin2/tree/inline-formsets

Get admin2.views.ModelDeketeView functioning

Potential state linkage between the view and the ModelAdmin2 object passed in the request

If the view, which is called by the urls generated by the ModelAdmin object and yet receives a reference to the ModelAdmin as passed in as_view() modifies the state of the ModelAdmin object, then everyone sees that new data.

This can be mitigated in three ways:

1. Document the issue and encourage developers not to change state on the ModelAdmin2 object. (Potential for a catastrophic developer-user mistake but is the django.contrib.admin standard)
2. Remove the passing of the ModelAdmin2 object (Will require major refactoring - @freakboy3742's preference).
3. Make a copy of the object that does not allow for state changes (Is a bit tricky but not insurmountable, unfortunately has potential performance problems).

Occurs: models.ModelAdmin2.get_default_view_kwargs

Add django-rest-framework powered API

Build is failing because of 2.6 support

We should drop 2.6 from travis since we don't support it.

Design goals - outline needed.

Right now there is no documentation outlining the design of the project.

Some questions that come to mind:

• How do the admin views interact with the admin instance? Do they have access to an Admin2 instance? Do the views use the Admin2 instance for common tasks like getting a queryset?
• How are related models handled with the desired registration scheme - are they still set up independently and added to the "main" Admin2 instance (inlines = [ ... ])?
• Is the goal to closely follow the "old" admin with respect to configuration (admin.list_display_fields, ...)? Or would it be preferable to reduce the amount of configuration on the Admin2 class and push more of it onto the CBVs?
• Is there a high level menu abstraction (like a get_menu_entries that returns all Entries for an Admin2 instance)?

...

If this kind of document already exists it would be great if it was added to the repo.

Implement Sphinx for docs

• Index needs to include the contributing.rst file.
• See https://github.com/opencomparison/opencomparison for inspiration. DON'T COPY/PASTE!

Make model_list.html look more like admin list view

http://127.0.0.1:8000/admin2/blog/post/ should look more like http://127.0.0.1:8000/admin/blog/post/, except with Bootstrap components

Support for legacy app models (e.g. contrib.auth models)

One way to provide support for commonly used django apps (like contrib.auth) would be to ship a simple package (admin2-legacy or something) that just tries to register those other apps with admin2.

• django.contrib.auth
• django.contrib.sites

Document Model._meta for public use

• Document Model._meta
• Get that documentation at some point in the future into django core documentation

Get admin2.views.ModelListView functioning

Layouts / fieldsets / simple ways to change the field order and layout

We should provide a simple way to rearrange/group fields in the admin without creating custom templates.
The current admin offers this functionality via fieldsets in a rather specific way.

We could look at how crispy form layouts does this stuff where you can go ahead and do stuff like this:

layout = Row(Span("name", "age"), Span("email", "phone"))

This would make it easy to produce nice form layouts without having to drop into the template
for simple modifications.

For more details see http://django-crispy-forms.readthedocs.org/en/d-0/layouts.html

Model add page: Implement save options

On the create model page, implement the 'Save and add another', 'Save and continue editing', and 'Save' options from the original admin.

Make runserver.sh properly executable

runserver.sh needs a shebang line.

Implement RESTFUL API

• Use django-rest-framework 2.3.3
• Create/Read/Update/Delete

Copy/edit contributor documentation from OpenComparison

This: https://github.com/opencomparison/opencomparison/blob/master/docs/contributing.rst

Needs to be brought into our documentation directory.

Add floppy-forms dependency

As per @pydanny's request.

I'll take this since it's related to #72, which I'm working on now.

Admin breadcrumb menu

We should probably implement breadcrumbs exactly as they are in the current admin (but with stock Bootstrap components)

utiils.get_admin2s() fails on imports

This is taken from django.contrib.admin.init.py and https://github.com/pydanny/django-mongonaut/blob/master/mongonaut/mixins.py#L54.

It works in those places but on my test project it fails.

Create example project to visually test against

We need something simple. It should have:

• 2 apps
• Each app needs 2 Models with one of each field type

Setup Continuous Integration

• Travis CI
• Add PyPI badges
• Add Github badge

Put view logic into functions

• Move logic in views into functions as much as possible
• Add exception handling for when a model is not found for a view.

model_edit_form.html should have the same layout as in the old admin

should look more like this:

Get admin2.views.IndexView functioning

Implement default bootstrap theme

• Using Bootstrap as provided by CDN, this must be a workable implementation of the HTML view.
• Minimal JQuery!
• base template
• index template
• form template
• detail template

Provide an easy way to change / extend menus

We need some way to specify which views are available for a certain admin.

It might make sense to have something like a get_menu_entries() method on the
admin instance that returns the urls + verbose names for all available views.
This would be used to build menus, dashboards and these kinds of things.

Also when extending the admin you could just add a new menu entry for additional custom views.

base.html needs a header with username and change password/log out links

Right now there is no header. It needs:

Default theme date/time widgets

Out of the box it would be nice if these were displayed with attractive bootstrap widgets

Implement test runner

Design Decision Needed: have admin2.core.Admin2 subclass contrib.admin.sites.AdminSite

I've not been at the sprints, so this may well have been discussed already.

Wanting to contribute, I started looking at implementing the admin auth urls (login, logout, password change, etc.). As I worked, it became clear that I was duplicating a lot of functionality from the original AdminSite class from contrib.admin. The only added 'feature' was incorporating ADMIN2_THEME_DIRECTORY into the template path.

It seems to me that if Admin2 subclassed AdminSite, we'd get a good bit of functionality for free. AdminSite implements all of the auth urls, Admin2 would only have to override get_urls, and change all of the template names as class attributes.

At first glance, it seems as if we might also be able to re-use at least some of the permissions code from AdminSite as well.

I've written a quick spike which takes the approach outlined above. All tests pass, after only having to change the test that counts the number of admin urls.

Note I had to refactor the settings file into separate files, since having django-debug-toolbar in INSTALLED_APPS was breaking the admin login test (specifically, the redirect intercepts). Ideally, settings would be a package, but I didn't want to break existing environments that might rely on DJANGO_SETTINGS_MODULE=example.settings.

Stub out UI for admin index page

The old admin looks like this:

We should flesh this out to function similarly:

See what ideas you can steal from django-dashbuilder

I started working on https://github.com/AndrewIngram/django-dashbuilder a while back. I didn't get that much done, but the basics of model editing is in place. The key thing that's missing is permissions. There might be some ideas or solutions you can steal.

I18n in templates

We should use i18n in all templates so we can translate it later on.

Theme guide

model_list.html UI cleanup

should function more like...

(This issue doesn't include the header -- that's a separate ticket)

Permissions functions in `models.py` need work

In models.py we define several methods for determining whether a user has permission on a view (eg has_view_permission). These methods don't offer very fine-grained control. Should we use the the has_perm method from contrib.auth as is done in the original admin in options.py?

Login and Logout page

Fix readthedocs.org post-commit hook

My docs update didn't show up on http://django-admin2.readthedocs.org/en/latest/ - please update.