ARCHIVE: Tables part 3: Fields

Last updated March 26, 2011. Created by aclight on November 24, 2006.
Edited by linclark, Darren Oh, robertDouglass, merlinofchaos. Log in to edit this page.

Fields are added to the table in an array of fields using the 'fields' key. The key for each field in the array should be the database name of the field; it doesn't have to be, however. But if it isn't, you should either set 'notafield' => TRUE or 'field' => 'actual_field_name'. This works exactly like table aliasing.

Example:

Field settings

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

name (Required)

This is the name displayed for the field on the admin UI. It is customary to give the field a name that lets people recognize that it belongs to your module. For example, Node: ID comes from the node module and Taxonomy: Term comes from the taxonomy module. Because it is part of the user interface, name 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.

notafield (Optional)

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. If you set 'notafield' to TRUE, this field will do nothing if there is no handler associated.

sortable (Optional)

If set to TRUE this field will offer click-sorting via table headers. Defaults to FALSE.

handler (Optional)

This is the handler that will control how the field is displayed. If no handler is present, the value will be run through Drupal's safety checks and displayed as is. This value supports an array of handlers; if the handlers are an array, a choice for which one to use will appear in the Views UI.

function views_field_handler($fieldinfo, $fielddata, $value, $data)

This handler will control the output for field. Usually this is some kind of transformation of the data; it may transform it into a link, or format a date or a currency value. It will be called for the field for every record in the view.

Parameters

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

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

$value The actual value retrieved from the database.

$data The entire record from the database. TODO document this. (probably a link)

Return value

The string to display.

query_handler (Optional)

A handler that allows the field to modify the query, for example to add additional data not in the table. This handler is rarely needed.

function views_field_query_handler($fielddata, $fieldinfo, &$query)

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

Parameters

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

$fieldinfo 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

sort_handler (Optional)

A handler to allow the field to specify how to 'tablesort' if it's not just a simple table.field sort. This is only valid if the field is set 'sortable' => TRUE.

function views_field_sort_handler($fielddata, $fieldinfo)

Return a formula to be used for tablesorting; specifically it will appear in the ORDER BY clause when that field's header is clicked on.

Parameters

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

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

Return value

A string to sort by. Without this handler it will simply be table.field. Please note that a query_handler may be necessary as some databases want ORDER BY clauses to also appear in the SELECT, which means a $query->add_field may need to be performed, and that cannot be performed by this handler.

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.

addlfields (Optional)

While the basic field will automatically be added to the query, other fields for the table might be needed. For example, the username field is often a link to the user, and this requires the user's uid as well. The format of this field is: array('field', 'field2', 'field3'). All fields must be from the same table; if fields from an additional table are required, use a query_handler instead.

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 $fieldinfo array.

An example field:

This is the definition of the created time, or the post date of a node. Dates have a series of handlers that can affect how they are output, and an option that may be used for customizing date output. Note that in this case the 'handler' is not actually a string, but a function that's called. That's because it's actually a shortcut for commonly used handlers. Here is the function that fills in the possible handlers:

As you can see, it simply returns an array of handlers that are common to dates.
And a more complex example:

This complex handler is a pseudo field -- as a single field, it doesn't exist at all. The field displays all files that are attached to a node. Because of the way multiples work in SQL, this needs to be done with a different query. For more information about the handlers used by the above field, see views_upload.inc in the views/modules directory.

Field 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.

label Database

The text label the View user has designated for this field. May be blank.

handler Database

If the handler is an array, this is the handler that was chosen for the field.

sortable Database

If sortable => TRUE in the field info, this is the Views user's choice as to whether or not this particular field should allow click sorting.

defaultsort Database

If sortable => TRUE in the field info, this is the Views user's choice as to whether or not this particular field should be the default sort; will either be ASC, DESC or FALSE.

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'.

fullname

For Views' internal convenience, this is table.field

queryname

When Views adds fields to queries, it aliases them to table_field to prevent collisions. The queryname is that alias.

Common field handlers

These are handlers used in views that are common and can be utilized by modules using the same output.

function views_handler_field_dates()

This isn't actually handler, but is a function that returns an array of handlers for formatting dates. If this handler is used, the field that utilizes it should always include 'option' => 'string' for custom dates, and should include a message in 'help' mentioning that the date format can be customized in the option field.

function views_handler_field_date_small($fieldinfo, $fielddata, $value, $data)

The date handler used by views_handler_field_dates() for medium dates.

function views_handler_field_date($fieldinfo, $fielddata, $value, $data)

The date handler used by views_handler_field_dates() for small dates.

function views_handler_field_date_large($fieldinfo, $fielddata, $value, $data)

The date handler used by views_handler_field_dates() for large dates.

function views_handler_field_date_custom($fieldinfo, $fielddata, $value, $data)

The date handler used by views_handler_field_dates() for custom dates.

function views_handler_field_since($fieldinfo, $fielddata, $value, $data)

The date handler used by views_handler_field_dates() for dates in the format of "X timespans ago".

function theme_views_nodate()

A theme function that may be overridden, used for fields that have 0 or an invalid date.

function views_handler_field_int($fieldinfo, $fielddata, $value, $data)

A simple output handler for integers that insures the value is output as an integer.

function views_handler_field_filesize($fieldinfo, $fielddata, $value, $data)

A simple handler that outputs a number as a filesize.