How to use Drupal's Contemplate module

Published May 31st, 2011

Learn how to use Drupal’s Contemplate module to achieve more granular theming of a node’s output.

Set up Contemplate module

Before proceeding, ensure that you have successfully installed the Contemplate module.

The cleverly-named Contemplate module is a very helpful tool to assist you in theming the more detailed aspects of the HTML code for content (nodes), which can sometimes be “trapped” inside of a single PHP variable in your theme. One common example of this is CCK fields which you’d like to control the output and placement of more than than simply outputting them in order on the page. By default, the Body, as well as all CCK fields are output by the single $content variable in node.tpl.php. Another example is the $submitted variable, which contains data such as the timestamp the node was created and the author’s user name and ID.

Contemplate allows you to “bypass” these variables and make use of the smaller pieces that make them up, giving your more granular control to customize and theme the individual parts, add to them, or throw away certain parts you don’t want. It provides a relatively simple (albeit cluttered) interface for you to “pick and choose” what you wish to include, to then simply copy and paste into your own template, augmenting or replacing the original variable (e.g. $content or $submitted in the case of the example) with your own custom version.

Important tip about using Contemplate

One important tip about Contemplate module is that many Drupal admins recommend the use of Contemplate only as tool to help you find, copy, and paste the necessary customization code into your own theme’s node.tpl.php file (or other theme files). Contemplate will “allow” you to make and save changes to your theme, saving the code for those changes directly in the database… however it is widely recommended that you do not ever press Contemplate’s “Submit” button to save changes. Copy Contemplate’s suggested code into your own .tpl.php files (where the code works equally well), keeping all of your theming code safely in actual files (otherwise accidental uninstallation of Contemplate module, among other things, could instantly and permanently wipe out your custom templates). Another reason it’s recommended to stick with all theming code in actual files is so that all theme-related code stays collected together in one place, which will help keep things simple, clear, and easier to understand for you (and others who might work on the site down the line)… it will be easier to see how the theme works (versus having to remember to edit “this” part of the theme in the files, but for “this bit and that other bit” you refer to the Contemplate page in Drupal, etc).

After you’ve finished using Contemplate to look up and copy/paste the code you need, simply close or leave its page without ever pressing the “Submit” button. If you find this tip confusing, don’t worry — you will see the whole process in action later in this section of the guide.

Settings if you use a WYSIWYG editor

Contemplate module’s interface works best if you disable any WYSIWYG editors from displaying on the Contemplate setting pages.

Using Contemplate

1. You will first need to have at least one node created of the Content Type you want to edit, in order for Contemplate to work. Create and save at least one sample node now.
2. Next you’ll want to prepare the custom node template where you will be pasting the code. Unless you’ve already created a custom template file, locate your theme’s node.tpl.php file and make a copy for the file. Name the copied file node-your_content_type.tpl.php where “your_content_type” is the name of the content type you want to theme (the name should be all lowercase and any spaces should be replaced with underscores). If by chance your theme did not come with a node.tpl.php file, you may copy Drupal core’s node.tpl.php file from the /modules/node/ directory. Your theme’s directory should now include both node.tpl.php and node-your_content_type.tpl.php (both files must be in your theme’s directory, even if you don’t plan to modify node.tpl.php). You may need to clear Drupal’s caches in order for your new template file to be recognized. If so, click the “Clear cached data” button at the bottom of Administer > Site configuration > Performance (admin/settings/performance).
3. Go to Administer » Content management » Content Templates (admin/content/templates) and click the “edit template” link in the row labeled with your Content Type name. Expand the “Body” fieldset, and click the checkbox for Affect body output, which changes the field from gray to white and makes it editable.
4. If you are seeking individual CCK fields to separate from the $content variable, these are visible immediately in the “Body Template” field, and no further digging is necessary. For example, you may see code for an individual CCK field such as <?php print $node->field_your_field_name[0]['view'] ?>. You may copy and paste this line directly into your node-your_content_type.tpl.php file. The surrounding div tags and any heading tags are optional.
5. Click in the “Body Template” field where you plan to add your new code (perhaps add a new blank line, or simply select all and erase the default text if you won’t be needing it), and then click to expand the “Body Variables” fieldset. Scroll through the list until you find the data you want to make use of (or use your browser’s Find feature, e.g. Ctrl+F), and click the link for that item. The PHP code snippet needed to display that bit of data on your page’s output will be printed into the “Body Template” field.
6. Copy the PHP code snippet(s) you want from the “Body Template” field and paste them into node-your_content_type.tpl.php.
7. As mentioned above, it’s not recommended that you save within Contemplate itself. After you’ve acquired the code snippets you were after, simply close the settings page without saving.
8. At this point, view your node. You may notice that some of the data is duplicated. This is because the $content variable is still outputting all of the CCK fields as normal, and your custom-added fields are being displayed as well. If there’s nothing in the $content variable you need any longer, you may simply delete it from the template. Locate and select the line <?php print $content ?> and then delete it. If you need to retain the $content variable but want to just get rid of the duplicate CCK field output, go to Administer » Content management » Content Types (admin/content/types) and click the “edit” link next to your desired Content Type. At the top of the page, click the “Display fields” tab. You may now check the “Exclude” checkbox for any fields you’d like removed from the $content variable, and press “Save”.