I'm working on beefing up some of the internal documentation on how the formatters work now. I'm porting the Date module and ran into lots of questions about how to do this so I'm adding documentation as I go.

I'm committing an initial round of documentation additions to explain that we now use drupal_render() to place the field's content in a custom template, explain when you'd use content_format(), move the example formatted node arrays up into the PHP docs, add the multiple value option to the core formatters so you can see where you would put a custom multiple value formatter, etc.

I still want to go back and fix up the documentation in the example code, but that is not done yet.

One question for yched, how would you describe the right place to use the new 'sanitize' field operation? That was one thing that seemed confusing to me so I want to clarify it.

Comments

yched’s picture

yched commented

Thanks for this, Karen. I'll try to update http://drupal.org/node/191796 later tonight.
I'll also update one of the example files with the 'dummy' multiple formatter I used in the 'formatters refactoring' patch, as a sample of how they should be coded.

I'm not sure I get your question. The 'sanitize' op should be implemented by every field module whose data needs to go through a check_plain or check_markup before being handed to the theme. I'd say this is about every field that stores textual data.
More generally, that's where you put any data massaging you don't want to be overridable in the theme.

karens’s picture

karens commented

I did some work on http://drupal.org/node/191796 and in the example field modules, but there is probably more to do.

My point about sanitize is that we don't really say anywhere what it is or what it is for, or for that matter, why we do it there instead of in the theme, which is where we did it in D5, so that needs more explanation. It was also hard to figure out where in the field module to implement it, so it should be added to the example field modules, too.

One more question that I found confusing, why do we use CONTENT_HANDLE_CORE and CONTENT_HANDLE_CUSTOM on the formatter multiple values? It's not really about whether it is handled by core or not, it's about whether it will theme a single element or multiple elements. It seems to me that that is a TRUE/FALSE question instead. Is this a formatter that handles multiples? If true, the content module will add it to the node array in the multiple value manner. If false, the content module will add it to the node in the single value manner. Either way, the content module adds it to the node and the field module provides an appropriate theme.

ugerhard’s picture

ugerhard commented

Is hook_field_formatter() still used by CCK 2 at all?

It's used in the /examples fields, but nowhere else in CCK as far as I can see.

I stumbled across this question when trying to use and looking at the D6 version of lightbox2, which still uses hook_field_formatter(), which seems never to get called.

ugerhard’s picture

ugerhard commented
Version: 6.x-1.x-dev » 6.x-2.x-dev

Changing version

karens’s picture

karens commented

The themeing was completely reworked after this issue was originally created. See #294797: 'full field' variable in node.tpl.php for the latest activity.

The function hook_field_formatter() is deprecated and is not used by any of the core CCK modules. I do see that it is still in the example code, so that needs to be updated.

Actually, we should just remove those examples, it is too much work to keep them current, so it's always better to use one of the core modules as an example anyway.

So this is still a task that needs to be done -- get the latest method completely documented.

bdragon’s picture

bdragon commented

This is still an issue.

'sanitize' still isn't documented, and only appears in text.module.

What is the "latest method", and did it pan out?

Grep of contrib for case 'sanitize':

addresses/Attic/addresses_cck.module,v:    case 'sanitize':
amazon/asin/asin.module,v:    case 'sanitize':
amazon/asin.module,v:    case 'sanitize':
barcode/barcode.module,v:    case 'sanitize':
cck/Attic/text.module,v:    case 'sanitize':
cck/modules/text/Attic/text.module,v:    case 'sanitize':
cck/fields/modules/text/Attic/text.module,v:    case 'sanitize':
cck.pre-rename/text.module,v:    case 'sanitize':
cdn2/cdn2_field.inc,v:    case 'sanitize':
date/date/date.module,v:    case 'sanitize':
duration/duration.module,v:    case 'sanitize':
email/email.module,v:    case 'sanitize':
email/email.module,v:@fixes case 'sanitize' in hook_field
emfield/Attic/emfield.cck.inc,v:        case 'sanitize':
emfield/Attic/emfield.cck.inc,v:  case 'sanitize':
filefield/filefield.module,v:    case 'sanitize':
fivestar/fivestar_field.inc,v:    case 'sanitize':
flashfield/flashfield.module,v:    case 'sanitize':
flexifield/flexifield.module,v:    case 'sanitize':
fusioncharts/fusioncharts_cck/Attic/fusioncharts_cck.module,v:    case 'sanitize':
gallery_addon/gallery_field/gallery_field.module,v:    case 'sanitize':
gmapfield/gmapfield.module,v:    case 'sanitize':
iframe/iframe.module,v:    case 'sanitize':
imagefield/imagefield.module,v:    case 'sanitize':
kaltura/plugins/field_kaltura/field_kaltura.module,v:    case 'sanitize':
kaltura/plugins/field_kaltura/field_kaltura.module,v:    case 'sanitize':
kaltura/plugins/field_kaltura/field_kaltura.module,v:    case 'sanitize':
kaltura/plugins/field_kaltura/field_kaltura.module,v:    case 'sanitize':
kaltura_drupal_6/plugins/field_kaltura/Attic/field_kaltura.module,v:    case 'sanitize':
link/link.module,v:    case 'sanitize':
relevant_content/relevant_content_cck/Attic/relevant_content_cck.module,v:    case 'sanitize' :

References:

#213279: Formatters refactoring
#247932: CCK needs better documentation...

drewish’s picture

drewish commented

subscribing...