APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Sidebar

A responsive, hierarchical navigation sidebar for APPNETOS applications.

CoreUi\Navigation\Sidebar normalizes application-defined navigation items and renders them through a Bootstrap-specific Twig template. The component handles presentation, not routing or access control. Core UI elements do not provide their own translations.

Overview and lifecycle

The application creates a Sidebar instance and passes its item definitions to init($items). Initialization resolves the shared Core\Files, Core\Css, Core\Render and Core\Ui controllers, registers the stylesheet, normalizes the navigation tree and invalidates the cached default view. getView() then resolves the Twig template through the Files layer and renders the title and normalized items.

Application items → Sidebar::init() → normalizeItems() → Core\Files + Core\Render → Bootstrap Twig / HTML

Use the generated HTML in an application view or pass it into a layout region such as the sidebar of a frameset. The component does not automatically attach itself to a frameset.

Quick start

use Core\Registry;
use CoreUi\Navigation\Sidebar;

$sidebar = Registry::getNew(Sidebar::class);

$sidebar->init([
    [
        'label' => 'Dashboard',
        'url' => '/admin',
        'active' => true,
    ],
    [
        'label' => 'Management',
        'url' => '/admin/management',
        'children' => [
            [
                'label' => 'Users',
                'url' => '/admin/users',
            ],
            [
                'label' => 'Groups',
                'url' => '/admin/groups',
            ],
        ],
    ],
]);

$sidebar->setTitle('Administration');
$sidebarHtml = $sidebar->getView();

Provide the generated $sidebarHtml to the application template or a suitable ViewSlot. The application must determine which item is active and provide the corresponding active value.

Property Normalized type Default Meaning
label string '' Displayed link content
url string '' Link destination
active bool false Active-link styling
children array [] Nested entries
level int Generated Zero-based nesting level

The root level is 0; children can reach levels 1 and 2. Any children of a level-2 entry are discarded during normalization. Non-array entries are ignored. Missing values receive defaults, supported scalar values are cast to their normalized types and additional input properties are not retained. getItems() returns the normalized tree.

Active status is assigned per item. The controller does not automatically compare the current request URL with navigation destinations or propagate active status to parent entries.

Responsive behavior

The default Bootstrap template uses a dark, vertically stacked navigation. Nested items are rendered recursively with level-specific classes and increasing indentation. Active links receive dedicated styling classes, including Bootstrap background, text and border utilities.

On smaller viewports the menu is placed inside a Bootstrap Collapse element controlled by a navbar toggler. The optional title is displayed as a mobile navbar brand (d-block d-lg-none); the default template does not display this title as a separate desktop heading.

The default template uses id="appnetos-ui-sidebar" for its Collapse target. If multiple sidebar instances appear on one page, override the template to assign unique IDs.

Rendering and caching

Method Behavior
init(array $items): void Resolves controllers, registers CSS, normalizes items and clears the cached default view.
setTitle(?string $title): static Sets the optional title and returns the instance.
getItems(): array Returns normalized navigation items.
getView(?string $template = null): string Returns the cached default HTML or renders an explicitly supplied template directly.

The default view is cached on the Sidebar instance after its first render. Calling init() again clears this cache. setTitle() does not invalidate an already rendered default view; set the title before the first getView() call, or reinitialize before rendering a changed title. Passing a custom template to getView($template) bypasses the default-view cache.

If the required Files or Render controller or the requested template is unavailable, the protected render method returns an empty string. Bootstrap configuration errors can instead raise a runtime exception when selecting the default template.

Templates and customization

The default template is resolved from appnetos/shared/ui/navigation/sidebar/templates/bootstrap/5.3/sidebar.html.twig using Core\Files::getTemplate(). The current implementation maps BootstrapVersion::V5_3_8 to 5.3. Bootstrap must be enabled; no implicit template-version fallback is provided.

The stylesheet is registered from /src/appnetos/shared/ui/navigation/sidebar/css/CoreUiNavigationSidebar.min.css. Subclasses may override the protected getCss() and getBaseTemplate() methods. For visual customization, use the APPNETOS file/template override workflow instead of modifying shared sources. The default markup also provides appnetos-ui-sidebar__* classes and *-custom hooks for styling.

An explicitly supplied custom template receives the same title and items variables as the default template.

Security and application responsibilities

The default Twig template renders labels and the optional title using |raw, allowing trusted HTML such as icons or custom markup. Do not pass untrusted user-generated HTML into these values without sanitizing it. Validate or constrain navigation URLs supplied by external data as appropriate.

Showing or hiding a navigation link does not authorize access to its destination. Applications must enforce authentication and authorization in their own routing and request handling. Translate labels in the application before passing them to Sidebar.

Next Steps

Previous

Navigation

Explore Navigation

Next

Business Core

Explore Business Core