Last updated May 17, 2011. Created on August 23, 2010.
Edited by arianek, agentrickard. Log in to edit this page.

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.

  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

Drupal 7

This module was introduced in Drupal 7.

CCK in Drupal 6 and lower

In Drupal 6, list field behavior was defined by the contributed CCK module.

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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

jimvenet’s picture

Is there a way to get the field list options from the database? I basically need to create a field list that allow you to choose among the node names... so the only solution is to get the list option from the database. Is there anybody who already solved this problem??
Thx

parisek’s picture

Skydda’s picture

How do I create list field, where users can input their own values?

kurtismccartney’s picture

Any luck finding a simple UL Field with add more function?

Panaromic.webdesign.com’s picture

I have a need to create a field of custom "dynamic" check boxes type. In Drupal 6 I was able to create this with inserting php code in field definition. Is there a similar capability in Drupal 7.

Even though I am able to insert php code in node body and block body (after enabling PHP Filter in Drupal core), I was expecting to do the same in creating a field in custom content type.

As I didn't see this feature right away, I started customizing the code I found under examples/field_example. Is this the way to go or is there a better way to do it.

Peace

-Gowri

qstyler’s picture

Hi!
Is there any chance I can use optgroups in this module?
Thank you!

calculus’s picture

Is there a way to add options to a list field, after content (that use it) has created? For example in list below:

0|red
1|blue
2|yellow

Can i add 3|black ?

langweer’s picture

My experiences say that you can still change the list even if content has been created. There is the warning, that it can't be done, but if you just do it, the system doesn't give an error.
BUT: I can not promise that this is the right way to do (although it works for me).

2dareis2do’s picture

Not sure if this is the best place to post this but I am experiencing a problem with the list module.

I have a integer select list with the following key|value(s)

01|01
02|02
03|03
04|04
05|05
06|06
07|07
08|08
09|09
10|10
11|11
12|12
13|13
14|14
15|15
16|16
17|17
18|18
19|19
20|20

When I edit the node in my custom content type, I can select the value sand they seem to save, however when I go to edit the form again, my previously selected values have disappeared and I have to enter them again.

Please help, what am I doing wrong? How do I keep my selected values I have over 20 integer select lists on a form and don't want to have to re-enter everytime I make a minor change to a node.

BTW, list using a float instead of integer seems to work fine.

Freelance Web Design and Development
---
http://www.danlobo.co.uk

Stomper’s picture

How does one remove or turn off the N/A option in a checkbox or radio list (text)?

rodrigo21’s picture

How does one remove or turn off the N/A option in a checkbox or radio list (text)?
https://drupal.org/node/1080726

Sustainable Transport in Drupal.
www.ridebubble.org
www.nosfuimos.cl

Stomper’s picture

Thanks. I figured it out. You just need to make the number of possible choices match the number of options.

gigab’s picture

Hi, how can i write "iframe" on Label?
Thanks

gauravjeet’s picture

Use hook_form_alter, that simple :)..

sethmac’s picture

I am really struggling to check a checkbox when creating a node using the following structure. Would love any insight..thanks!:

function mymodule_install() {
$node = new stdClass();
$node->type = 'group';
$node->title = 'MY AWESOME GROUP';
$node->language = LANGUAGE_NONE;

$node->group_group[$node->language] = array(0 => array('value' => 1));
$node->group_access[$node->language] = array(0 => array('value' => 1));
$node->field_list_one[$node->language] = array(0 => array('value' => 'AAA'));

$node->promote = 0;
$node->status = 1;
$node->uid = $user->uid;
node_save($node);

}