Outline

import { AXOutlineModule } from '@acorex/cdk/outline';

The ACoreX outline directives (AXOutlineContainer, AXOutlineItem, and AXOutlineSideMenu) provide a robust and streamlined way to create dynamic, scroll-linked navigation menus within ACoreX applications. These directives simplify the process of generating table of contents or side navigation elements that automatically highlight the currently visible section of a page as the user scrolls, enhancing user experience on long-form content.

Outline container

Purpose: The AXOutlineContainer directive is the core of the ACoreX outline navigation system. Apply it to a container element to enable outline navigation within that container. It handles:

Identifying outline items within the container.
Generating unique IDs for outline items (if they don't have one).
Tracking the container's scroll position.
Determining the active outline item.
Providing an observable (outlineItems$) that emits the list of outline items with their active state.

Selector:[axOutlineContainer]

Inputs:

target: (Type: string, Optional) A CSS selector string. Elements matching this selector will also be included as outline items, in addition to elements with the data-ax-outline-item="true" attribute. Use this to include elements that shouldn't have the data attribute.
smoothScroll: (Type: boolean, Default: true) Enables smooth scrolling when navigating via the side menu. This uses CSS scroll-behavior: smooth.
activationOffset: (Type: number, Default: 16) The offset, in pixels, from the top of an outline item that triggers its activation.
activateLastAtBottom: (Type: boolean, Default: true) Activates the last outline item when the user scrolls to the bottom of the container.
scrollableElementId: (Type: string, Optional) Use this if the element that scrolls is not the same element the `axOutlineContainer` directive is applied to. Provide the `id` of the scrollable element (the one that has the scrollbar).

Example Usage:

example.component.html

Outline item

Purpose: Use the axOutlineItem directive to explicitly mark elements within an axOutlineContainer as navigation items.

Selector:[AXOutlineItem]

Inputs:

id: (Type: string, Required) A unique identifier for the outline item. This is crucial for navigation and scrolling. If the element already has an id, this input will be ignored. If not, the directive generates an id based on the element's text content or a random string.
disabled: (Type: boolean, Default: 16, Optional) Disables item. (Don't show inside on this page.)

Example Usage:

example.component.html

`Outline side menu`

Purpose: The axOutlineSideMenu directive connects an AXSideMenuComponent to an axOutlineContainer. It populates the side menu based on the container's outline items.

Selector:[axOutlineSideMenu]

Example Usage:

example.component.html

Example

Consider a documentation page with multiple sections and subsections. The ACoreX outline directives allow you to create a dynamic side navigation menu:

example.component.html

Explanation:

Apply axOutlineContainer to the main content container.
Use axOutlineItem on headings (<h2> in this case) to mark them as navigation items.
Use the target input on axOutlineContainer to include other elements (<h3> in this example) as outline items.
Apply axOutlineSideMenu to the ax-side-menu component. This automatically populates the side menu with links to the headings.
Scrolling the main content will automatically update the active state of the side menu items. Clicking on a side menu item will smoothly scroll the page to the corresponding section.