googletorp.com

A field formatter is what CCK uses to format it's fields or in Drupal terms: theme. All that a formatter really is, is a theme function that's designed for CCK. Where ever a field is displayed it can have several options as to how it should be displayed. One example could be link fields which by default can be displayed in different ways, title as link, URL as link etc. This can be selected as standard for the node full and teaser views, but can also be used in different views where you thus can display the same field in different ways.

The hardest thing about making a formatter for fields, is finding out how you make something that CCK can understand and will know about, the rest is pretty much like any other theme function. The tricky part here is that CCK doesn't have that much documentation, which makes finding out how to do these things more difficult. The way I figured out how to do what I needed, was mostly looking at how others did it in various modules. So this will be a quick 3 step walkthrough of what I've find during my search and experimentation.

Step 1

What you need to do first, is to make an inplementation of hook_field_formatter_info. This is what tells CCK that your formatter exists. That way CCK will present it as a display option where needed. In code this looks like this.

function module_name_field_formatter_info() {
    $item = array();
    $item['formatter_name'] = array(
        'label' => t('The label which is what will be shown in the AI'),
        'field types' => array('link'), // an array of field types where for which the formatter can be used
        'multiple values' => CONTENT_HANDLE_CORE,
     );
     return $items;
}

Label and field types are pretty easy to understand. At the time of writing I can't remember how multiple values work exactly. It was something I didn't need to explore as my fields didn't have multiple values. But I believe that you can decide if cck or your something else should determine how multiple values should be handled. Maybe wanted to make 1 table with all the values instead of 1 table for each value or something similar.

In the example above I used the field type link, which is for link fields. This was what I needed to make a formatter for, since the site I was building was selling clicks. A lot of tracking was also involved so being able to control the output of the link was very important. All the links was external of cause, but to be able to do tracking and such we wanted to create an internal URL instead. We could then react on that, store useful information we needed and redirect to the actual url. This is just a simple use case, of how controlling the output can be very important and that the actual output you generate can be very different from what is "normal".

Step 2

Amyways once you have made your implementation of hook_field_formatter_info, the rest is pretty easy.

Implementation of hook_theme, is the next step, which is pretty much like usual, except you need to add formatter to the theme name so you get a theme name that looks like A_formatter_B, where A is the module name and B is the formatter name:

function module_name_theme() {
    $items =  array();
    $items['module_name_formatter_formatter_name'] = array(
        'arguments' => array('element' => NULL),
    );
    return $items;

Step 3

The only thing that's left if to create the actual theme function, which is just like you would expect. You just prepend _theme to the name.

function  theme_module_name_formatter_formatter_name($element) {
     // Do your stuff here.
}

One thing that you need to be aware of, is that $element will vary a bit in different cases. These are not big chances, but you should be aware that there can be changes, especially when you use the formatter in a normal node display vs using it for a field in views.

That's all there is to it, you can now create your own CCK field formatters.