Permalink
Find file Copy path
7e5e907 Sep 5, 2017
2 contributors

Users who have contributed to this file

@sehmaschine @MJafarMashhadi
349 lines (260 sloc) 10.2 KB

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):
        Dashboard.__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
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.
target
A string or boolean value describing what is the link target. To open link in a new window/tab you can pass True or '_blank' value to this parameter. When you pass an string value, it is directly used in the target attribute of the generated a tag in the template.

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

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!',
                    'target': '_blank',
                },
                ['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 :class:`~grappelli.dashboard.modules.DashboardModule` properties, the :class:`~grappelli.dashboard.modules.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 :class:`~grappelli.dashboard.modules.DashboardModule` properties, the :class:`~grappelli.dashboard.modules.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 :class:`~grappelli.dashboard.modules.DashboardModule` properties, the :class:`~grappelli.dashboard.modules.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 :class:`~grappelli.dashboard.modules.DashboardModule` properties, the :class:`~grappelli.dashboard.modules.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,
        ))