How to add Templates (Presets) for List Tables

Templates (also called presets) are predefined table views that you can make available across your installation. Instead of configuring every column from scratch, users can pick a ready-made template as a starting point for a List Table and tweak it from there.

Templates are stored as JSON files on the file system. This makes them easy to ship with a plugin or theme, migrate between environments, and keep under version control (VCS) so you can share them with your fellow developers. Adding templates is done with a single custom hook.

A common reason to use templates is when you manage multiple sites that should start from the same columns. Instead of rebuilding the same column set on every site, you register it once as a template and reuse it everywhere as a starting point.

Quick start

1. In the column settings screen, configure a List Table the way you want it and export the column set to JSON from the Tools tab. Repeat for every template you want to offer (one .json  file each).
2. Place the JSON files in a folder you control, for example a templates folder inside your plugin or theme.
3. Register the files with the acp/storage/template/files filter (see Loading the template files).
4. The templates now appear under Table Views: click + Add View and select your template in the Settings selector to use it as a starting point.

The sections below explain each step and the hook in more detail.

Templates or File Storage?

Templates and File Storage both let you store column settings in files, but they serve a different purpose.

Use templates when you want a reusable starting point. A template provides a base column set that a user applies while creating a new column set, and which they can freely adjust afterward. The columns are not locked. The template is just a convenient way to avoid starting from a blank slate, which is ideal for sharing the same baseline across multiple sites.

Use File Storage when you want fixed columns. File Storage is meant for column settings that should be loaded as-is, typically read-only, or for storing your settings in version control (Git) and migrating them between environments. In that scenario, the columns are managed through files rather than configured per site.

In short: reach for templates when users still need to customize, and for File Storage when the columns should stay fixed. See How to setup File Storage for the latter.

The hook

Templates are registered through the acp/storage/template/files filter. The filter receives an array of absolute paths to JSON template files and expects that array back, with your own files merged in.

Creating a template file

A template is a single .json   file that contains the settings for one column set.

To create one, configure a List Table exactly the way you want it in the column settings screen, and then export that column set to JSON. Each template is a separate file, so you export every column set you want to offer individually, one .json   file per template.

Once you have your JSON files, place them in the location where you want to load them from, for example a templates   folder inside your plugin or theme, and register that location through the hook (see below).

Loading the template files

Add each file to the stack by pointing to the absolute path of every .json   file you want to register:

Once this hook is loaded, the registered templates become available in the column settings screen for the matching List Tables.

Using a template

After the hook is loaded, the registered templates become available when you create a new view in the Table Views panel.

1. In the Table Views panel, click + Add View. The Table View dialog opens.
2. Enter a label for the new view.
3. Under Settings, open the selector ("Select settings from an existing view or template") and choose your template.
4. Click Create. The new view starts from the template's columns, which you can adjust and save like any other view.