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¶
-
get_default_expandable_menu_renderable
(**kwargs)¶ Get the default expandable menu renderable.
The one set in the
DJANGO_CRADMIN_DEFAULT_EXPANDABLE_MENU_CLASS
.Parameters: **kwargs – Kwargs for the expandable menu class constructor. Returns: Expandable menu renderable object or None
.Return type: AbstractMenuRenderable
-
class
BaseMenuLinkRenderable
(label, url, is_active=False, bem_variant_list=None, parent_bem_block=None, **kwargs)¶ Bases:
django_cradmin.renderable.AbstractBemRenderable
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.
-
get_bem_element
()¶ Get the bem element string.
-
get_bem_variant_list
()¶ Get a list of BEM variants.
You do not include the block/element, just the part after
--
.
-
class
NavLinkItemRenderable
(label, url, is_active=False, bem_variant_list=None, parent_bem_block=None, **kwargs)¶ 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, **kwargs)¶ 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.
-
get_bem_variant_list
()¶ Get a list of BEM variants.
You do not include the block/element, just the part after
--
.
-
class
ExpandableMenuItem
(label, url, is_active=False, bem_variant_list=None, parent_bem_block=None, **kwargs)¶ 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.
-
get_bem_element
()¶ Get the bem element string.
-
class
ExpandableMenuSeparator
(parent_bem_block=None, **kwargs)¶ Bases:
django_cradmin.renderable.AbstractBemRenderable
-
get_bem_element
()¶ Get the bem element string.
-
-
class
MenuToggleItemItemRenderable
(parent_bem_block=None, **kwargs)¶ Bases:
django_cradmin.renderable.AbstractBemRenderable
Use this to add an expandable menu toggle to the menu.
-
get_bem_element
()¶ Get the bem element string.
-
-
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.-
link_renderable_class
= None¶ The link renderable class used by
make_link_renderable()
.
-
separator_renderable_class
= None¶ The separator renderable class used by
make_separator_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_link_renderable_class
()¶ Get the link renderable class.
The default implementation returns
link_renderable_class
, and raises ValueError if it isNone
.You can override this method, or override
link_renderable_class
to change the link renderable class.
-
get_separator_renderable_class
()¶ Get the separator renderable class.
The default implementation returns
separator_renderable_class
, and raises ValueError if it isNone
.You can override this method, or override
separator_renderable_class
to change the separator renderable class.
-
get_button_renderable_class
()¶ Get the button renderable class.
The default implementation returns
button_renderable_class
, and raises ValueError if it isNone
.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()
ormake_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 byget_child_renderable_parent_bem_block()
.
-
make_link_renderable
(**kwargs)¶ 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_separator_renderable
(**kwargs)¶ Make a separator renderable.
Uses the renderable returned by
get_separator_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 separator 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.
-
append_link
(**kwargs)¶ Uses
make_link_renderable()
to create a renderable, and appends the created link to the menu.
-
prepend_link
(**kwargs)¶ Uses
make_link_renderable()
to create a renderable, and prepends the created link to the menu.
-
insert_link
(index, **kwargs)¶ Uses
make_link_renderable()
to create a renderable, and inserts the created link in the menu.
-
append_separator
(**kwargs)¶ Uses
make_separator_renderable()
to create a renderable, and appends the created separator to the menu.
-
prepend_separator
(**kwargs)¶ Uses
make_separator_renderable()
to create a renderable, and prepends the created separator to the menu.
-
insert_separator
(index, **kwargs)¶ Uses
make_separator_renderable()
to create a renderable, and inserts the created separator in the menu.
-
append_button
(**kwargs)¶ Uses
make_button_renderable()
to create a renderable, and appends the created button to the menu.
-
prepend_button
(**kwargs)¶ Uses
make_button_renderable()
to create a renderable, and prepends the created button to 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.
-
insert
(index, renderable_object)¶ Insert a renderable object at a specific index in the menu.
Parameters: - index (int) – The index to insert at.
- renderable_object – The renderable object (a subclass
of
django_cradmin.renderable.AbstractRenderable
)
-
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
)
-
-
class
DefaultMainMenuRenderable
(request, cradmin_instance=None)¶ Bases:
django_cradmin.crmenu.AbstractMenuRenderable
The default large screen (desktop)
Menu
renderable.-
menutoggle_renderable_class
¶ alias of
MenuToggleItemItemRenderable
-
link_renderable_class
¶ alias of
NavLinkItemRenderable
-
button_renderable_class
¶ alias of
NavLinkButtonItemRenderable
-
get_wrapper_htmltag_id
()¶ Get the ID of the wrapper HTML element.
-
-
class
DefaultExpandableMenuRenderable
(request, cradmin_instance=None)¶ Bases:
django_cradmin.crmenu.AbstractMenuRenderable
The default small screen (mobile)
Menu
renderable.-
link_renderable_class
¶ alias of
ExpandableMenuItem
-
separator_renderable_class
¶ alias of
ExpandableMenuSeparator
-
get_wrapper_htmltag_id
()¶ Get the ID of the wrapper HTML element.
-