Theming CCK the Agaric Way

CCK is in constant development, so by the time I finish writing this, this advice will be obsolete.

Seriously, if you've been searching the internet for information on how to theme Drupal CCK nodes, you should probably stop, because at the time of this writing the best documentation with invaluable example files is in the module download itself: cck/theme

[Update: with CCK in core in Drupal 5, I don't know where this documentation is. Grab yourself a 4.7 version (or check the attached file for the full node theme example), it seems to be still be good for this part, with one big exception: node-example.tpl.php instead of node-content_example.tpl.php.]

[Further Update: with custom content types using the node body in Drupal 5, their is no "field" type for the body text. So how do you get it out? You will be so glad you asked, instead of trying yourself:

    // print $node->body;
    // print $body;
    // print $field-body[0]['view'];
    // print $body->content['body']['#value'];
    // print $content['body']['#value'];
    print $node->content['body']['#value'];

So yeah, the commented out ones (// ) don't work right. The last one does.]

All right, so on to the promised Agaric Way for Themes of CCK:

1. Save as complete web page an example of how your current CCK content type presents itself. This provides you with several things:
   • all the default HTML element names (which you may have already used in CSS), and which give you a useful standard in any case (UPDATE: I wouldn't bother with all off those divs, it's ridiculous.)
   • the look of the original so you have your baseline to improve upon! -- and can be double sure you include all fields
2. We skip all the theming individual fields, usually, and theme the whole node-- this means the template.php code and the various field.tpl etc. files are not needed. Instead we just use node-content_example_type.tpl.php
3. Remember the .tpl. part of the CCK node theme override filename!
4. Simply use print $field_example_field[0]['view']; (for single value fields) wherever you want your custom fields, surrounded by custom text or wrapper tags to match all the CSS you care to lay on it. (Multiple value fields use while or for statements swapping out that 0 with a number.) You can use conditional logic <?php if ($field_example_field[0]['view']) { ?> to decide whether to, say, print your custom title for field (which you do have to include if you want a title at all), and then the print view code, and close the if statement with <?php } ?>
5. When you enable imagecache, which is great, you do not need to associate an imagecache image scale/crop/size thingie with a particular CCK field or CCK content type. You simply have to call for the image you want, using the imagecache name for the crop/scale/size preset thingie (that's the proper technical term) and the file path to the original image (created by imagefield). You do that with code like this: print theme('imagecache', 'files/imagecache/your_imagecache_preset', $field_example_image[0]['filepath']); (filepath is literally what you use, that's not an example, it gets the original filepath for you). If I remembered that wrong the right code is in a comment on a Lullabot thread about this.
6. Don't forget that if you add to or edit your content_ type, you'll have to update your content_ .tpl.php also!. I don't know if there's an analog to form_render to make sure you output any fields you haven't used, but it's actually useful to create "private" fields by either not including them in the custom node-content .tpl.php, or by putting access control code around them.

From the CCK theme readme:

If you need more flexibility than is afforded by theming individual fields, you may theme the entire node as a unit. This allows you to affect field order, to change the HTML structure to something more complicated, like a table, or even to exclude fields from the presentation entirely. The setup for theming a node is simpler than for theming a field; simply create a file called "node-content_foo.tpl.php" where "content_foo" is the content type name as listed on the administration page. For an example of the typical contents of this file, investigate the included example here ("node-content_example.tpl.php") or the "node.tpl.php" file that comes with your theme.

All the instructions for the per-field theming are in that cck/theme/README.txt if you want to do it that way, and is also covered in the Drupal handbook on CCK.