Rendering menus
The BootstrapUiComponentFactory
provides several builders for generating markup based on an Across Menu
.
All builders extend NavComponentBuilder
and support some of the same options.
Builder class | Factory method | Description |
---|---|---|
|
|
Converts a |
|
|
Converts a |
|
|
Generates a breadcrumb for the selected items of a |
Example
An example of generating a nav structure from a Menu
.
PathBasedMenuBuilder menu = new PathBasedMenuBuilder();
menu.item( "/one", "One", "#" ).order( 1 ).and()
.group( "/two", "Two" ).order( 2 ).and()
.item( "/two/one", "Sub item 1", "#" ).and()
.item( "/two/two", "Sub item 2", "#" );
model.addAttribute(
"customNav",
bootstrapUiComponentFactory.nav( menu ).tabs().build( builderContext )
);
<nav>
<across:view element="${customNav}" />
</nav>
<nav>
<ul class="nav nav-tabs">
<li><a href="#" title="One">One</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" title="Two" class="dropdown-toggle">
Two <span class="caret"></span>
</a>
<ul class="dropdown-menu">
<li><a href="#" title="Sub item 1">Sub item 1</a></li>
<li><a href="#" title="Sub item 2">Sub item 2</a></li>
</ul>
</li>
</ul>
</nav>
Supported nav styles
You can generate specific nav structures using the DefaultNavComponentBuilder
by specifying a nav style.
Method | CSS appended | Remarks |
---|---|---|
|
Default mode. |
|
|
navbar-nav |
|
|
nav-tabs |
|
|
nav-pills |
|
|
nav-pills nav-stacked |
All NavComponentBuilder
implementations also support custom HTML attributes to be configured directly on the root element.
Default menu conversion behaviour
When mapping a Menu
onto a nav, the following rules are followed:
-
only 3 levels of items/groups are supported in the
Menu
-
an item is always rendered as a single item, even if it has children
-
an item or group are only rendered if they are not disabled
-
when an item is selected, the item itself as well as all its parent will have the active css class
-
a group is only rendered if it has at least one non-disabled child
-
a group is rendered as a dropdown
-
a group inside a group is rendered as a labeled section in the dropdown
-
a group having only a single item is rendered as that single item unless the attribute nav:keepAsGroup is set
Menu item title
All nav related builders support message code snippets in Menu
titles.
Putting for example #{my.code=Item title} as title
property will be replaced by the Locale
specific message for my.code or by Item title if that message code can’t be resolved
Replacing group label by the selected item
By default the label of a dropdown will always be the title of the group.
If you want the label to be replaced by the label of the selected item, you should configure the NavComponentBuilder
with replaceGroupBySelectedItem
.
With replaceGroupBySelectedItem
true
, if no item is selected in the group, the dropdown label will still be the title of the group.
If an item is selected however, the dropdown label will be the item label, unless the group itself has the attribute nav:keepGroupItem set to true
.
Customizing nav rendering through the Menu
You can influence the generated output by setting reserved attributes on the Menu
items.
Attribute names mentioned here are available as constants on the NavComponentBuilder class.
|
The following attributes are support on Menu
items:
nav:icon |
|
nav:iconOnly |
Only applicable on a group. If an icon is set, this will render the group itself as only the icon. |
nav:linkViewElement |
Possible child items will still be rendered as a nested unordered list if the item is a group. A custom link should handle opening the dropdown in that case. |
nav:itemViewElement |
|
nav:keepAsGroup |
Only applicable on a group.
If set to |
nav:keepGroupItem |
Only applicable on a group and if NOTE: Attribute is only relevant for a |
nav:panelStyle |
Holds the CSS class that determines the panel styling. If set, the default panel-default class will be omitted. Only applicable on group menu items that would result in a panel being rendered. NOTE: Attribute is only relevant for a |
nav:renderAsPanel |
If set to false on an group menu item that would be rendered as a panel (a group on the top level), no panel will be rendered but a sidebar nav list will directly be rendered. Optionally a title will still be included if the group has one. Non-panel lists do not support groups as items, these will be ignored. NOTE: Attribute is only relevant for a |
html:* |
Any attribute with a name starting with html: will be added as html attribute to the list item. Name of the html attribute will be the menu attribute name without the html: prefix. |
Examples
Adding an icon
Adding an icon to an item or group is easily done by setting the nav:icon attribute with a ViewElement
or ViewElementBuilder
value.
menu.item( "/dl", "Download", "#" )
.attribute( NavComponentBuilder.ATTR_ICON, new GlyphIcon( GlyphIcon.DOWNLOAD ) )
.order( 1 );
An icon based dropdown
If you set attribute nav:iconOnly to true
, the dropdown will only render the icon for the group.
If there is no icon value set on the group item, the dropdown will render the group title.
The children of the group (dropdown options) will always be rendered as full items.
If however the dropdown label is replaced by an item or the group only contains a single item, the item will also be rendered as only an icon.
menu.group( "/options", "Options", "#" )
.attribute( NavComponentBuilder.ATTR_ICON, new GlyphIcon( GlyphIcon.COG ) )
.attribute( NavComponentBuilder.ATTR_ICON_ONLY, true )
.and()
.item( "/options/dl", "Download", "#" )
.attribute( NavComponentBuilder.ATTR_ICON, new GlyphIcon( GlyphIcon.DOWNLOAD ) );