Welcome to django-admin-tools’s documentation!¶

Installing django-admin-tools¶

django-admin-tools requires Django version 1.3 or superior, optionally, if you want to display feed modules, you’ll also need the Universal Feed Parser module.

There are several ways to install django-admin-tools, this is explained in the installation section.

For the impatient, the easiest method is to install django-admin-tools via easy_install or pip.

Using easy_install, type:

easy_install -Z django-admin-tools

Note that the -Z flag is required, to tell easy_install not to create a zipped package; zipped packages prevent certain features of Django from working properly.

Using pip, type:

pip install django-admin-tools

Basic configuration¶

For a more detailed guide on how to configure django-admin-tools, please consult the configuration section.

INSTALLED_APPS = (
    'admin_tools',
    'admin_tools.theming',
    'admin_tools.menu',
    'admin_tools.dashboard',
    'django.contrib.auth',
    'django.contrib.sites',
    'django.contrib.admin'
    # ...other installed applications...
)

urlpatterns = patterns('',
    url(r'^admin_tools/', include('admin_tools.urls')),
    #...other url patterns...
)

python manage.py migrate

Testing your new shiny admin interface¶

Congrats! At this point you should have a working installation of django-admin-tools. Now you can just login to your admin site and see what changed.

django-admin-tools is fully customizable, but this is out of the scope of this quickstart. To learn how to customize django-admin-tools modules please read the customization section.

Requirements¶

Before installing django-admin-tools, you’ll need to have a copy of Django already installed. For the 0.6 release, Django 1.7 or newer is required.

For further information, consult the Django download page, which offers convenient packaged downloads and installation instructions.

Installing django-admin-tools¶

There are several ways to install django-admin-tools:

• Automatically, via a package manager.
• Manually, by downloading a copy of the release package and installing it yourself.
• Manually, by performing a Mercurial checkout of the latest code.

It is also highly recommended that you learn to use virtualenv for development and deployment of Python software; virtualenv provides isolated Python environments into which collections of software (e.g., a copy of Django, and the necessary settings and applications for deploying a site) can be installed, without conflicting with other installed software. This makes installation, testing, management and deployment far simpler than traditional site-wide installation of Python packages.

easy_install -Z django-admin-tools

pip install django-admin-tools

python setup.py install

git clone https://github.com/django-admin-tools/django-admin-tools.git

Basic configuration¶

Once installed, you can add django-admin-tools to any Django-based project you’re developing.

django-admin-tools is composed of several modules:

• admin_tools.theming: an app that makes it easy to customize the look and feel of the admin interface;
• admin_tools.menu: a customizable navigation menu that sits on top of every django administration index page;
• admin_tools.dashboard: a customizable dashboard that replaces the django administration index page.

INSTALLED_APPS = (
    'admin_tools.theming',
    'admin_tools.menu',
    'admin_tools.dashboard',
    'django.contrib.auth',
    'django.contrib.sites',
    'django.contrib.admin'
    # ...other installed applications...
)

INSTALLED_APPS = (
    'admin_tools.dashboard',
    'django.contrib.auth',
    'django.contrib.sites',
    'django.contrib.admin'
    # ...other installed applications...
)

python manage.py migrate

urlpatterns = patterns('',
    url(r'^admin_tools/', include('admin_tools.urls')),
    #...other url patterns...
)

Available settings variables¶

ADMIN_TOOLS_MENU

The path to your custom menu class, for example “yourproject.menu.CustomMenu”.

ADMIN_TOOLS_INDEX_DASHBOARD

The path to your custom index dashboard, for example “yourproject.dashboard.CustomIndexDashboard”.

ADMIN_TOOLS_APP_INDEX_DASHBOARD

The path to your custom app index dashboard, for example “yourproject.dashboard.CustomAppIndexDashboard”.

ADMIN_TOOLS_THEMING_CSS

The path to your theming css stylesheet, relative to your MEDIA_URL, for example:

ADMIN_TOOLS_THEMING_CSS = 'css/theming.css'

Introduction¶

django-admin-tools is very easy to customize, you can override the admin menu, the index dashboard and the app index dashboard.

For this django-admin-tools provides two management commands:

• custommenu
• customdashboard

Customizing the navigation menu¶

To customize the admin menu, the first step is to do the following:

python manage.py custommenu

This will create a file named menu.py in your project directory. If for some reason you want another file name, you can do:

python manage.py custommenu somefile.py

The created file contains a class that is a copy of the default menu, it is named CustomMenu, you can rename it if you want but if you do so, make sure you put the correct class name in your ADMIN_TOOLS_MENU settings variable.

