-
Notifications
You must be signed in to change notification settings - Fork 10
Sidenav
Since V1.1.0
Eager to get started ? Check out this video intro
Sidenav is a 4-levels depth navigation component. Is a side menu with selectable and collapsible nested menu items. The user can select or expand one menu item per time; a selected menu item is automatically expanded. The developer can control the sidenav component programmatically by editing the element's runtime properties and using the element's API. The sidenav can slide in/out to the left side or to the right side. The component is fully stylable with CSS3.
Table of contents
Use the api setRootMenuItems to populate the sidenav with Menu Items. You can nest Menu Items up to 4 levels depth.
var menu = [{ id: 1, text: "Sample Item #1", styleClass : "sn-large", iconStyleClass: "glyphicon glyphicon-search", data: { description: "This is sample information that can be added to a menuItem" }, menuItems: [{ id: 5, text: "Sub Item #1" }, { id: 6, text: "Sub Item #2"}] }, { id: 2, text: "Sample Item #2" },{ isDivider: true },{ id: 3, text: "Sample Item #3", enabled: false }]; elements.sideNavigation.setRootMenuItems(menu);
The method setRootMenuItems requires an Array of Menu Item object.
The menu item is a JSON object representing an item in the sidenav. A menu item may nest other menu items. A menu item may be also used as divider, which is nothing else then a line separating the menu item above and below, in this case all other properties of the menu item are ignored.
Property | Type | Required | Description |
---|---|---|---|
String, Number | id | yes | uniquely identifies the menuItem in the menu object. |
String | text | no | The menu text, optional, default is empty. |
String | styleClass | no | add style classes to the menuItem, optional,. Separate multiple value with a SPACE char. example 'nav-large nav-primary'. |
String | iconStyleClass | no | use style classes to display icons as Font Icons, optional. example 'glyphicon glyphicon-search'. |
Boolean | enabled | no | menuItem cannot be selected or expanded if disabled, optional. Default true. |
Object | data | no | data object can be used to add custom properties to the menuItem, optional. For example you may set the formName to be shown when the menuItem is selected { formName: "aFormName", description: "This menu item will open the given form" }. |
Array | menuItems | no | an array of nested menuItems, optional. |
Boolean | isDivider | no | if true render a divider into the menu instead of a menuItem, optional. All other properties are ignored. Default false. |
This is a menu item with 2 sub menu items
var menuItem = { id: 1, text: "Sample Item #1", styleClass : "sn-large", iconStyleClass: "glyphicon glyphicon-search", data: { description: "This is sample information that can be added to a menuItem" }, menuItems: [{ id: 5, text: "Sub Item #1" }, { id: 6, text: "Sub Item #2"}] };
This menu item is instead rendered as a divider
var menuDivider = { isDivider: true };
To update a menu item you should get the menu item object using the component's API getMenuItem, any change to the returned object will be reflected on the sidenav component.
Example
var menuItem = elements.sidenav.getMenuItem(1); menuItem.text = "Update the text of the menuItem"; menuItem.styleClass = "nav-large nav-bold"; menuItem.data = { "lastUpdate" : new Date(); }
Updating an old reference of the menuItem which has not been retrieved via API it won't be possible.
Don't do this:
var menuItem = { id:1, text: "init text"}; elements.sidenav.addMenuItem(menuItem); menuItem.text = "Update text of menu item 1 like this is not reflected on UI"
Instead do
var menuItem = { id:1, text: "init text"}; elements.sidenav.addMenuItem(menuItem); // get the menuItem via API menuItem = elements.sidenav.getMenuItem(1); menuItem.text = "Update text of menu item 1 like this is correct"
There are several CSS class selectors you can use for fine-grained styling of the sidenav component.
element selector | summary |
---|---|
.svy-extra-sidenav | the root element, style is applied to the sidenav and to the tablesspanel |
.svy-sidenav | style the whole sidenav component |
.svy-sidenav-tablesspanel | style the tablesspanel container |
.svy-sidenav-menu | style the menu and all it's content |
.svy-sidenav-dropdown | style the dropdown list in each menu level |
.svy-sidenav-item | style the menu item in dropdown list |
.svy-sidenav-collapse-icon | stlye the collapse/expand icon |
.svy-sidenav-divider | style the divider |
.svy-navitem-selected | style the selected menu item |
.svy-sidenav-collapsed | style the menu item expanded |
.svy-sidenav-disabled | style the menu item disabled |
.svy-slide-out | stlye the nav menu when is closed |
To style a specif element on a specific level combine the element element selector above with the level selector below
level selector | summary |
---|---|
.sn-level-1 | the elements in root level |
.sn-level-2 | the elements in the second level |
.sn-level-3 | the elements in the third level |
.sn-level-4 | the elements in the fourth level |
Examples
/* Style all the menu items */ .svy-sidenav-item { font-size: 12px; color : #444; padding: 8px 15px; } /*Style the menu item in the first level only */ .svy-sidenav-item.sn-level-1 { font-size: 18px; color: #000; } /* Show a border the the selected item in the first level only */ .svy-navitem-selected.sn-level-1 { border-left: 3px solid; }
Property | Type | Default | Description |
---|---|---|---|
Boolean | animate | true | The menu animates when opened/closed and when items are expanded/collapsed. |
Boolean | enabled | true | The menu is disabled, menu items cannot be selected or expanded. If disabled the items cannot be selected/collapsed neither programmatically via API. |
Form | containedForm | The contained form property behaves as a tablesspanel container. The form is shown at the side of the menu and uses the same animation when the menu is opened or closed. | |
String | iconCollapseStyleClass | fa fa-cart-down | Font Icon used as icon for the menu item when is expanded. |
String | iconExpandStyleClass | fa fa-caret-right | Font Icon used as icon for the menu item when is collapsed. |
String | iconOpenStyleClass | fa fa-bars | Font Icon used as icon for the toggle button to close the side menu. |
String | iconCloseStyleClass | fa fa-bars | Font Icon used as icon for the toggle button to open the side menu. |
Boolean | open | true | If true the menu is open, when changed to false the menu slides away. Open cannot be set to false if the slidePosition is STATIC. |
String | scrollbarPosition | LEFT | defines the position of the srollbar for the sidenav. Possible values are LEFT and RIGHT. |
Number | sidenavWidth | 300 | the width, in pixel, of the sidenav menu; the containedForm will use the remaing width. The menu will use all the available width if sidenavWidth is set to 0. This option is ignored in a non-responsive form when the menu doesn't have a containedForm. |
Number | responsiveHeight | 0 | the height, in pixel, of the sidenav menu in a responsive form; The menu will use all the necessary height if the height is set to 0. This option is ignored in non-responsive forms. |
String | slidePosition | LEFT | defines to which side the menu slides out when closed. Possible values are LEFT, RIGHT and STATIC. A STATIC menu cannot slide away, is always open. |
String | slideAnimation | SLIDE-MENU | type SLIDE-MENU the menu slides away and is not visible when 'open' is false; for the type COLLAPSE-MENU the menu is collapsed and only the icons are visible when the 'open' is false. |
String | togglePosition | FIXED-TOGGLE | defines the position of the toggle button. possible values are FIXED-TOGGLE, SIDE-TOGGLE and HIDE-TOGGLE. |
String | styleClass | menu style Classes. | |
Boolean | visible | true | if the menu is visible or not. |
Event | Params | Return | Description |
---|---|---|---|
onMenuItemCollapsed | menuItemId:String-Number, event:JSEvent | Event executed when the user collapses a Menu Item. | |
onMenuItemExpanded | menuItemId:String-Number, event:JSEvent | Event executed when a Menu Item is expanded. | |
onMenuItemSelected | menuItemId:String-Number, event:JSEvent | Boolean | Event executed when a Menu Item is selected. The selection will be prevented if the onMenuItemSelected returns false. |
onOpenToggled | event:JSEvent | Event executed when the user clicks on the open button to open or close the menu. |
Method | Params | Return | Description |
---|---|---|---|
addMenuItem | menuItem:MenuItem, menuItemId:String-Number, index:Number | Boolean | Add a menu item. The menu is added as sub Menu Item if a menuItemId is provided, otherwise is added in root. |
clearMenuItems | [depth:Number] | Remove all the menu items. If depth is specified removes all the menu items at depth. | |
getMenuItem | menuItemId:String-Number | MenuItem | Returns the menu item object. |
getParentMenuItem | menuItemId:String-Number | MenuItem | Returns the parent of the menu item object with id menuItemId. |
getRootMenuItems | Array<MenuItem> | Returns the root menu items. | |
getSelectedMenuItem | [level:Number] | MenuItem | Returns the selected menu item. |
getSubMenuItems | menuItemId:String-Number | menuItems:Array<MenuItem> | Get the menuItems of the menu item with id 'menuItemId'. |
isMenuItemEnabled | menuItemId:String-Number | Boolean | Returns true if the menuItem and all it's ancestors are enabled. |
isMenuItemExpanded | menuItemId:String | Number | Boolean |
setMenuItemEnabled | menuItemId:String-Number, enabled:Boolean | Boolean | Enable or disable the menu item. |
setMenuItemExpanded | menuItemId:String-Number, expanded:Boolean, [mustExecuteOnMenuItemExpand:Boolean] | Boolean | Force the menuItem to be expanded or collapsed. |
setRootMenuItems | Array<MenuItem> | ||
setSelectedMenuItem | menuItemId:String, [mustExecuteOnMenuItemSelect:Boolean], [mustExecuteOnMenuItemExpand:Boolean], [level:Number] | Boolean | Select the menu item with the given id. |
setSubMenuItems | menuItemId:String-Number, menuItems:Array<MenuItem> | Boolean | Set the menuItems as sub menu items of the menu item with id menuItemId. |
removeMenuItem | menuItemId:String-Number | Boolean | Remove the menu item and all it's subMenuItems from the tree. |
removeSubMenuItems | menuItemId:String-Number | Boolean | Remove all the sub menu items of the menu item with id 'menuItemId'. |
Params
Type | Name | Description | Required |
---|---|---|---|
MenuItem | menuItem | the menu item object to be added. | Required |
String-Number | menuItemId | add the item as subMenuItem of the menuItemId. | Optional, Default add the menu item as root. |
Number | index | 0-based. The index at which to insert the item. Optional. Index value should not be greater then number of sibelings. | Optional, Default is at the end. |
Returns Boolean
Add a menu item. The menu is added as sub Menu Item if a menuItemId is provided, otherwise is added in root. If index is provided the menu is added at the specified index position, otherwise is added as last element. Return false if menuItemId cannot be found.
Example
var menuItem = { id: 100, text: "Sample Item #1", styleClass : "nav-large nav-primary", iconStyleClass: "glyphicon glyphicon-search", data: { description: "This is sample information that can be added to a menuItem" }, menuItems: [{ id: 101, text: "Sub Item #1" }, { id: 102, text: "Sub Item #2"}] }; elements.sideNavigation.addMenuItem(menuItem, 1, 0);
Params
Type | Name | Description | Required |
---|---|---|---|
Number | depth | 1-based. The depth to be cleared of all it's menuItems | Optional, Default 1 |
Returns void
Remove all the menu items. If depth is specified removes all the menu items at depth. If depth is equal to 1 all roots will be removed. Default depth is 1.
Example
// clear the whole menu removing all nodes. elements.sidenav.clearMenuItems(); // clear menu at depth 2 removes the sub menu items of each root menu. elements.sidenav.clearMenuItems(2);
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the menu item id. | Required |
Returns MenuItem
Returns the menu item object.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the menu item id. | Required |
Returns MenuItem
Returns the parent menu item object of the menu item with id menuItemId. Nothing is returned if the menu item is in the root menu.
Params none
Returns Array<MenuItem>
Returns the root menu items.
Params
Type | Name | Description | Required |
---|---|---|---|
Number | level | if level is provided search for the selected menu item at level. | Required |
Returns MenuItem
Returns the selected menu item.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Returns Array<MenuItem>
Get the menuItems of the menu item with id 'menuItemId'.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Returns Boolean
Returns true if the menuItem and all it's ancestors are enabled. Return false if menuItemId cannot be found or is disabled.
NOTE: The method returns false if any ancestor of the menuItem is not enabled; if the property enabled of the menuItem is set to true, but has a parent with the enabled property set to false, then isMenuItemEnabled returns false.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Returns Boolean
Returns true if the menuItem is expanded.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Boolean | enabled | true to enable the menu item, false to disable it | Required |
Returns Boolean
Enable or disable the menu item. Return false if menuItemId cannot be found.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Boolean | expanded | force the menuItem to expand if true, is collapsed otherwise | Required |
Boolean | mustExecuteOnMenuItemExpand | force the onMenuItemExpand to be executed. | Optional, Default false. |
Returns Boolean
Return false if menuItemId cannot be found or is disabled.
Params
Type | Name | Description | Required |
---|---|---|---|
Array<MenuItem> | menuItems | is an array of MenuItem objects. Each MenuItem object should set the required properties 'id', which uniquely identifies the menuItem object in menu, and 'text' property. The MenuItem may contain the optional properties 'styleClass', 'iconStyleClass', 'data', 'enabled', 'menuItems', 'isDivider'. | Required |
Returns void
Init the menu setting the root menuItems.
Example
var menu = [{ id: 1, text: "Sample Item #1", styleClass : "sn-large", iconStyleClass: "glyphicon glyphicon-search", data: { description: "This is sample information that can be added to a menuItem" }, menuItems: [{ id: 5, text: "Sub Item #1" }, { id: 6, text: "Sub Item #2" }] }, { id: 2, text: "Sample Item #2" },{ isDivider: true },{ id: 3, text: "Sample Item #3", enabled: false }]; elements.sideNavigation.setRootMenuItems(menu);
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Boolean | mustExecuteOnMenuItemSelect | force the onMenuItemSelect to be executed. | Optional, Default false. |
Boolean | mustExecuteOnMenuItemExpand | force the onMenuItemExpand to be executed. | Optional, Default false. |
Number | level | reduce the search to the selected menuItem at level, if any menuItem is selected at level. | Optional |
Returns Boolean
Select the menu item with the given id. If level is provided search is optimized since it will search only within the descendant of the selected menuItem at level. For example if a root menuItem is selected and level is equal 2 search only in the subMenuItems of the selected root. Return false if menuItemId cannot be found or is disabled.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | the id of the menu item. | Required |
Array<MenuItem> | menuItems | is an array of MenuItem objects. Each MenuItem object should set the required properties 'id', which uniquely identifies the menuItem object in menu, and 'text' property. The MenuItem may contain the optional properties 'styleClass', 'iconStyleClass', 'data', 'enabled', 'menuItems', 'isDivider'. | Required |
Returns Boolean
Set the menuItems as sub menu items of the menu item with id 'menuItemId' Return false if menuItemId cannot be found.
Example
var menuItems = [{ id: 10, text: "Sample Item #1", styleClass : "sn-large", iconStyleClass: "glyphicon glyphicon-search", data: { description: "This is sample information that can be added to a menuItem" }, menuItems: [{ id: 12, text: "Sub Item #1" } }] }, { id: 11, text: "Sample Item #2" },{ isDivider: true }]; elements.sideNavigation.setSubMenuItems(menuItems);
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | The id of the menu item. | Required |
Returns Boolean
Remove the menu item and all it's subMenuItems from the tree. Return false if menuItemId cannot be found.
Params
Type | Name | Description | Required |
---|---|---|---|
String-Number | menuItemId | The id of the menu item. | Required |
Returns Boolean
Remove all the sub menu items of the menu item with id 'menuItemId'. Return false if menuItemId cannot be found.