django-admin2 0.7.1
An introspective interface for Django's ORM.
License: MIT
Keywords: django,admin

=============
django-admin2
=============

.. image:: https://jazzband.co/static/img/badge.svg
   :target: https://jazzband.co/
   :alt: Jazzband
.. image:: https://travis-ci.org/jazzband/django-admin2.png
   :alt: Build Status
   :target: https://travis-ci.org/jazzband/django-admin2
.. image:: https://coveralls.io/repos/github/jazzband/django-admin2/badge.svg?branch=develop
   :alt: Coverage Status
   :target: https://coveralls.io/github/jazzband/django-admin2?branch=develop
.. image:: https://badges.gitter.im/Join Chat.svg
   :target: https://gitter.im/pydanny/django-admin2?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

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

Requirements
============

* Django 1.7+
* Python 2.7+ or Python 3.3+
* django-braces_
* django-extra-views_
* django-rest-framework_
* django-filter_
* Sphinx_ (for documentation)

.. _django-braces: https://github.com/brack3t/django-braces
.. _django-extra-views: https://github.com/AndrewIngram/django-extra-views
.. _django-rest-framework: https://github.com/tomchristie/django-rest-framework
.. _django-filter: https://github.com/alex/django-filter
.. _Sphinx: http://sphinx-doc.org/



Installation
============

Use pip to install from PyPI:

.. code-block:: python

   pip install django-admin2

Add djadmin2 and rest_framework to your settings file:

.. code-block:: python

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

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

.. code-block:: python

    # 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:

.. code-block:: python

    # 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
==================================

.. code-block:: python

  # 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:

.. code-block:: python

    # 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:

.. code-block:: python

    # 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:

.. code-block:: python

    # 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:

.. code-block:: python

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

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

.. code-block:: python

    # 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`_.

.. _`Jazzband Code of Conduct`: https://jazzband.co/about/conduct

Follows Best Practices
======================

.. image:: http://twoscoops.smugmug.com/Two-Scoops-Press-Media-Kit/i-C8s5jkn/0/O/favicon-152.png
   :name: Two Scoops Logo
   :align: center
   :alt: Two Scoops of Django
   :target: http://twoscoopspress.org/products/two-scoops-of-django-1-8

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

.. _`Two Scoops of Django: Best Practices for Django 1.8`: http://twoscoopspress.org/products/two-scoops-of-django-1-8


History
=========

0.7.0 (2016-11-16)

* Fix Django 1.8 issues and add 1.9, 1.10 compatibility
* Update django-rest-framework to 3.3.x
* Remove django-crispy-forms and django-floppyforms
* Regenerate example project to make it django 1.9 compatible
* Update tox and travis and add flake8
* Rename AdminModel2Mixin to Admin2ModelMixin
* Add migrations 
* remove south migrations
* Replace IPAddressField with GenericIPAddressField
* Fix password link in user admin
* Fix user logout on password change
* Fix tests
* Drop support of django versions lower then 1.8
* Drop older url.patterns



0.6.1 (2014-02-26)

 * Fix empty form display
 * Added more explicit installation instructions
 * Added migration instructions
 * Added view descriptions for "registry" and "app_verbose_names"
 * Show a nice message and margin if there are no visible fields
 * Updated widget controls for Django 1.6 changes.
 * Better error messages for admin views that fail to instantiate
 * Added png glyphicons to MANIFEST

0.6.0 (2013-09-12)

 * Implemented LogHistory to track recent history
 * New system for adding new views to ModelAdmin2 object
 * Fixed missing enctype="multipart/form-data" functionality
 * Implemented "app verbose name"
 * Apps can have customized names
 * List Actions can be set so they don't require selecting a model
 * Implemented ModelAdmin2.ordering
 * To maintain API consistency, renamed views.AdminView's "url" argument to "regex" 
 * Implemented ModelAdmin2.date_hierarchy
 * Changed theming system to make default theme follow the same rules as third-party themes.
 * Inlines now separated into stacked and tabular formats
 * Code coverage now displaying in README
 * User list page now showing all default columns and filters
 * Vast documentation improvements
 * Converted to ``django.utils.encoding.force_str`` instead ``unicode`` in order to type edge cases
 * setup.py fix

0.5.1 (2013-07-14)

 * No longer pinning dependencies on specific versions
 * `Documentation on built-in views`_ shows context variables.
 * Added django-filter to dependency list
 * Problem with related_name resolved
 * Fixed the height of the change_form
 * Example app actually shows added content
 * Pull requests going forward are internationalized_
 * FAQ_ begun

.. _`internationalized`: https://django-admin2.readthedocs.io/en/latest/contributing.html#internationalize
.. _`Documentation on built-in views`: https://django-admin2.readthedocs.io/en/latest/ref/built-in-views.html
.. _faq: https://django-admin2.readthedocs.io/en/latest/faq.html

0.5.0 (2013-07-08)

  * Implemented customizable value renderers
  * Implemented list filters using django-filters. Greatly supersedes what Django provides.
  * Implemented ModelAdmin2.save_on_top and ModelAdmin2.save_on_bottom
  * Implemented BooleanField icons for List and Detail views
  * Implemented default ``django.contrib.auth`` and ``django.contrib.sites`` registrations
  * Implemented the displayed of verbose field/method names in list view
  * Implemented client-side ordering of model list fields in default theme
  * Implemented improved internal naming conventions
  * Improved example project home page
  * Improved internal test coverage
  * Documentation for Context Variables in Themes
  * Corrected early nomenclature decisions
  * Much improved Internationalization
  * Added django-admin2 to Transifex
  * Translations for French, Polish, Slovak, Chinese, German, Catalan, Italian, and Spanish.

0.4.0 (2013-06-30)

  * Implemented both Function- and Class-based Action views
  * Implemented ModelAdmin2.list_display
  * Implemented ModelAdmin2.fieldsets
  * Dropdown widget now displays the selected choice
  * Added support for callables in ModelAdmin2.list_display
  * Added screenshots to README
  * Added second example project
  * Fixed breadcrumbs
  * Default theme: Proper closing of template and media blocks
  * Default theme: Standardized indentation in default theme templates
  * Default theme: Pointed to CDN for JQuery
  * Default theme: Added basic style for login form
  * Default theme: Internationalized all text strings


0.3.0 (2013-05-31)

  * HTML5 forms via floppyforms.
  * Many API improvements.
  * Added Breadcrumbs.
  * Added Login, Logout, ChangePassword views.
  * Added Actions.
  * Added support for inlines.
  * Added view based permission controls
  * Implement delete confirmations for child models.
  * Testrunner now can run on a specific test set or module.
  * Internal code refactoring to follow standards.
  * Moved to git-flow for accepting pull requests.
  * Model create/update pages now have save options.
  * Added i18n to all templates, much of internal code.
  * All print statements replaced with proper logging.
  * Design goals specified in the documentation.

0.2.0 (2013-05-19)

  * Birth! (Working Prototype)
  * Easy-to-extend API that follows similar patterns to django.contrib.admin.
  * Built-in RESTFUL API powered by django-rest-framework.
  * Default theme built on Twitter Bootstrap.
  * Easy to implement theme system.
  * Basic permission controls.
  * Testrunner
  * Documentation

0.1.1 (2013-05-17)

  * Code adoption from django-mongonaut.
  * Preperation for Django Circus sprints.

0.1 (2013-05-13)

  * Discussion with Russell Keith-Magee.
  * Inception.