Product support

Get help in the plugin support forum.


Why do I need this?

Are you often applying the same filters to your lists? Wouldn't it be easier to have a dedicated page that you could share with others that has all your filters (and more) already applied? With lenses, that's exactly what you get. Create backend pages with a custom query applied to your list. You can also modify the list columns if you wish.


  • Blends into OctoberCMS as if it were a native feature
  • Automatically uses the controller's default list configuration
  • Configurable like any other OctoberCMS controller behavior (List, Form, Relation, etc.)
  • Built with October - there are no external assets or dependencies

Compatible with OctoberCMS v2


List Lens Behavior is a controller modifier that adds lenses to a back-end page. The controller must also implement the List Controller Behavior.

In order to use the list lens behavior, you should add it to the $implement property of the controller class. Also, the $listLensConfig class property should be defined and its value should refer to the YAML file used for configuring the behavior options.

namespace Acme\Blog\Controllers;

class Categories extends \Backend\Classes\Controller
    public $implement = [

    public $listLensConfig = 'config_list_lens.yaml';

Configuring the Lenses

The configuration file referred in the $listLensConfig property is defined in YAML format. The file should be placed into the controller's views directory. Below is an example of a typical form behavior configuration file.

# ===================================
#  List Lens Behavior Config
# ===================================

listUrl: 'lovata/shopaholic/products'

        title: 'Best selling products'
        list: $/kpolicar/custom/models/product/columns.yaml

        title: 'New products'

The following fields are required in the form configuration file.

Field Description
listUrl url to the default list page
lenses a configuration array - valid fields are: title, list (optional). The key will be used as the path in the URL for the lens page

Open Lens Dropdown

In order to display a dropdown of all lenses that are available, you will need to make sure the configuration for the controller's list controller behavior is valid.

The List will need to have a filter widget (see Filtering the List). Once the list has a valid filter widget, the lenses dropdown will appear on the rightmost side. It is perfectly valid for the filter widget to contain an empty configuration, without any scopes defined.

Applying the query

After you've completed all the previous steps, you are now ready to begin writing the lens query. Once the lens page is opened, the behavior will run the same actions as it would on the default list page. It will not display any buttons above the list, as they are not relevant for the lens page. Additionally, it will call a method to the controller where you can make adjustments to the query builder.

The method that is called has the following format:

lens{name} # eg. lensBestSellingProducts

The name corresponds to what is defined as the key in the configuration. Below is an example of this method implementation.

class Products extends Backend\Classes\Controller
    public function lensActiveProducts($query)
        $query->where('active', true);

First version of BackendListLenses

Jul 17, 2021