Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation / Developer Applications

Quick Filters

Quick Filters

Quick Filters are the links that appear in the right hand column of any and all listing screens. These filters provide users with the convenient means of constraining the list on the page by virtually any criteria. When you register a quick filter, you register a name and a handler for it. The handler is responsible for modifying the query terms and arguments that control how the query that generates the list of objects is constrained and sorted.

Sample config.yaml File

 1 name: Example Plugin for Movable Type
 2 id: Example
 3 description: This plugin is an example plugin for Movable Type.
 4 version: 1.0
 5 applications:
 6     list_filters:
 7         entry:
 8             myfilter1: 
 9                 label: "My Filter"
10                 order: 1
11                 handler: $Example::Example::Plugin::myfilter1

On line 7 you see the phrase “entry” which refers to the listing screen you wish to target. A list of listing screens or tables you can target list actions for has been provided below.

On line 8 you see the unique ID or key the developer has assigned to the quick filter. It is not used directly by Movable Type.

List Filter Properties

  • label - the display name of the filter
  • order - the sort order of the filter when other filters are present on the page
  • handler - a subroutine which takes as input a hash reference to the list of filter terms, and a hash reference to a list of args used in rendering the current page

Lists You Can Target

  • asset - Manage Assets screen
  • comment - Manage Comments screen
  • entry - Manage Entries and Manage Pages screen
  • ping- Manage TrackBacks screen
  • template - List Templates screen
  • tag - Manage Tags screenthe
  • sys_user - Manage Users screen (system wide)
  • user - Manage Users screen (blog specific)

List Filter Handlers

Now that you have registered your list filter, you need to implement the handler that is responsible for making modifications to the terms and arguments used in the query that generates the listing screen in question. Let’s take a look at the following very basic handler, and then discuss what it is doing:

sub my_filter {
    my ( $terms, $args ) = @_;
    $terms->{status} = 2;
}

Each list filter, like the one in the sample above, is passed two parameters:

  • A hash reference to the list of terms that will be used to filter the list of objects currently being viewed.

  • A hash reference of the arguments used in viewing the contents of the current page. These arguments can control how the list is sorted and in what direction (ascending and descending order for example).

Within a filter handler, developers can modify the contents of the query terms and search arguments passed to them. Let’s look at a concrete example. Suppose we wanted to create a list filter for entries that only displayed those entries with a status of published, and a title of “Movable Type.” In our filter handler, we then set those two properties accordingly:

sub my_filter { 
    my ( $terms, $args ) = @_;
    $terms->{status} = 2;
    $terms->{title} = "Movable Type";
}

The terms you can filter by correspond to the property names of the object being filtered. Consult the documentation for the specific object you are filtering by for a complete list of properties and their names.

Back