Tables part 5: Filters

Filters are added to the table an array of fields using the 'filters' key. The key for each field in the array should be the database name of the field, but like sorts and fields, it doesn't have to be. If it isn't, you should set 'field' => 'actual_field_name', unless your filter has its own handler.

Example:

Filter settings

The following items may be added to the definition of a filter.

name (Required)

This is the name displayed for the field on the admin UI. It is customary to tag your this with something recognizable as your module. For example, Node: ID or Taxonomy: Term. This should always be wrapped in a t().

help (Required)

This contains help text for the field, which should tell the user how to utilize the field. This should be wrapped with t() for translation. This should always appear, even if it just contains a few words describing the field.

field (Optional)

This is the 'real' name of the field that is being operated on. This can be useful if you have several instances of a field that are used entirely differently, and not simply as handlers.

operator (Required)

May be a string which points to a function which takes no arguments and returns an array of operators, or may be an array of allowed operators. (=, !=, LIKE, etc). In the case of a LIST, only AND, OR and NOR have any meaning. There are several functions in Views that provide typical operators, such as views_handler_operator_andor

list (Deprecated)

This may be an array of possible values; it is preferred that the 'value' field is used instead, with a proper forms API array. This setting will disappear in Views 2.0.

list-type (Deprecated)

If 'list' is used, this should be be set to 'select' or 'list'; defaults to 'list'. 'list' indicates multi-select capability, whereas select is just one.

value (Required)

This must be a forms API array. Technically this is optional, but either 'list' or 'value' is required in filters. If neither is present, 'value' will be set to a textfield Forms API array. If the formsAPI array is of type 'select', and the '#options' field is a string, that string will be assumed to be a handler which will be called to return the list of options available, which is useful to prevent the options from being cached.

value-type (Optional)

Set this to 'array' if the 'value' form object can return a multi-select. Views will try to intelligently deal with arrays. Note that arrays have a limited set of usable operators (mostly the and/or/nor variety).

cacheable (Optional)

Whether or not the filter is cacheable. Defaults to TRUE; set this to 'no' if the handler requires some run-time data that would cause the query to break if it is cached.

handler (Optional)

A handler that allows the filter to modify the query, and perform the $query->add_where option. If the handler is not specified, Views simply performs a $query->add_where("$field $operator $value"). If the handler is present the preceding operation is not performed and you MUST provide the add_where.

function views_filter_handler($op, $filterdata, $filterinfo, &$query)

Modify the $query object when a particular field is part of the query's filters. Ordinarily this handler will call $query->add_where().

Parameters

$filterdata The information on the field from the database. See below for more information.

$filterinfo The array from the $tables data for this particular field. It will contain the information from this very list.

&$query The query object to modify.

Return value

None

validate (Optional)

A handler to validate from the UI to ensure the data makes sense.

function views_field_validator($fielddata, $view, $form)

Validate that settings on a field are within the boundaries of reason.

Parameters

$fielddata The information on the field from the database. Note that this is the unmodified version; it may be mostly blank if the view does not exist, but the 'id' from this will be necessary to find the part of the form to validate.

$view The array from the $tables data for this particular field. It will contain the information from this very list.

$form The full form array to validate. TODO: tell how to find the information in the $form array to actually validate.

Return value

None. If the data is not valid, use form_error($form[...], 'message') to fail the validation process.

option (Optional)

Setting this field will require an additional form item to appear for this field in the UI. If this is set to 'string' or 'integer' a simple textfield will appear, but this may also be complete formAPI array (such as for choosing an option from an array). See more on options below.

[arbitrary] (Optional)

Some handlers might need extra data, and they can set arbitrary names here. Views commonly uses things such as 'uid', for example, to tell the handler what the name of the uid field in that particular table is. Any data placed here will be available in all of the handlers as part of the $filterinfo array.

Filter data

The $fielddata array is passed to field handlers. It is loaded from the database, and represents a single field on a view.

vid Database

Loaded from the database, this field simply matches the record to the view it belongs to. Should not be used.

tablename Database

The table this field belongs to.

field Database

The name of the field, from the key of the array -- this may be a pseudo-field, not necessarily the real name of the field.

operator Database

The operator as selected by the view admin user.

value Database

The value as selected by the view admin user. If 'value-type' => 'array' or 'list-type' => 'list' this will be an array. If the handler and value in the $filterinfo table support it, this could be a serialized string.

options Database

A stored representation of the options. If the option was set to string/integer it will simply be the value; if set to a forms api array it will be whatever value that returned. Complex forms API arrays may return serialized data here, but this is rare.

position Database

The order of the field, starting from 0.

id

A 'unique' representation of the field so Views can find it. This is usually in the form of 'table.field'.

Common handlers

function views_handler_operator_andor()

Returns an array of standard and/or/nor operators.

function views_handler_operator_or()

Returns an array of or/nor operators, but does not include AND.

function views_handler_operator_eqneq()

Returns an array of simple equality (equal/not equal to) operators.

function views_handler_operator_gtlt()

Returns an array of the typical numeric =/> operators

function views_handler_operator_yesno()

Returns yes/no values. (This is misnamed as an operator).

function views_handler_operator_like()

Returns an array of the typical string operators.

function views_handler_filter_like($op, $filter, $filterinfo, &$query)

A filter handler to handle the string operators.

function views_handler_filter_timestamp($op, $filter, $filterinfo, &$query)

Returns a 'value' array for timestamps that can pop up a timestamp chooser.

function views_handler_filter_date_value_form()

A handler for the timestamp value above; supports 'from_unixtime' as an arbitrary $filterinfo key -- if true, will transform the date from a standard unix date into a database date.