Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Field API glossary

Last updated on
October 14, 2016 - 20:56
  1. field types
  2. field storage
  3. widgets
  4. formatters
  5. fields
  6. fieldable objects
  7. field bundles and instances

Field types

Field types define the type of data that will be stored and any operations that should be performed before storing the data and after the data is loaded. For example an Amazon ASIN field might store an ASIN number (which refers to a book) as a string. Before the ASIN number is stored it could check with amazon.com to verify the validity of the number. After the ASIN number is loaded it could query amazon.com for details about the book it references and pass that information to the field formatter.

Field storage

The actual low level work of saving/loading/deleting data is performed by field storage modules. Drupal core provides a field SQL storage module which performs all the SQL statements necessary for handling field save/load/delete tasks for SQL database storage. Field storage modules could be written to store field data in a variety of ways including HyperTable, Amazon S3 or CouchDB. Per field a different storage engine can be chosen. Choosing the appropriate storage engine for your field can improve scalability.

Field widgets

Field widgets provide an interface for users to enter data. This could be as simple as an HTML textarea, or as complex as a Farbtastic color picker like the one used by color module for theme settings. Field widgets do not perform any validation on the actual data, they simply pass along whatever information has been entered for further processing.

Field formatters

Field formatters control how the data is displayed. These are, practically, theme functions which also have a user readable name.


A field consists of a field type and specific settings which can not be changed once the field is created. For example, you can create an author field which contains a text type and only one of that.

Fieldable objects

A fieldable object is something that calls the field attach API for its CRUD (create, read, update, delete) operations. In core, node, taxonomy term, comment, and user are fieldable objects.

Field bundles and instances

A bundle is a place to attach a field. Core defines a bundle for every node type, for comments on each node type, for taxonomy terms (for each vocabulary), and one for user, aptly named 'user'. Every bundle contains a number of field instances. A field instance is created from a field when that gets attached to the bundle. Also, the field instance has settings that are changeable any time, like a formatter and a widget.