OUTDATED: Views Module Developer API

NOTE: This page is deprecated.
Please see http://drupal.org/handbook/modules/views/api for the current page.

To be documented:

• the extra element in views_tables is undocumented
• hook_views_query_substitutions
• style plugins may return $query and $countquery elements
• hook_views_pre_view: alter returned data before it is rendered
• hook_views_post_view: alter the output string after render

The most important aspect to the Views system is that any module can expose its tables to the Views module. It can select which fields can be sorted on, filtered on, and viewed in the table format. It can expose fields to be used as URL arguments to a view. And it can define default views which are exposed to the admin and may be overridden, modified or otherwise customized.

Hooks and Handlers

You have to tell Views about your tables using a hook. Views offers 3 hooks:

In addition, Views also supports handlers for a number of tasks, making it possible to customize the behavior of fields when being used. The handlers take various kinds of data, and some of them even allow direct access to the query building object. Care must be used to ensure that manipulating that object doesn't cause the query builder to write SQL that won't parse!

Exposing your tables

hook_views_tables() returns an array of tables the module provides. Here
is an example of this data:

The above code, pulled directly from the internal version of the views system, exposes the 'users' table to the system.

This field should be the name of the table.

The query generator needs to know how this table JOINs to the node table. One limitation of this system is that any table referenced must somehow join to the NODE table, *but it does not have to be direct*. More on this later.

The left side of the join is the table that is closest to the node table. In this case, it is the node table. The field entry tells the query builder which field in the left table will be used for this join.

The right side of the join is always the table in question. Only the field needs to be specified. The result will produce SQL "LEFT JOIN {$left['table']} ON $left['table'].$left['field'] = $table.$right['field']". Approximately.

The 'fields' array tells Views which fields are available to be used in the Table or List views. The 'name' is displayed in the select box during list administration, and should prominently identify which table or module is providing the field. It is also the default label in table view, but that can be overridden.

The 'handler' is a function or list of functions that tells the views system how to display the value. If left blank, the value will simply be displayed. In the case of a username, though, Drupal has a system to make the username a link based on whether or not the viewer has access to that user's profile. This handler transforms the data and returns that result. 'handler' may also be an array, providing a list of handlers. In that case, the admin chooses which handler to use.

This version of 'sortable' only means that the system will allow the viewer to click on the table header to re-sort the table by this field.

'addlfields' tells the views system that another field needs to be in the query for this. Any additional fields are only used by the provided handler.

This is not a known variable entry by the views system, but is a variable used by the handler; handlers have full access to whatever data is in this array.

The "sorts" definition provides a list of fields that will be provided to the admin for the ORDER BY clause. In this case, only one field is provided: The username. This example is slightly confusing. The first instance of "name" is actually the field to be sorted on. The second instance of "name" is telling the system what to display to the admin in the select box.

"filters" are, if you're keeping up with this, what the system can filter the query on. In the case above, the system can filter by the "uid". "name" is the display name. 'operator' is either an array of operators allowed in the WHERE clause (i.e, '=', '>', etc) OR it is a function, which returns a list of operators. However, if 'list' is true, (in which it is), the 'operator' has a slightly different meaning. It's a list which includes some or all of 'AND', 'OR', and 'NOR'. If 'AND', all selected items in the list must be present (which can only have meaning on things like taxonomy where a node can have more than one). If OR any of the selected items in the list can be present. And NOR will select nodes that have NONE of the selected items in the list.

The 'list' can either be an array of items, or it can be a handler which returns an array. In the above case, it actually returns an array of all users in the system.

If you've followed along so far, hopefully this one makes sense. Because "anon" isn't really a field, we use 'field' to tell the system what the field really is (uid is already used, above). The handler provides anonymous.

Similar to above, but a custom handler is required at query run time, because current user changes depending upon who is logged in. Because of that, we also inform the system that if this filter is present, the query SQL may not be cached and must be regenerated whenever the query is run.

Additional Notes on Tables

Tables don't have to directly link to the node table. For example, the roles table does not have any sort of NID in it, but instead it's a list of roles with the RID as the primary identifier. However, the users_roles table has both a NID an an RID. So on the left side of the join involving the roles table will be users_roles.

