Commit 1a251a74 authored by webchick's avatar webchick

#361839 by puradata and yched: Document return structures from field attach.

parent a45e7925
......@@ -58,14 +58,16 @@ class FieldQueryException extends FieldException {}
*/
/**
* Argument for an insert operation.
* Argument for an update operation.
*
* This is used in hook_field_storage_write when updating an
* existing object.
*/
define('FIELD_STORAGE_UPDATE', 'update');
/**
* Argument for an update operation.
* Argument for an insert operation.
*
* This is used in hook_field_storage_write when inserting a new object.
*/
define('FIELD_STORAGE_INSERT', 'insert');
......@@ -353,9 +355,65 @@ function _field_invoke_multiple_default($op, $obj_type, $objects, &$a = NULL, &$
* The form structure to fill in.
* @param $form_state
* An associative array containing the current state of the form.
* @return
* The form elements are added by reference at the top level of the $form
* parameter. Sample structure:
* @code
* array(
* '#fields' => array(
* // One sub-array per field appearing in the form, keyed by field name.
* 'field_foo' => array (
* 'field' => the field definition structure,
* 'instance' => the field instance definition structure,
* 'form_path' => an array of keys indicating the path to the field
* element within the full $form structure, used by the 'add more
* values' AHAH button. Any 3rd party module using form_alter() to
* modify the structure of the form should update this entry as well.
* ),
* ),
*
* TODO : document the resulting $form structure, like we do for
* field_attach_view().
* // One sub-array per field appearing in the form, keyed by field name.
* // The structure of the array differs slightly depending on whether the
* // widget is 'single-value' (provides the input for one field value,
* // most common case), and will therefore be repeated as many times as
* // needed, or 'multiple-values' (one single widget allows the input of
* // several values, e.g checkboxes, select box...).
* 'field_foo' => array(
* '#field_name' => the name of the field,
* '#tree' => TRUE,
* '#required' => whether or not the field is required,
* '#title' => the label of the field instance,
* '#description' => the description text for the field instance,
*
* // Only for 'single' widgets:
* '#theme' => 'field_multiple_value_form',
* '#multiple' => the field cardinality,
* // One sub-array per copy of the widget, keyed by delta.
* 0 => array(
* '#title' => the title to be displayed by the widget,
* '#default_value' => the field value for delta 0,
* '#required' => whether the widget should be marked required,
* '#delta' => 0,
* '#field_name' => the name of the field,
* '#bundle' => the name of the bundle,
* '#columns' => the array of field columns,
* // The remaining elements in the sub-array depend on the widget.
* '#type' => the type of the widget,
* ...
* ),
* 1 => array(
* ...
* ),
*
* // Only for multiple widgets:
* '#bundle' => $instance['bundle'],
* '#columns' => array_keys($field['columns']),
* // The remaining elements in the sub-array depend on the widget.
* '#type' => the type of the widget,
* ...
* ),
* )
* @endcode
*/
function field_attach_form($obj_type, $object, &$form, &$form_state) {
$form += (array) _field_invoke_default('form', $obj_type, $object, $form, $form_state);
......@@ -879,6 +937,54 @@ function field_attach_query_revisions($field_name, $conditions, $count, &$cursor
* Build mode, e.g. 'full', 'teaser'...
* @return
* A structured content array tree for drupal_render().
* Sample structure:
* @code
* array(
* 'field_foo' => array(
* // The structure of the array differs slightly depending on whether
* // the formatter is 'single-value' (displays one single field value,
* // most common case) or 'multiple-values' (displays all the field's
* // values, e.g. points on a graph or a map).
* '#theme' => 'field',
* '#title' => the label of the field instance,
* '#label_display' => the label display mode,
* '#object' => the fieldable object being displayed,
* '#object_type' => the type of the object being displayed,
* '#build_mode' => the build mode,
* '#field_name' => the name of the field,
* '#single' => boolean indicating whether the formatter is single or
* multiple,
* 'items' => array(
* // One sub-array per field value, keyed by delta.
* 0 => array(
* '#item' => the field value for delta 0,
*
* // Only for 'single-value' formatters:
* '#theme' => the formatter's theme function,
* '#formatter' => name of the formatter,
* '#settings' => array of formatter settings,
* '#object' => the fieldable object being displayed,
* '#object_type' => the type of the object being displayed,
* '#field_name' => the name of the field,
* '#bundle' => the object's bundle,
* '#delta' => 0,
* ),
* 1 => array(
* ...
* ),
*
* // Only for 'multiple-values' formatters:
* '#theme' => the formatter's theme function,
* '#formatter' => name of the formatter,
* '#settings' => array of formatter settings,
* '#object' => the fieldable object being displayed,
* '#object_type' => the type of the object being displayed,
* '#field_name' => the name of the field,
* '#bundle' => the object's bundle,
* ),
* ),
* );
* @endcode
*/
function field_attach_view($obj_type, $object, $build_mode = 'full') {
// Let field modules sanitize their data for output.
......
......@@ -50,63 +50,10 @@ function field_default_insert($obj_type, $object, $field, $instance, &$items) {
}
}
}
/**
* The 'view' operation constructs the $object in a way that you can use
* drupal_render() to display the formatted output for an individual field.
* i.e. print drupal_render($object->content['field_foo']);
*
* The code supports both single value formatters, which theme an individual
* item value, and multiple value formatters, which theme all values for the
* field in a single theme. The multiple value formatters could be used, for
* instance, to plot field values on a single map or display them in a graph.
* Single value formatters are the default, multiple value formatters can be
* designated as such in formatter_info().
* Default field 'view' operation.
*
* The $object array will look like:
* $object->content['field_foo'] = array(
* '#theme' => 'field',
* '#title' => 'label'
* '#field_name' => 'field_name',
* '#object' => $object,
* '#object_type' => $obj_type,
* // Value of the $build_mode param of hook_node('view').
* '#build_mode' => $build_mode,
* 'items' =>
* 0 => array(
* '#item' => $items[0],
* // Only for 'single-value' formatters
* '#theme' => $theme,
* '#field_name' => 'field_name',
* '#bundle' => $bundle,
* '#formatter' => $formatter_name,
* '#settings' => $formatter_settings,
* '#object' => $object,
* '#object_type' => $obj_type,
* '#delta' => 0,
* ),
* 1 => array(
* '#item' => $items[1],
* // Only for 'single-value' formatters
* '#theme' => $theme,
* '#field_name' => 'field_name',
* '#bundle' => $bundle_name,
* '#formatter' => $formatter_name,
* '#settings' => $formatter_settings,
* '#object' => $object,
* '#object_type' => $obj_type,
* '#delta' => 1,
* ),
* // Only for 'multiple-value' formatters
* '#theme' => $theme,
* '#field_name' => 'field_name',
* '#bundle' => $bundle_name,
* '#formatter' => $formatter_name,
* '#settings' => $formatter_settings,
* '#object' => $object,
* '#object_type' => $obj_type,
* ),
* );
* @see field_attach_view()
*/
function field_default_view($obj_type, $object, $field, $instance, $items, $build_mode) {
list($id, $vid, $bundle) = field_attach_extract_ids($obj_type, $object);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment