Drupal 7 Tutorial: List Fields

Drupal tutorial: List Fields

In the tutorial "Adding Fields," we saw how we can attach text fields to content types for people to add data. But there are times you want more control than a free form text field or text area box. You might want to limit the authors selection to a fixed set of options. This is where a list field comes in handy. In this tutorial, we'll take a look at how list fields work and some of the unique options they provide.

Let's say our demo company ACME Widgets offers different length support periods for their different products and they want to go ahead and add this information to the product node types. We could do this using a text box to input the information, however there's only a few different options so the openness of a text box isn't justified. If we were to use an open text field, things could get messy quick. If, for example, we wanted to group widgets by support length then we'd have to make sure that node authors always typed in the support options the exact same way.

Adding a List Field

A better solution is to provide node authors with a list to choose from that is always controlled. So let's go ahead and add our list field. Now the first thing I want to do for this demo is I want to pop up our node edit form so we can see how it changes as we add and configure our list field. I'm going to open up in a new tab and play with the content type so to do that I'm going to go to structure, open link in new tab, and then over here I'm going to click on content types and then underneath our product content types I'm going to manage fields.

Here we see the fields we've added in a previous video but now I'm going to go ahead and add our list field, I'm going to call this one support. Because we're going to be storing the number of days I actually want to give it a machine name of something like supportdays. Now we select what type of data we want to be storing. We want to select one of these different list options and we see that we have two options for numbers: 1) whether we want to store a whole number or an integer or we want to store a decimal (which is a floating point number) or 2) whether we want to store text. Because we are just going to be dealing with just whole numbers of days, I want to go ahead and use the integer.

Configuring a List Field

Then we see we get two selections for our input widget: 1) a select list or 2) this check boxes/radio buttons we're actually going to be demo-ing both but for now I'm just going to select "Select list." And I'm going to show you one other trick I like to use: normally we click "Save" and we start moving through our configuration then later we have to go organize the sort order for this field but what I'm going to do is I'm going to go ahead and drag this up to the top and then save. So now we've kind of killed two birds with one stone. It's sorted we don't have to do it afterwards.

On this screen we need to configure how we are going to store the data into the database. In particular, what we need to do on a list field is find what values can the author select from. The key to understanding how to do this is this line down here in the instructions where it says we need to use this format key pipe label. And when I say the word pipe I'm referring to a vertical bar and you can find that key on your keyboard generally it's above the enter key and it's a shift of the backslash key. So I'm going to go ahead and paste in some values, and what we see here is I've selected four values on the left hand side I have a number which is what's going to get stored into the database. On the right hand side of the pipe I have these word values this is what's going to be displayed in the select box on the node edit form and it's also what's going to get displayed on a node view. I'm just going to go down and save these settings. And now we're going to run through the configuration for the widget.

The label is fine, I'm going to put in a little bit of instructions then I'm going to go ahead and scroll down and leave it set to only one value and go ahead and click save settings. So now let's go take a look at our new field over our node edit form. Just flip back over to this tab hit refresh and here's our select list. So we can just select from of these let's say for example our blue widget has 30 days of support. Scroll down to the bottom, click save. And here on our node view we can see our new field.

So now let's take a look at how some of the fields settings affect our input widgets. To see the differences let me pop open the node edit form. I'm going to run back over to this tab where we are editing our support field, we can click on edit and here I want to check off on the required field and see what effect this has. I save our settings. Now I run back over here we see the drop down the way it was before it was checked where we have this none plus the four different options we put in when we first created the field. We do a refresh and we can see the effect of checking off on the required field box.

Now we see that the none is gone all we have are our four fields we have to select one of those. Now let's look at an even more dramatic change by completely changing out our input widget to something different. I'm going to run back over to our tab where we are editing our content type and this time instead of clicking on edit underneath the widget I'm going to click on this select list. Now what we see is I can check two different types, select list or this check boxes and radio buttons so I'm going to switch to the check boxes and radio buttons and click continue. Now if I run back over to my node edit form, I click refresh we see that we get a completely different UI widget where before we had the drop down now we have a bunch of radio buttons. But it works the exact same way it's just a way of breaking things out into something that might be a little easier for node authors to work with it's particularly nice for smaller sets of things particularly if it's just something like an on off or for example if you want to do the gender and you want to do the male female or something that's going to be a binary decision a lot of times it's easier to use a radio or check box than it is a drop down box.

So speaking of check boxes let's look at how to convert these radio buttons into a check box input widget. To do that we run back over to where we are editing our field and at first you might think well underneath these widget settings we could change that to check boxes but we only have one option that allows us to do both. Where we actually make this change is underneath our edit link. And what's a little bit difficult for people new to Drupal is there is nothing on this page that says make this a radio button or make this a checkbox. The secret is under these number of values so if I switch them from one to unlimited and then I click save settings. I run back over to our node edit form and click refresh we now see that I have check boxes where I use to have radio buttons. And if you think about it, it actually makes a lot of sense what Drupal is doing it's being pretty intelligent. Radio buttons make sense when can only select one option but if you allow people to select multiple options that's when you need check boxes. So it always is enforcing good form UI elements for you automatically.

Now let's take a look at what happens if we change our widget back to a select box. To do that run back over to where I'm editing my field and I click underneath the widget column to change this back to a select list and click continue. Go back and do a refresh and I get a select box back but this ones a little different it's not a single drop down like it was before it's now expanded giving me multiple options. And so here I can actually go and using a control click I can select multiple different options if I want to. The reason it's now expanded is because we have our values set to unlimited instead of one. If we want to see the original version I can back and change it back to one value. So under support I click edit, I scroll down to number of values change this to one and save my settings. I do a refresh and now we're back to the drop down list we started with.

The one last thing I want to go ahead and do is clean up our node view. So we see that a list field is kinda hanging out down here below where we've organized these fields from a previous video. To change that I run back over to my tab where I'm under structure content types and then I wanna click on managed displays. So here the first thing I want to do is drag our support field above our description field. And then I want to change my label from being above to being in-line I click save. Now I run back over to our node view, refresh and now everything is nice and cleaned up.

List fields can be very handy when you want to standardize a set of options for authors to select. It helps that Drupal enforces the right types of form widgets for various types of input options. We looked at the basic list fields in this tutorial. But there are two additional field types that provide similar functionality. Term reference fields builds lists from Drupals taxonomy term system and reference fields builds lists groups of nodes or users. We'll look at these more advanced versions in later videos but for now if you need a simple way of controlling data sets, list fields are a great way to go.