TitleBuilder Class Documentation

Public Methods

Method	Parameters	Description
`create()`	`string $title = ''`	Static factory method
`title()`	`string $title`	Set the main title text
`setPage()`	`string $page_name`	Set page name for action links
`description()`	`string $description`	Add description below the title
`addButton()`	`string $title, string $link, string $color = 'primary', string $class = '', ?string $fetch = null, string $target = ''`	Add a link button (supports fetch and target)
`addClickButton()`	`string $title, string $onclick, string $color = 'primary', string $class = ''`	Add a JavaScript click button
`addButtons()`	`array $buttons`	Add multiple buttons at once
`clearButtons()`	`(no parameters)`	Remove all buttons
`addSearch()`	`string $filter_id, string $placeholder = 'Search...', string $label = 'Search'`	Add search input tied to a table filter
`setSearchHtml()`	`string $html`	Override search HTML with custom markup
`clearSearch()`	`(no parameters)`	Remove search functionality
`addRightContent()`	`string $html`	Add custom right-side content
`addBottomContent()`	`string $html`	Add full-width content below the title row
`clearRight()`	`(no parameters)`	Clear right-side content
`clearBottom()`	`(no parameters)`	Clear bottom content
`includeMessages()`	`bool $include = true`	Toggle MessagesHandler rendering
`setCols()`	`int $left`	Set column widths for title/search layout
`render()`	`(no parameters)`	Generate and return HTML
`getHtml()`	`(no parameters)`	Alias for render()
`__toString()`	`(no parameters)`	Auto-render when used as string

The TitleBuilder class provides a fluent interface for creating consistent page headers with titles, buttons, search functionality, and descriptions. It generates responsive layouts that work seamlessly across desktop and mobile devices.

System Overview

TitleBuilder simplifies the creation of page headers by providing:

Responsive Layout: Automatic mobile-friendly layouts using Bootstrap grid
Button Management: Easy addition of action buttons with various styles
Search Integration: Built-in search functionality with table filtering
Message Handling: Optional integration with MessagesHandler
Custom Content: Flexible right-side content areas

It replaces the need to manually create complex responsive header layouts and ensures consistency across your application.

Basic Usage

Constructor and Factory Method


// Standard constructor
$title = new \Builders\TitleBuilder('Page Title');

// Factory method (recommended)
$title = \Builders\TitleBuilder::create('Page Title');

Simple Title Creation


// Basic title with description
echo (new \Builders\TitleBuilder('Posts Management'))
    ->description('Manage your blog posts and articles')
    ->render();

// With a single button
echo \Builders\TitleBuilder::create('Users')
    ->addButton('Add New User', '?page=users&action=add', 'primary')
    ->render();

Button Management

Adding Single Buttons


$title = \Builders\TitleBuilder::create('Posts')
    // Link button
    ->addButton('Add New', '?page=posts&action=add', 'primary')
    
    // Button with custom CSS class
    ->addButton('Import', '?page=posts&action=import', 'secondary', 'btn-lg')

    // Link with target (new tab)
    ->addButton('Docs', 'https://example.com', 'info', '', null, '_blank')

    // Create a link that will be called in ajax. The response must be in json format.
    ->addButton('Add New', '?page=posts&action=add', 'primary', '', 'get')
    or
    ->addButton('Add New', '?page=posts&action=add', 'primary', '', 'post')
    
    // Click button with JavaScript
    ->addClickButton('Export All', 'exportPosts()', 'success')
    
    ->render();

For information on links transformed into 'ajax' see javascript-fetch-link

Adding Multiple Buttons


$title = \Builders\TitleBuilder::create('Dashboard')
    ->addButtons([
        [
            'title' => 'Add New Post',
            'link' => '?page=posts&action=add',
            'color' => 'primary'
        ],
        [
            'title' => 'Settings',
            'link' => '?page=settings',
            'color' => 'secondary',
            'class' => 'btn-outline-secondary',
            'target' => '_blank'
        ],
        [
            'title' => 'Refresh Data',
            'click' => 'refreshDashboard()',
            'color' => 'info'
        ]
    ])
    ->render();

Search Functionality

Basic Search Integration


// Simple search that integrates with TableBuilder
$title = \Builders\TitleBuilder::create('Posts')
    ->addButton('Add New', '?page=posts&action=add', 'primary')
    ->addSearch('posts_table', 'Search posts...', 'Search')
    ->render();

// The search will automatically work with TableBuilder:
$table = \Builders\TableBuilder::create($model, 'posts_table')
    ->filterLike('search', 'title')  // This matches the search above
    ->getTable();

Custom Search HTML


// Override with custom search HTML
$custom_search = '<div class="input-group">
    <input type="text" class="form-control js-milk-filter-onchange" 
           data-filter-id="posts_table" data-filter-type="search" 
           placeholder="Type to search...">
    <button class="btn btn-outline-secondary" type="button">
        <i class="bi bi-search"></i>
    </button>
</div>';

$title = \Builders\TitleBuilder::create('Posts')
    ->setSearchHtml($custom_search)
    ->render();

// The custom HTML will be properly rendered using _ph() internally
echo $title;

Layout and Responsive Design

Desktop vs Mobile Layout


// This creates a responsive layout:
// Desktop: Title + Buttons (left) | Search (right)
// Mobile:  Title + Buttons (full width)
//          Search (full width, next row)

$title = \Builders\TitleBuilder::create('Products')
    ->addButton('Add Product', '?page=products&action=add', 'primary')
    ->addButton('Categories', '?page=categories', 'secondary')
    ->addSearch('products_table', 'Search products...', 'Search')
    ->description('Manage your product inventory')
    ->render();

Custom Right Content


// Add custom content to the right area
$custom_content = '
    <div class="dropdown">
        <button class="btn btn-outline-secondary dropdown-toggle" type="button" 
                data-bs-toggle="dropdown">
            Actions
        </button>
        <ul class="dropdown-menu">
            <li><a class="dropdown-item" href="?action=export">Export Data</a></li>
            <li><a class="dropdown-item" href="?action=import">Import Data</a></li>
        </ul>
    </div>';

$title = \Builders\TitleBuilder::create('Reports')
    ->addRightContent($custom_content)
    ->render();

Message Integration

Controlling Message Display


// Messages are included by default
$title = \Builders\TitleBuilder::create('Users')
    ->description('Manage system users')
    ->render();
// This will include MessagesHandler::displayMessages()

// Disable messages if you want to show them elsewhere
$title = \Builders\TitleBuilder::create('Settings')
    ->includeMessages(false)
    ->render();

// Show messages manually later
\App\MessagesHandler::displayMessages();

Method Chaining and Fluent Interface

Clearing and Resetting


$title = \Builders\TitleBuilder::create('Dynamic Title')
    ->addButton('Button 1', '#', 'primary')
    ->addButton('Button 2', '#', 'secondary')
    ->addSearch('table1', 'Search...')
    
    // Clear individual elements
    ->clearButtons()     // Remove all buttons
    ->clearSearch()      // Remove search
    ->clearRight()       // Remove right content
    
    // Add new content
    ->addButton('New Button', '?page=new', 'success')
    ->render();

Complete Examples

Blog Management Page


// Complete blog management header
$title = \Builders\TitleBuilder::create('Blog Posts')
    ->addButtons([
        ['title' => 'New Post', 'link' => '?page=posts&action=add', 'color' => 'primary'],
        ['title' => 'Categories', 'link' => '?page=categories', 'color' => 'secondary'],
        ['title' => 'Bulk Import', 'click' => 'showImportModal()', 'color' => 'info']
    ])
    ->addSearch('posts_table', 'Search posts by title or content...', 'Search')
    ->description('Create, edit and manage your blog posts. Use the search to find specific posts or filter by category.')
    ->render();

echo $title;

// Matching table with filters
$table = \Builders\TableBuilder::create($posts_model, 'posts_table')
    ->filterLike('search', 'title', 'both')
    ->filterLike('search', 'content', 'both', 'OR')
    ->getTable();

echo $table;

User Management with Advanced Actions


// Advanced user management header
$stats_html = '
    <div class="d-flex align-items-center text-body-secondary small">
        <span class="me-3">
            <i class="bi bi-people-fill text-primary"></i> 
            ' . $user_count . ' users
        </span>
        <span>
            <i class="bi bi-person-check-fill text-success"></i> 
            ' . $active_count . ' active
        </span>
    </div>';

$actions_dropdown = '
    <div class="dropdown">
        <button class="btn btn-outline-secondary dropdown-toggle btn-sm" 
                type="button" data-bs-toggle="dropdown">
            <i class="bi bi-gear"></i> Tools
        </button>
        <ul class="dropdown-menu dropdown-menu-end">
            <li><a class="dropdown-item" href="?action=export">
                <i class="bi bi-download"></i> Export Users
            </a></li>
            <li><a class="dropdown-item" href="?action=import">
                <i class="bi bi-upload"></i> Import Users
            </a></li>
            <li><hr class="dropdown-divider"></li>
            <li><a class="dropdown-item text-danger" href="#" onclick="cleanupUsers()">
                <i class="bi bi-trash"></i> Cleanup Inactive
            </a></li>
        </ul>
    </div>';

$title = \Builders\TitleBuilder::create('User Management')
    ->addButton('Add New User', '?page=users&action=add', 'primary')
    ->addRightContent($stats_html . '<div class="ms-3">' . $actions_dropdown . '</div>')
    ->description('Manage system users, roles and permissions. Search by name, email or username.')
    ->render();

echo $title;

E-commerce Product Management


// E-commerce product management
$quick_actions = '
    <div class="btn-group" role="group">
        <button type="button" class="btn btn-outline-info btn-sm" onclick="syncInventory()">
            <i class="bi bi-arrow-clockwise"></i> Sync
        </button>
        <button type="button" class="btn btn-outline-warning btn-sm" onclick="showBulkEdit()">
            <i class="bi bi-pencil-square"></i> Bulk Edit
        </button>
        <button type="button" class="btn btn-outline-success btn-sm" onclick="exportProducts()">
            <i class="bi bi-file-earmark-spreadsheet"></i> Export
        </button>
    </div>';

$title = \Builders\TitleBuilder::create('Products')
    ->addButtons([
        [
            'title' => '<i class="bi bi-plus-circle"></i> Add Product',
            'link' => '?page=products&action=add',
            'color' => 'primary'
        ],
        [
            'title' => '<i class="bi bi-tags"></i> Categories',
            'link' => '?page=categories',
            'color' => 'secondary'
        ]
    ])
    ->addSearch('products_table', 'Search by name, SKU or description...', 'Search')
    ->addRightContent($quick_actions)
    ->description('Manage your product catalog. Add new products, organize categories, and track inventory levels.')
    ->render();

echo $title;

// Enhanced table with multiple search filters
$table = \Builders\TableBuilder::create($products_model, 'products_table')
    ->filterLike('search', 'name', 'both')
    ->filterLike('search', 'sku', 'both', 'OR')
    ->filterLike('search', 'description', 'both', 'OR')
    ->setActions([
        'edit' => [
            'label' => '<i class="bi bi-pencil"></i>',
            'link' => '?page=products&action=edit&id=%id%',
            'class' => 'btn btn-sm btn-outline-primary'
        ],
        'view' => [
            'label' => '<i class="bi bi-eye"></i>',
            'link' => '/products/{slug}',
            'target' => '_blank',
            'class' => 'btn btn-sm btn-outline-secondary'
        ]
    ])
    ->getTable();

echo $table;

Simple Edit Page Header


// Simple edit page (like in test-modellist.module.php)
$title = _absint($_REQUEST['id'] ?? 0) > 0 ? 'Edit Post' : 'Add Post';

echo \Builders\TitleBuilder::create($title)
    ->description('Fill in the form below to create or update a blog post.')
    ->addButton('Cancel', '?page=posts', 'secondary')
    ->render();

// Then your form follows...

Integration with TableBuilder

Perfect Integration Example


// This shows how TitleBuilder and TableBuilder work together
class PostsModule {
    public function listPosts() {
        // Title with search
        $title = \Builders\TitleBuilder::create('Posts')
            ->addButton('Add New', '?page=posts&action=add', 'primary')
            ->addSearch('posts_table', 'Search posts...', 'Search')
            ->description('Manage your blog posts')
            ->render();
        
        // Table that responds to the search
        $table = \Builders\TableBuilder::create($this->model, 'posts_table')
            ->filterLike('search', 'title')  // Matches the search filter-type
            ->filterEquals('status', 'status')
            ->setActions([
                'edit' => ['label' => 'Edit', 'link' => '?page=posts&action=edit&id=%id%']
            ])
            ->getHtml();
        
        // Render the page
        echo $title;
        echo $table['html'];
    }
}

Method Reference Summary

Category	Method	Description
Title	`title(string $title)`	Set the main title text
Title	`description(string $text)`	Add description below title
Buttons	`addButton(string $title, string $link, string $color = 'primary', string $class = '', ?string $fetch = null, string $target = '')`	Add link button (supports fetch and target)
	`addClickButton()`	Add JavaScript click button
	`addButtons(array)`	Add multiple buttons at once
	`clearButtons()`	Remove all buttons
Search & Content	`addSearch()`	Add table search functionality
	`setSearchHtml()`	Set custom search HTML
	`addRightContent()`	Add custom right-side content
	`clearSearch()`	Remove search functionality
Messages	`includeMessages(bool)`	Control MessagesHandler inclusion
Output	`render()`	Generate and return HTML
	`getHtml()`	Alias for render()
	`__toString()`	Auto-render when used as string
Factory	`create(string $title)`	Static factory method

Best Practices

Responsive Design

The TitleBuilder automatically handles mobile layouts - search moves to full-width second row
Buttons wrap gracefully when there are many of them
Use mb-2 class on buttons for proper spacing when wrapped

Search Integration

Always match the data-filter-id in TitleBuilder with TableBuilder's table ID
Use descriptive placeholder text in search inputs
Consider using filter_like with multiple fields for comprehensive search

Button Organization

Primary actions should use 'primary' color
Secondary actions should use 'secondary' or 'outline-*' variants
Destructive actions should use 'danger' color
Group related actions together when adding multiple buttons

Next Steps

Now that you understand TitleBuilder, you can explore:

TableBuilder: Create data tables that integrate with TitleBuilder search
SearchBuilder: Advanced search forms with multiple filters
Form Builders: Create consistent form layouts
Theme Integration: Customize the appearance across your application

Milk Admin

Getting started

Abstracts Class

Builders

Advanced

Modules

Expressions

Extensions

Form

List

Model

Related Content

Table