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.

List module overview

Last updated on
November 21, 2016 - 21:07

The List module defines various fields for storing a list of items, for use with the Field module. Usually these items are entered through a select list, checkboxes or radio buttons. This module is an internal element of the Field API.

Creating a list field

Creating a list field

Uses

List module defines and creates interface elements for select lists, checkboxes and radio buttons used by the Field UI. When creating new fields for content nodes or users, you may use the four basic list options when creating fields:

  1. List - The default list type, a simple selection of text options, for example:
    red
    green
    blue
    white
    

    This field type stores values based on the order of each item. Altering the options after creating the field can result in lost data. These values may not have optional display labels. To use labels with named keys, select the List Text field format.

  2. Boolean - Creates a single yes/no option. When creating this field, you may select two radio buttons or a single on/off checkbox. When creating boolean fields, you supply labels for the on and off states. Note that changing the labels after creating the field will not affect existing data.
  3. List (numeric) - Creates a list of items with associated numeric keys, such that the order of elements does not matter for data storage. This type is suitable for most lists, as it allows human-readable labels, for example:
    0|Red
    1|Green
    2|Blue
    3|White
    

    These labels may contain limited HTML for formatting the forms created by your field. Changing the labels after creating the field is acceptable. Changing the numeric keys may result in a loss of data. Note that leading zeroes on any of the integer keys should be omitted, as they will cause problems.

  4. List (text) - Creates a list of items with text keys for data storage. These lists are useful for storing data which has meaningful text keys, such as the abbreviations of countries:
    CA|Canada
    MX|Mexico
    US|United States
    

    These labels may contain limited HTML for formatting the forms created by your field. Changing the labels after creating the field is acceptable. Changing the text keys may result in a loss of data.

Entering field options

When entering field options, you are creating a list that Drupal can present to your users. Each element in the list is defined by a linebreak, so you must enter one item per line.

Correct:

CA|Canada
MX|Mexico
US|United States

Correct:

Canada
Mexico
United States

Incorrect:

Canada, Mexico, United States

Incorrect:

Canada|Mexico|United States

About field labels

Field labels are used to provide human-readable form elements. The keys of each key|label pair are stored in the database, while the labels are displayed to site users. When entering keys and labels, use the pipe character | to separate the key from the label.

Labels may contain limited HTML to improve form readability. For example, you may provide help links for an item or use emphasis:

CA|Canada (<a href="http://en.wikipedia.org/wiki/Canada">Wikipedia entry</a>)
MX|<strong>Mexico</strong>
US|United States

Versions

This module was introduced in Drupal 7.

Details

Default module: Yes
Dependencies: Field
Related Modules: Field UI, Field SQL Storage, File, Image, Number, Text
Permissions: None.
API Documentation: Field types API
Database tables: None.

Tags