field_collection.api.php 5.88 KB
Newer Older
1
2
3
4
<?php

/**
 * @file
5
 * Contains API documentation and examples for the Field Collection.
6
7
 */

8
9
10
11
12
/**
 * @addtogroup hooks
 * @{
 */

13
14
15
16
17
18
/**
 * Alter whether a field collection item is considered empty.
 *
 * This hook allows modules to determine whether a field collection is empty
 * before it is saved.
 *
Ra Mänd's avatar
Ra Mänd committed
19
 * @param bool $is_empty
20
21
22
23
24
25
26
27
28
 *   Whether or not the field should be considered empty.
 * @param FieldCollectionItemEntity $item
 *   The field collection we are currently operating on.
 */
function hook_field_collection_is_empty_alter(&$is_empty, FieldCollectionItemEntity $item) {
  if (isset($item->my_field) && empty($item->my_field)) {
    $is_empty = TRUE;
  }
}
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

/**
 * Acts on field collections being loaded from the database.
 *
 * This hook is invoked during field collection item loading, which is handled
 * by entity_load(), via the EntityCRUDController.
 *
 * @param array $entities
 *   An array of field collection item entities being loaded, keyed by id.
 *
 * @see hook_entity_load()
 */
function hook_field_collection_item_load(array $entities) {
  $result = db_query('SELECT pid, foo FROM {mytable} WHERE pid IN(:ids)', array(':ids' => array_keys($entities)));
  foreach ($result as $record) {
    $entities[$record->pid]->foo = $record->foo;
  }
}

/**
 * Responds when a field collection item is inserted.
 *
 * This hook is invoked after the field collection item is inserted into the
 * database.
 *
 * @param FieldCollectionItemEntity $field_collection_item
 *   The field collection item that is being inserted.
 *
 * @see hook_entity_insert()
 */
function hook_field_collection_item_insert(FieldCollectionItemEntity $field_collection_item) {
  db_insert('mytable')->fields(array(
    'id' => entity_id('field_collection_item', $field_collection_item),
    'extra' => print_r($field_collection_item, TRUE),
  ))->execute();
}

/**
 * Acts on a field collection item being inserted or updated.
 *
Ra Mänd's avatar
Ra Mänd committed
69
70
 * This hook is invoked before the field collection item is saved to the
 * database.
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 *
 * @param FieldCollectionItemEntity $field_collection_item
 *   The field collection item that is being inserted or updated.
 *
 * @see hook_entity_presave()
 */
function hook_field_collection_item_presave(FieldCollectionItemEntity $field_collection_item) {
  $field_collection_item->name = 'foo';
}

/**
 * Responds to a field collection item being updated.
 *
 * This hook is invoked after the field collection item has been updated in the
 * database.
 *
 * @param FieldCollectionItemEntity $field_collection_item
 *   The field collection item that is being updated.
 *
 * @see hook_entity_update()
 */
function hook_field_collection_item_update(FieldCollectionItemEntity $field_collection_item) {
  db_update('mytable')
    ->fields(array('extra' => print_r($field_collection_item, TRUE)))
    ->condition('id', entity_id('field_collection_item', $field_collection_item))
    ->execute();
}

/**
 * Responds to field collection item deletion.
 *
 * This hook is invoked after the field collection item has been removed from
 * the database.
 *
 * @param FieldCollectionItemEntity $field_collection_item
 *   The field collection item that is being deleted.
 *
 * @see hook_entity_delete()
 */
function hook_field_collection_item_delete(FieldCollectionItemEntity $field_collection_item) {
  db_delete('mytable')
    ->condition('pid', entity_id('field_collection_item', $field_collection_item))
    ->execute();
}

/**
 * Act on a field collection item that is being assembled before rendering.
 *
 * @param $field_collection_item
 *   The field collection item entity.
 * @param $view_mode
 *   The view mode the field collection item is rendered in.
 * @param $langcode
 *   The language code used for rendering.
 *
 * The module may add elements to $field_collection_item->content prior to
 * rendering. The structure of $field_collection_item->content is a renderable
 * array as expected by drupal_render().
 *
 * @see hook_entity_prepare_view()
 * @see hook_entity_view()
 */
function hook_field_collection_item_view($field_collection_item, $view_mode, $langcode) {
  $field_collection_item->content['my_additional_field'] = array(
    '#markup' => $additional_field,
    '#weight' => 10,
    '#theme' => 'mymodule_my_additional_field',
  );
}

/**
 * Alter the results of entity_view() for field collection items.
 *
Ra Mänd's avatar
Ra Mänd committed
144
 * This hook is called after the content has been assembled in a structured
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 * array and may be used for doing processing which requires that the complete
 * field collection item content structure has been built.
 *
 * If the module wishes to act on the rendered HTML of the field collection item
 * rather than the structured content array, it may use this hook to add a
 * #post_render callback. See drupal_render() and theme() documentation
 * respectively for details.
 *
 * @param $build
 *   A renderable array representing the field collection item content.
 *
 * @see hook_entity_view_alter()
 */
function hook_field_collection_item_view_alter($build) {
  if ($build['#view_mode'] == 'full' && isset($build['an_additional_field'])) {
    // Change its weight.
    $build['an_additional_field']['#weight'] = -10;

    // Add a #post_render callback to act on the rendered HTML of the entity.
    $build['#post_render'][] = 'my_module_post_render';
  }
}

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
/**
 * Alter the label for a field collection.
 *
 * @param FieldCollectionItemEntity $item
 *   The field collection item object.
 * @param $host
 *   The host entity of the field collection item.
 * @param $field
 *   The field information about the item.
 *
 * @return $label
 *   A string to represent the label for this item type.
 */
function hook_field_collection_item_label($item, $host, $field) {
  switch ($item->field_name) {
    case 'field_my_first_collection':
      $item_wrapper = entity_metadata_wrapper('field_collection_item', $item);

Ra Mänd's avatar
Ra Mänd committed
186
      $title = $item_wrapper->field_title->value();
187
188
189
190
191
192
193
      $author = $item_wrapper->field_author->value();

      return "{$title} by {$author}";
  }
}


194
195
/**
 * @}
196
 */