Cradmin menu system

Using crmenu with BaseCrAdminInstance

Simple example

Lets create a menu with two links, one to the “dashboard” app, and one to the “pages” app (both apps are within the cradmin instance):

class CrInstance(crinstance.BaseCrAdminInstance):
    # ... other required BaseCrAdminInstance attributes and methods ...

     apps = [
        ('dashboard', dashboard.App),
        ('dashboard', pages.App),
     ]

    def get_menu_item_renderables(self):
        return [
            crmenu.LinkItemRenderable(
                label=ugettext_lazy('Dashboard'),
                url=self.appindex_url('dashboard'),
                is_active=self.request.cradmin_app.appname == 'dashboard'),
            crmenu.LinkItemRenderable(
                label=ugettext_lazy('Pages'),
                url=self.appindex_url('pages'),
                is_active=self.request.cradmin_app.appname == 'pages'),
        ]

How it all fits together

The menu is split into a main menu and an expandable menu. Both the main and expandable menu are subclasses of django_cradmin.crmenu.AbstractMenuRenderable.

By default the main menu and the expandable menu get their menu items from django_cradmin.crinstance.BaseCrAdminInstance.get_menu_item_renderables(), but you can make them have different items by overriding:

  • get_main_menu_item_renderables()
  • get_expandable_menu_item_renderables()

If you want to change how the menu is rendered, you can change the menu renderer classes by overring the following attributes:

If changing the renderer classes is not enough, you can override the methods that creates renderable objects:

The last option gives you full control, and only require you to return an django_cradmin.renderable.AbstractRenderable object.

Implementation details

A menu is just a django_cradmin.renderable.AbstractRenderable, and with some overrides of methods in django_cradmin.crinstance.BaseCrAdminInstance, you can even use any direct subclass of AbstractRenderable. For most cases you will want to use a subclass of django_cradmin.crmenu.AbstractMenuRenderable for your menu.

Since we just use the AbstractRenderable framework, it is really easy to use a plain Django template for your menu. This is nice when working with complex menus.

API

class NavLinkItemRenderable(label, url, is_active=False, bem_variant_list=None, parent_bem_block=None)

Bases: django_cradmin.crmenu.BaseMenuLinkRenderable

Use this to add links to the main menu.

Parameters:
  • label – A label shown in the menu.
  • url – The url to go to whem the user clicks the menu item.
  • is_active – Should be True if the menuitem should be styled as active.
class NavLinkButtonItemRenderable(label, url, is_active=False, bem_variant_list=None, parent_bem_block=None)

Bases: django_cradmin.crmenu.NavLinkItemRenderable

Use this to add links styled as a button to the main menu.

Parameters:
  • label – A label shown in the menu.
  • url – The url to go to whem the user clicks the menu item.
  • is_active – Should be True if the menuitem should be styled as active.
class ExpandableMenuItem(label, url, is_active=False, bem_variant_list=None, parent_bem_block=None)

Bases: django_cradmin.crmenu.BaseMenuLinkRenderable

Use this to add links to the main menu.

Parameters:
  • label – A label shown in the menu.
  • url – The url to go to whem the user clicks the menu item.
  • is_active – Should be True if the menuitem should be styled as active.
class MenuToggleItemItemRenderable(parent_bem_block=None, **kwargs)

Bases: django_cradmin.renderable.AbstractBemRenderable

Use this to add an expandable menu toggle to the menu.

class AbstractMenuRenderable(request, cradmin_instance=None)

Bases: django_cradmin.renderable.AbstractRenderableWithCss

Base class for rendering a menu.

To get a completely custom HTML menu, you simply set your own template (see django_cradmin.renderable.AbstractRenderable.get_template_name()) and write your own HTML.

The link renderable class used by make_link_renderable().

button_renderable_class = None

The button renderable class used by make_button_renderable().

iter_renderables()

Get an iterator over the items in the list.

Get the link renderable class.

The default implementation returns link_renderable_class, and raises ValueError if it is None.

You can override this method, or override link_renderable_class to change the link renderable class.

get_button_renderable_class()

Get the button renderable class.

The default implementation returns button_renderable_class, and raises ValueError if it is None.

You can override this method, or override button_renderable_class to change the button renderable class.

make_child_renderable_kwargs(**kwargs)

Takes the user provided kwargs for make_link_renderable() or make_button_renderable() and returns the final kwargs that should be used as argument for the constructor of the renderable class.

By default, this adds the parent_bem_block kwarg with the value returned by get_child_renderable_parent_bem_block().

Make a link renderable.

Uses the renderable returned by get_link_renderable_class(), and forwards **kwargs to the constructor of that class.

Kwargs is filtered through make_child_renderable_kwargs(), so you can override that method to add default kwargs.

Returns:A link renderable object.
make_button_renderable(**kwargs)

Make a button renderable.

Uses the renderable returned by get_button_renderable_class(), and forwards **kwargs to the constructor of that class.

Kwargs is filtered through make_child_renderable_kwargs(), so you can override that method to add default kwargs.

Returns:A button renderable object.

Uses make_link_renderable() to create a renderable, and appends the created link to the menu.

append_button(**kwargs)

Uses make_button_renderable() to create a renderable, and appends the created button to the menu.

Uses make_link_renderable() to create a renderable, and prepends the created link to the menu.

prepend_button(**kwargs)

Uses make_button_renderable() to create a renderable, and prepends the created button to the menu.

Uses make_link_renderable() to create a renderable, and inserts the created link in the menu.

insert_button(index, **kwargs)

Uses make_button_renderable() to create a renderable, and inserts the created button in the menu.

get_wrapper_htmltag()

Get the HTML tag to wrap the menu in.

Defaults to "div".

get_wrapper_htmltag_id()

Get the ID of the wrapper HTML element.

has_items()
Returns:True if the list has any items, and False otherwise.
Return type:bool
insert(index, renderable_object)

Insert a renderable object at a specific index in the menu.

Parameters:
prepend(renderable_object)

Prepend a renderable object to the menu.

Parameters:renderable_object – The renderable object (a subclass of django_cradmin.renderable.AbstractRenderable)
append(renderable_object)

Append a renderable object to the menu.

Parameters:renderable_object – The renderable object (a subclass of django_cradmin.renderable.AbstractRenderable)
extend(renerable_iterable)

Just like append() except that it takes an iterable of renderables instead of a single renderable.

class DefaultMainMenuRenderable(request, cradmin_instance=None)

Bases: django_cradmin.crmenu.AbstractMenuRenderable

The default large screen (desktop) Menu renderable.

menutoggle_renderable_class

alias of MenuToggleItemItemRenderable

alias of NavLinkItemRenderable

button_renderable_class

alias of NavLinkButtonItemRenderable

class DefaultExpandableMenuRenderable(request, cradmin_instance=None)

Bases: django_cradmin.crmenu.AbstractMenuRenderable

The default small screen (mobile) Menu renderable.

alias of ExpandableMenuItem