Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

How to create a CCK formatter

Parent Feed: 

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:

<?php
/**
* 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.'),
    );
  }
  return
$formatters;
}
?>

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.

<?php
/**
* 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));
  }
  return
$theme;
}
?>

'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 ;)

<?php
/**
* 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_')));
  }
  return
$output;
}
/* 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));
  return
$output;
}
?>

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.

Conclusion.

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.

Attachment Size
formattertest.tar.gz 1.22 KB
Author: 
Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web