The join for the 'roles' table then looks like this:

The join for 'users_roles' looks like this:

'operator' can be a handler or an array, as can list, as shown in this pieceof code:

Specifics

This section is a theoretically exhaustive list of what parameters are available.

Fields:

The key should be the database name of the field; it doesn't have to be, however. You may include a handler which creates data for the field.

name:

This is the name displayed to the admin. PLEASE PLEASE PLEASE tag your name field with something recognizable as your module.

sortable:

If 'true' this field will offer click-sorting.

handler:

Optional. Set to a string that is used for a handler; only necessary for complex fields or non-fields. May be set to an array; if so, the user will be allowed to choose the handler. The key will be the function name and the value will be text displayed to the user.

addlfields:

Some handlers may require additional fields in the query; this will a automatically add them.

help:

Help text for the field.

uid:

specific to the username handler; gives the name of the UID field so it can properly use theme('username').

notafield:

Set to true if this isn't actually field but instead is some sort of aggregate, to prevent the query generator from trying to retrieve it.

Sorts:

The key should be the database name of the field to sort on.

name:

This is the name displayed to the admin. PLEASE PLEASE PLEASE tag your name field with something recognizable as your module.

field:

This is the actual database name of the field to sort on. Should match the key.

help:

This is the help text for the sort, displayed to the admin.

Filters:

The key should be the database name of the field that may be filtered on.

name:

This is the name displayed to the admin. PLEASE PLEASE PLEASE tag your name field with something recognizable as your module.

list:

May be an array of options; the key of the array is stored as the 'value', while the value of the array is displayed to the admin.

list-type:

May be 'select' or 'list'; defaults to 'list'. 'list' indicates multi-select capability, whereas select is just one.

operator:

May be a string which points to a function, 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

cacheable:

Whether or not the filter is cacheable. Defaults to true; use this if the handler requires some run-time data (such as the currently logged in user).

handler:

This is used for any custom filtering that needs to be done; useful for complex filters that aren't quite as simple as just WHERE field operator value.

help:

This is the help text displayed to the admin.

Arguments

hook_views_arguments() returns much less data than hook_views_tables(). In that respect it's a little easier. Unfortunately, the handlers are much more complex.

There are 4 operations for the handler:

The 'summary' op means that the system wants to know what fields need to be added to the query in order to utilize the argument. In the above case, the node type is used. (Note that the system calls the 'node' table 'n'. It is the only table it does not refer to by full name; this is because of the way
db_rewrite_sql() works).

The 'filter' op is called when it needs to add the WHERE part of the query while not in summary mode.

The 'link' op is called only in summary mode. Summary mode is when an argument is required but not given by the user. If configured to allow it, the Views system will provide a list of possible arguments. In the above case, it ran a query to find what node types are available. The 'link' tells it how to link to the next level of the view. In the 'link' case, $query isn't the query object, but it is a row of results.

The 'title' op is called to deal with title substitution. For example, 'recent posts for %1' needs to know the name of the user arg 1 happens to be. In this case, the argument is passed via the $query parameter. Yea,
I know. Overloading causes weirdness.

Another, more complex example:

The 'year' argument can provide a summary of Years available, 1 for every year in which nodes appear in the system. To do this it has to play a little magic, since there is no field that matches. The field above is added to the query as 'field' AS 'fieldname' so that it knows how to refer to it.

Handlers

An example of a custom filter handler:

function views_handler_filter_usercurrent_custom($op, $filter, $filterinfo, &$query) {
global $user;
$query->ensure_table("users");
$query->add_where("users.uid $filter[operator] '$user->uid'");
}
?>
$query->ensure_table() makes sure the table (and any tables between it and the node table) properly appear in the query.

Other handlers are, fortunately, much simpler:

Providing Default Views

Luckily for everyone, this part is actually very simple.

Expose your tables in your module. Then, use the interface and construct a view. Get it exactly the way you want it.

Then, export the view. You should be able to plug that code directly into your hook_views_default_tables(). Then just return the $views variable.

Example:

The above view is the generated code of the view that (almost) exactly duplicates the functionality of http://www.example.com/tracker