Data Source

Select the data source

Creating a New Table

After installation, you would notice a new Tables item has been added to the sidebar navigation menu:

Click on the item and the click on the "New Table" Button on the top-right corner:

Input your table name (handle is automatically deduced from name, but you can change it):

Now, let's select a data source for our table. Available data sources include:

  • Entry -> Section -> Entry Type

  • Category -> Category Group

  • Tag -> Tag Group

  • Asset -> Asset Volume

  • User -> User Groups (or All Users)

  • Product -> Product Type (When Craft eCommerce is installed)

Select the data source:

Narrow down the selection based on the data source selected:

Client vs Server Table

Lastly, before continuing to columns definition, you can select whether the data is loaded in its entirety to the browser on initial load (= Client Table), or only the data that is displayed on the current page (= Server Table). In the latter case, every interaction with the table (except for row selection) will send an AJAX request to fetch the relevant data. Use Server Table if you have a very large dataset that cannot be loaded to the browser without affecting performance or crashing the browser altogether. Otherwise stick with the "smarter" Client Table, which does everything in the front end. You can switch between a Client and Server table at any time (e.g if you started with a small dataset that grew over time):

When using the server table and filtering multiple list or relations columns (e.g checkboxes or categories) you will need to add the field to Craft's search index for filtering to work. Go to the field definition and check "Use this field’s values as search keywords".

Click "Save and Continue" to save the table draft and move on to columns selection:

Once you save the data source it cannot be altered. Create a new table if you require a different data source

Structure Strategy

Structure (nested) types refer to:

  1. An Entry with a Structure entry type

  2. A Category

When selecting one of the above, you will be presented with an option to control how structure data is handled:

The first two options are essentially the same, i.e they both load all records in a flat level (similar to a Channel type). The only difference is that the second option applies a visual indentation to represent the different levels, when no sorting is applied (this is exactly how Craft handles the Structure index page in the Control Panel). See example below:

The third option, Load data in a nested structure, loads the data as a nested array that mirrors the structure. Each parent row (that is not "childless") will have a children property, that will contain the child rows recursively until the max level.

This translates to only the root rows (level 1) being displayed by default. In order to display the children (or more precisely the descendants), you would need to add a child row and render the content there. This is assuming you are using the Default template. If you are building a custom template you can apply the rendering logic there.

The server table does not support nested structures at the moment. Therefore, the plugin will not allow saving a combination of Server Table + Nesting Strategy

Products and Variants

If you are using Craft eCommerce and have selected a product type with multiple variants, you will get a choice of how to handle Variants fields:

  1. Nest: Each product has one row. Variants are nested under the row inside a variants property, which you can render on the table using a child row or specific field templates.

  2. Join: Each variant has one row. Product and variant are joined. All variant fields will have the variant__ prefix, and you will be able to select them on the Columns page, just like Product fields.

Last updated