NavList

Description

NavList provides a simple way to render side navigation, i.e. navigation that appears to the left or right side of some main content. Each group in a nav list is a list of links.

Nav list groups can contain sub items. Rather than navigating to a URL, groups with sub items expand and collapse on click. To indicate this functionality, the group will automatically render with a trailing chevron icon that changes direction when the group expands and collapses.

Nav list items appear visually active when selected. Each nav item must have one or more ID values that determine which item will appear selected. Use the selected_item_id argument to select the appropriate item.

Arguments

Slots

heading

The heading for the list at large. Accepts the arguments accepted by Primer::Beta::NavList::Heading.

items

Items. Items can be individual items, dividers, or groups. See the documentation for #with_item, #with_divider, and #with_group respectively for more information.

Methods

with_item(component_klass: Class, system_arguments: Hash)

Adds an item to the list.

Parameters

with_avatar_item(src: String, username: String, full_name: String, full_name_scheme: Symbol, component_klass: Class, avatar_arguments: Hash, system_arguments: Hash)

Adds an avatar item to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image.

Parameters

with_group(system_arguments: Hash)

Adds a group to the list. A group is a list of links and a (required) heading.

Parameters

with_divider(system_arguments: Hash)

Adds a divider to the list. Dividers visually separate items and groups.

Parameters

build_item(component_klass: Class, system_arguments: Hash)

Builds a new item but does not add it to the list. Use this method instead of the #with_item slot if you need to render an item outside the context of a list, eg. if rendering additional items to append to an existing list, perhaps via a separate HTTP request.

Parameters

build_avatar_item(src: String, username: String, full_name: String, full_name_scheme: Symbol, component_klass: Class, avatar_arguments: Hash, system_arguments: Hash)

Builds a new avatar item but does not add it to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image. Use this method instead of the #with_avatar_item slot if you need to render an avatar item outside the context of a list, eg. if rendering additional items to append to an existing list, perhaps via a separate HTTP request.

Parameters

render_outer_list? -> Boolean

Lists that contain top-level items (i.e. items outside of a group) should be wrapped in a <ul>

NavList::Heading

The heading placed above a NavList's items.

See Primer::Beta::NavList for usage examples.

Arguments

Methods

title

Returns the value of attribute title.

id

Returns the value of attribute id.

heading_level

Returns the value of attribute heading_level.

system_arguments

Returns the value of attribute system_arguments.

NavList::Item

Items are rendered as styled links. They can optionally include leading and/or trailing visuals, such as icons, avatars, and counters. Items are selected by ID. IDs can be specified via the selected_item_ids argument, which accepts a list of valid IDs for the item. Items can also themselves contain sub items. Sub items are rendered collapsed by default.

Arguments

Slots

items

description

Description content that complements the item's label, with optional test_selector. See ActionList's description_scheme argument for layout options.

leading_visual

An icon, avatar, SVG, or custom content that will render to the left of the label.

To render an icon, call the with_leading_visual_icon method, which accepts the arguments accepted by Primer::Beta::Octicon.

To render an SVG, call the with_leading_visual_svg method.

To render custom content, call the with_leading_visual_content method and pass a block that returns a string.

trailing_visual

An icon, label, counter, or text to render to the right of the label.

To render an icon, call the with_leading_visual_icon method, which accepts the arguments accepted by Primer::Beta::Octicon.

To render a label, call the with_leading_visual_label method, which accepts the arguments accepted by Primer::Beta::Label.

To render a counter, call the with_leading_visual_counter method, which accepts the arguments accepted by Primer::Beta::Counter.

To render text, call the with_leading_visual_text method and pass a block that returns a string. Eg:

with_leading_visual_text { "Text here" }

trailing_action

A button rendered after the trailing icon that can be used to show a menu, activate a dialog, etc.

tooltip

Tooltip that appears on mouse hover or keyboard focus over the trailing action button. Use tooltips sparingly and as a last resort. Important: This tooltip defaults to type: :description. In a few scenarios, type: :label may be more appropriate. Consult the Primer::Alpha::Tooltip documentation for more information.

Methods

selected_by_ids

Returns the value of attribute selected_by_ids.

sub_item

Returns the value of attribute sub_item.

sub_item? -> Boolean

Returns the value of attribute sub_item. Whether or not this item is nested under a parent item.

expand!

Cause this item to show its list of sub items when rendered.

item_active? -> Boolean

Normally it would be easier to simply ask each item for its active status, eg. items.any?(&:active?), but unfortunately the view context is not set on each item until after the parent's before_render, etc methods have been called. This means helper methods like current_page? will blow up with an error, since helpers is simply an alias for the view context (i.e. an instance of ActionView::Base). Since we know the view context for the parent object must be set before before_render is invoked, we can call helper methods here in the parent and bypass the problem entirely. Maybe not the most OO approach, but it works.

NavList::Divider

Separator with optional text rendered above groups or between individual items.

Arguments

NavList::Group

A logical grouping of navigation links with an optional heading.

See Primer::Beta::NavList for usage examples.

Arguments

Slots

show_more_item

A special "show more" list item that appears at the bottom of the group. Clicking the item will fetch the next page of results from the URL passed in the src argument and append the resulting chunk of HTML to the group.

items

Items.

heading

Heading text rendered above the list of items.

Methods

expand!

Cause this group to show its list of sub items when rendered. :nocov: