The django-admin-tools menu and menu items API¶
This section describe the API of the django-admin-tools menu and menu items. Make sure you read this before creating your custom menu.
The Menu
class¶
-
class
admin_tools.menu.
Menu
(**kwargs)¶ This is the base class for creating custom navigation menus. A menu can have the following properties:
template
- A string representing the path to template to use to render the menu.
As for any other template, the path must be relative to one of the
directories of your
TEMPLATE_DIRS
setting. Default value: “admin_tools/menu/menu.html”. children
- A list of children menu items. All children items mus be instances of
the
MenuItem
class.
If you want to customize the look of your menu and it’s menu items, you can declare css stylesheets and/or javascript files to include when rendering the menu, for example:
from admin_tools.menu import Menu class MyMenu(Menu): class Media: css = {'all': ('css/mymenu.css',)} js = ('js/mymenu.js',)
Here’s a concrete example of a custom menu:
from django.core.urlresolvers import reverse from admin_tools.menu import items, Menu class MyMenu(Menu): def __init__(self, **kwargs): super(MyMenu, self).__init__(**kwargs) self.children += [ items.MenuItem('Home', reverse('admin:index')), items.AppList('Applications'), items.MenuItem('Multi level menu item', children=[ items.MenuItem('Child 1', '/foo/'), items.MenuItem('Child 2', '/bar/'), ] ), ]
Below is a screenshot of the resulting menu:
-
init_with_context
(context)¶ Sometimes you may need to access context or request variables to build your menu, this is what the
init_with_context()
method is for. This method is called just before the display with adjango.template.RequestContext
as unique argument, so you can access to all context variables and to thedjango.http.HttpRequest
.
The MenuItem
class¶
-
class
admin_tools.menu.items.
MenuItem
(title=None, url=None, **kwargs)¶ This is the base class for custom menu items. A menu item can have the following properties:
title
- String that contains the menu item title, make sure you use the django gettext functions if your application is multilingual. Default value: ‘Untitled menu item’.
url
- String that contains the menu item URL. Default value: ‘#’.
css_classes
- A list of css classes to be added to the menu item
li
class attribute. Default value: []. accesskey
- The menu item accesskey. Default value: None.
description
- An optional string that will be used as the
title
attribute of the menu-itema
tag. Default value: None. enabled
- Boolean that determines whether the menu item is enabled or not. Disabled items are displayed but are not clickable. Default value: True.
template
- The template to use to render the menu item. Default value: ‘admin_tools/menu/item.html’.
children
- A list of children menu items. All children items must be instances of
the
MenuItem
class.
-
init_with_context
(context)¶ Like for menus, menu items have a
init_with_context
method that is called with adjango.template.RequestContext
instance as unique argument. This gives you enough flexibility to build complex items, for example, let’s build a “history” menu item, that will list the last ten visited pages:from admin_tools.menu.items import MenuItem class HistoryMenuItem(MenuItem): title = 'History' def init_with_context(self, context): request = context['request'] # we use sessions to store the visited pages stack history = request.session.get('history', []) for item in history: self.children.append(MenuItem( title=item['title'], url=item['url'] )) # add the current page to the history history.insert(0, { 'title': context['title'], 'url': request.META['PATH_INFO'] }) if len(history) > 10: history = history[:10] request.session['history'] = history
Here’s a screenshot of our history item:
-
is_empty
()¶ Helper method that returns
True
if the menu item is empty. This method always returnsFalse
for basic items, but can returnTrue
if the item is an AppList.
-
is_selected
(request)¶ Helper method that returns
True
if the menu item is active. A menu item is considered as active if it’s URL or one of its descendants URL is equals to the current URL.
The AppList
class¶
-
class
admin_tools.menu.items.
AppList
(title=None, **kwargs)¶ A menu item that lists installed apps an their models. In addition to the parent
MenuItem
properties, theAppList
has two extra properties:models
- A list of models to include, only models whose name (e.g. “blog.comments.Comment”) match one of the strings (e.g. “blog.*”) in the models list will appear in the menu item.
exclude
- A list of models to exclude, if a model name (e.g. “blog.comments.Comment”) match an element of this list (e.g. “blog.comments.*”) it won’t appear in the menu item.
If no models/exclude list is provided, all apps are shown.
Here’s a small example of building an app list menu item:
from admin_tools.menu import items, Menu class MyMenu(Menu): def __init__(self, **kwargs): super(MyMenu, self).__init__(**kwargs) self.children.append(items.AppList( title='Applications', exclude_list=('django.contrib',) )
The screenshot of what this code produces:
Note
Note that this menu takes into account user permissions, as a consequence, if a user has no rights to change or add a
Group
for example, thedjango.contrib.auth.Group model
child item won’t be displayed in the menu.-
init_with_context
(context)¶ Please refer to
init_with_context()
documentation fromMenuItem
class.
-
is_empty
()¶ Helper method that returns
True
if the applist menu item has no children.>>> from admin_tools.menu.items import MenuItem, AppList >>> item = AppList(title='My menu item') >>> item.is_empty() True >>> item.children.append(MenuItem(title='foo')) >>> item.is_empty() False >>> item.children = [] >>> item.is_empty() True
The ModelList
class¶
-
class
admin_tools.menu.items.
ModelList
(title=None, models=None, exclude=None, **kwargs)¶ A menu item that lists a set of models. In addition to the parent
MenuItem
properties, theModelList
has two extra properties:models
- A list of models to include, only models whose name (e.g. “blog.comments.Comment”) match one of the strings (e.g. “blog.*”) in the include list will appear in the dashboard module.
exclude
- A list of models to exclude, if a model name (e.g. “blog.comments.Comment” match an element of this list (e.g. “blog.comments.*”) it won’t appear in the dashboard module.
Here’s a small example of building a model list menu item:
from admin_tools.menu import items, Menu class MyMenu(Menu): def __init__(self, **kwargs): super(MyMenu, self).__init__(**kwargs) self.children += [ items.ModelList( 'Authentication', ['django.contrib.auth.*',] ) ]
Note
Note that this menu takes into account user permissions, as a consequence, if a user has no rights to change or add a
Group
for example, thedjango.contrib.auth.Group model
item won’t be displayed in the menu.-
init_with_context
(context)¶ Please refer to
init_with_context()
documentation fromMenuItem
class.
-
is_empty
()¶ Helper method that returns
True
if the modellist menu item has no children.>>> from admin_tools.menu.items import MenuItem, ModelList >>> item = ModelList(title='My menu item') >>> item.is_empty() True >>> item.children.append(MenuItem(title='foo')) >>> item.is_empty() False >>> item.children = [] >>> item.is_empty() True
The Bookmarks
class¶
-
class
admin_tools.menu.items.
Bookmarks
(title=None, **kwargs)¶ A menu item that lists pages bookmarked by the user. This menu item also adds an extra button to the menu that allows the user to bookmark or un-bookmark the current page.
Here’s a small example of adding a bookmark menu item:
from admin_tools.menu import items, Menu class MyMenu(Menu): def __init__(self, **kwargs): super(MyMenu, self).__init__(**kwargs) self.children.append(items.Bookmarks('My bookmarks'))
-
init_with_context
(context)¶ Please refer to
init_with_context()
documentation fromMenuItem
class.
-
is_selected
(request)¶ A bookmark menu item is never considered as active, the real item is.
-