TableBuilder Class Documentation

The TableBuilder class provides a fluent, field-first interface for creating and managing dynamic tables. It uses a modern chaining pattern where you configure each field individually, making your code more readable and maintainable.

System Overview

TableBuilder acts as a wrapper that combines:

• ModelList: Database connection and query management
• ListStructure: Column structure and configuration
• PageInfo: Pagination and display information

It provides a single, chainable API for building tables with less code and better readability.

Method Reference Summary

Basic Usage

<div id="posts_table">
    <?php echo $table_html; ?>
</div>

<?php echo $table_html; ?>

Constructor and Factory Method

$table = \Builders\TableBuilder::create($model, 'table_id');

Simple Table Creation

// CONTROLLER
$model = new \Models\PostModel();

$tableBuilder = \Builders\TableBuilder::create($model, 'posts_table')
    ->limit(20)
    ->orderBy('created_at', 'desc')
    ->setDefaultActions()
    // Field-first pattern: configure title field
    ->field('title')
        ->link('?page='.$this->page.'&action=edit&id=%id%');

$response = $tableBuilder->getResponse();
Response::render('view.php', $response);

// VIEW (view.php)
// <?php echo $table_html; ?>  ← Just this! Don't wrap it!

Query Building Methods

TableBuilder supports all standard query operations. Here are the most common:

$conf['page_info_limit'] = 50;  // Default rows per page

$table = \Builders\TableBuilder::create($model, 'posts_table')
    // Basic operations
    ->select(['id', 'title', 'status', 'created_at'])
    ->where('status = ?', ['published'])
    ->orderBy('created_at', 'desc')
    ->limit(50)

    // Advanced operations
    ->whereIn('status', ['active', 'pending'])
    ->whereLike('title', 'search_term', 'both')  // LIKE '%search_term%'
    ->whereBetween('created_at', '2024-01-01', '2024-12-31')
    ->leftJoin('categories', 'posts.category_id = categories.id')

    ->getTable();

Field-First Pattern

The field-first pattern provides a clean, readable way to configure each table column. Instead of calling methods with the field name as a parameter, you first select the field with field() and then chain configuration methods.

Basic Field Configuration

$table = \Builders\TableBuilder::create($model, 'posts_table')
    // Configure each field with method chaining
    ->field('id')
        ->label('ID')
        ->hide()  // Hide this field

    ->field('title')
        ->label('Article Title')
        ->link('?page=posts&action=edit&id=%id%')
        ->truncate(80)

    ->field('status')
        ->label('Status')
        ->type('select')
        ->options([
            'draft' => 'Draft',
            'published' => 'Published',
            'archived' => 'Archived'
        ])

    ->field('created_at')
        ->label('Publication Date')
        ->type('datetime')

    ->getTable();

Available Field Methods

Display Formatting Methods

Links - link() method

The link() method converts a field to a clickable link with placeholder support.

$table = \Builders\TableBuilder::create($model, 'posts_table')
    // Basic link
    ->field('title')
        ->link('?page=posts&action=edit&id=%id%')

    // Link with options
    ->field('author')
        ->link('/profile/%author_id%', [
            'target' => '_blank',
            'class' => 'text-primary fw-bold'
        ])

    // Multiple placeholders
    ->field('full_name')
        ->link('/user/%id%?tab=profile&ref=%category%')

    // Link with fetch (AJAX loading)
    ->field('lessons')
        ->link('?page=courses&action=lessons&entity_id=%id%', [
            'data-fetch' => 'post'
        ])

    ->getTable();

// Supported placeholders:
// %id% - Primary key or 'id' field
// %field_name% - Any column value (e.g., %title%, %status%, %created_at%)

// Available options:
// 'target' => '_blank' | '_self' | '_parent' | '_top'
// 'class' => 'css-classes-here'
// 'data-fetch' => 'post' | 'get' - Enable AJAX loading
    

Files - file() method

The file() method converts array fields containing file data into download links. Automatically applied when model has type=array and form-type=file.

$table = \Builders\TableBuilder::create($model, 'documents_table')
    // Basic usage
    ->field('attachments')
        ->file()

    // With custom options
    ->field('files')
        ->file([
            'class' => 'btn btn-link text-primary',
            'target' => '_blank'
        ])

    ->getTable();

// Expected data format:
// $row->attachments = [
//     ['url' => 'media/file1.pdf', 'name' => 'Document.pdf'],
//     ['url' => 'media/file2.docx', 'name' => 'Report.docx']
// ];

// Available options:
// 'class' => 'custom-css-class'  // Default: 'js-file-download'
// 'target' => '_blank' | '_self'  // Default: '_blank'
    

Images - image() method

The image() method displays image thumbnails. Automatically applied when model has type=array and form-type=image.

$table = \Builders\TableBuilder::create($model, 'products_table')
    // Basic usage
    ->field('photos')
        ->image()

    // With custom options
    ->field('gallery')
        ->image([
            'size' => 80,              // Thumbnail size in pixels
            'class' => 'rounded',      // CSS classes
            'lightbox' => true,        // Clickable links
            'max_images' => 3          // Limit displayed images
        ])

    ->getTable();

