Quick Filters are the links that appear in the right hand column of many Manage screens. These filters provide users with the convenient means of constraining the list on the page by virtually any criteria, unlike the standard mechanism in place for users to filter the list manually using the build in filter mechanism.

Each page is capable of having a unique set of filters defined for it. The value of the list_filters registry property is actually an array of pages, in which each page contains a list of filters associated with it. For example, the following code sample shows three different list filters being defined for the Manage Entries screen, Manage Comments screen and the Manage Tags screen respectively:

sub init_registry {
    my $plugin = shift;
    $plugin->registry({
        'applications' => {
            'cms'      => {
                list_filters   => {
                    entry => {
                        myfilter1 => sub { my_filter1(@_); }
                    },
                    comment => {
                        myfilter2 => sub { my_filter2(@_); }
                    },
                    tag => {
                        myfilter3 => sub { my_filter3(@_); }
                    },
                },
            },
        },
    });
}

Below is a list of all the screens for which list filters can be registered:

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

The Anatomy of a List Filter

Listed below is a simple list filter that will be listed on the Manage Entries screen. Following the code sample we will explain each of the registry properties and what they mean.

sub init_registry {
    my $plugin = shift;
    $plugin->registry({
        'applications' => {
            'cms'      => {
                list_filters   => {
                    entry => {   #1. the screen the filter will be listed on
                        my_filter => {  #2. the unique identifier for the filter
                            label => "My Filter",   #3. the display name of the filter
                            order   => 100,  #4. the sort order of the filter
                            handler => sub { #5. the filter handler
                                my ( $terms, $args ) = @_;
                                $terms->{status} = 2;
                            },
                        },
                    },
                },
            },
        },
    });
}

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

List Filter Handler

Each list filter is passed two parameters:

• A hash reference to the list of terms that will comprise the filter against the current object being viewed
• A hash reference of all the arguments used in viewing the contents of the current page

For example, an entry consists of the following properties:

• id
• blog_id
• status
• author_id
• allow_comments
• title
• excerpt
• text
• text_more
• convert_breaks
• topingurls
• pinged_urls
• allow_pings
• keywords
• tangent_cache
• basename
• atom_id
• authored_on
• week_number
• template_id
• category_id

Therefore to compose a filter handler for the entry page, or Manage Entries page, the following code will register a handler that will only show entries with a status of "2" (or Published), and a title of "Foo".

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

The ways in which a list can be constrained is limited only to the properties of the object being filtered.