Properties & methods

The Table definition describes how the table is rendered, how dataTables should handle it and how the data that the AJAX requests send back should be formatted.

It's the heart of this package and unique for every table you want to render.

Here's the general workflow:

1. Generate a new definition
2. Make the needed tweaks, if necessary
3. Add it in app/Http/Kernel.php to its $tables property
4. Load the table definition in your controller and render it in a view

Properties

All of these properties get set automatically, if left untouched. But you're free to change that of course.

Routing

protected $kernel_identifier

All table definitions are registered in App\Http\Kernel::$tables, this is an array that consists of a key (kernel identifier) and a value (that namespaced class).

This property stores the key that this Table definition is assigned to.

The $kernel_identifier gets passed to the AJAX route, so it knows which table to load the data for when making requests.

If you leave it at null it will be filled with the model's name.

protected $route

This property stores the name of the route that is used for AJAX requests for this specific Table definition.

If you leave this as false, the global route will be used.

Data loading

public data()

This is the function where you would define your data source, it should return:

• an Eloquent model
• a result of DB::table()

public $relationships

If you need to load relations for your select statements you can define them here.
They get loaded just as Eloquent's with() would load them.

I would only load BelongsTo and hasOne relations.

It will contain relations you load through your field definitions.

PHP

    public $relationships = [
       'role'
    ];

It's only possible to make use of this feature when using Eloquent models

protected $select

The $select property is used by the definition to store column select statements, to limit the columns that are loaded when querying the database during AJAX requests.

It gets filled with statements by the fields you define. This might be useful if you have the need to load extra database columns that you don't necessarily want to display in your table, but need for formatting data.

It's best practice to prefix columns you add in here with a table name. If you prefix it with (:table), then the model's table will be used.

PHP

    protected $select = [
        '(:table).username AS username',
        'roles.name AS role_name'
    ];

HTML

public $js_var

As the name implies this is the name of the javascript variable to which the dataTable object gets assigned.

If you leave this empty it will be filled with a studley case version of your $kernel_identifier, prefixed with 'table'.

PHP

    public $js_var = 'tableUsers';

public $html_id

The value of this property will be used as your <table> tag's ìd.

If you leave this empty it will be filled with a dashed snake case version of your $kernel_identifier, prefixed with 'table-';

Methods

Row manipulation

DataTables allows you set all kinds of data when rendering table rows.

📘

The following methods are helpers, each method gets a parameter assigned that contains the data for the row it get's called for.

protected function row_format_id($row)

This method let's you set an id on the <tr>.

By default it will return $this->html_id . '-row-' . $row->id, you can change that by defining your own method in your definition:

PHP

/**
     * Return the 'id' attribute for every single row's TR in the table.
     *
     * ! Overwrite if needed.
     *
     * @param $row
     *
     * @return string
     */
    protected function row_format_id($row)
    {
        return $this->html_id . '-row-' . $row->id;
    }

protected function row_attributes($row)

This method allows you to add extra HTML attributes to the specific <tr>.

It returns an array where the key would be the name of the attribute and the value its content.

By default it does not send any extra attributes.

PHP

/**
     * Return extra attributes that should be added to a single row's TR in the table.
     *
     * ! Overwrite if needed.
     *
     * @param $row
     *
     * @return array
     */
    protected function row_attributes($row)
    {
        return ['colspan' => '2'];
    }

protected function row_data_attributes($row)

This method allows you to assign data-attributes to the specific row.

It should return an array, each key would be the name of the data attribute.
By default no data attributes get returned.

PHP

/**
     * Return data attributes that should be added to a single row's TR in the table.
     *
     * ! Overwrite if needed.
     *
     * @param $row
     *
     * @return array
     */
    protected function row_data_attributes($row)
    {
        return [];
    }

protected function row_class($row)

Lastly you can assign a class to each row with this method.

It should return a string with a class name(s).

By default it returns no class name.

PHP

/**
     * Return class name(s) that should be added to a single row's TR in the table.
     *
     * ! Overwrite if needed.
     *
     * @param $row
     *
     * @return string|array
     */
    protected function row_class($row)
    {
        return 'bg-info';
    }

Setting dataTable options

DataTables allows you to set a lot of options when initialising an instance.

Out of the box DragonFly\Lists only sets a few:

• serverSide
• processing
• ajax & data
• columns & columnDefs
• ordering

You're free to set any or all of the other options available in your setup() method, or when when you load your table to generate the HTML.

There's a little bit of magic going on with those options, in order to set these options you call a method on the Table object that starts with 'set' and then the name of the option you want to set. That method takes 1 argument, which will be the value of the option you want to set.

PHP

public function setup() {
    // Let's disable pagination
    $this->setPaging(false);
    
    // Let's also set up default ordering (the second column descending)
    $this->setOrder([[1, 'desc']]);
}