Milk Admin

LinksBuilder Class Documentation

The LinksBuilder class provides a powerful fluent interface for creating navigation elements with support for multiple rendering styles, groups, search functionality, and advanced customization options.

System Overview

LinksBuilder simplifies navigation creation by providing:

  • Multiple Rendering Styles: navbar, breadcrumb, tabs, vertical, sidebar
  • Group Management: Organize links into logical groups
  • Search Integration: Built-in search functionality for sidebars
  • State Management: Active and disabled states with automatic detection
  • Custom Attributes: Full control over HTML attributes and styling
  • External Links: Support for external links in sidebars

Basic Usage

Constructor and Factory Method

$links = \Builders\LinksBuilder::create();

Simple Navigation Creation

$navbar = LinksBuilder::create()
    ->add('Home', '#')
        ->icon('bi bi-house')
        ->active()
    ->add('Posts', '#')
        ->icon('bi bi-file-earmark-text')
    ->add('Settings', '#')
        ->icon('bi bi-gear')
        ->disable()
    ->render('navbar');

Example Output:

Puoi applicare i menu alla barra degli header:


// Apply to different header positions
Theme::set('header.top-left', $navbar);   // Left side
Theme::set('header.top-right', $navbar);  // Right side

2. Breadcrumb Style

Creates semantic breadcrumb navigation with proper ARIA labels and Bootstrap styling.

$breadcrumb = LinksBuilder::create()
    ->add('Dashboard', '/')
        ->icon('bi bi-speedometer2')
    ->add('Posts', '?page=posts')
        ->icon('bi bi-file-earmark-text')
    ->add('My Posts', '?page=myposts')
        ->icon('bi bi-file-earmark-person')
        ->active()
    ->render('breadcrumb');

// Automatic features:
// - Last item is automatically marked as active
// - Proper aria-current="page" attribute
// - Bootstrap breadcrumb styling

Example Output:

3. Tabs Style

Bootstrap tab navigation with active state management. Perfect for content sections with tab panels.

$tabs = LinksBuilder::create()
    ->add('General', '#general-tab')
        ->icon('bi bi-gear')
        ->active()
    ->add('Advanced', '#advanced-tab')
        ->icon('bi bi-sliders')
    ->add('Security', '#security-tab')
        ->icon('bi bi-shield-lock')
    ->add('Premium', '#premium-tab')
        ->icon('bi bi-star')
        ->disable()
    ->render('tabs');

Example Output with Working Tabs:

General Settings

Configure basic application settings here.

  • Site name and description
  • Default language
  • Timezone settings
Advanced Settings

Configure advanced application features.

  • Cache settings
  • Database optimization
  • API configurations
Security Settings

Manage security and authentication options.

  • Password policies
  • Two-factor authentication
  • Access controls
Premium Features

Premium features are disabled in this demo.

4. Pills Style

Modern pill-style navigation with rounded buttons and subtle hover effects.

$pills = LinksBuilder::create()
    ->add('Dashboard', '#dashboard')
        ->active()
    ->add('Utenti', '#users')
    ->add('Ordini', '#orders')
    ->add('Report', '#reports')
    ->add('Impostazioni', '#settings')
        ->disable()
    ->render('pills');

Example Output:

5. Vertical Style (Simple Sidebar)

Vertical navigation without groups, perfect for simple sidebars.

$vertical = LinksBuilder::create()
    ->add('Dashboard', '?page=dashboard')
        ->icon('bi bi-speedometer2')
    ->add('Posts', '?page=posts')
        ->icon('bi bi-file-earmark-text')
    ->add('My Posts', '?page=myposts')
        ->icon('bi bi-file-earmark-person')
        ->active()
    ->add('Categories', '?page=categories')
        ->icon('bi bi-tags')
    ->add('Settings', '?page=settings')
        ->icon('bi bi-gear')
        ->disable()
    ->render('vertical');

Example Output:

Group Management

Sidebar with Groups and Advanced Features

Complete sidebar implementation with groups, search, and external links - as used in documentation.

