field.tpl.php Default template implementation to display the value of a field.

This file is not used and is here as a starting point for customization only.

Available variables:

  • $items: An array of field values. Use render() to output them.
  • $label: The item label.
  • $label_hidden: Whether the label display is set to 'hidden'.
  • $classes: String of classes that can be used to style contextually through CSS. It can be manipulated through the variable $classes_array from preprocess functions. The default values can be one or more of the following:

    • field: The current template type, i.e., "theming hook".
    • field-name-[field_name]: The current field name. For example, if the field name is "field_description" it would result in "field-name-field-description".
    • field-type-[field_type]: The current field type. For example, if the field type is "text" it would result in "field-type-text".
    • field-label-[label_display]: The current label position. For example, if the label position is "above" it would result in "field-label-above".

Other variables:

  • $element['#object']: The entity to which the field is attached.
  • $element['#view_mode']: View mode, e.g. 'full', 'teaser'...
  • $element['#field_name']: The field name.
  • $element['#field_type']: The field type.
  • $element['#field_language']: The field language.
  • $element['#field_translatable']: Whether the field is translatable or not.
  • $element['#label_display']: Position of label display, inline, above, or hidden.
  • $field_name_css: The css-compatible field name.
  • $field_type_css: The css-compatible field type.
  • $classes_array: Array of html class attribute values. It is flattened into a string within the variable $classes.

See also

theme_field()

template_preprocess_field()

79 string references to the theme hook from field.tpl.php

Note: this list is generated by looking for the string for this theme hook, so it may include some references that are not actually using this theme hook.

comment_admin_overview in modules/comment/comment.admin.inc
Form builder for the comment overview administration form.
DatabaseCondition::compile in includes/database/query.inc
Implements QueryConditionInterface::compile().
DatabaseCondition::condition in includes/database/query.inc
Implements QueryConditionInterface::condition().
DatabaseCondition::where in includes/database/query.inc
Implements QueryConditionInterface::where().
DatabaseCondition::__clone in includes/database/query.inc
PHP magic __clone() method.

... See full list

File

modules/field/theme/field.tpl.php
View source
  1. <?php
  2. /**
  3. * @file field.tpl.php
  4. * Default template implementation to display the value of a field.
  5. *
  6. * This file is not used and is here as a starting point for customization only.
  7. * @see theme_field()
  8. *
  9. * Available variables:
  10. * - $items: An array of field values. Use render() to output them.
  11. * - $label: The item label.
  12. * - $label_hidden: Whether the label display is set to 'hidden'.
  13. * - $classes: String of classes that can be used to style contextually through
  14. * CSS. It can be manipulated through the variable $classes_array from
  15. * preprocess functions. The default values can be one or more of the
  16. * following:
  17. * - field: The current template type, i.e., "theming hook".
  18. * - field-name-[field_name]: The current field name. For example, if the
  19. * field name is "field_description" it would result in
  20. * "field-name-field-description".
  21. * - field-type-[field_type]: The current field type. For example, if the
  22. * field type is "text" it would result in "field-type-text".
  23. * - field-label-[label_display]: The current label position. For example, if
  24. * the label position is "above" it would result in "field-label-above".
  25. *
  26. * Other variables:
  27. * - $element['#object']: The entity to which the field is attached.
  28. * - $element['#view_mode']: View mode, e.g. 'full', 'teaser'...
  29. * - $element['#field_name']: The field name.
  30. * - $element['#field_type']: The field type.
  31. * - $element['#field_language']: The field language.
  32. * - $element['#field_translatable']: Whether the field is translatable or not.
  33. * - $element['#label_display']: Position of label display, inline, above, or
  34. * hidden.
  35. * - $field_name_css: The css-compatible field name.
  36. * - $field_type_css: The css-compatible field type.
  37. * - $classes_array: Array of html class attribute values. It is flattened
  38. * into a string within the variable $classes.
  39. *
  40. * @see template_preprocess_field()
  41. * @see theme_field()
  42. *
  43. * @ingroup themeable
  44. */
  45. ?>
  46. <!--
  47. THIS FILE IS NOT USED AND IS HERE AS A STARTING POINT FOR CUSTOMIZATION ONLY.
  48. See http://api.drupal.org/api/function/theme_field/7 for details.
  49. After copying this file to your theme's folder and customizing it, remove this
  50. HTML comment.
  51. -->
  52. <div class="<?php print $classes; ?>"<?php print $attributes; ?>>
  53. <?php if (!$label_hidden): ?>
  54. <div class="field-label"<?php print $title_attributes; ?>><?php print $label ?>:&nbsp;</div>
  55. <?php endif; ?>
  56. <div class="field-items"<?php print $content_attributes; ?>>
  57. <?php foreach ($items as $delta => $item): ?>
  58. <div class="field-item <?php print $delta % 2 ? 'odd' : 'even'; ?>"<?php print $item_attributes[$delta]; ?>><?php print render($item); ?></div>
  59. <?php endforeach; ?>
  60. </div>
  61. </div>

