ARCHIVE: Arguments

Last updated March 26, 2011. Created by Darren Oh on November 24, 2006.
Edited by linclark, webchick, Bèr Kessels, Senpai. Log in to edit this page.

Arguments act a lot like SQL fields, sorts and filters, except that they aren't specifically associated with a table; they are generally their own entities. They provide handlers that react to additions in the URL, and can also be passed through as arguments via views_build_view().

Like tables, Arguments are defined via a hook, though they get their own hook. Like fields, sorts and filters, Arguments are implemented via handlers, although they have only one handler which uses an option statement to determine what it will do.

Arguments have to tell Views how to behave when the argument is present, and they also have to tell Views the necessary information to generate a Summary View, which is a special, limited view that can be displayed when the argument is missing. The summary view displays links to all possible views that an argument can generate.

The argument hook

To provide arguments, your module must implement hook_views_arguments() which returns an array of argument arrays. You can provide as many arguments as you like. As usual, the key to each argument must be unique, thus it is recommended that you tag the key with your module name to protect namespace.

Each argument consists of the following data:

name (Required)

As with fields, sorts and filters, this is the visible name of the argument that the views administrator will select. It should be tagged in order to keep it identifiable.

help (Required)

As with fields, sorts and filters this is help text that appears with the argument, and should describe how the argument functions.

handler (Required)

This is a string containing the name of the handler function that will implement this argument.

option (Optional)

This is a standard option field that can be used to give choices to the argument.

The argument handler

The argument handler must have this signature:

$op = 'summary'

$a1 is the argument type (the key to the array that defines the argument), and $a2 is the option the user selected, if applicable.

The handler must create the summary query, which requires adding the right fields and filters to the $query object and returning an array of information that tells Views how to interpret the summary query results. If needs to perform a $query->add_field() on any fields that will be used to display the summary.

The $fieldinfo object needs to contain:

• field: The name of the field to group on. This should be the same field that will become the argument of the query, and is used to count the number of records that will be associated with the argument. If it is a simple field it should be in the form of 'table.field'.
• fieldname: If the 'field' above is not a simple field, this must contain an alias for the field that will be used to identify it. If fieldname appears, the 'field' mentioned above will automatically be added to the query. However, if it does not, you are responsible for adding it.

$op = 'sort'

$a1 is the sort direction; either ASC or DESC.

$a2 is unused.

The handler must apply the proper sorting to the summary view. This handler will not always be called, as the user may select a type of summary view that is not sorted.

$op = 'link'

$query is not the query object in this case; it is actually the raw data object returned from the query for this record in the summary view.

$a1 is the argument type.

$a2 is the base of the URL, which is usually the URL of the summary view.

During a summary view, this operation is called to provide a link to the view with that argument for each result. This should be run through l().

$op = 'filter'

$a1 is the full database information of the argument (including the 'options').

$a2 is the actual arg from the URL.

The handler must apply a filter for the given argument.

$op = 'title'

$query is not the query object in this case; it is actually the raw argument used.

$a1 is the argument type.

$a2 is unused.

When creating a view that uses an argument, or a breadcrumb based on an argument, this operation returns a substitution value for the title, as explained in Views Arguments. This is often used to translate values into a human-readable form.