Now you need to tell django-admin-tools to use your custom menu instead of the default one, open your settings.py file and add the following:

ADMIN_TOOLS_MENU = 'yourproject.menu.CustomMenu'

Obviously, you need to change “yourproject” to the real project name, if you have chosen a different file name or if you renamed the menu class, you’ll also need to change the above string to reflect your modifications.

At this point the menu displayed in the admin is your custom menu, now you can read the menu and menu items API documentation to learn how to create your custom menu.

Customizing the dashboards¶

To customize the index and app index dashboards, the first step is to do the following:

python manage.py customdashboard

This will create a file named dashboard.py in your project directory. If for some reason you want another file name, you can do:

python manage.py customdashboard somefile.py

The created file contains two classes:

• The CustomIndexDashboard class that corresponds to the admin index page dashboard;
• The CustomAppIndexDashboard class that corresponds to the index page of each installed application.

You can rename theses classes if you want but if you do so, make sure adjust the ADMIN_TOOLS_INDEX_DASHBOARD and ADMIN_TOOLS_APP_INDEX_DASHBOARD settings variables to match your class names.

Now you need to tell django-admin-tools to use your custom dashboard(s). Open your settings.py file and add the following:

ADMIN_TOOLS_INDEX_DASHBOARD = 'yourproject.dashboard.CustomIndexDashboard'
ADMIN_TOOLS_APP_INDEX_DASHBOARD = 'yourproject.dashboard.CustomAppIndexDashboard'

If you only want a custom index dashboard, you would just need the first line. Obviously, you need to change “yourproject” to the real project name, if you have chosen a different file name or if you renamed the dashboard classes, you’ll also need to change the above string to reflect your modifications.

At this point the dashboards displayed in the index and the app index should be your custom dashboards, now you can read the dashboard and dashboard modules API documentation to learn how to create your custom dashboard.

Customizing the theme¶

This is very simple, just configure the ADMIN_TOOLS_THEMING_CSS to point to your custom css file, for example:

ADMIN_TOOLS_THEMING_CSS = 'css/theming.css'

A good start is to copy the admin_tools/media/admin_tools/css/theming.css to your custom file and to modify it to suits your needs.

Introduction¶

Django supports custom admin sites, and of course you can have as many admin sites as you want, django-admin-tools provides basic support for this, you can setup a custom dashboard or menu for each admin site.

Setting up a different dashboard and menu for each admin site instance¶

In the following example we will assume that you have two admin site instances: the default django admin site and a custom admin site of your own. In your urls, you should have something like this:

from django.conf.urls.defaults import *
from django.contrib import admin
from yourproject.admin import admin_site

admin.autodiscover()

urlpatterns = patterns('',
    (r'^admin/', include(admin.site.urls)),
    (r'^myadmin/', include(admin_site.urls)),
)

Now to configure your dashboards, you could do:

python manage.py customdashboard django_admin_dashboard.py
python manage.py customdashboard my_admin_dashboard.py

And to tell django-admin-tools to use your custom dashboards depending on the admin site being used, you just have to add the following to your project settings file:

ADMIN_TOOLS_INDEX_DASHBOARD = {
    'django.contrib.admin.site': 'yourproject.django_admin_dashboard.CustomIndexDashboard',
    'yourproject.admin.admin_site': 'yourproject.my_admin_dashboard.CustomIndexDashboard',
}

Note that the same applies for the ADMIN_TOOLS_APP_INDEX_DASHBOARD settings variable.

Finally do the same thing for menu:

python manage.py custommenu django_admin_menu.py
python manage.py custommenu my_admin_menu.py

And to tell django-admin-tools to use your custom menu depending on the admin site being used:

ADMIN_TOOLS_MENU = {
    'django.contrib.admin.site': 'yourproject.django_admin_menu.CustomMenu',
    'yourproject.admin.admin_site': 'yourproject.my_admin_menu.CustomMenu',
}

The Menu class¶

The MenuItem class¶

The AppList class¶

The ModelList class¶

The Bookmarks class¶

The Dashboard class¶

The AppIndexDashboard class¶

The DashboardModule class¶

The Group class¶

The LinkList class¶

The AppList class¶

The ModelList class¶

The RecentActions class¶

The Feed class¶

Running tests¶

First, cd the test_proj directory:

$ cd test_proj

And to run the tests, just type:

$ python manage.py test

Code coverage report¶

Install the coverage.py library and the django-coverage app:

$ pip install coverage django-coverage

Then run tests and open test_proj/_coverage/index.html file in browser.

Where tests live¶

Unit tests should be put into appropriate module’s tests.py. Functional/integration tests should be put somewhere into test_proj.