| Drupal | PHP Cross Reference | Content Management Systems |
1 <?php 2 3 /** 4 * @addtogroup hooks 5 * @{ 6 */ 7 8 /** 9 * Exposes "pseudo-field" components on fieldable entities. 10 * 11 * Field UI's "Manage fields" and "Manage display" pages let users re-order 12 * fields, but also non-field components. For nodes, these include the title, 13 * poll choices, and other elements exposed by modules through hook_form() or 14 * hook_form_alter(). 15 * 16 * Fieldable entities or modules that want to have their components supported 17 * should expose them using this hook. The user-defined settings (weight, 18 * visible) are automatically applied on rendered forms and displayed 19 * entities in a #pre_render callback added by field_attach_form() and 20 * field_attach_view(). 21 * 22 * @see _field_extra_fields_pre_render() 23 * @see hook_field_extra_fields_alter() 24 * 25 * @return 26 * A nested array of 'pseudo-field' components. Each list is nested within 27 * the following keys: entity type, bundle name, context (either 'form' or 28 * 'display'). The keys are the name of the elements as appearing in the 29 * renderable array (either the entity form or the displayed entity). The 30 * value is an associative array: 31 * - label: The human readable name of the component. 32 * - description: A short description of the component contents. 33 * - weight: The default weight of the element. 34 */ 35 function hook_field_extra_fields() { 36 $extra['node']['poll'] = array( 37 'form' => array( 38 'choice_wrapper' => array( 39 'label' => t('Poll choices'), 40 'description' => t('Poll choices'), 41 'weight' => -4, 42 ), 43 'settings' => array( 44 'label' => t('Poll settings'), 45 'description' => t('Poll module settings'), 46 'weight' => -3, 47 ), 48 ), 49 'display' => array( 50 'poll_view_voting' => array( 51 'label' => t('Poll vote'), 52 'description' => t('Poll vote'), 53 'weight' => 0, 54 ), 55 'poll_view_results' => array( 56 'label' => t('Poll results'), 57 'description' => t('Poll results'), 58 'weight' => 0, 59 ), 60 ) 61 ); 62 63 return $extra; 64 } 65 66 /** 67 * Alter "pseudo-field" components on fieldable entities. 68 * 69 * @param $info 70 * The associative array of 'pseudo-field' components. 71 * 72 * @see hook_field_extra_fields() 73 */ 74 function hook_field_extra_fields_alter(&$info) { 75 // Force node title to always be at the top of the list by default. 76 foreach (node_type_get_types() as $bundle) { 77 if (isset($info['node'][$bundle->type]['form']['title'])) { 78 $info['node'][$bundle->type]['form']['title']['weight'] = -20; 79 } 80 } 81 } 82 83 /** 84 * @defgroup field_types Field Types API 85 * @{ 86 * Define field types. 87 * 88 * In the Field API, each field has a type, which determines what kind of data 89 * (integer, string, date, etc.) the field can hold, which settings it provides, 90 * and so on. The data type(s) accepted by a field are defined in 91 * hook_field_schema(); other basic properties of a field are defined in 92 * hook_field_info(). The other hooks below are called by the Field Attach API 93 * to perform field-type-specific actions. 94 * 95 * The Field Types API also defines two kinds of pluggable handlers: widgets 96 * and formatters. @link field_widget Widgets @endlink specify how the field 97 * appears in edit forms, while @link field_formatter formatters @endlink 98 * specify how the field appears in displayed entities. 99 * 100 * A third kind of pluggable handlers, storage backends, is defined by the 101 * @link field_storage Field Storage API @endlink. 102 * 103 * See @link field Field API @endlink for information about the other parts of 104 * the Field API. 105 */ 106 107 /** 108 * Define Field API field types. 109 * 110 * @return 111 * An array whose keys are field type names and whose values are arrays 112 * describing the field type, with the following key/value pairs: 113 * - label: The human-readable name of the field type. 114 * - description: A short description for the field type. 115 * - settings: An array whose keys are the names of the settings available 116 * for the field type, and whose values are the default values for those 117 * settings. 118 * - instance_settings: An array whose keys are the names of the settings 119 * available for instances of the field type, and whose values are the 120 * default values for those settings. Instance-level settings can have 121 * different values on each field instance, and thus allow greater 122 * flexibility than field-level settings. It is recommended to put settings 123 * at the instance level whenever possible. Notable exceptions: settings 124 * acting on the schema definition, or settings that Views needs to use 125 * across field instances (for example, the list of allowed values). 126 * - default_widget: The machine name of the default widget to be used by 127 * instances of this field type, when no widget is specified in the 128 * instance definition. This widget must be available whenever the field 129 * type is available (i.e. provided by the field type module, or by a module 130 * the field type module depends on). 131 * - default_formatter: The machine name of the default formatter to be used 132 * by instances of this field type, when no formatter is specified in the 133 * instance definition. This formatter must be available whenever the field 134 * type is available (i.e. provided by the field type module, or by a module 135 * the field type module depends on). 136 * - no_ui: (optional) A boolean specifying that users should not be allowed 137 * to create fields and instances of this field type through the UI. Such 138 * fields can only be created programmatically with field_create_field() 139 * and field_create_instance(). Defaults to FALSE. 140 * 141 * @see hook_field_info_alter() 142 */ 143 function hook_field_info() { 144 return array( 145 'text' => array( 146 'label' => t('Text'), 147 'description' => t('This field stores varchar text in the database.'), 148 'settings' => array('max_length' => 255), 149 'instance_settings' => array('text_processing' => 0), 150 'default_widget' => 'text_textfield', 151 'default_formatter' => 'text_default', 152 ), 153 'text_long' => array( 154 'label' => t('Long text'), 155 'description' => t('This field stores long text in the database.'), 156 'settings' => array('max_length' => ''), 157 'instance_settings' => array('text_processing' => 0), 158 'default_widget' => 'text_textarea', 159 'default_formatter' => 'text_default', 160 ), 161 'text_with_summary' => array( 162 'label' => t('Long text and summary'), 163 'description' => t('This field stores long text in the database along with optional summary text.'), 164 'settings' => array('max_length' => ''), 165 'instance_settings' => array('text_processing' => 1, 'display_summary' => 0), 166 'default_widget' => 'text_textarea_with_summary', 167 'default_formatter' => 'text_summary_or_trimmed', 168 ), 169 ); 170 } 171 172 /** 173 * Perform alterations on Field API field types. 174 * 175 * @param $info 176 * Array of information on field types exposed by hook_field_info() 177 * implementations. 178 */ 179 function hook_field_info_alter(&$info) { 180 // Add a setting to all field types. 181 foreach ($info as $field_type => $field_type_info) { 182 $info[$field_type]['settings'] += array( 183 'mymodule_additional_setting' => 'default value', 184 ); 185 } 186 187 // Change the default widget for fields of type 'foo'. 188 if (isset($info['foo'])) { 189 $info['foo']['default widget'] = 'mymodule_widget'; 190 } 191 } 192 193 /** 194 * Define the Field API schema for a field structure. 195 * 196 * This hook MUST be defined in .install for it to be detected during 197 * installation and upgrade. 198 * 199 * @param $field 200 * A field structure. 201 * 202 * @return 203 * An associative array with the following keys: 204 * - columns: An array of Schema API column specifications, keyed by column 205 * name. This specifies what comprises a value for a given field. For 206 * example, a value for a number field is simply 'value', while a value for 207 * a formatted text field is the combination of 'value' and 'format'. It is 208 * recommended to avoid having the column definitions depend on field 209 * settings when possible. No assumptions should be made on how storage 210 * engines internally use the original column name to structure their 211 * storage. 212 * - indexes: (optional) An array of Schema API indexes definitions. Only 213 * columns that appear in the 'columns' array are allowed. Those indexes 214 * will be used as default indexes. Callers of field_create_field() can 215 * specify additional indexes, or, at their own risk, modify the default 216 * indexes specified by the field-type module. Some storage engines might 217 * not support indexes. 218 * - foreign keys: (optional) An array of Schema API foreign keys 219 * definitions. 220 */ 221 function hook_field_schema($field) { 222 if ($field['type'] == 'text_long') { 223 $columns = array( 224 'value' => array( 225 'type' => 'text', 226 'size' => 'big', 227 'not null' => FALSE, 228 ), 229 ); 230 } 231 else { 232 $columns = array( 233 'value' => array( 234 'type' => 'varchar', 235 'length' => $field['settings']['max_length'], 236 'not null' => FALSE, 237 ), 238 ); 239 } 240 $columns += array( 241 'format' => array( 242 'type' => 'varchar', 243 'length' => 255, 244 'not null' => FALSE, 245 ), 246 ); 247 return array( 248 'columns' => $columns, 249 'indexes' => array( 250 'format' => array('format'), 251 ), 252 'foreign keys' => array( 253 'format' => array( 254 'table' => 'filter_format', 255 'columns' => array('format' => 'format'), 256 ), 257 ), 258 ); 259 } 260 261 /** 262 * Define custom load behavior for this module's field types. 263 * 264 * Unlike most other field hooks, this hook operates on multiple entities. The 265 * $entities, $instances and $items parameters are arrays keyed by entity ID. 266 * For performance reasons, information for all available entity should be 267 * loaded in a single query where possible. 268 * 269 * Note that the changes made to the field values get cached by the field cache 270 * for subsequent loads. You should never use this hook to load fieldable 271 * entities, since this is likely to cause infinite recursions when 272 * hook_field_load() is run on those as well. Use 273 * hook_field_formatter_prepare_view() instead. 274 * 275 * Make changes or additions to field values by altering the $items parameter by 276 * reference. There is no return value. 277 * 278 * @param $entity_type 279 * The type of $entity. 280 * @param $entities 281 * Array of entities being loaded, keyed by entity ID. 282 * @param $field 283 * The field structure for the operation. 284 * @param $instances 285 * Array of instance structures for $field for each entity, keyed by entity 286 * ID. 287 * @param $langcode 288 * The language code associated with $items. 289 * @param $items 290 * Array of field values already loaded for the entities, keyed by entity ID. 291 * Store your changes in this parameter (passed by reference). 292 * @param $age 293 * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or 294 * FIELD_LOAD_REVISION to load the version indicated by each entity. 295 */ 296 function hook_field_load($entity_type, $entities, $field, $instances, $langcode, &$items, $age) { 297 // Sample code from text.module: precompute sanitized strings so they are 298 // stored in the field cache. 299 foreach ($entities as $id => $entity) { 300 foreach ($items[$id] as $delta => $item) { 301 // Only process items with a cacheable format, the rest will be handled 302 // by formatters if needed. 303 if (empty($instances[$id]['settings']['text_processing']) || filter_format_allowcache($item['format'])) { 304 $items[$id][$delta]['safe_value'] = isset($item['value']) ? _text_sanitize($instances[$id], $langcode, $item, 'value') : ''; 305 if ($field['type'] == 'text_with_summary') { 306 $items[$id][$delta]['safe_summary'] = isset($item['summary']) ? _text_sanitize($instances[$id], $langcode, $item, 'summary') : ''; 307 } 308 } 309 } 310 } 311 } 312 313 /** 314 * Prepare field values prior to display. 315 * 316 * This hook is invoked before the field values are handed to formatters 317 * for display, and runs before the formatters' own 318 * hook_field_formatter_prepare_view(). 319 * 320 * Unlike most other field hooks, this hook operates on multiple entities. The 321 * $entities, $instances and $items parameters are arrays keyed by entity ID. 322 * For performance reasons, information for all available entities should be 323 * loaded in a single query where possible. 324 * 325 * Make changes or additions to field values by altering the $items parameter by 326 * reference. There is no return value. 327 * 328 * @param $entity_type 329 * The type of $entity. 330 * @param $entities 331 * Array of entities being displayed, keyed by entity ID. 332 * @param $field 333 * The field structure for the operation. 334 * @param $instances 335 * Array of instance structures for $field for each entity, keyed by entity 336 * ID. 337 * @param $langcode 338 * The language associated to $items. 339 * @param $items 340 * $entity->{$field['field_name']}, or an empty array if unset. 341 */ 342 function hook_field_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items) { 343 // Sample code from image.module: if there are no images specified at all, 344 // use the default image. 345 foreach ($entities as $id => $entity) { 346 if (empty($items[$id]) && $field['settings']['default_image']) { 347 if ($file = file_load($field['settings']['default_image'])) { 348 $items[$id][0] = (array) $file + array( 349 'is_default' => TRUE, 350 'alt' => '', 351 'title' => '', 352 ); 353 } 354 } 355 } 356 } 357 358 /** 359 * Validate this module's field data. 360 * 361 * If there are validation problems, add to the $errors array (passed by 362 * reference). There is no return value. 363 * 364 * @param $entity_type 365 * The type of $entity. 366 * @param $entity 367 * The entity for the operation. 368 * @param $field 369 * The field structure for the operation. 370 * @param $instance 371 * The instance structure for $field on $entity's bundle. 372 * @param $langcode 373 * The language associated with $items. 374 * @param $items 375 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 376 * @param $errors 377 * The array of errors (keyed by field name, language code, and delta) that 378 * have already been reported for the entity. The function should add its 379 * errors to this array. Each error is an associative array with the following 380 * keys and values: 381 * - error: An error code (should be a string prefixed with the module name). 382 * - message: The human readable message to be displayed. 383 */ 384 function hook_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) { 385 foreach ($items as $delta => $item) { 386 if (!empty($item['value'])) { 387 if (!empty($field['settings']['max_length']) && drupal_strlen($item['value']) > $field['settings']['max_length']) { 388 $errors[$field['field_name']][$langcode][$delta][] = array( 389 'error' => 'text_max_length', 390 'message' => t('%name: the value may not be longer than %max characters.', array('%name' => $instance['label'], '%max' => $field['settings']['max_length'])), 391 ); 392 } 393 } 394 } 395 } 396 397 /** 398 * Define custom presave behavior for this module's field types. 399 * 400 * Make changes or additions to field values by altering the $items parameter by 401 * reference. There is no return value. 402 * 403 * @param $entity_type 404 * The type of $entity. 405 * @param $entity 406 * The entity for the operation. 407 * @param $field 408 * The field structure for the operation. 409 * @param $instance 410 * The instance structure for $field on $entity's bundle. 411 * @param $langcode 412 * The language associated with $items. 413 * @param $items 414 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 415 */ 416 function hook_field_presave($entity_type, $entity, $field, $instance, $langcode, &$items) { 417 if ($field['type'] == 'number_decimal') { 418 // Let PHP round the value to ensure consistent behavior across storage 419 // backends. 420 foreach ($items as $delta => $item) { 421 if (isset($item['value'])) { 422 $items[$delta]['value'] = round($item['value'], $field['settings']['scale']); 423 } 424 } 425 } 426 } 427 428 /** 429 * Define custom insert behavior for this module's field data. 430 * 431 * This hook is invoked from field_attach_insert() on the module that defines a 432 * field, during the process of inserting an entity object (node, taxonomy term, 433 * etc.). It is invoked just before the data for this field on the particular 434 * entity object is inserted into field storage. Only field modules that are 435 * storing or tracking information outside the standard field storage mechanism 436 * need to implement this hook. 437 * 438 * @param $entity_type 439 * The type of $entity. 440 * @param $entity 441 * The entity for the operation. 442 * @param $field 443 * The field structure for the operation. 444 * @param $instance 445 * The instance structure for $field on $entity's bundle. 446 * @param $langcode 447 * The language associated with $items. 448 * @param $items 449 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 450 * 451 * @see hook_field_update() 452 * @see hook_field_delete() 453 */ 454 function hook_field_insert($entity_type, $entity, $field, $instance, $langcode, &$items) { 455 if (variable_get('taxonomy_maintain_index_table', TRUE) && $field['storage']['type'] == 'field_sql_storage' && $entity_type == 'node' && $entity->status) { 456 $query = db_insert('taxonomy_index')->fields(array('nid', 'tid', 'sticky', 'created', )); 457 foreach ($items as $item) { 458 $query->values(array( 459 'nid' => $entity->nid, 460 'tid' => $item['tid'], 461 'sticky' => $entity->sticky, 462 'created' => $entity->created, 463 )); 464 } 465 $query->execute(); 466 } 467 } 468 469 /** 470 * Define custom update behavior for this module's field data. 471 * 472 * This hook is invoked from field_attach_update() on the module that defines a 473 * field, during the process of updating an entity object (node, taxonomy term, 474 * etc.). It is invoked just before the data for this field on the particular 475 * entity object is updated into field storage. Only field modules that are 476 * storing or tracking information outside the standard field storage mechanism 477 * need to implement this hook. 478 * 479 * @param $entity_type 480 * The type of $entity. 481 * @param $entity 482 * The entity for the operation. 483 * @param $field 484 * The field structure for the operation. 485 * @param $instance 486 * The instance structure for $field on $entity's bundle. 487 * @param $langcode 488 * The language associated with $items. 489 * @param $items 490 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 491 * 492 * @see hook_field_insert() 493 * @see hook_field_delete() 494 */ 495 function hook_field_update($entity_type, $entity, $field, $instance, $langcode, &$items) { 496 if (variable_get('taxonomy_maintain_index_table', TRUE) && $field['storage']['type'] == 'field_sql_storage' && $entity_type == 'node') { 497 $first_call = &drupal_static(__FUNCTION__, array()); 498 499 // We don't maintain data for old revisions, so clear all previous values 500 // from the table. Since this hook runs once per field, per object, make 501 // sure we only wipe values once. 502 if (!isset($first_call[$entity->nid])) { 503 $first_call[$entity->nid] = FALSE; 504 db_delete('taxonomy_index')->condition('nid', $entity->nid)->execute(); 505 } 506 // Only save data to the table if the node is published. 507 if ($entity->status) { 508 $query = db_insert('taxonomy_index')->fields(array('nid', 'tid', 'sticky', 'created')); 509 foreach ($items as $item) { 510 $query->values(array( 511 'nid' => $entity->nid, 512 'tid' => $item['tid'], 513 'sticky' => $entity->sticky, 514 'created' => $entity->created, 515 )); 516 } 517 $query->execute(); 518 } 519 } 520 } 521 522 /** 523 * Update the storage information for a field. 524 * 525 * This is invoked on the field's storage module from field_update_field(), 526 * before the new field information is saved to the database. The field storage 527 * module should update its storage tables to agree with the new field 528 * information. If there is a problem, the field storage module should throw an 529 * exception. 530 * 531 * @param $field 532 * The updated field structure to be saved. 533 * @param $prior_field 534 * The previously-saved field structure. 535 * @param $has_data 536 * TRUE if the field has data in storage currently. 537 */ 538 function hook_field_storage_update_field($field, $prior_field, $has_data) { 539 if (!$has_data) { 540 // There is no data. Re-create the tables completely. 541 $prior_schema = _field_sql_storage_schema($prior_field); 542 foreach ($prior_schema as $name => $table) { 543 db_drop_table($name, $table); 544 } 545 $schema = _field_sql_storage_schema($field); 546 foreach ($schema as $name => $table) { 547 db_create_table($name, $table); 548 } 549 } 550 else { 551 // There is data. See field_sql_storage_field_storage_update_field() for 552 // an example of what to do to modify the schema in place, preserving the 553 // old data as much as possible. 554 } 555 drupal_get_schema(NULL, TRUE); 556 } 557 558 /** 559 * Define custom delete behavior for this module's field data. 560 * 561 * This hook is invoked from field_attach_delete() on the module that defines a 562 * field, during the process of deleting an entity object (node, taxonomy term, 563 * etc.). It is invoked just before the data for this field on the particular 564 * entity object is deleted from field storage. Only field modules that are 565 * storing or tracking information outside the standard field storage mechanism 566 * need to implement this hook. 567 * 568 * @param $entity_type 569 * The type of $entity. 570 * @param $entity 571 * The entity for the operation. 572 * @param $field 573 * The field structure for the operation. 574 * @param $instance 575 * The instance structure for $field on $entity's bundle. 576 * @param $langcode 577 * The language associated with $items. 578 * @param $items 579 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 580 * 581 * @see hook_field_insert() 582 * @see hook_field_update() 583 */ 584 function hook_field_delete($entity_type, $entity, $field, $instance, $langcode, &$items) { 585 list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity); 586 foreach ($items as $delta => $item) { 587 // For hook_file_references(), remember that this is being deleted. 588 $item['file_field_name'] = $field['field_name']; 589 // Pass in the ID of the object that is being removed so all references can 590 // be counted in hook_file_references(). 591 $item['file_field_type'] = $entity_type; 592 $item['file_field_id'] = $id; 593 file_field_delete_file($item, $field, $entity_type, $id); 594 } 595 } 596 597 /** 598 * Define custom revision delete behavior for this module's field types. 599 * 600 * This hook is invoked just before the data is deleted from field storage 601 * in field_attach_delete_revision(), and will only be called for fieldable 602 * types that are versioned. 603 * 604 * @param $entity_type 605 * The type of $entity. 606 * @param $entity 607 * The entity for the operation. 608 * @param $field 609 * The field structure for the operation. 610 * @param $instance 611 * The instance structure for $field on $entity's bundle. 612 * @param $langcode 613 * The language associated with $items. 614 * @param $items 615 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 616 */ 617 function hook_field_delete_revision($entity_type, $entity, $field, $instance, $langcode, &$items) { 618 list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity); 619 foreach ($items as $delta => $item) { 620 // For hook_file_references, remember that this file is being deleted. 621 $item['file_field_name'] = $field['field_name']; 622 if (file_field_delete_file($item, $field, $entity_type, $id)) { 623 $items[$delta] = NULL; 624 } 625 } 626 } 627 628 /** 629 * Define custom prepare_translation behavior for this module's field types. 630 * 631 * @param $entity_type 632 * The type of $entity. 633 * @param $entity 634 * The entity for the operation. 635 * @param $field 636 * The field structure for the operation. 637 * @param $instance 638 * The instance structure for $field on $entity's bundle. 639 * @param $langcode 640 * The language associated to $items. 641 * @param $items 642 * $entity->{$field['field_name']}[$langcode], or an empty array if unset. 643 * @param $source_entity 644 * The source entity from which field values are being copied. 645 * @param $source_langcode 646 * The source language from which field values are being copied. 647 */ 648 function hook_field_prepare_translation($entity_type, $entity, $field, $instance, $langcode, &$items, $source_entity, $source_langcode) { 649 // If the translating user is not permitted to use the assigned text format, 650 // we must not expose the source values. 651 $field_name = $field['field_name']; 652 $formats = filter_formats(); 653 $format_id = $source_entity->{$field_name}[$source_langcode][0]['format']; 654 if (!filter_access($formats[$format_id])) { 655 $items = array(); 656 } 657 } 658 659 /** 660 * Define what constitutes an empty item for a field type. 661 * 662 * @param $item 663 * An item that may or may not be empty. 664 * @param $field 665 * The field to which $item belongs. 666 * 667 * @return 668 * TRUE if $field's type considers $item not to contain any data; 669 * FALSE otherwise. 670 */ 671 function hook_field_is_empty($item, $field) { 672 if (empty($item['value']) && (string) $item['value'] !== '0') { 673 return TRUE; 674 } 675 return FALSE; 676 } 677 678 /** 679 * @} End of "defgroup field_types". 680 */ 681 682 /** 683 * @defgroup field_widget Field Widget API 684 * @{ 685 * Define Field API widget types. 686 * 687 * Field API widgets specify how fields are displayed in edit forms. Fields of a 688 * given @link field_types field type @endlink may be edited using more than one 689 * widget. In this case, the Field UI module allows the site builder to choose 690 * which widget to use. Widget types are defined by implementing 691 * hook_field_widget_info(). 692 * 693 * Widgets are @link forms_api_reference.html Form API @endlink elements with 694 * additional processing capabilities. Widget hooks are typically called by the 695 * Field Attach API during the creation of the field form structure with 696 * field_attach_form(). 697 * 698 * @see field 699 * @see field_types 700 * @see field_formatter 701 */ 702 703 /** 704 * Expose Field API widget types. 705 * 706 * @return 707 * An array describing the widget types implemented by the module. 708 * The keys are widget type names. To avoid name clashes, widget type 709 * names should be prefixed with the name of the module that exposes them. 710 * The values are arrays describing the widget type, with the following 711 * key/value pairs: 712 * - label: The human-readable name of the widget type. 713 * - description: A short description for the widget type. 714 * - field types: An array of field types the widget supports. 715 * - settings: An array whose keys are the names of the settings available 716 * for the widget type, and whose values are the default values for those 717 * settings. 718 * - behaviors: (optional) An array describing behaviors of the widget, with 719 * the following elements: 720 * - multiple values: One of the following constants: 721 * - FIELD_BEHAVIOR_DEFAULT: (default) If the widget allows the input of 722 * one single field value (most common case). The widget will be 723 * repeated for each value input. 724 * - FIELD_BEHAVIOR_CUSTOM: If one single copy of the widget can receive 725 * several field values. Examples: checkboxes, multiple select, 726 * comma-separated textfield. 727 * - default value: One of the following constants: 728 * - FIELD_BEHAVIOR_DEFAULT: (default) If the widget accepts default 729 * values. 730 * - FIELD_BEHAVIOR_NONE: if the widget does not support default values. 731 * - weight: (optional) An integer to determine the weight of this widget 732 * relative to other widgets in the Field UI when selecting a widget for a 733 * given field instance. 734 * 735 * @see hook_field_widget_info_alter() 736 * @see hook_field_widget_form() 737 * @see hook_field_widget_form_alter() 738 * @see hook_field_widget_WIDGET_TYPE_form_alter() 739 * @see hook_field_widget_error() 740 * @see hook_field_widget_settings_form() 741 */ 742 function hook_field_widget_info() { 743 return array( 744 'text_textfield' => array( 745 'label' => t('Text field'), 746 'field types' => array('text'), 747 'settings' => array('size' => 60), 748 'behaviors' => array( 749 'multiple values' => FIELD_BEHAVIOR_DEFAULT, 750 'default value' => FIELD_BEHAVIOR_DEFAULT, 751 ), 752 ), 753 'text_textarea' => array( 754 'label' => t('Text area (multiple rows)'), 755 'field types' => array('text_long'), 756 'settings' => array('rows' => 5), 757 'behaviors' => array( 758 'multiple values' => FIELD_BEHAVIOR_DEFAULT, 759 'default value' => FIELD_BEHAVIOR_DEFAULT, 760 ), 761 ), 762 'text_textarea_with_summary' => array( 763 'label' => t('Text area with a summary'), 764 'field types' => array('text_with_summary'), 765 'settings' => array('rows' => 20, 'summary_rows' => 5), 766 'behaviors' => array( 767 'multiple values' => FIELD_BEHAVIOR_DEFAULT, 768 'default value' => FIELD_BEHAVIOR_DEFAULT, 769 ), 770 // As an advanced widget, force it to sink to the bottom of the choices. 771 'weight' => 2, 772 ), 773 ); 774 } 775 776 /** 777 * Perform alterations on Field API widget types. 778 * 779 * @param $info 780 * Array of informations on widget types exposed by hook_field_widget_info() 781 * implementations. 782 */ 783 function hook_field_widget_info_alter(&$info) { 784 // Add a setting to a widget type. 785 $info['text_textfield']['settings'] += array( 786 'mymodule_additional_setting' => 'default value', 787 ); 788 789 // Let a new field type re-use an existing widget. 790 $info['options_select']['field types'][] = 'my_field_type'; 791 } 792 793 /** 794 * Return the form for a single field widget. 795 * 796 * Field widget form elements should be based on the passed-in $element, which 797 * contains the base form element properties derived from the field 798 * configuration. 799 * 800 * Field API will set the weight, field name and delta values for each form 801 * element. If there are multiple values for this field, the Field API will 802 * invoke this hook as many times as needed. 803 * 804 * Note that, depending on the context in which the widget is being included 805 * (regular entity form, field configuration form, advanced search form...), 806 * the values for $field and $instance might be different from the "official" 807 * definitions returned by field_info_field() and field_info_instance(). 808 * Examples: mono-value widget even if the field is multi-valued, non-required 809 * widget even if the field is 'required'... 810 * 811 * Therefore, the FAPI element callbacks (such as #process, #element_validate, 812 * #value_callback...) used by the widget cannot use the field_info_field() 813 * or field_info_instance() functions to retrieve the $field or $instance 814 * definitions they should operate on. The field_widget_field() and 815 * field_widget_instance() functions should be used instead to fetch the 816 * current working definitions from $form_state, where Field API stores them. 817 * 818 * Alternatively, hook_field_widget_form() can extract the needed specific 819 * properties from $field and $instance and set them as ad-hoc 820 * $element['#custom'] properties, for later use by its element callbacks. 821 * 822 * Other modules may alter the form element provided by this function using 823 * hook_field_widget_form_alter(). 824 * 825 * @param $form 826 * The form structure where widgets are being attached to. This might be a 827 * full form structure, or a sub-element of a larger form. 828 * @param $form_state 829 * An associative array containing the current state of the form. 830 * @param $field 831 * The field structure. 832 * @param $instance 833 * The field instance. 834 * @param $langcode 835 * The language associated with $items. 836 * @param $items 837 * Array of default values for this field. 838 * @param $delta 839 * The order of this item in the array of subelements (0, 1, 2, etc). 840 * @param $element 841 * A form element array containing basic properties for the widget: 842 * - #entity_type: The name of the entity the field is attached to. 843 * - #bundle: The name of the field bundle the field is contained in. 844 * - #field_name: The name of the field. 845 * - #language: The language the field is being edited in. 846 * - #field_parents: The 'parents' space for the field in the form. Most 847 * widgets can simply overlook this property. This identifies the 848 * location where the field values are placed within 849 * $form_state['values'], and is used to access processing information 850 * for the field through the field_form_get_state() and 851 * field_form_set_state() functions. 852 * - #columns: A list of field storage columns of the field. 853 * - #title: The sanitized element label for the field instance, ready for 854 * output. 855 * - #description: The sanitized element description for the field instance, 856 * ready for output. 857 * - #required: A Boolean indicating whether the element value is required; 858 * for required multiple value fields, only the first widget's values are 859 * required. 860 * - #delta: The order of this item in the array of subelements; see $delta 861 * above. 862 * 863 * @return 864 * The form elements for a single widget for this field. 865 * 866 * @see field_widget_field() 867 * @see field_widget_instance() 868 * @see hook_field_widget_form_alter() 869 * @see hook_field_widget_WIDGET_TYPE_form_alter() 870 */ 871 function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) { 872 $element += array( 873 '#type' => $instance['widget']['type'], 874 '#default_value' => isset($items[$delta]) ? $items[$delta] : '', 875 ); 876 return $element; 877 } 878 879 /** 880 * Alter forms for field widgets provided by other modules. 881 * 882 * @param $element 883 * The field widget form element as constructed by hook_field_widget_form(). 884 * @param $form_state 885 * An associative array containing the current state of the form. 886 * @param $context 887 * An associative array containing the following key-value pairs, matching the 888 * arguments received by hook_field_widget_form(): 889 * - form: The form structure to which widgets are being attached. This may be 890 * a full form structure, or a sub-element of a larger form. 891 * - field: The field structure. 892 * - instance: The field instance structure. 893 * - langcode: The language associated with $items. 894 * - items: Array of default values for this field. 895 * - delta: The order of this item in the array of subelements (0, 1, 2, etc). 896 * 897 * @see hook_field_widget_form() 898 * @see hook_field_widget_WIDGET_TYPE_form_alter() 899 */ 900 function hook_field_widget_form_alter(&$element, &$form_state, $context) { 901 // Add a css class to widget form elements for all fields of type mytype. 902 if ($context['field']['type'] == 'mytype') { 903 // Be sure not to overwrite existing attributes. 904 $element['#attributes']['class'][] = 'myclass'; 905 } 906 } 907 908 /** 909 * Alter widget forms for a specific widget provided by another module. 910 * 911 * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a 912 * specific widget form, rather than using hook_field_widget_form_alter() and 913 * checking the widget type. 914 * 915 * @param $element 916 * The field widget form element as constructed by hook_field_widget_form(). 917 * @param $form_state 918 * An associative array containing the current state of the form. 919 * @param $context 920 * An associative array containing the following key-value pairs, matching the 921 * arguments received by hook_field_widget_form(): 922 * - "form": The form structure where widgets are being attached to. This 923 * might be a full form structure, or a sub-element of a larger form. 924 * - "field": The field structure. 925 * - "instance": The field instance structure. 926 * - "langcode": The language associated with $items. 927 * - "items": Array of default values for this field. 928 * - "delta": The order of this item in the array of subelements (0, 1, 2, 929 * etc). 930 * 931 * @see hook_field_widget_form() 932 * @see hook_field_widget_form_alter() 933 */ 934 function hook_field_widget_WIDGET_TYPE_form_alter(&$element, &$form_state, $context) { 935 // Code here will only act on widgets of type WIDGET_TYPE. For example, 936 // hook_field_widget_mymodule_autocomplete_form_alter() will only act on 937 // widgets of type 'mymodule_autocomplete'. 938 $element['#autocomplete_path'] = 'mymodule/autocomplete_path'; 939 } 940 941 /** 942 * Alters the widget properties of a field instance before it gets displayed. 943 * 944 * Note that instead of hook_field_widget_properties_alter(), which is called 945 * for all fields on all entity types, 946 * hook_field_widget_properties_ENTITY_TYPE_alter() may be used to alter widget 947 * properties for fields on a specific entity type only. 948 * 949 * This hook is called once per field per added or edit entity. If the result 950 * of the hook involves reading from the database, it is highly recommended to 951 * statically cache the information. 952 * 953 * @param $widget 954 * The instance's widget properties. 955 * @param $context 956 * An associative array containing: 957 * - entity_type: The entity type; e.g., 'node' or 'user'. 958 * - entity: The entity object. 959 * - field: The field that the widget belongs to. 960 * - instance: The instance of the field. 961 * 962 * @see hook_field_widget_properties_ENTITY_TYPE_alter() 963 */ 964 function hook_field_widget_properties_alter(&$widget, $context) { 965 // Change a widget's type according to the time of day. 966 $field = $context['field']; 967 if ($context['entity_type'] == 'node' && $field['field_name'] == 'field_foo') { 968 $time = date('H'); 969 $widget['type'] = $time < 12 ? 'widget_am' : 'widget_pm'; 970 } 971 } 972 973 /** 974 * Flag a field-level validation error. 975 * 976 * @param $element 977 * An array containing the form element for the widget. The error needs to be 978 * flagged on the right sub-element, according to the widget's internal 979 * structure. 980 * @param $error 981 * An associative array with the following key-value pairs, as returned by 982 * hook_field_validate(): 983 * - error: the error code. Complex widgets might need to report different 984 * errors to different form elements inside the widget. 985 * - message: the human readable message to be displayed. 986 * @param $form 987 * The form structure where field elements are attached to. This might be a 988 * full form structure, or a sub-element of a larger form. 989 * @param $form_state 990 * An associative array containing the current state of the form. 991 */ 992 function hook_field_widget_error($element, $error, $form, &$form_state) { 993 form_error($element, $error['message']); 994 } 995 996 997 /** 998 * @} End of "defgroup field_widget". 999 */ 1000 1001 1002 /** 1003 * @defgroup field_formatter Field Formatter API 1004 * @{ 1005 * Define Field API formatter types. 1006 * 1007 * Field API formatters specify how fields are displayed when the entity to 1008 * which the field is attached is displayed. Fields of a given 1009 * @link field_types field type @endlink may be displayed using more than one 1010 * formatter. In this case, the Field UI module allows the site builder to 1011 * choose which formatter to use. Field formatters are defined by implementing 1012 * hook_field_formatter_info(). 1013 * 1014 * @see field 1015 * @see field_types 1016 * @see field_widget 1017 */ 1018 1019 /** 1020 * Expose Field API formatter types. 1021 * 1022 * Formatters handle the display of field values. Formatter hooks are typically 1023 * called by the Field Attach API field_attach_prepare_view() and 1024 * field_attach_view() functions. 1025 * 1026 * @return 1027 * An array describing the formatter types implemented by the module. 1028 * The keys are formatter type names. To avoid name clashes, formatter type 1029 * names should be prefixed with the name of the module that exposes them. 1030 * The values are arrays describing the formatter type, with the following 1031 * key/value pairs: 1032 * - label: The human-readable name of the formatter type. 1033 * - description: A short description for the formatter type. 1034 * - field types: An array of field types the formatter supports. 1035 * - settings: An array whose keys are the names of the settings available 1036 * for the formatter type, and whose values are the default values for 1037 * those settings. 1038 * 1039 * @see hook_field_formatter_info_alter() 1040 * @see hook_field_formatter_view() 1041 * @see hook_field_formatter_prepare_view() 1042 */ 1043 function hook_field_formatter_info() { 1044 return array( 1045 'text_default' => array( 1046 'label' => t('Default'), 1047 'field types' => array('text', 'text_long', 'text_with_summary'), 1048 ), 1049 'text_plain' => array( 1050 'label' => t('Plain text'), 1051 'field types' => array('text', 'text_long', 'text_with_summary'), 1052 ), 1053 1054 // The text_trimmed formatter displays the trimmed version of the 1055 // full element of the field. It is intended to be used with text 1056 // and text_long fields. It also works with text_with_summary 1057 // fields though the text_summary_or_trimmed formatter makes more 1058 // sense for that field type. 1059 'text_trimmed' => array( 1060 'label' => t('Trimmed'), 1061 'field types' => array('text', 'text_long', 'text_with_summary'), 1062 ), 1063 1064 // The 'summary or trimmed' field formatter for text_with_summary 1065 // fields displays returns the summary element of the field or, if 1066 // the summary is empty, the trimmed version of the full element 1067 // of the field. 1068 'text_summary_or_trimmed' => array( 1069 'label' => t('Summary or trimmed'), 1070 'field types' => array('text_with_summary'), 1071 ), 1072 ); 1073 } 1074 1075 /** 1076 * Perform alterations on Field API formatter types. 1077 * 1078 * @param $info 1079 * An array of information on formatter types exposed by 1080 * hook_field_formatter_info() implementations. 1081 */ 1082 function hook_field_formatter_info_alter(&$info) { 1083 // Add a setting to a formatter type. 1084 $info['text_default']['settings'] += array( 1085 'mymodule_additional_setting' => 'default value', 1086 ); 1087 1088 // Let a new field type re-use an existing formatter. 1089 $info['text_default']['field types'][] = 'my_field_type'; 1090 } 1091 1092 /** 1093 * Allow formatters to load information for field values being displayed. 1094 * 1095 * This should be used when a formatter needs to load additional information 1096 * from the database in order to render a field, for example a reference field 1097 * which displays properties of the referenced entities such as name or type. 1098 * 1099 * This hook is called after the field type's own hook_field_prepare_view(). 1100 * 1101 * Unlike most other field hooks, this hook operates on multiple entities. The 1102 * $entities, $instances and $items parameters are arrays keyed by entity ID. 1103 * For performance reasons, information for all available entities should be 1104 * loaded in a single query where possible. 1105 * 1106 * @param $entity_type 1107 * The type of $entity. 1108 * @param $entities 1109 * Array of entities being displayed, keyed by entity ID. 1110 * @param $field 1111 * The field structure for the operation. 1112 * @param $instances 1113 * Array of instance structures for $field for each entity, keyed by entity 1114 * ID. 1115 * @param $langcode 1116 * The language the field values are to be shown in. If no language is 1117 * provided the current language is used. 1118 * @param $items 1119 * Array of field values for the entities, keyed by entity ID. 1120 * @param $displays 1121 * Array of display settings to use for each entity, keyed by entity ID. 1122 * 1123 * @return 1124 * Changes or additions to field values are done by altering the $items 1125 * parameter by reference. 1126 */ 1127 function hook_field_formatter_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $displays) { 1128 $tids = array(); 1129 1130 // Collect every possible term attached to any of the fieldable entities. 1131 foreach ($entities as $id => $entity) { 1132 foreach ($items[$id] as $delta => $item) { 1133 // Force the array key to prevent duplicates. 1134 $tids[$item['tid']] = $item['tid']; 1135 } 1136 } 1137 1138 if ($tids) { 1139 $terms = taxonomy_term_load_multiple($tids); 1140 1141 // Iterate through the fieldable entities again to attach the loaded term 1142 // data. 1143 foreach ($entities as $id => $entity) { 1144 $rekey = FALSE; 1145 1146 foreach ($items[$id] as $delta => $item) { 1147 // Check whether the taxonomy term field instance value could be loaded. 1148 if (isset($terms[$item['tid']])) { 1149 // Replace the instance value with the term data. 1150 $items[$id][$delta]['taxonomy_term'] = $terms[$item['tid']]; 1151 } 1152 // Otherwise, unset the instance value, since the term does not exist. 1153 else { 1154 unset($items[$id][$delta]); 1155 $rekey = TRUE; 1156 } 1157 } 1158 1159 if ($rekey) { 1160 // Rekey the items array. 1161 $items[$id] = array_values($items[$id]); 1162 } 1163 } 1164 } 1165 } 1166 1167 /** 1168 * Build a renderable array for a field value. 1169 * 1170 * @param $entity_type 1171 * The type of $entity. 1172 * @param $entity 1173 * The entity being displayed. 1174 * @param $field 1175 * The field structure. 1176 * @param $instance 1177 * The field instance. 1178 * @param $langcode 1179 * The language associated with $items. 1180 * @param $items 1181 * Array of values for this field. 1182 * @param $display 1183 * The display settings to use, as found in the 'display' entry of instance 1184 * definitions. The array notably contains the following keys and values; 1185 * - type: The name of the formatter to use. 1186 * - settings: The array of formatter settings. 1187 * 1188 * @return 1189 * A renderable array for the $items, as an array of child elements keyed 1190 * by numeric indexes starting from 0. 1191 */ 1192 function hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) { 1193 $element = array(); 1194 $settings = $display['settings']; 1195 1196 switch ($display['type']) { 1197 case 'sample_field_formatter_simple': 1198 // Common case: each value is displayed individually in a sub-element 1199 // keyed by delta. The field.tpl.php template specifies the markup 1200 // wrapping each value. 1201 foreach ($items as $delta => $item) { 1202 $element[$delta] = array('#markup' => $settings['some_setting'] . $item['value']); 1203 } 1204 break; 1205 1206 case 'sample_field_formatter_themeable': 1207 // More elaborate formatters can defer to a theme function for easier 1208 // customization. 1209 foreach ($items as $delta => $item) { 1210 $element[$delta] = array( 1211 '#theme' => 'mymodule_theme_sample_field_formatter_themeable', 1212 '#data' => $item['value'], 1213 '#some_setting' => $settings['some_setting'], 1214 ); 1215 } 1216 break; 1217 1218 case 'sample_field_formatter_combined': 1219 // Some formatters might need to display all values within a single piece 1220 // of markup. 1221 $rows = array(); 1222 foreach ($items as $delta => $item) { 1223 $rows[] = array($delta, $item['value']); 1224 } 1225 $element[0] = array( 1226 '#theme' => 'table', 1227 '#header' => array(t('Delta'), t('Value')), 1228 '#rows' => $rows, 1229 ); 1230 break; 1231 } 1232 1233 return $element; 1234 } 1235 1236 /** 1237 * @} End of "defgroup field_formatter". 1238 */ 1239 1240 /** 1241 * @ingroup field_attach 1242 * @{ 1243 */ 1244 1245 /** 1246 * Act on field_attach_form(). 1247 * 1248 * This hook is invoked after the field module has performed the operation. 1249 * Implementing modules should alter the $form or $form_state parameters. 1250 * 1251 * @param $entity_type 1252 * The type of $entity; for example, 'node' or 'user'. 1253 * @param $entity 1254 * The entity for which an edit form is being built. 1255 * @param $form 1256 * The form structure where field elements are attached to. This might be a 1257 * full form structure, or a sub-element of a larger form. The 1258 * $form['#parents'] property can be used to identify the corresponding part 1259 * of $form_state['values']. Hook implementations that need to act on the 1260 * top-level properties of the global form (like #submit, #validate...) can 1261 * add a #process callback to the array received in the $form parameter, and 1262 * act on the $complete_form parameter in the process callback. 1263 * @param $form_state 1264 * An associative array containing the current state of the form. 1265 * @param $langcode 1266 * The language the field values are going to be entered in. If no language 1267 * is provided the default site language will be used. 1268 */ 1269 function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode) { 1270 // Add a checkbox allowing a given field to be emptied. 1271 // See hook_field_attach_submit() for the corresponding processing code. 1272 $form['empty_field_foo'] = array( 1273 '#type' => 'checkbox', 1274 '#title' => t("Empty the 'field_foo' field"), 1275 ); 1276 } 1277 1278 /** 1279 * Act on field_attach_load(). 1280 * 1281 * This hook is invoked after the field module has performed the operation. 1282 * 1283 * Unlike other field_attach hooks, this hook accounts for 'multiple loads'. 1284 * Instead of the usual $entity parameter, it accepts an array of entities, 1285 * indexed by entity ID. For performance reasons, information for all available 1286 * entities should be loaded in a single query where possible. 1287 * 1288 * The changes made to the entities' field values get cached by the field cache 1289 * for subsequent loads. 1290 * 1291 * See field_attach_load() for details and arguments. 1292 */ 1293 function hook_field_attach_load($entity_type, $entities, $age, $options) { 1294 // @todo Needs function body. 1295 } 1296 1297 /** 1298 * Act on field_attach_validate(). 1299 * 1300 * This hook is invoked after the field module has performed the operation. 1301 * 1302 * See field_attach_validate() for details and arguments. 1303 */ 1304 function hook_field_attach_validate($entity_type, $entity, &$errors) { 1305 // @todo Needs function body. 1306 } 1307 1308 /** 1309 * Act on field_attach_submit(). 1310 * 1311 * This hook is invoked after the field module has performed the operation. 1312 * 1313 * @param $entity_type 1314 * The type of $entity; for example, 'node' or 'user'. 1315 * @param $entity 1316 * The entity for which an edit form is being submitted. The incoming form 1317 * values have been extracted as field values of the $entity object. 1318 * @param $form 1319 * The form structure where field elements are attached to. This might be a 1320 * full form structure, or a sub-part of a larger form. The $form['#parents'] 1321 * property can be used to identify the corresponding part of 1322 * $form_state['values']. 1323 * @param $form_state 1324 * An associative array containing the current state of the form. 1325 */ 1326 function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) { 1327 // Sample case of an 'Empty the field' checkbox added on the form, allowing 1328 // a given field to be emptied. 1329 $values = drupal_array_get_nested_value($form_state['values'], $form['#parents']); 1330 if (!empty($values['empty_field_foo'])) { 1331 unset($entity->field_foo); 1332 } 1333 } 1334 1335 /** 1336 * Act on field_attach_presave(). 1337 * 1338 * This hook is invoked after the field module has performed the operation. 1339 * 1340 * See field_attach_presave() for details and arguments. 1341 */ 1342 function hook_field_attach_presave($entity_type, $entity) { 1343 // @todo Needs function body. 1344 } 1345 1346 /** 1347 * Act on field_attach_insert(). 1348 * 1349 * This hook is invoked after the field module has performed the operation. 1350 * 1351 * See field_attach_insert() for details and arguments. 1352 */ 1353 function hook_field_attach_insert($entity_type, $entity) { 1354 // @todo Needs function body. 1355 } 1356 1357 /** 1358 * Act on field_attach_update(). 1359 * 1360 * This hook is invoked after the field module has performed the operation. 1361 * 1362 * See field_attach_update() for details and arguments. 1363 */ 1364 function hook_field_attach_update($entity_type, $entity) { 1365 // @todo Needs function body. 1366 } 1367 1368 /** 1369 * Alter field_attach_preprocess() variables. 1370 * 1371 * This hook is invoked while preprocessing the field.tpl.php template file 1372 * in field_attach_preprocess(). 1373 * 1374 * @param $variables 1375 * The variables array is passed by reference and will be populated with field 1376 * values. 1377 * @param $context 1378 * An associative array containing: 1379 * - entity_type: The type of $entity; for example, 'node' or 'user'. 1380 * - entity: The entity with fields to render. 1381 * - element: The structured array containing the values ready for rendering. 1382 */ 1383 function hook_field_attach_preprocess_alter(&$variables, $context) { 1384 // @todo Needs function body. 1385 } 1386 1387 /** 1388 * Act on field_attach_delete(). 1389 * 1390 * This hook is invoked after the field module has performed the operation. 1391 * 1392 * See field_attach_delete() for details and arguments. 1393 */ 1394 function hook_field_attach_delete($entity_type, $entity) { 1395 // @todo Needs function body. 1396 } 1397 1398 /** 1399 * Act on field_attach_delete_revision(). 1400 * 1401 * This hook is invoked after the field module has performed the operation. 1402 * 1403 * See field_attach_delete_revision() for details and arguments. 1404 */ 1405 function hook_field_attach_delete_revision($entity_type, $entity) { 1406 // @todo Needs function body. 1407 } 1408 1409 /** 1410 * Act on field_purge_data(). 1411 * 1412 * This hook is invoked in field_purge_data() and allows modules to act on 1413 * purging data from a single field pseudo-entity. For example, if a module 1414 * relates data in the field with its own data, it may purge its own data 1415 * during this process as well. 1416 * 1417 * @param $entity_type 1418 * The type of $entity; for example, 'node' or 'user'. 1419 * @param $entity 1420 * The pseudo-entity whose field data is being purged. 1421 * @param $field 1422 * The (possibly deleted) field whose data is being purged. 1423 * @param $instance 1424 * The deleted field instance whose data is being purged. 1425 * 1426 * @see @link field_purge Field API bulk data deletion @endlink 1427 * @see field_purge_data() 1428 */ 1429 function hook_field_attach_purge($entity_type, $entity, $field, $instance) { 1430 // find the corresponding data in mymodule and purge it 1431 if ($entity_type == 'node' && $field->field_name == 'my_field_name') { 1432 mymodule_remove_mydata($entity->nid); 1433 } 1434 } 1435 1436 /** 1437 * Perform alterations on field_attach_view() or field_view_field(). 1438 * 1439 * This hook is invoked after the field module has performed the operation. 1440 * 1441 * @param $output 1442 * The structured content array tree for all of the entity's fields. 1443 * @param $context 1444 * An associative array containing: 1445 * - entity_type: The type of $entity; for example, 'node' or 'user'. 1446 * - entity: The entity with fields to render. 1447 * - view_mode: View mode; for example, 'full' or 'teaser'. 1448 * - display: Either a view mode string or an array of display settings. If 1449 * this hook is being invoked from field_attach_view(), the 'display' 1450 * element is set to the view mode string. If this hook is being invoked 1451 * from field_view_field(), this element is set to the $display argument 1452 * and the view_mode element is set to '_custom'. See field_view_field() 1453 * for more information on what its $display argument contains. 1454 * - language: The language code used for rendering. 1455 */ 1456 function hook_field_attach_view_alter(&$output, $context) { 1457 // Append RDF term mappings on displayed taxonomy links. 1458 foreach (element_children($output) as $field_name) { 1459 $element = &$output[$field_name]; 1460 if ($element['#field_type'] == 'taxonomy_term_reference' && $element['#formatter'] == 'taxonomy_term_reference_link') { 1461 foreach ($element['#items'] as $delta => $item) { 1462 $term = $item['taxonomy_term']; 1463 if (!empty($term->rdf_mapping['rdftype'])) { 1464 $element[$delta]['#options']['attributes']['typeof'] = $term->rdf_mapping['rdftype']; 1465 } 1466 if (!empty($term->rdf_mapping['name']['predicates'])) { 1467 $element[$delta]['#options']['attributes']['property'] = $term->rdf_mapping['name']['predicates']; 1468 } 1469 } 1470 } 1471 } 1472 } 1473 1474 /** 1475 * Perform alterations on field_attach_prepare_translation(). 1476 * 1477 * This hook is invoked after the field module has performed the operation. 1478 * 1479 * @param $entity 1480 * The entity being prepared for translation. 1481 * @param $context 1482 * An associative array containing: 1483 * - entity_type: The type of $entity; e.g. 'node' or 'user'. 1484 * - langcode: The language the entity has to be translated in. 1485 * - source_entity: The entity holding the field values to be translated. 1486 * - source_langcode: The source language from which translate. 1487 */ 1488 function hook_field_attach_prepare_translation_alter(&$entity, $context) { 1489 if ($context['entity_type'] == 'custom_entity_type') { 1490 $entity->custom_field = $context['source_entity']->custom_field; 1491 } 1492 } 1493 1494 /** 1495 * Perform alterations on field_language() values. 1496 * 1497 * This hook is invoked to alter the array of display languages for the given 1498 * entity. 1499 * 1500 * @param $display_language 1501 * A reference to an array of language codes keyed by field name. 1502 * @param $context 1503 * An associative array containing: 1504 * - entity_type: The type of the entity to be displayed. 1505 * - entity: The entity with fields to render. 1506 * - langcode: The language code $entity has to be displayed in. 1507 */ 1508 function hook_field_language_alter(&$display_language, $context) { 1509 // Do not apply core language fallback rules if they are disabled or if Locale 1510 // is not registered as a translation handler. 1511 if (variable_get('locale_field_language_fallback', TRUE) && field_has_translation_handler($context['entity_type'], 'locale')) { 1512 locale_field_language_fallback($display_language, $context['entity'], $context['language']); 1513 } 1514 } 1515 1516 /** 1517 * Alter field_available_languages() values. 1518 * 1519 * This hook is invoked from field_available_languages() to allow modules to 1520 * alter the array of available languages for the given field. 1521 * 1522 * @param $languages 1523 * A reference to an array of language codes to be made available. 1524 * @param $context 1525 * An associative array containing: 1526 * - entity_type: The type of the entity the field is attached to. 1527 * - field: A field data structure. 1528 */ 1529 function hook_field_available_languages_alter(&$languages, $context) { 1530 // Add an unavailable language. 1531 $languages[] = 'xx'; 1532 1533 // Remove an available language. 1534 $index = array_search('yy', $languages); 1535 unset($languages[$index]); 1536 } 1537 1538 /** 1539 * Act on field_attach_create_bundle(). 1540 * 1541 * This hook is invoked after the field module has performed the operation. 1542 * 1543 * See field_attach_create_bundle() for details and arguments. 1544 */ 1545 function hook_field_attach_create_bundle($entity_type, $bundle) { 1546 // When a new bundle is created, the menu needs to be rebuilt to add the 1547 // Field UI menu item tabs. 1548 variable_set('menu_rebuild_needed', TRUE); 1549 } 1550 1551 /** 1552 * Act on field_attach_rename_bundle(). 1553 * 1554 * This hook is invoked after the field module has performed the operation. 1555 * 1556 * See field_attach_rename_bundle() for details and arguments. 1557 */ 1558 function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) { 1559 // Update the extra weights variable with new information. 1560 if ($bundle_old !== $bundle_new) { 1561 $extra_weights = variable_get('field_extra_weights', array()); 1562 if (isset($info[$entity_type][$bundle_old])) { 1563 $extra_weights[$entity_type][$bundle_new] = $extra_weights[$entity_type][$bundle_old]; 1564 unset($extra_weights[$entity_type][$bundle_old]); 1565 variable_set('field_extra_weights', $extra_weights); 1566 } 1567 } 1568 } 1569 1570 /** 1571 * Act on field_attach_delete_bundle. 1572 * 1573 * This hook is invoked after the field module has performed the operation. 1574 * 1575 * @param $entity_type 1576 * The type of entity; for example, 'node' or 'user'. 1577 * @param $bundle 1578 * The bundle that was just deleted. 1579 * @param $instances 1580 * An array of all instances that existed for the bundle before it was 1581 * deleted. 1582 */ 1583 function hook_field_attach_delete_bundle($entity_type, $bundle, $instances) { 1584 // Remove the extra weights variable information for this bundle. 1585 $extra_weights = variable_get('field_extra_weights', array()); 1586 if (isset($extra_weights[$entity_type][$bundle])) { 1587 unset($extra_weights[$entity_type][$bundle]); 1588 variable_set('field_extra_weights', $extra_weights); 1589 } 1590 } 1591 1592 /** 1593 * @} End of "defgroup field_attach". 1594 */ 1595 1596 /** 1597 * @addtogroup field_storage 1598 * @{ 1599 */ 1600 1601 /** 1602 * Expose Field API storage backends. 1603 * 1604 * @return 1605 * An array describing the storage backends implemented by the module. 1606 * The keys are storage backend names. To avoid name clashes, storage backend 1607 * names should be prefixed with the name of the module that exposes them. 1608 * The values are arrays describing the storage backend, with the following 1609 * key/value pairs: 1610 * - label: The human-readable name of the storage backend. 1611 * - description: A short description for the storage backend. 1612 * - settings: An array whose keys are the names of the settings available 1613 * for the storage backend, and whose values are the default values for 1614 * those settings. 1615 */ 1616 function hook_field_storage_info() { 1617 return array( 1618 'field_sql_storage' => array( 1619 'label' => t('Default SQL storage'), 1620 'description' => t('Stores fields in the local SQL database, using per-field tables.'), 1621 'settings' => array(), 1622 ), 1623 ); 1624 } 1625 1626 /** 1627 * Perform alterations on Field API storage types. 1628 * 1629 * @param $info 1630 * Array of informations on storage types exposed by 1631 * hook_field_field_storage_info() implementations. 1632 */ 1633 function hook_field_storage_info_alter(&$info) { 1634 // Add a setting to a storage type. 1635 $info['field_sql_storage']['settings'] += array( 1636 'mymodule_additional_setting' => 'default value', 1637 ); 1638 } 1639 1640 /** 1641 * Reveal the internal details about the storage for a field. 1642 * 1643 * For example, an SQL storage module might return the Schema API structure for 1644 * the table. A key/value storage module might return the server name, 1645 * authentication credentials, and bin name. 1646 * 1647 * Field storage modules are not obligated to implement this hook. Modules 1648 * that rely on these details must only use them for read operations. 1649 * 1650 * @param $field 1651 * A field structure. 1652 * 1653 * @return 1654 * An array of details. 1655 * - The first dimension is a store type (sql, solr, etc). 1656 * - The second dimension indicates the age of the values in the store 1657 * FIELD_LOAD_CURRENT or FIELD_LOAD_REVISION. 1658 * - Other dimensions are specific to the field storage module. 1659 * 1660 * @see hook_field_storage_details_alter() 1661 */ 1662 function hook_field_storage_details($field) { 1663 $details = array(); 1664 1665 // Add field columns. 1666 foreach ((array) $field['columns'] as $column_name => $attributes) { 1667 $real_name = _field_sql_storage_columnname($field['field_name'], $column_name); 1668 $columns[$column_name] = $real_name; 1669 } 1670 return array( 1671 'sql' => array( 1672 FIELD_LOAD_CURRENT => array( 1673 _field_sql_storage_tablename($field) => $columns, 1674 ), 1675 FIELD_LOAD_REVISION => array( 1676 _field_sql_storage_revision_tablename($field) => $columns, 1677 ), 1678 ), 1679 ); 1680 } 1681 1682 /** 1683 * Perform alterations on Field API storage details. 1684 * 1685 * @param $details 1686 * An array of storage details for fields as exposed by 1687 * hook_field_storage_details() implementations. 1688 * @param $field 1689 * A field structure. 1690 * 1691 * @see hook_field_storage_details() 1692 */ 1693 function hook_field_storage_details_alter(&$details, $field) { 1694 if ($field['field_name'] == 'field_of_interest') { 1695 $columns = array(); 1696 foreach ((array) $field['columns'] as $column_name => $attributes) { 1697 $columns[$column_name] = $column_name; 1698 } 1699 $details['drupal_variables'] = array( 1700 FIELD_LOAD_CURRENT => array( 1701 'moon' => $columns, 1702 ), 1703 FIELD_LOAD_REVISION => array( 1704 'mars' => $columns, 1705 ), 1706 ); 1707 } 1708 } 1709 1710 /** 1711 * Load field data for a set of entities. 1712 * 1713 * This hook is invoked from field_attach_load() to ask the field storage 1714 * module to load field data. 1715 * 1716 * Modules implementing this hook should load field values and add them to 1717 * objects in $entities. Fields with no values should be added as empty 1718 * arrays. 1719 * 1720 * @param $entity_type 1721 * The type of entity, such as 'node' or 'user'. 1722 * @param $entities 1723 * The array of entity objects to add fields to, keyed by entity ID. 1724 * @param $age 1725 * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or 1726 * FIELD_LOAD_REVISION to load the version indicated by each entity. 1727 * @param $fields 1728 * An array listing the fields to be loaded. The keys of the array are field 1729 * IDs, and the values of the array are the entity IDs (or revision IDs, 1730 * depending on the $age parameter) to add each field to. 1731 * @param $options 1732 * An associative array of additional options, with the following keys: 1733 * - deleted: If TRUE, deleted fields should be loaded as well as 1734 * non-deleted fields. If unset or FALSE, only non-deleted fields should be 1735 * loaded. 1736 */ 1737 function hook_field_storage_load($entity_type, $entities, $age, $fields, $options) { 1738 $field_info = field_info_field_by_ids(); 1739 $load_current = $age == FIELD_LOAD_CURRENT; 1740 1741 foreach ($fields as $field_id => $ids) { 1742 $field = $field_info[$field_id]; 1743 $field_name = $field['field_name']; 1744 $table = $load_current ? _field_sql_storage_tablename($field) : _field_sql_storage_revision_tablename($field); 1745 1746 $query = db_select($table, 't') 1747 ->fields('t') 1748 ->condition('entity_type', $entity_type) 1749 ->condition($load_current ? 'entity_id' : 'revision_id', $ids, 'IN') 1750 ->condition('language', field_available_languages($entity_type, $field), 'IN') 1751 ->orderBy('delta'); 1752 1753 if (empty($options['deleted'])) { 1754 $query->condition('deleted', 0); 1755 } 1756 1757 $results = $query->execute(); 1758 1759 $delta_count = array(); 1760 foreach ($results as $row) { 1761 if (!isset($delta_count[$row->entity_id][$row->language])) { 1762 $delta_count[$row->entity_id][$row->language] = 0; 1763 } 1764 1765 if ($field['cardinality'] == FIELD_CARDINALITY_UNLIMITED || $delta_count[$row->entity_id][$row->language] < $field['cardinality']) { 1766 $item = array(); 1767 // For each column declared by the field, populate the item 1768 // from the prefixed database column. 1769 foreach ($field['columns'] as $column => $attributes) { 1770 $column_name = _field_sql_storage_columnname($field_name, $column); 1771 $item[$column] = $row->$column_name; 1772 } 1773 1774 // Add the item to the field values for the entity. 1775 $entities[$row->entity_id]->{$field_name}[$row->language][] = $item; 1776 $delta_count[$row->entity_id][$row->language]++; 1777 } 1778 } 1779 } 1780 } 1781 1782 /** 1783 * Write field data for an entity. 1784 * 1785 * This hook is invoked from field_attach_insert() and field_attach_update(), 1786 * to ask the field storage module to save field data. 1787 * 1788 * @param $entity_type 1789 * The entity type of entity, such as 'node' or 'user'. 1790 * @param $entity 1791 * The entity on which to operate. 1792 * @param $op 1793 * FIELD_STORAGE_UPDATE when updating an existing entity, 1794 * FIELD_STORAGE_INSERT when inserting a new entity. 1795 * @param $fields 1796 * An array listing the fields to be written. The keys and values of the 1797 * array are field IDs. 1798 */ 1799 function hook_field_storage_write($entity_type, $entity, $op, $fields) { 1800 list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity); 1801 if (!isset($vid)) { 1802 $vid = $id; 1803 } 1804 1805 foreach ($fields as $field_id) { 1806 $field = field_info_field_by_id($field_id); 1807 $field_name = $field['field_name']; 1808 $table_name = _field_sql_storage_tablename($field); 1809 $revision_name = _field_sql_storage_revision_tablename($field); 1810 1811 $all_languages = field_available_languages($entity_type, $field); 1812 $field_languages = array_intersect($all_languages, array_keys((array) $entity->$field_name)); 1813 1814 // Delete and insert, rather than update, in case a value was added. 1815 if ($op == FIELD_STORAGE_UPDATE) { 1816 // Delete languages present in the incoming $entity->$field_name. 1817 // Delete all languages if $entity->$field_name is empty. 1818 $languages = !empty($entity->$field_name) ? $field_languages : $all_languages; 1819 if ($languages) { 1820 db_delete($table_name) 1821 ->condition('entity_type', $entity_type) 1822 ->condition('entity_id', $id) 1823 ->condition('language', $languages, 'IN') 1824 ->execute(); 1825 db_delete($revision_name) 1826 ->condition('entity_type', $entity_type) 1827 ->condition('entity_id', $id) 1828 ->condition('revision_id', $vid) 1829 ->condition('language', $languages, 'IN') 1830 ->execute(); 1831 } 1832 } 1833 1834 // Prepare the multi-insert query. 1835 $do_insert = FALSE; 1836 $columns = array('entity_type', 'entity_id', 'revision_id', 'bundle', 'delta', 'language'); 1837 foreach ($field['columns'] as $column => $attributes) { 1838 $columns[] = _field_sql_storage_columnname($field_name, $column); 1839 } 1840 $query = db_insert($table_name)->fields($columns); 1841 $revision_query = db_insert($revision_name)->fields($columns); 1842 1843 foreach ($field_languages as $langcode) { 1844 $items = (array) $entity->{$field_name}[$langcode]; 1845 $delta_count = 0; 1846 foreach ($items as $delta => $item) { 1847 // We now know we have someting to insert. 1848 $do_insert = TRUE; 1849 $record = array( 1850 'entity_type' => $entity_type, 1851 'entity_id' => $id, 1852 'revision_id' => $vid, 1853 'bundle' => $bundle, 1854 'delta' => $delta, 1855 'language' => $langcode, 1856 ); 1857 foreach ($field['columns'] as $column => $attributes) { 1858 $record[_field_sql_storage_columnname($field_name, $column)] = isset($item[$column]) ? $item[$column] : NULL; 1859 } 1860 $query->values($record); 1861 if (isset($vid)) { 1862 $revision_query->values($record); 1863 } 1864 1865 if ($field['cardinality'] != FIELD_CARDINALITY_UNLIMITED && ++$delta_count == $field['cardinality']) { 1866 break; 1867 } 1868 } 1869 } 1870 1871 // Execute the query if we have values to insert. 1872 if ($do_insert) { 1873 $query->execute(); 1874 $revision_query->execute(); 1875 } 1876 } 1877 } 1878 1879 /** 1880 * Delete all field data for an entity. 1881 * 1882 * This hook is invoked from field_attach_delete() to ask the field storage 1883 * module to delete field data. 1884 * 1885 * @param $entity_type 1886 * The entity type of entity, such as 'node' or 'user'. 1887 * @param $entity 1888 * The entity on which to operate. 1889 * @param $fields 1890 * An array listing the fields to delete. The keys and values of the 1891 * array are field IDs. 1892 */ 1893 function hook_field_storage_delete($entity_type, $entity, $fields) { 1894 list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity); 1895 1896 foreach (field_info_instances($entity_type, $bundle) as $instance) { 1897 if (isset($fields[$instance['field_id']])) { 1898 $field = field_info_field_by_id($instance['field_id']); 1899 field_sql_storage_field_storage_purge($entity_type, $entity, $field, $instance); 1900 } 1901 } 1902 } 1903 1904 /** 1905 * Delete a single revision of field data for an entity. 1906 * 1907 * This hook is invoked from field_attach_delete_revision() to ask the field 1908 * storage module to delete field revision data. 1909 * 1910 * Deleting the current (most recently written) revision is not 1911 * allowed as has undefined results. 1912 * 1913 * @param $entity_type 1914 * The entity type of entity, such as 'node' or 'user'. 1915 * @param $entity 1916 * The entity on which to operate. The revision to delete is 1917 * indicated by the entity's revision ID property, as identified by 1918 * hook_fieldable_info() for $entity_type. 1919 * @param $fields 1920 * An array listing the fields to delete. The keys and values of the 1921 * array are field IDs. 1922 */ 1923 function hook_field_storage_delete_revision($entity_type, $entity, $fields) { 1924 list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity); 1925 1926 if (isset($vid)) { 1927 foreach ($fields as $field_id) { 1928 $field = field_info_field_by_id($field_id); 1929 $revision_name = _field_sql_storage_revision_tablename($field); 1930 db_delete($revision_name) 1931 ->condition('entity_type', $entity_type) 1932 ->condition('entity_id', $id) 1933 ->condition('revision_id', $vid) 1934 ->execute(); 1935 } 1936 } 1937 } 1938 1939 /** 1940 * Execute an EntityFieldQuery. 1941 * 1942 * This hook is called to find the entities having certain entity and field 1943 * conditions and sort them in the given field order. If the field storage 1944 * engine also handles property sorts and orders, it should unset those 1945 * properties in the called object to signal that those have been handled. 1946 * 1947 * @param EntityFieldQuery $query 1948 * An EntityFieldQuery. 1949 * 1950 * @return 1951 * See EntityFieldQuery::execute() for the return values. 1952 */ 1953 function hook_field_storage_query($query) { 1954 $groups = array(); 1955 if ($query->age == FIELD_LOAD_CURRENT) { 1956 $tablename_function = '_field_sql_storage_tablename'; 1957 $id_key = 'entity_id'; 1958 } 1959 else { 1960 $tablename_function = '_field_sql_storage_revision_tablename'; 1961 $id_key = 'revision_id'; 1962 } 1963 $table_aliases = array(); 1964 // Add tables for the fields used. 1965 foreach ($query->fields as $key => $field) { 1966 $tablename = $tablename_function($field); 1967 // Every field needs a new table. 1968 $table_alias = $tablename . $key; 1969 $table_aliases[$key] = $table_alias; 1970 if ($key) { 1971 $select_query->join($tablename, $table_alias, "$table_alias.entity_type = $field_base_table.entity_type AND $table_alias.$id_key = $field_base_table.$id_key"); 1972 } 1973 else { 1974 $select_query = db_select($tablename, $table_alias); 1975 $select_query->addTag('entity_field_access'); 1976 $select_query->addMetaData('base_table', $tablename); 1977 $select_query->fields($table_alias, array('entity_type', 'entity_id', 'revision_id', 'bundle')); 1978 $field_base_table = $table_alias; 1979 } 1980 if ($field['cardinality'] != 1) { 1981 $select_query->distinct(); 1982 } 1983 } 1984 1985 // Add field conditions. 1986 foreach ($query->fieldConditions as $key => $condition) { 1987 $table_alias = $table_aliases[$key]; 1988 $field = $condition['field']; 1989 // Add the specified condition. 1990 $sql_field = "$table_alias." . _field_sql_storage_columnname($field['field_name'], $condition['column']); 1991 $query->addCondition($select_query, $sql_field, $condition); 1992 // Add delta / language group conditions. 1993 foreach (array('delta', 'language') as $column) { 1994 if (isset($condition[$column . '_group'])) { 1995 $group_name = $condition[$column . '_group']; 1996 if (!isset($groups[$column][$group_name])) { 1997 $groups[$column][$group_name] = $table_alias; 1998 } 1999 else { 2000 $select_query->where("$table_alias.$column = " . $groups[$column][$group_name] . ".$column"); 2001 } 2002 } 2003 } 2004 } 2005 2006 if (isset($query->deleted)) { 2007 $select_query->condition("$field_base_table.deleted", (int) $query->deleted); 2008 } 2009 2010 // Is there a need to sort the query by property? 2011 $has_property_order = FALSE; 2012 foreach ($query->order as $order) { 2013 if ($order['type'] == 'property') { 2014 $has_property_order = TRUE; 2015 } 2016 } 2017 2018 if ($query->propertyConditions || $has_property_order) { 2019 if (empty($query->entityConditions['entity_type']['value'])) { 2020 throw new EntityFieldQueryException('Property conditions and orders must have an entity type defined.'); 2021 } 2022 $entity_type = $query->entityConditions['entity_type']['value']; 2023 $entity_base_table = _field_sql_storage_query_join_entity($select_query, $entity_type, $field_base_table); 2024 $query->entityConditions['entity_type']['operator'] = '='; 2025 foreach ($query->propertyConditions as $property_condition) { 2026 $query->addCondition($select_query, "$entity_base_table." . $property_condition['column'], $property_condition); 2027 } 2028 } 2029 foreach ($query->entityConditions as $key => $condition) { 2030 $query->addCondition($select_query, "$field_base_table.$key", $condition); 2031 } 2032 2033 // Order the query. 2034 foreach ($query->order as $order) { 2035 if ($order['type'] == 'entity') { 2036 $key = $order['specifier']; 2037 $select_query->orderBy("$field_base_table.$key", $order['direction']); 2038 } 2039 elseif ($order['type'] == 'field') { 2040 $specifier = $order['specifier']; 2041 $field = $specifier['field']; 2042 $table_alias = $table_aliases[$specifier['index']]; 2043 $sql_field = "$table_alias." . _field_sql_storage_columnname($field['field_name'], $specifier['column']); 2044 $select_query->orderBy($sql_field, $order['direction']); 2045 } 2046 elseif ($order['type'] == 'property') { 2047 $select_query->orderBy("$entity_base_table." . $order['specifier'], $order['direction']); 2048 } 2049 } 2050 2051 return $query->finishQuery($select_query, $id_key); 2052 } 2053 2054 /** 2055 * Act on creation of a new field. 2056 * 2057 * This hook is invoked from field_create_field() to ask the field storage 2058 * module to save field information and prepare for storing field instances. 2059 * If there is a problem, the field storage module should throw an exception. 2060 * 2061 * @param $field 2062 * The field structure being created. 2063 */ 2064 function hook_field_storage_create_field($field) { 2065 $schema = _field_sql_storage_schema($field); 2066 foreach ($schema as $name => $table) { 2067 db_create_table($name, $table); 2068 } 2069 drupal_get_schema(NULL, TRUE); 2070 } 2071 2072 /** 2073 * Act on deletion of a field. 2074 * 2075 * This hook is invoked from field_delete_field() to ask the field storage 2076 * module to mark all information stored in the field for deletion. 2077 * 2078 * @param $field 2079 * The field being deleted. 2080 */ 2081 function hook_field_storage_delete_field($field) { 2082 // Mark all data associated with the field for deletion. 2083 $field['deleted'] = 0; 2084 $table = _field_sql_storage_tablename($field); 2085 $revision_table = _field_sql_storage_revision_tablename($field); 2086 db_update($table) 2087 ->fields(array('deleted' => 1)) 2088 ->execute(); 2089 2090 // Move the table to a unique name while the table contents are being deleted. 2091 $field['deleted'] = 1; 2092 $new_table = _field_sql_storage_tablename($field); 2093 $revision_new_table = _field_sql_storage_revision_tablename($field); 2094 db_rename_table($table, $new_table); 2095 db_rename_table($revision_table, $revision_new_table); 2096 drupal_get_schema(NULL, TRUE); 2097 } 2098 2099 /** 2100 * Act on deletion of a field instance. 2101 * 2102 * This hook is invoked from field_delete_instance() to ask the field storage 2103 * module to mark all information stored for the field instance for deletion. 2104 * 2105 * @param $instance 2106 * The instance being deleted. 2107 */ 2108 function hook_field_storage_delete_instance($instance) { 2109 $field = field_info_field($instance['field_name']); 2110 $table_name = _field_sql_storage_tablename($field); 2111 $revision_name = _field_sql_storage_revision_tablename($field); 2112 db_update($table_name) 2113 ->fields(array('deleted' => 1)) 2114 ->condition('entity_type', $instance['entity_type']) 2115 ->condition('bundle', $instance['bundle']) 2116 ->execute(); 2117 db_update($revision_name) 2118 ->fields(array('deleted' => 1)) 2119 ->condition('entity_type', $instance['entity_type']) 2120 ->condition('bundle', $instance['bundle']) 2121 ->execute(); 2122 } 2123 2124 /** 2125 * Act before the storage backends load field data. 2126 * 2127 * This hook allows modules to load data before the Field Storage API, 2128 * optionally preventing the field storage module from doing so. 2129 * 2130 * This lets 3rd party modules override, mirror, shard, or otherwise store a 2131 * subset of fields in a different way than the current storage engine. 2132 * Possible use cases include per-bundle storage, per-combo-field storage, etc. 2133 * 2134 * Modules implementing this hook should load field values and add them to 2135 * objects in $entities. Fields with no values should be added as empty 2136 * arrays. In addition, fields loaded should be added as keys to $skip_fields. 2137 * 2138 * @param $entity_type 2139 * The type of entity, such as 'node' or 'user'. 2140 * @param $entities 2141 * The array of entity objects to add fields to, keyed by entity ID. 2142 * @param $age 2143 * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or 2144 * FIELD_LOAD_REVISION to load the version indicated by each entity. 2145 * @param $skip_fields 2146 * An array keyed by field IDs whose data has already been loaded and 2147 * therefore should not be loaded again. Add a key to this array to indicate 2148 * that your module has already loaded a field. 2149 * @param $options 2150 * An associative array of additional options, with the following keys: 2151 * - field_id: The field ID that should be loaded. If unset, all fields 2152 * should be loaded. 2153 * - deleted: If TRUE, deleted fields should be loaded as well as 2154 * non-deleted fields. If unset or FALSE, only non-deleted fields should be 2155 * loaded. 2156 */ 2157 function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields, $options) { 2158 // @todo Needs function body. 2159 } 2160 2161 /** 2162 * Act before the storage backends insert field data. 2163 * 2164 * This hook allows modules to store data before the Field Storage API, 2165 * optionally preventing the field storage module from doing so. 2166 * 2167 * @param $entity_type 2168 * The type of $entity; for example, 'node' or 'user'. 2169 * @param $entity 2170 * The entity with fields to save. 2171 * @param $skip_fields 2172 * An array keyed by field IDs whose data has already been written and 2173 * therefore should not be written again. The values associated with these 2174 * keys are not specified. 2175 * @return 2176 * Saved field IDs are set set as keys in $skip_fields. 2177 */ 2178 function hook_field_storage_pre_insert($entity_type, $entity, &$skip_fields) { 2179 if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) { 2180 $query = db_insert('forum_index')->fields(array('nid', 'title', 'tid', 'sticky', 'created', 'comment_count', 'last_comment_timestamp')); 2181 foreach ($entity->taxonomy_forums as $language) { 2182 foreach ($language as $delta) { 2183 $query->values(array( 2184 'nid' => $entity->nid, 2185 'title' => $entity->title, 2186 'tid' => $delta['value'], 2187 'sticky' => $entity->sticky, 2188 'created' => $entity->created, 2189 'comment_count' => 0, 2190 'last_comment_timestamp' => $entity->created, 2191 )); 2192 } 2193 } 2194 $query->execute(); 2195 } 2196 } 2197 2198 /** 2199 * Act before the storage backends update field data. 2200 * 2201 * This hook allows modules to store data before the Field Storage API, 2202 * optionally preventing the field storage module from doing so. 2203 * 2204 * @param $entity_type 2205 * The type of $entity; for example, 'node' or 'user'. 2206 * @param $entity 2207 * The entity with fields to save. 2208 * @param $skip_fields 2209 * An array keyed by field IDs whose data has already been written and 2210 * therefore should not be written again. The values associated with these 2211 * keys are not specified. 2212 * @return 2213 * Saved field IDs are set set as keys in $skip_fields. 2214 */ 2215 function hook_field_storage_pre_update($entity_type, $entity, &$skip_fields) { 2216 $first_call = &drupal_static(__FUNCTION__, array()); 2217 2218 if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) { 2219 // We don't maintain data for old revisions, so clear all previous values 2220 // from the table. Since this hook runs once per field, per entity, make 2221 // sure we only wipe values once. 2222 if (!isset($first_call[$entity->nid])) { 2223 $first_call[$entity->nid] = FALSE; 2224 db_delete('forum_index')->condition('nid', $entity->nid)->execute(); 2225 } 2226 // Only save data to the table if the node is published. 2227 if ($entity->status) { 2228 $query = db_insert('forum_index')->fields(array('nid', 'title', 'tid', 'sticky', 'created', 'comment_count', 'last_comment_timestamp')); 2229 foreach ($entity->taxonomy_forums as $language) { 2230 foreach ($language as $delta) { 2231 $query->values(array( 2232 'nid' => $entity->nid, 2233 'title' => $entity->title, 2234 'tid' => $delta['value'], 2235 'sticky' => $entity->sticky, 2236 'created' => $entity->created, 2237 'comment_count' => 0, 2238 'last_comment_timestamp' => $entity->created, 2239 )); 2240 } 2241 } 2242 $query->execute(); 2243 // The logic for determining last_comment_count is fairly complex, so 2244 // call _forum_update_forum_index() too. 2245 _forum_update_forum_index($entity->nid); 2246 } 2247 } 2248 } 2249 2250 /** 2251 * Returns the maximum weight for the entity components handled by the module. 2252 * 2253 * Field API takes care of fields and 'extra_fields'. This hook is intended for 2254 * third-party modules adding other entity components (e.g. field_group). 2255 * 2256 * @param $entity_type 2257 * The type of entity; e.g. 'node' or 'user'. 2258 * @param $bundle 2259 * The bundle name. 2260 * @param $context 2261 * The context for which the maximum weight is requested. Either 'form', or 2262 * the name of a view mode. 2263 * @return 2264 * The maximum weight of the entity's components, or NULL if no components 2265 * were found. 2266 */ 2267 function hook_field_info_max_weight($entity_type, $bundle, $context) { 2268 $weights = array(); 2269 2270 foreach (my_module_entity_additions($entity_type, $bundle, $context) as $addition) { 2271 $weights[] = $addition['weight']; 2272 } 2273 2274 return $weights ? max($weights) : NULL; 2275 } 2276 2277 /** 2278 * Alters the display settings of a field before it gets displayed. 2279 * 2280 * Note that instead of hook_field_display_alter(), which is called for all 2281 * fields on all entity types, hook_field_display_ENTITY_TYPE_alter() may be 2282 * used to alter display settings for fields on a specific entity type only. 2283 * 2284 * This hook is called once per field per displayed entity. If the result of the 2285 * hook involves reading from the database, it is highly recommended to 2286 * statically cache the information. 2287 * 2288 * @param $display 2289 * The display settings that will be used to display the field values, as 2290 * found in the 'display' key of $instance definitions. 2291 * @param $context 2292 * An associative array containing: 2293 * - entity_type: The entity type; e.g., 'node' or 'user'. 2294 * - field: The field being rendered. 2295 * - instance: The instance being rendered. 2296 * - entity: The entity being rendered. 2297 * - view_mode: The view mode, e.g. 'full', 'teaser'... 2298 * 2299 * @see hook_field_display_ENTITY_TYPE_alter() 2300 */ 2301 function hook_field_display_alter(&$display, $context) { 2302 // Leave field labels out of the search index. 2303 // Note: The check against $context['entity_type'] == 'node' could be avoided 2304 // by using hook_field_display_node_alter() instead of 2305 // hook_field_display_alter(), resulting in less function calls when 2306 // rendering non-node entities. 2307 if ($context['entity_type'] == 'node' && $context['view_mode'] == 'search_index') { 2308 $display['label'] = 'hidden'; 2309 } 2310 } 2311 2312 /** 2313 * Alters the display settings of a field on a given entity type before it gets displayed. 2314 * 2315 * Modules can implement hook_field_display_ENTITY_TYPE_alter() to alter display 2316 * settings for fields on a specific entity type, rather than implementing 2317 * hook_field_display_alter(). 2318 * 2319 * This hook is called once per field per displayed entity. If the result of the 2320 * hook involves reading from the database, it is highly recommended to 2321 * statically cache the information. 2322 * 2323 * @param $display 2324 * The display settings that will be used to display the field values, as 2325 * found in the 'display' key of $instance definitions. 2326 * @param $context 2327 * An associative array containing: 2328 * - entity_type: The entity type; e.g., 'node' or 'user'. 2329 * - field: The field being rendered. 2330 * - instance: The instance being rendered. 2331 * - entity: The entity being rendered. 2332 * - view_mode: The view mode, e.g. 'full', 'teaser'... 2333 * 2334 * @see hook_field_display_alter() 2335 */ 2336 function hook_field_display_ENTITY_TYPE_alter(&$display, $context) { 2337 // Leave field labels out of the search index. 2338 if ($context['view_mode'] == 'search_index') { 2339 $display['label'] = 'hidden'; 2340 } 2341 } 2342 2343 /** 2344 * Alters the display settings of pseudo-fields before an entity is displayed. 2345 * 2346 * This hook is called once per displayed entity. If the result of the hook 2347 * involves reading from the database, it is highly recommended to statically 2348 * cache the information. 2349 * 2350 * @param $displays 2351 * An array of display settings for the pseudo-fields in the entity, keyed 2352 * by pseudo-field names. 2353 * @param $context 2354 * An associative array containing: 2355 * - entity_type: The entity type; e.g., 'node' or 'user'. 2356 * - bundle: The bundle name. 2357 * - view_mode: The view mode, e.g. 'full', 'teaser'... 2358 */ 2359 function hook_field_extra_fields_display_alter(&$displays, $context) { 2360 if ($context['entity_type'] == 'taxonomy_term' && $context['view_mode'] == 'full') { 2361 $displays['description']['visible'] = FALSE; 2362 } 2363 } 2364 2365 /** 2366 * Alters the widget properties of a field instance on a given entity type 2367 * before it gets displayed. 2368 * 2369 * Modules can implement hook_field_widget_properties_ENTITY_TYPE_alter() to 2370 * alter the widget properties for fields on a specific entity type, rather than 2371 * implementing hook_field_widget_properties_alter(). 2372 * 2373 * This hook is called once per field per displayed widget entity. If the result 2374 * of the hook involves reading from the database, it is highly recommended to 2375 * statically cache the information. 2376 * 2377 * @param $widget 2378 * The instance's widget properties. 2379 * @param $context 2380 * An associative array containing: 2381 * - entity_type: The entity type; e.g., 'node' or 'user'. 2382 * - entity: The entity object. 2383 * - field: The field that the widget belongs to. 2384 * - instance: The instance of the field. 2385 * 2386 * @see hook_field_widget_properties_alter() 2387 */ 2388 function hook_field_widget_properties_ENTITY_TYPE_alter(&$widget, $context) { 2389 // Change a widget's type according to the time of day. 2390 $field = $context['field']; 2391 if ($field['field_name'] == 'field_foo') { 2392 $time = date('H'); 2393 $widget['type'] = $time < 12 ? 'widget_am' : 'widget_pm'; 2394 } 2395 } 2396 2397 /** 2398 * @} End of "addtogroup field_storage". 2399 */ 2400 2401 /** 2402 * @addtogroup field_crud 2403 * @{ 2404 */ 2405 2406 /** 2407 * Act on a field being created. 2408 * 2409 * This hook is invoked from field_create_field() after the field is created, to 2410 * allow modules to act on field creation. 2411 * 2412 * @param $field 2413 * The field just created. 2414 */ 2415 function hook_field_create_field($field) { 2416 // @todo Needs function body. 2417 } 2418 2419 /** 2420 * Act on a field instance being created. 2421 * 2422 * This hook is invoked from field_create_instance() after the instance record 2423 * is saved, so it cannot be used to modify the instance itself. 2424 * 2425 * @param $instance 2426 * The instance just created. 2427 */ 2428 function hook_field_create_instance($instance) { 2429 // @todo Needs function body. 2430 } 2431 2432 /** 2433 * Forbid a field update from occurring. 2434 * 2435 * Any module may forbid any update for any reason. For example, the 2436 * field's storage module might forbid an update if it would change 2437 * the storage schema while data for the field exists. A field type 2438 * module might forbid an update if it would change existing data's 2439 * semantics, or if there are external dependencies on field settings 2440 * that cannot be updated. 2441 * 2442 * To forbid the update from occurring, throw a FieldUpdateForbiddenException. 2443 * 2444 * @param $field 2445 * The field as it will be post-update. 2446 * @param $prior_field 2447 * The field as it is pre-update. 2448 * @param $has_data 2449 * Whether any data already exists for this field. 2450 */ 2451 function hook_field_update_forbid($field, $prior_field, $has_data) { 2452 // A 'list' field stores integer keys mapped to display values. If 2453 // the new field will have fewer values, and any data exists for the 2454 // abandoned keys, the field will have no way to display them. So, 2455 // forbid such an update. 2456 if ($has_data && count($field['settings']['allowed_values']) < count($prior_field['settings']['allowed_values'])) { 2457 // Identify the keys that will be lost. 2458 $lost_keys = array_diff(array_keys($field['settings']['allowed_values']), array_keys($prior_field['settings']['allowed_values'])); 2459 // If any data exist for those keys, forbid the update. 2460 $query = new EntityFieldQuery(); 2461 $found = $query 2462 ->fieldCondition($prior_field['field_name'], 'value', $lost_keys) 2463 ->range(0, 1) 2464 ->execute(); 2465 if ($found) { 2466 throw new FieldUpdateForbiddenException("Cannot update a list field not to include keys with existing data"); 2467 } 2468 } 2469 } 2470 2471 /** 2472 * Act on a field being updated. 2473 * 2474 * This hook is invoked just after field is updated in field_update_field(). 2475 * 2476 * @param $field 2477 * The field as it is post-update. 2478 * @param $prior_field 2479 * The field as it was pre-update. 2480 * @param $has_data 2481 * Whether any data already exists for this field. 2482 */ 2483 function hook_field_update_field($field, $prior_field, $has_data) { 2484 // Reset the static value that keeps track of allowed values for list fields. 2485 drupal_static_reset('list_allowed_values'); 2486 } 2487 2488 /** 2489 * Act on a field being deleted. 2490 * 2491 * This hook is invoked just after a field is deleted by field_delete_field(). 2492 * 2493 * @param $field 2494 * The field just deleted. 2495 */ 2496 function hook_field_delete_field($field) { 2497 // @todo Needs function body. 2498 } 2499 2500 /** 2501 * Act on a field instance being updated. 2502 * 2503 * This hook is invoked from field_update_instance() after the instance record 2504 * is saved, so it cannot be used by a module to modify the instance itself. 2505 * 2506 * @param $instance 2507 * The instance as it is post-update. 2508 * @param $prior_$instance 2509 * The instance as it was pre-update. 2510 */ 2511 function hook_field_update_instance($instance, $prior_instance) { 2512 // @todo Needs function body. 2513 } 2514 2515 /** 2516 * Act on a field instance being deleted. 2517 * 2518 * This hook is invoked from field_delete_instance() after the instance is 2519 * deleted. 2520 * 2521 * @param $instance 2522 * The instance just deleted. 2523 */ 2524 function hook_field_delete_instance($instance) { 2525 // @todo Needs function body. 2526 } 2527 2528 /** 2529 * Act on field records being read from the database. 2530 * 2531 * This hook is invoked from field_read_fields() on each field being read. 2532 * 2533 * @param $field 2534 * The field record just read from the database. 2535 */ 2536 function hook_field_read_field($field) { 2537 // @todo Needs function body. 2538 } 2539 2540 /** 2541 * Act on a field record being read from the database. 2542 * 2543 * This hook is invoked from field_read_instances() on each instance being read. 2544 * 2545 * @param $instance 2546 * The instance record just read from the database. 2547 */ 2548 function hook_field_read_instance($instance) { 2549 // @todo Needs function body. 2550 } 2551 2552 /** 2553 * Acts when a field record is being purged. 2554 * 2555 * In field_purge_field(), after the field configuration has been 2556 * removed from the database, the field storage module has had a chance to 2557 * run its hook_field_storage_purge_field(), and the field info cache 2558 * has been cleared, this hook is invoked on all modules to allow them to 2559 * respond to the field being purged. 2560 * 2561 * @param $field 2562 * The field being purged. 2563 */ 2564 function hook_field_purge_field($field) { 2565 db_delete('my_module_field_info') 2566 ->condition('id', $field['id']) 2567 ->execute(); 2568 } 2569 2570 /** 2571 * Acts when a field instance is being purged. 2572 * 2573 * In field_purge_instance(), after the field instance has been 2574 * removed from the database, the field storage module has had a chance to 2575 * run its hook_field_storage_purge_instance(), and the field info cache 2576 * has been cleared, this hook is invoked on all modules to allow them to 2577 * respond to the field instance being purged. 2578 * 2579 * @param $instance 2580 * The instance being purged. 2581 */ 2582 function hook_field_purge_instance($instance) { 2583 db_delete('my_module_field_instance_info') 2584 ->condition('id', $instance['id']) 2585 ->execute(); 2586 } 2587 2588 /** 2589 * Remove field storage information when a field record is purged. 2590 * 2591 * Called from field_purge_field() to allow the field storage module 2592 * to remove field information when a field is being purged. 2593 * 2594 * @param $field 2595 * The field being purged. 2596 */ 2597 function hook_field_storage_purge_field($field) { 2598 $table_name = _field_sql_storage_tablename($field); 2599 $revision_name = _field_sql_storage_revision_tablename($field); 2600 db_drop_table($table_name); 2601 db_drop_table($revision_name); 2602 } 2603 2604 /** 2605 * Remove field storage information when a field instance is purged. 2606 * 2607 * Called from field_purge_instance() to allow the field storage module 2608 * to remove field instance information when a field instance is being 2609 * purged. 2610 * 2611 * @param $instance 2612 * The instance being purged. 2613 */ 2614 function hook_field_storage_purge_field_instance($instance) { 2615 db_delete('my_module_field_instance_info') 2616 ->condition('id', $instance['id']) 2617 ->execute(); 2618 } 2619 2620 /** 2621 * Remove field storage information when field data is purged. 2622 * 2623 * Called from field_purge_data() to allow the field storage 2624 * module to delete field data information. 2625 * 2626 * @param $entity_type 2627 * The type of $entity; for example, 'node' or 'user'. 2628 * @param $entity 2629 * The pseudo-entity whose field data to delete. 2630 * @param $field 2631 * The (possibly deleted) field whose data is being purged. 2632 * @param $instance 2633 * The deleted field instance whose data is being purged. 2634 */ 2635 function hook_field_storage_purge($entity_type, $entity, $field, $instance) { 2636 list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity); 2637 2638 $table_name = _field_sql_storage_tablename($field); 2639 $revision_name = _field_sql_storage_revision_tablename($field); 2640 db_delete($table_name) 2641 ->condition('entity_type', $entity_type) 2642 ->condition('entity_id', $id) 2643 ->execute(); 2644 db_delete($revision_name) 2645 ->condition('entity_type', $entity_type) 2646 ->condition('entity_id', $id) 2647 ->execute(); 2648 } 2649 2650 /** 2651 * @} End of "addtogroup field_crud". 2652 */ 2653 2654 /** 2655 * Determine whether the user has access to a given field. 2656 * 2657 * This hook is invoked from field_access() to let modules block access to 2658 * operations on fields. If no module returns FALSE, the operation is allowed. 2659 * 2660 * @param $op 2661 * The operation to be performed. Possible values: 'edit', 'view'. 2662 * @param $field 2663 * The field on which the operation is to be performed. 2664 * @param $entity_type 2665 * The type of $entity; for example, 'node' or 'user'. 2666 * @param $entity 2667 * (optional) The entity for the operation. 2668 * @param $account 2669 * (optional) The account to check; if not given use currently logged in user. 2670 * 2671 * @return 2672 * TRUE if the operation is allowed, and FALSE if the operation is denied. 2673 */ 2674 function hook_field_access($op, $field, $entity_type, $entity, $account) { 2675 if ($field['field_name'] == 'field_of_interest' && $op == 'edit') { 2676 return user_access('edit field of interest', $account); 2677 } 2678 return TRUE; 2679 } 2680 2681 /** 2682 * @} End of "addtogroup hooks". 2683 */
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
title