Related topics

Comments

It would be nice if what you needed to rename the templates to was noted in the docs/comments. Maybe I missed it, but it's hard to find.

I have just started to delve into field level theming (because D7's render is so nice) so take this with a grain of salt but, my convention (verified) is.

Field: field_page_photos
File: /mytheme/anyfolder(optional)/field--field-page-photos.tpl.php
Cache: Clear it.

Note, that...

  • yes - you should clear cache b/c D7s theme registry is far more impressive now.
  • Underscores seem to always become -'s in tpl filesnames now.
  • Yes, you can put themes into folders (I use mytheme/templates/fields)
  • "--" are used to separate parts of the file such as the general statement: entity--bundle-name.tpl.php

Why is it that (with a text field, for example) in the field template I get $item['#markup'] only, where in the $node object I have $node->myfield['und'][0]['value'], $node->myfield['und'][0]['safe_value'], etc?

Is there the possibility of getting a non-safe value when using the field template?

Possible override templates are:

  • field.tpl.php
  • field--field-type.tpl.php
  • field--field-name.tpl.php
  • field--content-type.tpl.php
  • field--field-name--content-type.tpl.php

I would like to see this helpful list included in the comments of the template files.

for example: /modules/field/theme/field.tpl.php

First off, the reference of Drupal field types is here: https://groups.drupal.org/node/124289
You will want to use the "machine readable name" as the basis for making your template file names.
Example: To have a field template file for fields of type "Long Text", your field.tpl.php file would be renamed to: field--text-long.tpl.php. Note the use of the "machine readable name" for the "Long Text" (text_long), and note that underscores become single hyphens.

Few more examples:
Text: field--text.tpl.php
Long Text: field--text-long.tpl.php
Long Text with Summary: field--text-with-summary.tpl.php
Decimal: field--number-decimal.tpl.php

Took me way to long to figure this out AND to find the reference for field types.

As detailed in the documentation ( $element['#field_type']: The field type.) to get the field-type just use the next code in field.tpl.php

<?php
 
print $element['#field_type'];
?>

for instance for a boolean field the type is list-boolean, so the custom field tpl is:

field--list-boolean.tpl.php

Another option is check the html and find the classes of that field. At least omega writes the field-type as a class.
<div class="field field-name-field-foo field-type-list-boolean field-label-inline clearfix">[...]</div>

I hope it helps someone.

The way it worked for me it was:
field name: field_pdf
template: field--field_pdf.tpl.php

you only need one field.tpl.php to get rif of the div crazyness in the output of drupal ...

<?php foreach ($items as $delta => $item) : ?>
    <?php print render($item); ?>
<?php endforeach; ?>

instead of using a lot of field template files ...

we know this concept from views and it was/is the total wrong direction ...
complicate solutions for simple tasks ... the node ['view'] object was much easier to handle in a lot of use cases ...

This clear simple concise code is exactly what I was looking for to get going.

Is it possible to over ride the default theme_field() for a specific view ?

I can over ride all fields by putting the field.tpl.php file in my themes folder, but I want to customize only for certain views.

For specific fields, the structure appears to be this:

themes/seven/field--contentfieldname.tpl.php

For specific fields on specific content types, it appears to be this:

themes/seven/field--contentfieldname--contenttypename.tpl.php

How would I override the field type only for a specfic view?

thanks

Because views essentially takes entities apart and joins fields accross enttities, it has its own field templates. Checkout the "theme" folder in the views module and find the field template and copy it to your theme. Hit the "Theme information" button under the advanced section in views to get a list of what to rename your copy of the template to to take over the display of different fields.

For general template suggestions, including this list, see: http://drupal.org/node/1089656

Say that the machine name of your custom field is field_phone, then your tpl-file should be named like this:

themes/seven/field--field-phone.tpl.php

I wasn't sure where to drop this tip but I think it would be useful to other folks.. there's a great example of code here:

http://drupal.org/node/1108164#comment-5111780

[snippet]

<?php

$field_name

='field_date';
$items = field_get_items('node', $node, $field_name);
$field = field_info_field($field_name);
$instance = field_info_instance('node', $field_name, $node->type);
$item=$items[0]; //Just display the first date
$display=field_get_display($instance, 'default', $node);
$display['settings']['format_type']='short'; //Alter the display
$vars['dates'] =date_formatter_process('date_default', 'node', $node, $field, $instance, $langcode, $item, $display);
$output=theme('date_display_combination', $vars); 
?>

hi,

Now is there any way that a field which is a timer (provided by the great great Countdown Timer Field module (http://drupal.org/project/field_countdown)) would start only on a flag click on that node

If you have a custom field called like secondary_field your template file should be called like this: field--field-secondary-field.tpl.php It took me way too long to figure out you need to prepend field twice. Once with two dashes after it and then again with one dash. Hope it helps someone.