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 |
|
The filter class. |
query |
true |
string |
|
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 |
|
The custom column class to use. |
wrapper |
false |
string |
|
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 |