Dashboard API — Django Grappelli 2.7.2 documentation

# Dashboard API

This section describe the API of the Grappelli dashboard and dashboard modules.

## The Dashboard class

Base class for dashboards. The dashboard class is a simple python list that has two additional properties:

`title`
  The dashboard title, by default, it is displayed above the dashboard in a `h2` tag. Default: `Dashboard`
`template`
  The template used to render the dashboard. Default: `grappelli/dashboard/dashboard.html`

Here’s an example of a custom dashboard:

    from django.core.urlresolvers import reverse
    from django.utils.translation import ugettext_lazy as _
    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):

            # append an app list module for "Applications"
            self.children.append(modules.AppList(
                title=_('Applications'),
                column=1,
                collapsible=True,
                exclude=('django.contrib.*',),
            ))

            # append an app list module for "Administration"
            self.children.append(modules.AppList(
                title=_('Administration'),
                column=1,
                collapsible=True,
                models=('django.contrib.*',),
            ))

            # append a recent actions module
            self.children.append(modules.RecentActions(
                title=_('Recent Actions'),
                column=2,
                collapsible=False,
                limit=5,
            ))

## The DashboardModule class

Base class for all dashboard modules. Dashboard modules have the following properties:

`collapsible`
  Boolean that determines whether the module is collapsible. Default: `True`
`column` (required)
  Integer that corresponds to the column. Default: `None`
`title`
  String that contains the module title, make sure you use the django gettext functions if your application is multilingual. Set to `''` if you need to suppress the title.
`css_classes`
  A list of css classes to be added to the module `div` class attribute. Default: `None`
`pre_content`
  Text or HTML content to display above the module content. Default: `None`
`content`
  The module text or HTML content. Default: `None`
`post_content`
  Text or HTML content to display under the module content. Default: `None`
`template`
  The template used to render the module. Default: `grappelli/dashboard/module.html`

## The Group class

Represents a group of modules:

    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):
            Dashboard.__init__(self, **kwargs)
            self.children.append(modules.Group(
                title="My group",
                column=1,
                collapsible=True,
                children=[
                    modules.AppList(
                        title='Administration',
                        models=('django.contrib.*',)
                    ),
                    modules.AppList(
                        title='Applications',
                        exclude=('django.contrib.*',)
                    )
                ]
            ))

## The LinkList class

A module that displays a list of links.

Link list modules children are simple python dictionaries that can have the following keys:

`title`
  The link title.
`url`
  The link URL.
`external`
  Boolean that indicates whether the link is an external one or not.
`description`
  A string describing the link, it will be the `title` attribute of the html `a` tag.

Children can also be iterables (lists or tuples) of length 2, 3 or 4.

Here’s an example of building a link list module:

    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):
            Dashboard.__init__(self, **kwargs)

            self.children.append(modules.LinkList(
                title='Links',
                column=2,
                children=(
                    {
                        'title': 'Python website',
                        'url': 'http://www.python.org',
                        'external': True,
                        'description': 'Python programming language rocks!',
                    },
                    ['Django website', 'http://www.djangoproject.com', True],
                    ['Some internal link', '/some/internal/link/'],
                )
            ))

## The AppList class

Module that lists installed apps and their models. As well as the `DashboardModule` properties, the `AppList` has two extra properties:

`models`
  A list of models to include, only models whose name (e.g. “blog.models.BlogEntry”) match one of the strings (e.g. “blog.*”) in the models list will appear in the dashboard module.
`exclude`
  A list of models to exclude, if a model name (e.g. “blog.models.BlogEntry”) match an element of this list (e.g. “blog.*”) it won’t appear in the dashboard module.

If no models/exclude list is provided, all apps are shown.

Here’s an example of building an app list module:

    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):
            Dashboard.__init__(self, **kwargs)

            # will only list the django.contrib apps
            self.children.append(modules.AppList(
                title='Administration',
                column=1,
                models=('django.contrib.*',)
            ))
            # will list all apps except the django.contrib ones
            self.children.append(modules.AppList(
                title='Applications',
                column=1,
                exclude=('django.contrib.*',)
            ))

Note

This module takes into account user permissions. For example, if a user has no rights to change or add a `Group`, then the django.contrib.auth.Group model won’t be displayed.

## The ModelList class

Module that lists a set of models. As well as the `DashboardModule` properties, the `ModelList` takes two extra arguments:

`models`
  A list of models to include, only models whose name (e.g. “blog.models.BlogEntry”) match one of the strings (e.g. “blog.*”) in the models list will appear in the dashboard module.
`exclude`
  A list of models to exclude, if a model name (e.g. “blog.models.BlogEntry”) match an element of this list (e.g. “blog.*”) it won’t appear in the dashboard module.

Here’s a small example of building a model list module:

    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):
            Dashboard.__init__(self, **kwargs)

            self.children.append(modules.ModelList(
                title='Several Models',
                column=1,
                models=('django.contrib.*',)
            ))

            self.children.append(modules.ModelList(
                title='Single Model',
                column=1,
                models=('blog.models.BlogEntry',)
            ))

Note

This module takes into account user permissions. For example, if a user has no rights to change or add a `Group`, then the django.contrib.auth.Group model won’t be displayed.

## The RecentActions class

Module that lists the recent actions for the current user. As well as the `DashboardModule` properties, the `RecentActions` takes three extra keyword arguments:

`include_list`
  A list of contenttypes (e.g. “auth.group” or “sites.site”) to include, only recent actions that match the given contenttypes will be displayed.
`exclude_list`
  A list of contenttypes (e.g. “auth.group” or “sites.site”) to exclude, recent actions that match the given contenttypes will not be displayed.
`limit`
  The maximum number of children to display. Default: `10`

Here’s an example of building a recent actions module:

    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):
            Dashboard.__init__(self, **kwargs)

            self.children.append(modules.RecentActions(
                title='Django CMS recent actions',
                column=3,
                limit=5,
            ))

## The Feed class

Class that represents a feed dashboard module.

Note

This class requires the Universal Feed Parser module, so you’ll need to install it.

As well as the `DashboardModule` properties, the `Feed` takes two extra keyword arguments:

`feed_url`
  The URL of the feed.
`limit`
  The maximum number of feed children to display. Default: `None` (which means that all children are displayed)

Here’s an example of building a recent actions module:

    from grappelli.dashboard import modules, Dashboard

    class MyDashboard(Dashboard):
        def __init__(self, **kwargs):
            Dashboard.__init__(self, **kwargs)

            self.children.append(modules.Feed(
                title=_('Latest Django News'),
                feed_url='http://www.djangoproject.com/rss/weblog/',
                column=3,
                limit=5,
            ))