field_format() is just a pile of code that doesn't work

Closed #491640: move field_view_field() to _field_invoke() single-field mode as 'won't fix' in the light of the above.

see my OP: field_attach_view() will take display settings saved in the $instance definition in the db. The intent of field_display_field() is to provide display settings on-the-fly, independently of whatever existing build modes or what's stored in the $instance definition. When displaying a field in a Panel pane, you want to specify the display settings within the Pane config screen, not in field UI 'Manage Display'.

Attached patch tackles field_view_field().

API changes:

- field_view_field() is gone (was broken anyway), renamed to field_build_field() since it returns a renderable array.

/**
 * Returns a renderable array for the value of a single field in an object.
 *
 * The resulting output is a fully themed field with label and multiple values.
 *
 * @param $obj_type
 * @param $object
 * @param $field_name
 * @param $display
 *   Can be either:
 *   - the name of a build mode
 *   - or an array of display settings to use for display, as found in the
 *   'display' entry of $instance definitions. @todo actual description and default values.
 * @param $langcode
 *   (Optional) The language the field values are to be shown in. If no language is
 *   provided the current language will be used.
 */
function field_build_field($obj_type, $object, $field_name, $display = array(), $langcode = NULL) {

(see patch for the full PHPdoc)

- hook_field_formatter_prepare_view() receives an array of display settings instead of previously a build mode for which they had to extract the display settings in $instance['display'][$build_mode] themselves.

-function hook_field_formatter_prepare_view($obj_type, $objects, $field, $instances, $langcode, &$items, $build_mode) {
+function hook_field_formatter_prepare_view($obj_type, $objects, $field, $instances, $langcode, &$items, $displays) {

Should affect very little existing code (rare hook). Only core implementation (taxonomy) didn't even use that param.

Internal changes:

- field_default_* functions involved in the 'display' workflow can accept a build_mode or (new) an array of custom display settings. Impacts field_default_prepare_view(), field_default_view().

- code in _field_info_prepare_instance() that massages 'display' settings for the current execution context factored out to a new _field_info_prepare_instance_display() helper. For consistency, same logic applied for widgets: new _field_info_prepare_instance_widget().

- fixes _field_invoke_multiple(), the $options param is not supposed to be passed to the invoked hooks. _field_invoke() doesn't do this.

Typo in the new _field_info_prepare_instance_widget(). That one should pass.

Easier tracking.

Rerolled + added some tests.

Rerolled after the various formatter API refactorings.
The needed API changes to allow displaying a field using one-off custom display settings have been rolled in #652834: Field formatters as render arrays, so no additional API change here.
Also, reverted the renaming of field_view_field() to field_build_field(), as per the general direction in #658364: Does build/view/formatter terminology make sense?. Field API consistently uses 'view'.

Re moshe #11
1. I'd tend to agree, but core is currently much more consistent on 'renderable arrays'.
2. The explanation is given in the PHPdoc for _field_info_prepare_instance(): " Since the instance was last saved or updated, a number of things might have changed: widgets or formatters disabled, new settings expected, new build modes added...". I'm not sure it's worth repeating, those are internal helper functions.
3. Indeed. removed that hunk.

Oops 80 lines wrap.

Fixed duplicate call to field_info_field() in field_view_field().

Ah, yes, I must be tired :-p.
Updated patch.

Note this patch only deals with field_view_field() (return render array for fully themed 'field' with all values).
field_format() (apply a formatter on a single field value) is still TODO (doesn't have to go in in the same commit, though).

LOL.

1) and 4) fixed.

+    drupal_alter('field_attach_view', $result, $context);

Hm... is this alter hook mismatch desired? Backwards compatibility?

Desired, because we want 3rd party modules to do the same alterations on one-off field displays than when a full object is rendered through field_attach_view().

This triggers the question whether 'full' shouldn't be 'default' in reality... not to be discussed here

I've been wondering this for quite a while. Technically I agree - then again: I'm not sure it should be the same as 'full'.
Do we want users to see 'Default' instead of 'Full node' when they want to configure the fields display for the main node page ?
Different issue indeed. Right now this patch is consistent on that aspect with what currently happens when a displaying a build mode the user has not configured yet - see // Fallback to 'full' display settings for unspecified build modes in _field_info_prepare_instance() .

Added a comment about hook_field_attach_view_alter()

Thks Dries. As per #16, reopening for the 2nd part - field_format().

re sun #17: "This triggers the question whether 'full' shouldn't be 'default' in reality". Opened #664544: Clean-up entity build/view modes

Oops. Sorry 'bout that. We sure miss the bot :-p.

Back to active for the remaining task.

Critical as in "the current field_format() function is just a pile of code that simply doesn't work".

I have some code, will try to polish and post a patch asap. Tough week ahead.

Sorry for not chiming in earlier, RL struck hard the last couple weeks.

field_view_field() returns a render array for a fully themed field ('#theme' => 'field'), with wrapping HTML, label, multiple values and RDF data - just like you'd find in a displayed node. Views (at least in D6) only displays individual field values, and takes care of the wrapping HTML and label display using its own mechanisms.

Also, theme('field') adds a non-negligible overhead vs. simply displaying a formatted field value. This was battled for months in #438570: Field API conversion leads to lots of expensive function calls and #659788: [meta issue] theme('field') is too slow, which is inhibiting its more widespread use; effulgentsia mitigated this in a awesome way in #652246: Optimize theme('field') and use it for comment body, but the cost is not negligible still.

So saying 'render this field, just hide the label', when all you want is just to run a given field value through a given formatter, is very unefficient. Would make a noticeable difference on a View displaying 10 entities with possibly 10 "field values" each.

However, it is doable to rely on field_view_field() to generate the render array for the whole field, and just grab the subpart we need, containing the render array for the specific value we want, as returned by the formatter. We reuse (not-so-simple) code, and the time spent in generating the wrapping array is negligible.

Attached patch does that
+ renames the function from field_format() (D7 only, never worked) to field_view_value(), for consistency with field_view_field()
+ adds tests for the function.

This field_view_value() won't give you the RDF wrapping, BTW. I'm not sure how Views wants to behave regarding RDF output, but I don't think it can afford the overhead of a full field theme "just" to get RDF data. IMO Views will need to add RDF data on its own (it will probably need to find a generic, Field + non-Field way to do so, I guess)

fix coding style

#access : indeed :-). Fixed.

re @plach #39: $item param in field_view_value() is already a value in a given language (e.g taken from some $entity->field_foo[$some_lang][$some_delta]). The $langcode param is there as a hint, because some formatters need to know the language of the value being rendered, and this is not available in the $item itself. So, yes, in a sense it's language agnostic.

Yet the code internally sticks the $item in a fake $cloned object to call field_view_field(), and thus relies on field_multilingual_available_languages() to determine the $langcode that will be used down the line in _field_invoke(). Whatever #657972: Make field fallback logic actually reusable refactors around there will need to be reflected here.

forgot the fixed patch.

Looks like Dries committed this earlier tonight.

Well, the upgrade guide doesn't mention any of the CCK D6 API funcs that have changed names while moving to fields.module D7...

@mcfilms : This is not related to the current thread. Could you open a separate issue ?

+ marking as 'fixed'.
This does not belong to the 6/7 upgrade page, the field_view_field() function had no equivalent in core D6.