How to override field templates in Drupal 7

INTRODUCTION

Drupal provides a quick and simple way to customize field output globally using template files. Overriding a field's template file can be useful if you need to customize the HTML, data, or provide custom logic to a Drupal field. Template files allow you to target all fields, fields of specific names, fields of specific types and fields of specific content types.

This method is a good choice for theme developers who prefer to customize template files that allow inputting of HTML instead of overriding functions. This allows customization of templates just like customizing other Drupal template files such as page.tpl.php or node.tpl.php. However, it is important to note that Drupal best practices call for any complex logic should be placed in theme hooks rather than template files outlined in this method as function calls are more efficient and are intended for processing PHP. If you need to override many fields or your overrides contain more than basic logic then you should use the theme_field hook instead.

INSTRUCTIONS

To create a template file to be used for overriding the output of a field:

1. Create a new template field in your theme's directory using the following naming conventions:
   • field.tpl.php - Will modify the output of all fields. Note, this has a large performance overhead and is not recommend to use.
   • field--field-type.tpl.php - Will target all fields of a specific type. For example, "field--body.tpl.php" would target all body fields.
   • field--field-name.tpl.php - Will target all fields of a specific machine name. For example, "field--field-demo.tpl.php" would target all fields with a machine name of field_demo - it is important to note that you must replace the underscores from the field's machine name with dashes.
   • field--content-type.tpl.php - Will target all fields from a specific content type. For example, "field--article.tpl.php" would target all fields within the Article content type. -
   • field--field-name--content-type.tpl.php -Will target a specific field name within a specific content type. For example, "field--field-demo--article.tpl.php" would target fields named field_demo in Article content types only.
2. Create or modify the output of the field in your new template file as desired.

Drupal comes with a field template file that can be used as a starting point. This template file is located at /modules/field/theme/field.tpl.php. You can copy this field into your theme's directory as a starting point for modification.

From within your new field template file you will have multiple variables available to work with for your custom output. Some variable to note are:

• $items: Contains an array of the actual field values.
• $label: Contains the field's label.
• $classes: Contains the field's CSS classes
• $element['#object']: Contains the entity object to which the field is attached.
• $element['#view_mode']: Contains the entities view mode, e.g. 'full', 'teaser'

EXAMPLES

Here is an example of creating a custom template file for a field of the type file. For this case we only want to target a specific field name which, in this case, is field_pdf (see screenshot).

To target the output of all occurrences of the field_pdf field we will create a new file in our theme's directory called field--field-pdf.tpl.php. We then clear our site's caches to make Drupal recognize our new theme file.

Now we'll modify our new theme file to suite our needs. In this, somewhat contrived, example we'll remove the wrapping HTML div and hard-code in a new static label. The static label will only be displayed when the field is viewed When editing the field the field's own label will still be displayed. This allows us to show one field label when the content creator or editor is creating the Entity and display a different (static) label when the field is viewed.

This is just a basic example but it should provide a good overview of out to create and use Drupal's field template files.