Check your version

This collection covers a topic in Drupal 7 which may or may not be the version you're using. We're keeping this tutorial online as a courtesy to users of Drupal 7, but we consider it archived.

Alternate resources: 

Drupal 7 Field API: Creating Custom Field Types, Widgets and Formatters

This series is for anyone that wants to learn more about how Drupal 7's Field API works from a module developer's perspective. Ever wonder how the text or image fields in Drupal work? Or how to create your own new custom field type and encapsulate the functionality provided by your module so that it can be mixed and matched with the rest of Drupal's fields by site administrators? This series will cover everything necessary to implement your first custom field type in Drupal 7.

Fields are the building blocks of Drupal's powerful content modeling system and the Field API allows for the development of custom field types to suit almost any data display and collection needs. When combined with the Entity API, which allows for the attachment of fields to entity bundles (commonly known as content types), Drupal becomes infinitly flexible without requiring writing any code.

There's already a pretty large ecosystem of Drupal 7 field types implemented by either Drupal core or other contributed modules, but what happens when the one you need doesn't exist? As a module developer knowing how to implement the Drupal 7 Field API and encapsulate your custom logic and functionality into a field can often times allow you to create modules that are far more reusable since they don't assume a specific information architecture.

We'll start out this series with a discussion of the pieces that make up the Drupal 7 Field API and some of the terminology like types, formatters, and widgets that you'll encounter when learning the Field API. We'll also talk about how fields are related to entities and the sometimes confusing concepts of field types and field instances. Having a firm grasp on the underlying concepts makes it easier to see how all the moving parts fit together, allowing you to have a better idea of where or when you might want to create a new field, or extend an existing one.

Then we'll take a more in-depth look at defining a new custom field type and the hooks we need to implement in order to teach Drupal about the data our field is going to store, and how and where to store it. In addition to figuring out how to store the data we'll also look at validating the data before saving it to the database to confirm that it meets our requirements.

After figuring out how to store the data we'll then look at using field widgets to allow users to of our site to input data for our fields via an HTML form element. Then we'll see how field formatters take that collected data and prepare it to be displayed to our end users. Both widgets and formatters allow for module developers to define additional configuration settings for administrators creating field instances. So we'll look at how to add settings in both of those scenarios.

After watching this series you should be able to:

  • Explain the different between field types, widgets, and formatters and what each one does.
  • Add a new custom field type.
  • Create a custom field widget and use it with your own field or an existing field type.
  • Define a custom field formatter and use it with your own or existing field type.
  • Peform additional operations on the data stored in a field when it's being loaded.


This series requires an understanding of PHP and basic Drupal 7 module development. For a refresher, or if you get stuck, check out our Drupal 7 Module Development series.