Help with node and field theming I am not particularly new to programming, but trying to theme how Drupal 7 outputs entity fields is giving me headaches. I think Drupal is great, but the documentation could be more organized and complete. I have sifted through a lot of material about this, but I'm still struggling to organize the bits and pieces of information into usable representation of how Drupal 7 treats and outputs field values.

This is an example output that one would like to obtain:

            &lt;h1&gt;#field value#&lt;/h1&gt;                      // Suppose this is the node title
            &lt;h2&gt;&lt;a href=""&gt;#field value#&lt;/a&gt;&lt;/h2&gt;       // Sub-title
            &lt;div class=""&gt;                              // Attributes:
                &lt;div&gt;
                    &lt;h3&gt;
                        #field title#:
                    &lt;/h3&gt;
                        #field value#
                &lt;/div&gt;
                &lt;div&gt;
                    &lt;h3&gt;
                        #field title#:
                    &lt;/h3&gt;
                        #field value#
                &lt;/div&gt;
                &lt;div&gt;
                    &lt;h3&gt;
                        #field title#:
                    &lt;/h3&gt;
                        #field value#
                &lt;/div&gt;
                &lt;div&gt;
                    &lt;h3&gt;
                        #field title#:
                    &lt;/h3&gt;
                        &lt;a href=""&gt;#field value#&lt;/a&gt;    // e.g. Link to Taxonomy term page
                &lt;/div&gt;
            &lt;/div&gt;


#field title# and #field value#, represent where one would like Drupal to output the field titles and/or values submitted when creating entities/nodes.

The idea sounds straight-forward, but I find it to be immensely complicated in practice.

Some pitfalls I have encountered: Drupal makes presumptions, on how the field should be displayed, it gives it additional markup, which I have been unlucky in managing. When outputting through Panels the UI does not provide ways to separate field value and title. Am I under correct impression that I need separate template files or functions for all fields if I want the above structure?

Please shine some light on the matter. I bet many people would love to hear how more experienced developers approach these problems.
This is probably not a full answer, but you will need to use field template suggestions.


field--[type|name[--content-type]|content-type].tpl.php
base template: field.tpl.php
Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:

field--field-name--content-type.tpl.php
field--content-type.tpl.php
field--field-name.tpl.php
field--field-type.tpl.php
Note that underscores in a Field's machine name are replaced by hyphens. Also remember to include "field-" in custom field names, e.g: field--field-phone.tpl.php.


The above is taken from https://drupal.org/node/1089656, so it for more information. As a side note, if there are a lot of fields being displayed or you are using a broad template, you would probably want to use a templating function instead, such an example can be seen in Bartik's bartik_field__taxonomy_term_reference (Link here). The functions have a similar naming scheme to the .tpl.php files but with underscors instead of dashes.

Update:
You can cover all fields of a certain type with field--field-type.tpl.php (or function theme_field__field_type()), or all fields on a content type with field--content-type.tpl.php (or function theme_field__content_type()). You can then override these functions by using a more specific template (They have an order of preference). This can really cut down on the number of theming templates or functions required, essentially if a content type has 100 fields, you could theme them all with one template or function, if you so wished.

So you could use 1 function to theme all the fields on a content type if you wished, no matter their type or name. Alternatively you could field all fields of a certain type (eg. taxonomy_term_reference in the case of Bartik) no matter what their field names are or which content types they are on.

You could override one of these more general templates or functions with one which is more specific, from the field.tpl.php documentation above field--field-type.tpl.php will be overridden by any of the ones listed above it, if a relevant function exists. While field--field-name--content-type.tpl.php has the highest preference and will not be overridden by any of the others. This is just core behaviour, custom modules may alter the list, including adding new ones, which can lead to quite a powerful set of themeing functionality.

Templates are easier for themers to work with, I am told. I prefer functions because it avoids what may be a large number of includes in some cases.