// Full-featured sidebar with groups
$sidebar = LinksBuilder::create()
    // Enable search functionality
    ->enableSearch('Search documentation...')
    ->setContainerClass('docs-sidebar border-end p-3')
    ->setContainerId('testContainer')

    // External links
    ->addExternalLinks([
        ['url' => 'https://milkadmin.org/docs', 'title' => 'API Documentation', 'target' => '_blank']
    ])

    // Custom attributes for search functionality
    ->setLiAttributes(['class' => 'nav-item doc-link'])
    ->setAAttributes(['class' => 'doc-link'])
    ->setActiveAttributes(['class' => 'doc-link-active'])

    // Getting Started group
    ->addGroup('getting-started', 'Getting Started')
    ->add('Introduction', '#')
        ->icon('bi bi-book')
        ->active()
    ->add('Installation', '#')
        ->icon('bi bi-download')

    // Development group
    ->addGroup('development', 'Development')
    ->addMany([
        ['title' => 'Modules', 'url' => '#', 'icon' => 'bi bi-code-slash'],
        ['title' => 'Models', 'url' => '#', 'icon' => 'bi bi-database'],
        ['title' => 'Views', 'url' => '#', 'icon' => 'bi bi-eye', 'disabled' => true]
    ])

    ->render('sidebar');

// Groups are visible in 'vertical' and 'sidebar' styles
// In other styles (navbar, breadcrumb, tabs), groups are ignored

Example Output (Sidebar with Groups):

Same Code with Navbar Style (Groups Hidden):

Groups Behavior by Style

Style Groups Visible Group Titles Use Case
navbar No Hidden Horizontal navigation
breadcrumb No Hidden Page hierarchy
tabs No Hidden Content sections
vertical Yes Simple headings Basic sidebar
sidebar Yes Full featured Documentation, admin panels

Link Management Methods

Adding Links

$links = LinksBuilder::create()
    // Basic link
    ->add('Home', '/')

    // Link with icon
    ->add('Posts', '/posts')
        ->icon('bi bi-file-earmark-text')

    // Active link
    ->add('Current Page', '/current')
        ->icon('bi bi-circle-fill')
        ->active()

    // Disabled link
    ->add('Coming Soon', '#')
        ->icon('bi bi-clock')
        ->disable()

    // Link with custom parameters
    ->add('Custom Link', '/custom')
        ->setParam('data-toggle', 'tooltip')
        ->setParam('title', 'Custom tooltip');

Example Output:

Bulk Adding with addMany()

$links = LinksBuilder::create()
    ->addMany([
        // Array format with keys
        ['title' => 'Home', 'url' => '/', 'icon' => 'bi bi-house', 'active' => true],
        ['title' => 'About', 'url' => '/about', 'icon' => 'bi bi-info-circle'],
        ['title' => 'Contact', 'url' => '/contact', 'icon' => 'bi bi-envelope', 'disabled' => true],

        // Alternative array format (positional)
        ['Services', '/services', ['icon' => 'bi bi-gear']]
    ]);

Example Output:

Method Reference

Basic Link Methods

add(title, url)

Parameters: string $title, string $url (default: '#')
Returns: self for method chaining
Usage: Adds a single link to the builder. Use '#' for anchors, '?page=...' for internal routes.

addMany(links)

Parameters: array $links
Returns: self for method chaining
Usage: Bulk add multiple links from array. Supports both associative and positional formats.

// Multiple format support
->addMany([
    ['title' => 'Home', 'url' => '#', 'icon' => 'bi bi-house', 'active' => true],
    ['About Us', '#about', ['icon' => 'bi bi-info-circle']]
]);

Example Output:

Link State Methods

icon(iconClass)

Parameters: string $icon
Usage: Adds an icon to the current link. Supports Bootstrap Icons classes.

active()

Usage: Marks the current link as active. Overrides automatic detection.

disable()

Usage: Disables the current link, making it non-clickable with appropriate styling.

fetch(method = 'post')

Usage: Transforms the link into an asynchronous fetch call. Adds the data-fetch attribute that enables automatic AJAX handling via JavaScript.

Parameters:

  • method (string): HTTP method - 'get' or 'post' (default: 'post')

Example:

$links = LinksBuilder::create()
    ->add('Edit Item', '?page=items&action=edit&id=123')
        ->icon('bi bi-pencil')
        ->fetch('post')  // Converts to fetch POST call
    ->add('Load Data', '?page=items&action=load')
        ->fetch('get')   // Converts to fetch GET call
    ->render('pills');

Generated HTML:

<a href="?page=items&action=edit&id=123" data-fetch="post">Edit Item</a>
<a href="?page=items&action=load" data-fetch="get">Load Data</a>

The JavaScript will automatically intercept these links and execute fetch calls instead of navigation. See data-fetch System Documentation for more details.

Works with addMany:

->addMany([
    ['title' => 'Delete', 'url' => '?page=items&action=delete&id=5', 'fetch' => 'post'],
    ['title' => 'Refresh', 'url' => '?page=items&action=refresh', 'fetch' => 'get']
])

setParam(name, value)

