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.
Navigation item structure
| 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.