Tables

Tables let you easily display a table of stream entries. They can also be used without streams using regular Eloquent models or without any database backend at all by manually loading entries.

Builders

Table builders are the entry point for creating a table. All tables will use a builder to convert your basic component definitions into their respective classes.

Basic Usage

To get started building a table. First create a TableBuilder that extends the \Anomaly\Streams\Platform\Ui\Table\TableBuilder class.

When using the make:stream command table builders are created for you. A generated table builder looks like this:

<?php namespace Example\TestModule\Test\Table;

use Anomaly\Streams\Platform\Ui\Table\TableBuilder;

class TestTableBuilder extends TableBuilder
{

    /**
     * The table views.
     *
     * @var array|string
     */
    protected $views = [];

    /**
     * The table filters.
     *
     * @var array|string
     */
    protected $filters = [];

    /**
     * The table columns.
     *
     * @var array|string
     */
    protected $columns = [];

    /**
     * The table buttons.
     *
     * @var array|string
     */
    protected $buttons = [
        'edit'
    ];

    /**
     * The table actions.
     *
     * @var array|string
     */
    protected $actions = [
        'delete'
    ];

    /**
     * The table options.
     *
     * @var array
     */
    protected $options = [];

    /**
     * The table assets.
     *
     * @var array
     */
    protected $assets = [];
}
TableBuilder::$filters

Table filters let you easily define inputs that filter the results of the table.

Example

protected $filters = [
    'title',
    'category',
    'description',
];
TableBuilder::$columns

Table columns are the basic building block of the table.

Example

protected $columns = [
    'title',
    'category',
    'description',
];
TableBuilder::$buttons

Table buttons display in the last column of each row.

Example

protected $buttons = [
    'edit',
    'view',
];
TableBuilder::$actions

Table actions let you define submittable buttons that perform an action on the selected rows.

Example

protected $actions = [
    'delete',
];
Ajax Tables

You can easily make tables use ajax behavior by setting the $ajax property.

protected $ajax = true;

You can also mark tables ajax on the fly.

$builder->setAjax(true);

Ajax tables are designed to be included in a modal by default but you can configure it to display like a normal table or however you like.

Table Models

Table models are used to determine the table repository to use and provide the model for the system to use when creating and updating an entry.

Table models are guessed based on the table builders position first. If using php artisan make:stream the model does not need to be set.

If an entry object is set the model will be pulled off of that next.

Lastly if you would like to or need to define a model yourself you can do so on the table builder.

protected $model = UserModel::class;
Table Repositories

Table repositories are used to create an entry when creating and to update an entry when editing. The repository is guessed based on the type of model used.

If you would like to or need to define a repository yourself you can do so on the table builder.

protected $repository = FancyTableRepository::class;

The table repository must implement \Anomaly\Streams\Platform\Ui\Table\Contract\TableRepositoryInterface and implement the following methods:

/**
 * Get the table entries.
 *
 * @param  TableBuilder $builder
 * @return Collection
 */
public function get(TableBuilder $builder);
Including Assets

Besides the obvious overriding views to include your own assets you can also specify assets to include with the $assets array.

Specify the assets to include per the collection they should be added to.

protected $assets = [
    'scripts.js' => [
        'theme::js/tables/initialize.js',
        'theme::js/tables/validation.js',
    ],
    'styles.css' => [
        'theme::scss/tables/validation.scss',
    ]
];

Filters

Filter definitions display filters to help find entry sets.

Defining Filters

You can also define filters manually.

protected $filters = [
    'title' => [
        'type' => 'text',
        'query' => \Example\Test\FilterQuery::class, // Assumes @handle
    ],
];
Using Field Filters

To specify filters from the entry stream being used simply define the filters by the field slug:

protected $filters = [
    'title',
    'category',
    'description',
];
Custom Filter Queries

While the filter querying is generally handled 100% automatically. You can provide your own filtering logic as well:

protected $filters = [
    'title' => [
        'query' => \Example\Test\CustomQuery::class
    ],
];

The query class must accept the query Builder, Filter instance, and is called with the service container.

<?php namespace Example\Test;

use Anomaly\Streams\Platform\Ui\Table\Component\Filter\Contract\FilterInterface;

class CustomFilter
{

    /**
     * Handle the filter.
     *
     * @param Builder         $query
     * @param FilterInterface $filter
     */
    public function handle(Builder $query, FilterInterface $filter)
    {
        $query->where($filter->getSlug(), 'LIKE', "%{$filter->getValue()}%");
    }
}
**Pro Tip:** Even automated stream filters can be completely overridden. Try providing your own custom query!
The Filter Definition

Below is a list of all possible filter definition properties available.

Properties
Key Required Type Default Description

slug

true

string

The definition value/key.

The filter slug is used for naming the filter input and identifying it amongst other filters.

heading

false

string

The filter assignment name.

The filter label.

placeholder

false

string

The filter label.

The filter input placeholder.

filter

true

string

\Anomaly\Streams\Platform\Ui\Table\Component\Filter\Type\InputFilter

The filter class.

query

true

string

\Anomaly\Streams\Platform\Ui\Table\Component\Filter\Query\GenericFilterQuery

The custom filter class to use.

Columns

Column definitions are the primary building block of a table. If your table uses a stream model then most of the work can be automated for you. However you can also define columns 100% manually too.

The Column Definition

Below is a list of all possible column definition properties available.

Properties
Key Required Type Default Description

value

true

string

none

The valuated string for the coumn text value. You can pass an array of values and merge them into the wrapper too.

slug

false

string

The definition key

The column slug is used for naming the column input and identifying it amongst other columns.

heading

false

string

The column assignment name.

The column label.

