field.tpl.php

You are here

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()

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.

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 ...

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

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