List Filters

Advanced filters for page lists

List Filters adds advanced filtering options for page lists to Cotonti. A list of available filter types is below. A demo is here.

Note: At the moment this plugin works only with the latest revision of Siena available on Github. This is because I had to fix something in order to get it to work.

#1. Installation

Simply install the plugin through the admin panel as you would with any other plugin. No configuration is required, just add the filters to your page.list.tpl file. Implementation details are below. You may modify the plugin rights to disable it for certain groups, by default all guests and members can use it.

#2. Filter types

  • eq Equals (page_$field = $value) Value can be any string or number.
  • ne Not Equal (page_$field != $value) Value can be any string or number.
  • lt Less Than (page_$field < $value) Value must be numeric.
  • lte Less Than or Equal (page_$field <= $value) Value must be numeric.
  • gt Greater Than (page_$field > $value) Value must be numeric.
  • gte Greater Than or Equal (page_$field >= $value) Value must be numeric.
  • in SQL IN operator (page_$field IN ($value1, $value2, $value3)) Values must be comma seperated.
  • rng SQL BETWEEN operator (page_$field BETWEEN $value1 AND $value2) Values must be seperated with two periods (1..2). Strings are supported.

#3. Implementation

Implementation of List Filters is a matter of modifying your page.list.tpl to include the filters. There are two ways in which you can display the filters: as plain text links or as a form. Which you choose depends on your use case. More complex filtering systems are easier implemented using forms, while plain links are more user friendly and quicker because there's no need to submit a form. The plugin provides helper functions for both implementation methods.

#3.1. Using links

For links the plugin provides the helper function listfilterurl(). This function takes three arguments and will return a URL to the list with the correct parameters for the filter. The arguments are filter type (see above), field name (database column name without 'page') and the value to apply. An example:

listfilter_url('eq', 'exttype', 'modules')

Assuming we're displaying the 'extensions' category, this will return:

index.php?e=page&c=extensions&filters[eq][exttype]=modules

It's also possible to leave out the last argument (the value). This will return a URL for the current list without this filter, effectively disabling it. Any other filters will still be included in the link. Since the function uses cot_url() you can rewrite it to look more appealing.

Another function that is convenient is listfilter_active() which returns TRUE or FALSE depending on whether or not the filter is currently active. It takes the exact same arguments as listfilter_url().

Here's a complete example that uses these functions as CoTemplate callbacks:

<li><a href="{PHP|listfilter_url('eq', 'exttype')}"<!-- IF {PHP|listfilter_active('eq', 'exttype')} --> class="selected"<!-- ENDIF -->>{PHP.L.All}</a></li>
<li><a href="{PHP|listfilter_url('eq', 'exttype', 'modules')}"<!-- IF {PHP|listfilter_active('eq', 'exttype', 'modules')} --> class="selected"<!-- ENDIF -->>{PHP.L.Modules}</a></li>
<li><a href="{PHP|listfilter_url('eq', 'exttype', 'plugins')}"<!-- IF {PHP|listfilter_active('eq', 'exttype', 'plugins')} --> class="selected"<!-- ENDIF -->>{PHP.L.Plugins}</a></li>

As you see this filter has three options: All, Modules and Plugins. In this case 'All' simply disables the filter. It's not a requirement to include a 'disable' link, because clicking an active filter will disable it too (like a toggle switch).

#3.2. Using a form

An alternative to using plain text links is to use a form. This can be more convenient in complex situations, however it does have a major drawback. If you use a form you will lose the ability to rewrite the filters part of the URL, instead the filters will be appended. To simplify creating the form, the plugin provides several helper functions for generating form elements. These functions are effectively wrappers for the functions included in the Cotonti Forms API (system/forms.php). They return complete HTML form fields. Provided functions are:

  • listfilter_form_checkbox($type, $field, $value, $default = 0, $title = NULL)
  • listfilter_form_inputbox($type, $field, $default = '')
  • listfilter_form_numberbox($type, $field, $min, $max, $step = 1, $default = NULL)
  • listfilter_form_radiobox($type, $field, $options, $default = '', $titles = NULL)
  • listfilter_form_rangebox($type, $field, $min, $max, $step = 1, $default = NULL)
  • listfilter_form_selectbox($type, $field, $options, $default = '', $titles = NULL)

Here's the arguments explained:

  • $type (string) One of the filter types listed above.
  • $field (string) Field name without 'page_' prefix.
  • $value (string) Value which the filter will check for.
  • $title (string) Text that will be displayed as a label (optional, defaults to $value).
  • $default (string) Default text to display in the input field (optional) or value that is selected by default or in case of a checkbox: 0 (not checked) or 1 (checked).
  • $min (float) Minimum allowed value
  • $max (float) Maximum allowed value
  • $step (float) Allowed number interval (optional, defaults to 1)
  • $options (string) Comma-separated list of options.
  • $titles (string) Comma-separated list of titles (optional, defaults to $values).

Your form should point to the current list URL and use GET as method:

<form action="{PHP|listfilters_plainurl()}" method="GET">

#3.3. Other helpers

listfilter_urlparam()

Returns the URL query parameter for all currently active filters. Example:

filters[eq][a]=b&filters[eq][c]=d&filters[ne][e]=f

listfilter_plainurl()

Returns the current URL without filters.

 


1. Kort  2011-11-18 05:54

Well done! Nice and longawaited addition to the plugins section.

2. GHengeveld  2011-11-20 15:34

I've added another helper: listfilter_count($type, $field, $value = null).

This will return the number of pages shown if the filter were active.

The latest version will also fix the value of LIST_ROWCAT_COUNT in page.list.tpl.

3. Dayver  2012-01-29 00:38

In text have error in <form action="{PHP|listfilterS_plainurl()}" method="GET">

4. staleo  2012-02-23 21:05

Did anybody try to inplement any modRewrite rules to replace these ugly urls (like here) with the seo-friendly ones?

5. Stam  2012-03-20 13:41

Excellent work Gert! Thank you :) 

6. diablo  2012-05-08 13:51

this is so awesome!

7. Chiaroscuro  2017-11-27 13:05

С ссылками все понятно, более разверннуто написать для работы с формами, спасибо многие скажут я думаю.

8. Chiaroscuro  2017-11-27 13:16

ААА все понятно есть функции, вызов в шаблонах {PHP{listfilter_form_...}

Only registered users can post new comments