Skip to Content
RSSGrab the RSS feed! ->

How to create a CCK formatter

CCK formatters are pieces of code that allow you to render a CCK field content how you want. In Drupal 6 this basicaly means a theme function.

As an example, we will build a formatter for the field type 'nodereference'.
This type of field, which is part of the standard CCK package, allows you to "reference" a node inside another.
The formatter that nodereference has by default, prints a standard link to the referenced node.

We are going to give the users other options, allowing them choose if they want the link to open in a new window or, if they have the popups module activated, that it opens in a jQuery modal window.

Let's call our module 'formattertest'.

Step 1: Declare our CCK formatters

To do this, the only thing needed is to implement our hook_field_formatter_info() in our module:

* Implementation of hook_field_formatter_info().
* Here we define an array with the options we will provide in display fields page
* The array keys will be used later in hook_theme and theme_

function formattertest_field_formatter_info() {
$formatters = array(
'newwindow' => array(
'label' => t('Open in new window link'),
'field types' => array('nodereference'),
'description' => t('Displays a link to the referenced node that opens in a new window.'),
  if (
module_exists('popups')) {
$formatters['popup'] = array(
'label' => t('Open in a popup window'),
'field types' => array('nodereference'),
'description' => t('Displays a link to the referenced node that opens in a jQuery modal window.'),

In this function, you have to return an arrays of arrays, that define each formatter that the module provides.

  • label: The name that the user will choose in the display fields configuration page
  • field types: an array with the types of cck fields that the formatter supports.

It's important to remember that the array keys you use, in our case 'newwindow' and 'popup', will be used later on to construct our functions hook_theme and theme_.
Note that in the second formatter, first we check if the module popups is active in the system, and then we add our formatter array that makes use of it.

2. Implement hook_theme

In hook_theme() you also return an array of arrays, defining the theme_ functions that will take care of rendering the cck field content. 'element' will be the content of the cck field, that will be used as the parameter for our theme function.

* Implementation of hook_theme().
* We declare our theme functions according to the array keys in  hook_field_formatter_info
function formattertest_theme() {
$theme = array(
'formattertest_formatter_newwindow' => array(
'arguments' => array('element' => NULL),
  if (
module_exists('popups')) {
$theme['formattertest_formatter_popup'] = array('arguments' => array('element' => NULL));

'formattertest_formatter_newwindow' and 'formattertest_formatter_popup' will be used to build our functions in the next step.

3. Build our theme functions.

Remember taht you can do dsm($element); (if you have devel installed), to see what you have to play with ;)

* Theming functions for our formatters
* And here we do our magic. You can use dsm($element) to see what you have to play with (requires devel module).
function theme_formattertest_formatter_newwindow($element) {
$output = '';
  if (!empty(
$element['#item']['nid']) && is_numeric($element['#item']['nid']) && ($title = _nodereference_titles($element['#item']['nid']))) {
$output = l($title, 'node/'. $element['#item']['nid'], array('attributes' => array('target' => 'blank_')));

/* Theme function for popup links */
function theme_formattertest_formatter_popup($element) {
$nid = $element['#item']['nid'];
$link_id = 'popup-'. $nid; // we want an unique id for each link so we can tell popups api to only do those =)
$output = '';
  if (!empty(
$nid) && is_numeric($nid) && ($title = _nodereference_titles($nid))) {
$output = l($title, 'node/'. $nid, array('attributes' => array('id' => $link_id)));
popups_add_popups(array('#'. $link_id));

In the first function, we start from the formatter that nodreference has by default, and we just add a target="_blank" so that the browser opens it in a new window.

In the second function, first we put inside the variable $nid the nid of the referenced node, in order to build the id that we'll use on the link ($link_id). We need this so that we can tell popups to only use the js on those specific link. That way we avoid having to scan the whole document for popup links, making our site faster in the front end.


Imagine for example, that your module also provides a default view. You can then use this view to pull out information depending on the content of a cck field. Any cck field that is using your formatter. No longer would you have to write complex and hard to maintain code in your template.php. You could just assign your formatter to any new field you create on any content type, reusing the same code.

formattertest.tar.gz1.22 KB

15 responses to this article.


Intimately, the article is

Intimately, the article is really the sweetest on this worthwhile topic. I harmonise with your conclusions and will eagerly look forward to your approaching updates. Just saying thanks will not just be adequate, for the phenomenal clarity in your writing. I will immediately grab your rss feed to stay abreast of any updates. Fabulous work and much success in yourbusiness efforts!
casino en ligne


Many thanks for your kind

Many thanks for your kind comments, I'm glad you found it useful. These kinds of comments give me motivation to write more articles like this - much appreciated!


Keep on writing, great job!

Keep on writing, great job!


Hi manuee, Great article, I

Hi manuee,

Great article, I only stumbled across it the other day and have already recommended it as a source to others wanting to know how to create a custom CCK Formatter.

But I wanted to let you know that your article, and a feature request for one of my modules, prompted me to write a module to simplify this process somewhat, a module that allows users to create a custom CCK Formatter inside of Drupal without the need to create a custom module to do so.

The module is called 'Custom Formatters', and you can get it at or I hope you find it of some interest.

Stuart Clark.


Thanks !! One spot I got

Thanks !!

One spot I got hung up on was I omitted _formatter_ hook. IT MUST BE USED to make it work. Joy this is pretty damn cool.


help a lot, thanks

help a lot, thanks


Thanks - just when I really

Thanks - just when I really needed it.


I like the module very mutch

I like the module very mutch bud I don't know how to start.
Can you tell me in Rookie languages how-to add pictures to THE galleryformatter. Thx


Note that you have to go to

Note that you have to go to the "Manage fields" tab to get the new formatters refreshed.

Took me some time to figure it out...


Hi, thanks for your post, I


thanks for your post, I had the hardest time figuring out how to add jQuery popups, thanks a lot.

Andrew Dickens


Great article with some very

Great article with some very clear examples. Thanks a lot pal, helped me understand this important feature.


I just moved two formatters

I just moved two formatters (that I've made earlier with Custom Formatters) to their designated place, a custom module with the help of your article. Thanks a lot!


excellent work- this code

excellent work- this code helped me bunches <


Thanks for the great

Thanks for the great post.
I'm trying to port jEditable to D7 version, see
Would this technique be the same for drupal 7, or how is it different in Drupal 7?
Any tips would be very appreciated!


Well I never used jEditable

Well I never used jEditable Ted, but I know in D7 you can use , give it a try!