Parameters: string $name, mixed $value
Usage: Adds custom parameters for variable substitution in attributes.

Group Management Methods

addGroup(name, title)

Parameters: string $name, string $title (default: '')
Usage: Creates a new group. Subsequent links will be added to this group until a new group is created.

Search and Container Methods

enableSearch(placeholder, inputId, resultId)

Parameters: string $placeholder, string $inputId, string $resultId
Usage: Enables search functionality in sidebar rendering. Only works with 'sidebar' style.

->enableSearch('Search items...', 'searchInput', 'resultCount')

setContainerClass(class)

Parameters: string $class
Usage: Sets CSS class for sidebar container. Only affects 'sidebar' style.

setContainerId(id)

Parameters: string $id
Usage: Sets HTML ID for container. Must start with a letter. Auto-generated if not provided.

addExternalLinks(links)

Parameters: array $links
Usage: Adds external links displayed at bottom of sidebar. Only affects 'sidebar' style.

->addExternalLinks([
    ['url' => 'https://example.com', 'title' => 'External Link', 'target' => '_blank']
])

Example Output:

HTML Attribute Methods

setLiAttributes(attributes), setAAttributes(attributes), etc.

Parameters: array $attributes
Usage: Sets HTML attributes for specific elements. Supports variable substitution with %variable%.

->setLiAttributes(['class' => 'custom-item', 'data-title' => '%title%'])
->setAAttributes(['class' => 'custom-link', 'data-track' => 'true'])

setActiveAttributes(attributes), setDisabledAttributes(attributes)

Usage: Sets attributes that override base attributes when links are active or disabled.

Example Output with Custom Attributes:

Output Methods

render(style)

Parameters: string $style (default: 'navbar')
Returns: string HTML output
Usage: Generates HTML for specified style: 'navbar', 'breadcrumb', 'tabs', 'pills', 'vertical', 'sidebar'.

fill()

Static method
Returns: LinksBuilder instance
Usage: Factory method to create new builder instance.

Additional Configuration Methods

setOptions(options)

Parameters: array $options
Usage: Sets multiple options at once for advanced configuration.

->setOptions([
    'show_search' => true,
    'search_placeholder' => 'Custom search...',
    'container_attributes' => ['role' => 'navigation']
])

setNavAttributes(attributes), setUlAttributes(attributes)

Parameters: array $attributes
Usage: Sets attributes for nav and ul wrapper elements respectively.

Automatic Features

Active State Detection

LinksBuilder automatically detects active states by comparing URLs with current page using Route::comparePageUrl(). Manual active() calls override automatic detection.

URL Processing

  • Query strings (?page=example) → processed with Route::url()
  • Hash fragments (#section) → used as-is for anchors
  • Full URLs (http://example.com) → used as-is
  • Array URLs → processed with Route::url()

JavaScript Integration

When search functionality is enabled, LinksBuilder automatically includes necessary JavaScript via the theme system using Theme::set('javascript.linksBuilder', ...).

Method Reference Summary

Category Method Description
Link Management add(title, url) Add a single link
addMany(links) Add multiple links from array
icon(iconClass) Add icon to current link
setParam(name, value) Add custom parameter to current link
State Management active() Mark current link as active
disable() Disable current link
fetch(method) Enable fetch mode (GET/POST)
isActive(link) Automatic active state detection
Group Management addGroup(name, title) Create a new group
getGroupedLinks() Get links organized by groups
Configuration enableSearch(placeholder, inputId, resultId) Enable search functionality
setContainerClass(class) Set container CSS class
setContainerId(id) Set container HTML ID
addExternalLinks(links) Add external links to sidebar
HTML Attributes setNavAttributes(attrs) Set nav element attributes
setUlAttributes(attrs) Set ul element attributes
setLiAttributes(attrs) Set li element attributes
setAAttributes(attrs) Set anchor element attributes
setActiveAttributes(attrs) Set attributes for active elements
setDisabledAttributes(attrs) Set attributes for disabled elements
Output render(style) Generate HTML with specified style
__toString() Default rendering (navbar style)

Rendering Styles Comparison

Style HTML Structure Groups Search External Links Best Use Case
navbar ul.nav > li > a No No No Header navigation
breadcrumb nav > ol.breadcrumb > li > a No No No Page hierarchy
tabs ul.nav-tabs > li.nav-item > a.nav-link No No No Content sections
pills ul.nav-pills > li.nav-item > a.nav-link No No No Modern button navigation
vertical ul.flex-column > li.nav-item > a Simple No No Simple sidebar
sidebar Complex structure with groups Full Yes Yes Admin panels, documentation