Sidebar
Summary
Sidebar component that contains page actions and navigation. Can be collapsed manually by the user by clicking, or automatically based on browser window resize
Status
| API status: | general |
|---|---|
| Included in AUI core? | Not in core You must explicitly require the web resource key. |
| Web resource key: |
com.atlassian.auiplugin:aui-sidebar
|
| AMD Module key: | N/A |
| General API: | 5.6.3 |
Code
Basic usage (HTML)
AUI Sidebar is meant to sit within the main #content section of the AUI Page Layout, before the aui-page-panel. See comments in example below for required markup patterns and CSS classes.
Sidebar navigation variations (HTML)
Various AUI Navigation options can be used within AUI Sidebar, and they will be styled correctly, however the ordering of the <span> elements within the <a> is important
Badges
The badge will show a number next to "Issues".
Nav item actions
The aui-nav-item-actions widget will be positioned on the right, but you will need to add your own dropdown functionality.
Nested navigation
Nested AUI Navigation is supported. The trigger elements need to have the nested-parent class If a expand / collapsed twixy is needed, use the aria-expanded Boolean attribute to change the twixy orientation.
The Kitchen Sink
AUI Badges can be used to display a count of items, and will be positioned on the right The element order of various nav item options is important otherwise the styles will not be applied correctly.
Soy template usage
Large avatar (eg project or space landing page)
JavaScript
Initialization
The sidebar element (.aui-sidebar) is automatically initialized on DOM ready, i.e., it requires no additional JavaScript code.
At DOM ready, if the sidebar is rendered (in markup) as expanded but the browser is too narrow, it is automatically collapsed (without animations). This will likely run prior to any other JavaScript code having had a chance to bind to the sidebar's collapse or expand events, so if you are interested in the initial state of the sidebar you may want to add a DOM ready handler that inspects isCollapsed().
The sidebar can be collapsed or expanded on initial page load by adding aui-page-sidebar and aui-sidebar-collapsed or aui-sidebar-expanded classes to the tag. The 'sidebar' layout type in the AUI Page Layout Soy template does this for you. This is to prevent a flash of the sidebar in an unexpected state, before the JavaScript executes and sets the state based on available screen width and/or user preference if it is stored by the host product.
Options
HTML attributes
There are a few configuration options that are expressed through markup on the main aui-sidebar container element
| Class | Description |
|---|---|
aui-is-animated
|
Enables CSS transitions for the toggling of expanded/collapsed state. Note that this has browser performance implications as it animates the main content area (and causes reflow/relayout) as well as the sidebar itself. YMMV. |
| Attribute | Values | Description |
|---|---|---|
aria-expanded
|
false | true
|
Specifies if the sidebar is collapsed (false) or expanded (true) by default, overriding the auto-expand/collapse behaviour |
data-aui-responsive
|
false
|
Specifies whether the sidebar should automatically collapse/expand based on browser width |
Sidebar groups
AUI sidebar uses a div with the aui-sidebar-group class inside of the aui-navgroup/aui-navgroup-inner to group related sidebar nav items together. When the sidebar is in a collapsed state, each aui-sidebar-group will be represented
by a single icon and the group's contents will be displayed in a fly-out menu.
There are two special sidebar groups – "Actions" and "Tier One".
The "Actions" sidebar group is typically used for action items that are contextual to the screen or section that the user is on. The Actions group will get a different different (ellipsis) icon and mouse hover/focus effect when the sidebar is collapsed,
and should be the very first sidebar group in the sidebar, directly below the sidebar header and above normal navigation items. There should only be ONE aui-sidebar-group-actions group.
Tier One sidebar groups will display all navigation items within the group even when the sidebar is collapsed (normal sidebar groups will collapse into a single icon). While icons are optional for regular navigation items, Tier One navigation items must have an icon, otherwise there will be empty gaps in the sidebar where the icon should be.
| Class | Description |
|---|---|
aui-sidebar-group-tier-one
|
Specifies that the sidebar group is a "Tier One" group |
aui-sidebar-group-actions
|
Specifies that the sidebar group is the "Actions" group |
Dividers
New in AUI 5.7.1
To insert a horizontal divider between AUI Navigation uls or aui-sidebar-groups, just use the <hr> element and it will be styled appropriately.
Soy params
There is a aui.sidebar.sidebar template that you can call with the following parameters which will render the correct HTML markup
| Param | Required | Description |
|---|---|---|
content
|
Required |
Main sidebar HTML content. Typically in the form of an AUI Vertical navigation. |
headerContent
|
Required |
Sidebar header HTML content. Typically in the form of an AUI Page Header. |
footerContent
|
Required |
Sidebar footer HTML content. Typically an AUI Button or Dropdown2. This will override the default settings button (see |
settingsButtonUrl
|
Optional |
Link to direct the standard sidebar settings button. Must be used together with |
settingsText
|
Optional |
Text to use for the standard sidebar settings button. Must be used together with |
settingsTooltip
|
Optional |
Tooltip to display with the sidebar settings button, defaults to |
id
|
Optional |
ID for the sidebar container. |
state
|
Optional |
String. 'collapsed', 'expanded' or left undefined. Used by AUI Sidebar to render the sidebar's initial state. |
tagName
|
Optional |
HTML element for the sidebar container. Default is 'div'. |
isResponsive
|
Optional |
Boolean. Whether the sidebar should automatically collapse/expand based on browser width. Default is true. |
isResizable
|
Optional |
Boolean. Enables a draggable handle to allow the user to resize the sidebar. Default is false. |
isAnimated
|
Optional |
Boolean. Enables animated transitions for Sidebar expanding and collapsing. Default is false. |
extraClasses
|
Optional |
String or Object. CSS classes to add to the outermost (.aui-sidebar) element. |
extraAttributes
|
Optional |
String or Object. Additional attributes to add to the outermost (.aui-sidebar) element. |
JavaScript API
You can retrieve an instance of the sidebar via AJS.sidebar(selector) where selector is a jQuery selector string, jQuery collection, or an element.
Methods
| Method | Description | Example Usage |
|---|---|---|
expand()
|
Expands the sidebar. If the browser window is less than 1280px wide (see expand event.
|
|
collapse()
|
Collapses the sidebar. Fires event listeners bound to thecollapse event.
|
|
toggle()
|
Expands the sidebar if it is currently collapsed; collapses it if it is currently expanded. Fires the relevantexpand/collapse event listeners.
|
|
isCollapsed()
|
Returns a boolean indicating whether the sidebar is currently collapsed. |
|
isViewportNarrow()
|
Returns a boolean indicating whether the browser is narrow enough to trigger the auto collapsing behaviour when resizing the browser and 'fly-out' mode when the sidebar is expanded. |
|
collapsedTriggersSelector()
|
Returns a jQuery selector string for the trigger elements when the sidebar is in a collapsed state, useful for delegated event binding. When using this selector in event handlers, the element (this) will either be an <a> (when the trigger was a tier-one menu item) or an element with class aui-sidebar-group (for non-tier-one
items).
You should check the value of |
Events
You can listen to events triggered by the sidebar by calling the on() method:
Event handlers attached with the on() method can be removed with the off() method:
| Event | Description | Example Usage |
|---|---|---|
expand-start, expand-end
|
Fired when the sidebar is expanded. One can distinguish between a user-initiated collapse and a browser resize collapse by checking the One can prevent sidebar from expanding by calling One can determine whether the sidebar is in fly-out mode by checking |
|
collapse-start, collapse-end
|
Fired when the sidebar is collapsed. One can prevent sidebar from collapsing by calling One can distinguish between a user-initiated collapse and a browser resize collapse by checking the |
If the sidebar has animation disabled, or the user has no animation support the *-end events will fire immediately after the changes have been made.