column

false

string

\Anomaly\Streams\Platform\Ui\Table\Component\Column\Column

The custom column class to use.

wrapper

false

string

{value}

The column value wrapper.

view

false

string

null

The view to delegate the column to.

class

false

string

null

The column class. Includes the heading row.

Defining Manual Columns

You can also define columns manually. Take a look at how the FileTableBuilder does it.

protected $columns = [
    'entry.preview' => [
        'heading' => 'anomaly.module.files::field.preview.name'
    ],
    'name'          => [
        'sort_column' => 'name',
        'wrapper'     => '
                <strong>{value.file}</strong>
                <br>
                <small class="text-muted">{value.disk}://{value.folder}/{value.file}</small>
                <br>
                <span>{value.size} {value.keywords}</span>',
        'value'       => [
            'file'     => 'entry.name',
            'folder'   => 'entry.folder.slug',
            'keywords' => 'entry.keywords.labels',
            'disk'     => 'entry.folder.disk.slug',
            'size'     => 'entry.size_label'
        ]
    ],
    'size'          => [
        'sort_column' => 'size',
        'value'       => 'entry.readable_size'
    ],
    'mime_type',
    'folder'
];
**Pro Tip:** Automated stream columns can be overridden too!
Using Stream Columns

To specify columns from the entry stream being used simply include the column slugs of the assigned columns.

protected $columns = [
    'title',
    'category',
    'description',
];

Just like other UI definitions you can override automation and defaults by including more intableation.

protected $columns = [
    'title' => [
        'heading' => 'Example Title'
    ],
    'category',
    'description',
];
**Note:** Tables using streams without defined columns will default to the title column (ID by default) only.

Actions

Actions determine available mass actions for the table when 1 or more rows are selected.

**Note:** Actions extend UI buttons so some actions may use registered buttons to further automate themselves.
The Action Definition

Below is a list of all action specific definition properties available. Since actions extend buttons please refer to UI button documentation for a complete set of options for buttons.

Properties
Key Required Type Default Description

slug

true

string

The definition key.

The action slug helps separate it from others.

permission

false

string

null

The required permission to view/execute the action.

handler

true

string

none

A callable class string or closure. The handler is passed an array of selected IDs from the table as well as the table builder itself.

The Action Registry

Below are the registered basic actions. Note the button options that will in turn automate more action properties. Actions may also simply be buttons and allow default handling behavior. So be sure to refer to the button registry for more options.

Registered actions can be found in Anomaly\Streams\Plattable\Ui\Table\Component\Action\ActionRegistry.

'delete'       => [
    'handler' => Delete::class
],
'prompt'       => [
    'handler' => Delete::class
],
'force_delete' => [
    'button'  => 'prompt',
    'handler' => ForceDelete::class,
    'text'    => 'streams::button.force_delete',
],
'export'       => [
    'button'  => 'info',
    'icon'    => 'download',
    'handler' => Export::class,
    'text'    => 'streams::button.export'
],
'edit'         => [
    'handler' => Edit::class
],
'reorder'      => [
    'handler' => Reorder::class,
    'text'    => 'streams::button.reorder',
    'icon'    => 'fa fa-sort-amount-asc',
    'class'   => 'reorder',
    'type'    => 'success'
]
Using Registered Actions

There are a number of actions registered in the Anomaly\Streams\Plattable\Ui\Table\Component\Action\ActionRegistry class. To use any of these actions simply include their string slug.

protected $actions = [
    'delete',
];

The full definition registered to the above actions is as follows.

protected $actions = [
    'delete' => [
        'handler' => \Anomaly\Streams\Platform\Ui\Table\Component\Action\Handler\Delete::class
    ],
];

After the delete button properties are merged in it looks like this:

protected $actions = [
    'delete' => [
        'icon'       => 'trash',
        'type'       => 'danger',
        'text'       => 'streams::button.delete',
        'attributes' => [
            'data-toggle'  => 'confirm',
            'data-message' => 'streams::message.confirm_delete',
        ],
        'handler' => \Anomaly\Streams\Platform\Ui\Table\Component\Action\Handler\Delete::class
    ],
];
Overriding Registered Actions

Just like other definitions either registered or automated, you can include more information in your definition to override things:

protected $actions = [
    'delete' => [
        'text' => 'Delete rows!'
    ],
];
The Action Handler

Below is an example of the action handler.

<?php namespace Example\Test;

use Anomaly\Streams\Platform\Ui\Table\Component\Action\ActionHandler;

class ExampleHandler extends ActionHandler
{

    public function handle(ExampleTableBuilder $builder, array $selected)
    {
        $model = $builder->getTableModel();

        foreach ($selected as $id) {

            $entry = $model->find($id);

            // Do something here
        }

        if ($selected) {
            $this->messages->success('Something amazing was done!');
        }
    }
}

Options

Table options help configure the behavior in general of the table. Anything from toggling specific UI on or off to adding a simple title and description can be done with the table options.

protected $options = [
    'title' => 'My awesome table!',
    'table_view' => 'module::my/custom/table'
];

You can also set/add options from the API.

$builder->addOption('title', 'Example Title');
Available Options

Below is a list of all available options for tables.

Options
Key Required Type Default Description

table_view

false

string

streams::table/table

The table view is the primary table layout view.

wrapper_view

false

string

streams::blank

The wrapper view is the admin layout wrapper. This is the view you would override if you wanted to include a sidebar with your table for example.

permission

false

string

{vendor}.module.{module}::{stream}.read

The permission string required to access the table.

no_results_message

false

string

No Results.

The text shown when not results are found.

order_by

false

array

null

Set the default ordering of the results. e.g ['created_at' => 'desc']