Search & Filters

Revision: 2025/12/16

SearchBuilder creates search and filter interfaces for tables and lists. It uses a fluent interface (method chaining) to build search fields, dropdowns, tab filters, and other filtering controls.

Basic Concepts

Creation and Table ID

SearchBuilder requires a unique ID that must match the ID of the table or list to filter:

$search = SearchBuilder::create('idTablePosts');

Automatic Search

The "search" field is automatically processed by TableBuilder across all text fields in the table. It does not require custom filter definitions.

Custom Filters

Other filter types (select, actionList, input) require explicit behavior definition through TableBuilder's filter() method.

Available Methods

Method	Type	Parameters	Description
Creator Methods - Create new fields
search($filter_type)	Creator	string (default: 'search')	Creates a text search field
select($filter_type)	Creator	string	Creates a dropdown select
actionList($filter_type)	Creator	string	Creates a clickable tab filter
input($type, $filter_type)	Creator	string, string	Creates a generic input (date, number, email, etc.)
searchButton()	Creator	-	Creates a manual search button
clearButton()	Creator	-	Creates a filter reset button
Modifier Methods - Modify the current field
label($label)	Modifier	string	Sets the field label
placeholder($placeholder)	Modifier	string	Sets the placeholder
class($class)	Modifier	string	Adds custom CSS classes to the container
layout($layout)	Modifier	'inline'|'stacked'|'full-width'	Sets the field layout
options($options)	Modifier	array	Sets options for select or actionList
selected($value)	Modifier	string	Sets selected value for select or actionList
value($value)	Modifier	string	Sets default value for input fields
Configuration Methods - Global settings
setSearchMode($mode, $auto_buttons)	Config	string, bool	Sets mode to 'onchange' or 'submit'
setWrapperClass($class)	Config	string	Sets CSS classes for the fields wrapper
setContainerClasses($classes)	Config	string	Sets CSS classes for the main container
setFormClasses($classes)	Config	string	Sets CSS classes for form elements
Output Methods
render($options)	Output	array	Generates and returns the HTML

Update Modes

SearchBuilder supports two filter execution modes:

onChange Mode (Default)

Filters are applied automatically on every value change. This is the default mode.

$search = SearchBuilder::create('idTablePosts')
    ->search('search')
    ->select('status')
        ->options(['all' => 'All', 'active' => 'Active'])
        ->selected('all');
// Filters activate automatically onChange

Submit Mode

Filters are applied only when clicking the Search button. Useful for multiple or complex filters.

$search = SearchBuilder::create('idTablePosts')
    ->setSearchMode('submit', true) // true automatically adds buttons
    ->input('date', 'start_date')
    ->input('date', 'end_date')
    ->select('category');
// Filters activate only when clicking Search

setSearchMode parameters:

• $mode: 'onchange' (default) or 'submit'
• $auto_buttons: if true, automatically adds Search and Clear buttons in submit mode

Field Layouts

Each field can have a specific layout via ->layout():

• inline (default): Label and field on the same row, horizontally aligned
• stacked: Label above the field, vertical layout
• full-width: Field takes full available width

TableBuilder Integration

Automatic Filter (search)

The search field is automatically handled by TableBuilder across all text fields:

$search = SearchBuilder::create('idTablePosts')
    ->search('search')
    ->placeholder('Search posts...');

$table = TableBuilder::create($model, 'idTablePosts');
// The search filter works automatically

Custom Filters

Other filters require definition with filter(). The filter name must match the $filter_type used in SearchBuilder:

$search = SearchBuilder::create('idTablePosts')
    ->actionList('status')
        ->label('Status:')
        ->options(['active' => 'Active', 'deleted' => 'Deleted'])
        ->selected('active');

$table = TableBuilder::create($model, 'idTablePosts')
    ->filter('status', function($query, $value) {
        if ($value === 'deleted') {
            $query->where('deleted_at IS NOT NULL');
        } else {
            $query->where('deleted_at IS NULL');
        }
    }, 'active');

Examples

Basic Search

$search = SearchBuilder::create('idTablePosts')
    ->search('search')
    ->placeholder('Type to search...');

Tab Filter (ActionList)

$search = SearchBuilder::create('idTablePosts')
    ->actionList('status')
        ->label('Filter by:')
        ->options([
            'all' => 'All',
            'published' => 'Published',
            'draft' => 'Draft'
        ])
        ->selected('all');

Dropdown Select

$search = SearchBuilder::create('idTableProducts')
    ->select('category')
        ->label('Category:')
        ->options(['' => 'All', 'tech' => 'Tech', 'design' => 'Design'])
        ->selected('');

Custom Input

$search = SearchBuilder::create('idTableOrders')
    ->input('date', 'start_date')
        ->label('From:')
        ->placeholder('2024-01-01')
    ->input('date', 'end_date')
        ->label('To:')
        ->placeholder('2024-12-31');

Multiple Filters with Layout

$search = SearchBuilder::create('idTableUsers')
    ->actionList('role')
        ->label('Role:')
        ->options(['all' => 'All', 'admin' => 'Admin', 'user' => 'User'])
        ->selected('all')
        ->layout('inline')
    ->select('status')
        ->label('Status:')
        ->options(['' => 'All', 'active' => 'Active', 'inactive' => 'Inactive'])
        ->layout('inline')
    ->search('search')
        ->placeholder('Search users...')
        ->layout('full-width');

$table = TableBuilder::create($userModel, 'idTableUsers')
    ->filter('role', function($query, $value) {
        if ($value !== 'all') {
            $query->where('role = ?', [$value]);
        }
    }, 'all')
    ->filter('status', function($query, $value) {
        if (!empty($value)) {
            $query->where('status = ?', [$value]);
        }
    }, '');

Important Notes

Related Documentation

• TableBuilder Documentation
• Row Actions Documentation
• Bulk Actions Documentation