Tables

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()}%");
    }
}

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'
];

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',
];

Actions

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

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']