// Expected data format:
// $row->photos = [
//     ['url' => 'media/photo1.jpg', 'name' => 'Product Image 1'],
//     ['url' => 'media/photo2.jpg', 'name' => 'Product Image 2']
// ];

// Available options:
// 'size' => 50                    // Width/height in pixels
// 'class' => ''                   // CSS classes
// 'lightbox' => false             // Enable clickable links
// 'max_images' => null            // Show "+N" for remaining
    

Text Truncation - truncate() method

The truncate() method limits text length, adding a suffix when exceeded.

$table = \Builders\TableBuilder::create($model, 'posts_table')
    // Basic truncation
    ->field('description')
        ->truncate(100)

    // Custom suffix
    ->field('title')
        ->truncate(50, '…')

    ->field('content')
        ->truncate(200, ' [read more]')

    ->getTable();

// Features:
// - UTF-8 safe (uses mb_substr and mb_strlen)
// - Applied after all formatting
// - Only truncates strings exceeding the specified length
// - Can be combined with other methods
    

Complete Example

$table = \Builders\TableBuilder::create($model, 'posts_table')
    // Query configuration
    ->where('status != ?', ['deleted'])
    ->orderBy('created_at', 'DESC')
    ->limit(20)

    // Field configurations with field-first pattern
    ->field('id')
        ->label('ID')
        ->hide()

    ->field('title')
        ->label('Article Title')
        ->link('?page=posts&action=edit&id=%id%')
        ->truncate(80)

    ->field('author_name')
        ->label('Author')
        ->fn(function($row) {
            return $row['first_name'] . ' ' . $row['last_name'];
        })

    ->field('category')
        ->label('Category')
        ->type('select')
        ->options([
            'tech' => 'Technology',
            'news' => 'News',
            'blog' => 'Blog'
        ])

    ->field('status')
        ->label('Status')

    ->field('photos')
        ->label('Images')
        ->image(['size' => 60, 'max_images' => 2])

    ->field('created_at')
        ->label('Publication Date')
        ->type('datetime')

    // Actions
    ->setPage('posts')
    ->setDefaultActions()

    ->getTable();

Row Actions

Row actions are buttons that appear for each table row, allowing users to perform operations like Edit, Delete, View, or custom actions.

Quick Example

$table = \Builders\TableBuilder::create($model, 'posts_table')
    ->setActions([
        'edit' => [
            'label' => 'Edit',
            'link' => '?page=posts&action=edit&id=%id%'
        ],
        'delete' => [
            'label' => 'Delete',
            'action' => [$this, 'actionDelete'],
            'confirm' => 'Are you sure?',
            'class' => 'btn-danger'
        ]
    ]);

Default Actions Helper

Use setDefaultActions() to automatically generate Edit and Delete actions:

$table = \Builders\TableBuilder::create($model, 'posts_table')
    ->setDefaultActions();  // Auto-generates Edit and Delete actions

See: Row Actions Documentation

Bulk Actions

For operations on multiple rows at once, use bulk actions.

See: Bulk Actions Documentation

Table Styling

TableBuilder provides comprehensive styling options including field-specific styling with conditional classes.

See: Table Styling Documentation

Output Methods

Understanding render() vs getResponse()

// Simple table - no actions or only link actions
$html = TableBuilder::create($model, 'table_id')
    ->field('title')->link('?page=posts&action=edit&id=%id%')
    ->render();

Response::render($view, ['html' => $html]);

// Table with action callbacks - MUST use getResponse()
$response = TableBuilder::create($model, 'table_id')
    ->setActions([
        'delete' => [
            'label' => 'Delete',
            'action' => [$this, 'actionDelete'], // Callback function
            'confirm' => 'Are you sure?'
        ]
    ])
    ->getResponse(); // Returns ['html' => '...', ...callback results]

// Pass entire $response array to Response::render()
Response::render($view, $response);

// ❌ WRONG - Don't concatenate with render() when you have callbacks
$response['html'] = $titleHtml . $tableBuilder->render();
Response::render($view, $response);

// ✅ CORRECT - Use getResponse() and add other data separately
$response = $tableBuilder->getResponse();
$response['title_html'] = $titleHtml;
Response::render($view, $response);

All Available Output Methods

$table = \Builders\TableBuilder::create($model, 'posts_table')
    ->limit(20)
    ->orderBy('created_at', 'desc');

// 1. Get complete data array (advanced usage)
$data = $table->getData();
// Returns: ['rows' => [...], 'info' => ListStructure, 'page_info' => PageInfo]

// 2. Get HTML table only (no actions with callbacks)
$html = $table->render();
echo $html;

// 3. Alternative syntax for render()
$html = $table->getTable();
echo $html;

// 4. Get response array (required for action callbacks)
$response = $table->getResponse();
// Returns: ['html' => '...', ...additional data from actions]

// 5. Get only function results from actions
$results = $table->getFunctionsResults();
    

Key Features Summary

• Field-First Pattern: Configure each field with clear, grouped method chains
• Fluent Interface: Method chaining for readable code
• Action Functions: Execute custom logic on selected rows with return values for theme integration
• Advanced Queries: Support for JOINs, WHERE conditions, and custom callbacks
• Flexible Display: Links, images, files, truncation, custom formatters
• Styling Options: Comprehensive table and field-specific styling with conditional classes