C H A P T E R 8
■ ■ ■
Working with Fields
A field is a commonly used component in Drupal that is used to store a value that a user has entered or a module has created. Information from fields is validated, stored in the database, and may be retrieved from the database and displayed on the web site. Examples of fields include usernames, street addresses, phone numbers, prices, a paragraph or two that describes an event, a date, or any other piece of information that you can think of.
The approach for creating fields changed dramatically in Drupal 7 with the addition of the Field API in core. What used to be a tedious task of defining tables and writing code that validates, stores, retrieves, and displays field-level information is now handled through a set of Field APIs. Many of the field-level capabilities added in Drupal 7 core come from the Drupal 6 Content Construction Kit (CCK) modules. The CCK modules provide a UI-level interface for creating fields in previous versions of Drupal.
In this chapter, I’ll show you the standard CCK-like functionality built into Drupal 7 core, how to extend that functionality by adding a new field type that any site administrator can attach to a content type, and finally how to use the Field API within a module to create a new content type with several different types of fields.
Creating Content Types
One of the “killer applications” in Drupal is the ability to create a custom content type, where a custom content type is defined as the framework for creating a node. Content types typically have at least a title field, a body field, and several other fields that are used to capture structured information. An example of a custom content type is an event, where an event has fields for capturing, storing, and displaying information such as the name of the event, a description of the event (body), the date and time of the event, and the location of the event. Let’s create a new event content type by navigating to Structure -> Content Types and clicking the “Add content type” link on the “Content types” page. Creating a new content type is relatively simple—enter the appropriate values for the name of the content type (in our example case, the name is Event) and a short description of the content type, and optionally override the label assigned to the title of the Event node. In the example, I changed the label from just Title to Event Title (see figure 8-1).
163
CHAPTER 8 ■ WORKING WITH FIELDS
Figure 8-1. Main page for creating a content type
With the “Submission form settings” values defined, the next step is to modify the publishing options to address the specific requirements of your site. Click the “Publishing options” tab and check/uncheck the options that you want to apply to Events. I’ll uncheck the “Promoted to front page” option, which by default is checked.
On the “Display settings” form, I’ll uncheck the box that triggers author information display when an Event is displayed. For my requirements, I don’t need to see who authored an event and when it was published.
The “Comment settings” form controls how comments will be displayed for a content type. In the case of an Event, comments aren’t needed. I’ll set the “Default comment setting for new content” to Hidden.
On the “Menu settings” form, I’ll uncheck the “Main menu” check box, as I don’t want content authors to have the ability to assign Events to menus. I’ll control where Events are displayed by incorporating them into Views on the pages where I want them to appear.
164
CHAPTER 8 ■ WORKING WITH FIELDS
With the content type wide configuration options set, I’m now ready to save the Event content type and proceed with the next step in the process—adding fields (see figure 8-2). After you click the “Save and add fields” button, Drupal takes you to the page where you can begin to add new fields to the Event content type.
Figure 8-2. The page for adding fields
Before adding the new fields, we need to decide whether dates will be entered in a plain text field or by using a date field that has features like a pop-up calendar that the author can use to select the date. In most cases, you’ll want to do the latter, as dates are often used for other purposes, like determining where to place a content item on a calendar, formatting dates so they display in the user’s local format, or doing date calculations. The Date module (http:// drupal.org/project/date) provides a field that we can use in our Event content type that includes a pop-up calendar for selecting a date. So before proceeding with the process of adding our fields, install the Date module following the standard approach for installing modules.
Adding Fields to a Content Type
The two additional fields for our Event content type are the location of the event and the date/time of the event. I’ll start with the event location field and will enter Event Location in the label field, event_location in the fieldname field, and I’ll select text as the type of data to store using the “Text field” widget (see figure 8-3).
165
CHAPTER 8 ■ WORKING WITH FIELDS
Figure 8-3. Adding the Event Location field to the Event content type
Clicking the Save button reveals the form for setting the maximum length of the Event Location text field. I’ll leave the default value, 255 characters, and will then click the “Save field settings” button. The next form (see Figure 8-4) displays detailed configuration options for the Event Location field.
The next set of values allows you to override the label that was entered using the form in Figure 8-3, by checking the box that sets the field to required, meaning that the author must enter a value for this field when creating a new event, setting the physical width of the text field as it appears on the screen, whether the author will have the ability change the input filter, the help text that will be displayed below the field on the screen, and the default value assigned to the field when it is rendered on the form.
166
CHAPTER 8 ■ WORKING WITH FIELDS
Figure 8-4. Field settings for the Event Location field
The last set of values that you can set for the field is the number of values, or cardinality, of the Event Location and the maximum number of characters that the author can enter in the field (see figure 8-5). I’ll leave the default value set to 1, as an event will likely have only one location, and I’ll leave the maximum length set to 255 characters. Clicking the “Save settings” button returns you to the form shown in Figure 8-3 with Event Location added to the list of fields.
Figure 8-5. Setting the cardinality and maximum number of characters for the field
167
CHAPTER 8 ■ WORKING WITH FIELDS
The next step is to add the field for the Event date. I will follow the same process that I used to create the Event Location field by entering Event Date and Time as the label and event_date_time as the fieldname, and selecting Datetime as the type of data to store and Text Field with Date Pop-up calendar as the widget that will appear on the screen. Clicking the Save button reveals the Field Settings page for a date field, as shown in Figure 8-6. I will leave all of the default settings with the exception of “Time zone handling”—which I’ll set to “No time zone conversion.” The time entered by the author is the time that I want to have displayed on the site.
Figure 8-6. The Field Settings page for the Event Date and Time field
After clicking the “Save field settings” button, the Event settings page is displayed for the Event Date field. On this page, I have the ability to override the label that I entered previously, select whether the field is required (date and time are required for an event for my site), help text that will be displayed below the field, the default display, which is the date format set in the date module, the default value that will be used if the author doesn’t select a value, the input format that defines the order and format of the date parts in the input form (e.g., 08/12/2010 – 08:00:00 or 12/08/2010 – 08:00:00 or Aug 12, 2010 – 08:00:00, etc.), the number of years backward and forward that will display on the pop-up calendar, and the incremental value for the minute field (if events occur on the hour, every half hour, or every quarter hour, you’ll likely want to change the increment to 60, 30, or 15 respectively). You also have the ability to
168