menu-btn

List Columns

List Columns

Learn how to define columns in a list structure.

List Columns are column definitions used by lists. These are referred to by the following areas.

All list columns are identified as their individual type property.

columns:
    mycolumn:
        type: number
        # ...

# Available Columns

The following list columns are available:

Text Number Image Switch Summary Date & Time Selectable Linkage Partial Color Picker

# Column Properties

For each column can specify these properties (where applicable):

Property Description
label a name when displaying the list column to the user.
type defines how this column should be rendered.
default specifies the default value for the column if value is empty.
searchable include this column in the list search results. Default: false.
invisible specifies if this column is hidden by default. Default: false.
sortable specifies if this column can be sorted. Default: true.
sortableDefault specifies if this column is sorted by default. This should only be used on a single sortable column. Supported values: asc, desc.
clickable if set to false, disables the default click behavior when the column is clicked. Default: true.
select defines a custom SQL select statement to use for the value.
valueFrom defines a model attribute to use for the source value.
displayFrom defines a model attribute to use for the display value.
relation defines a model relationship column.
relationCount display the number of related records as the column value. Must be used with the relation option. Default: false
relationWith eager load the specified relation definition with the list query. Useful to improve performance of nested column selections.
cssClass assigns a CSS class to the column container.
headCssClass assigns a CSS class to the column header container.
width sets the column width, can be specified in percents (10%) or pixels (50px). There could be a single column without width specified, it will be stretched to take the available space.
align specifies the column alignment. Possible values are left, right and center.
permissions the permissions that the current backend user must have in order for the column to be used. Supports either a string for a single permission or an array of permissions of which only one is needed to grant access.
order a numerical weight when determining the display order, default value increments at 100 points per column.
after place this column after another existing column name using the display order (+1).
before place this column before another existing column name using the display order (-1).
tooltip adds an icon with a tooltip after the column label. See below for more detailed settings.

# Custom Value Selection

It is possible to change the source and display values for each column. If you want to source the column value from another column, do so with the valueFrom option.

other_name:
    label: Something Great
    valueFrom: name

If you want to keep the source column value but display a different value from the model attribute, use the displayFrom option.

status_code:
    label: Status
    displayFrom: status_label

This is mostly applicable when a model accessor is used to modify the display value. This is useful where you want to display a certain value, but sort and search by a different value.

public function getStatusLabelAttribute()
{
    return title_case($this->status_code);
}

# Nested Column Selection

In some cases it makes sense to retrieve a column value from a nested data structure, such as a model relationship column or a jsonable array. The following example would look for the value in PHP equivalent of $record->content->title or $record->content['title'] respectively.

content[title]:
    name: Title
    sortable: false

The only drawback of doing this is the column cannot use searchable or sortable options. To make the column searchable, and for performance reasons, we recommend duplicating its value on the local database table using model events. Alternatively, you can use the relation property described further below.

# Direct SQL Selection

The select property allows you to create a column using a custom select statement. Any valid SQL SELECT statement works here.

full_name:
    label: Full Name
    select: concat(first_name, ' ', last_name)

The relation property allows you to display related columns as part of the database query, allowing for searching and sorting of that column. The relation is set to the name of the model relationship. In the next example the name value will be translated to the name attribute found in the related model (eg: $model->name).

group_name:
    label: Group
    relation: groups
    select: name

To display a column that shows the number of related records, use the relationCount property.

users_count:
    label: Users
    type: number
    relation: users
    relationCount: true

Be careful not to name relations the same as existing database columns. For example, using a name group_id could break the group relation due to a naming conflict.

# Tooltip

The tooltip property enhances list columns by adding an informational icon in the column header. Hovering over this icon displays a tooltip, offering additional context or details about the column. This feature aids in providing users with guidance or clarification for understanding column content.

count:
    label: Count
    type: number
    tooltip: Number of users in the group

In addition to providing a tooltip title, you can also specify the icon (available icons) and the placement (right, bottom, left, default value is top) of the tooltip.

count:
    label: Count
    type: number
    tooltip:
        title: Number of users in the group
        placement: bottom
        icon: icon-users

← Filter Scopes →