Project

General

Profile

Paste
Download (24.3 KB) Statistics
| Branch: | Revision:

root / drupal7 / sites / all / modules / entity / entity.api.php @ 7d7b5830

1
<?php
2

    
3
/**
4
 * @file
5
 * Hooks provided by the entity API.
6
 */
7

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

    
13
/**
14
 * Provide an entity type via the entity CRUD API.
15
 *
16
 * This is a placeholder for describing further keys for hook_entity_info(),
17
 * which are introduced the entity API for providing a new entity type with the
18
 * entity CRUD API. For that the entity API provides two controllers:
19
 *  - EntityAPIController: A regular CRUD controller.
20
 *  - EntityAPIControllerExportable: Extends the regular controller to
21
 *    additionally support exportable entities and/or entities making use of a
22
 *    name key.
23
 * See entity_metadata_hook_entity_info() for the documentation of additional
24
 * keys for hook_entity_info() as introduced by the entity API and supported for
25
 * any entity type.
26
 *
27
 * The entity CRUD API supports the following keys:
28
 * - entity class: (optional) A class the controller will use for instantiating
29
 *   entities. It is suggested to make use of the provided "Entity" class or to
30
 *   extend it.
31
 * - bundle of: (optional) Entity types can be used as bundles for
32
 *   other entity types. To enable this functionality, use the 'bundle of' key
33
 *   to indicate which entity type this entity serves as a bundle for. But note
34
 *   that the other entity type will still need to declare entities of this
35
 *   type as bundles, as described by the documentation of hook_entity_info().
36
 *   If the other entity type is fieldable, the entity API controller takes
37
 *   care of invoking the field API bundle attachers. Note that
38
 *   field_attach_delete_bundle() has to be invoked manually upon module
39
 *   uninstallation. See entity_test_entity_info() and entity_test_uninstall()
40
 *   for examples.
41
 * - module: (optional) The module providing the entity type. This is optional,
42
 *   but strongly suggested.
43
 * - exportable: (optional) Whether the entity is exportable. Defaults to FALSE.
44
 *   If enabled, a name key should be specified and db columns for the module
45
 *   and status key as defined by entity_exportable_schema_fields() have to
46
 *   exist in the entity's base table. Also see 'entity keys' below.
47
 *   This option requires the EntityAPIControllerExportable to work.
48
 * - entity keys: An array of keys as defined by Drupal core. The following
49
 *   additional keys are used by the entity CRUD API:
50
 *   - name: (optional) The key of the entity property containing the unique,
51
 *     machine readable name of the entity. If specified, this is used as
52
 *     identifier of the entity, while the usual 'id' key is still required and
53
 *     may be used when modules deal with entities generically, or to refer to
54
 *     the entity internally, i.e. in the database.
55
 *     If a name key is given, the name is used as entity identifier by the
56
 *     entity API module, metadata wrappers and entity-type specific hooks.
57
 *     However note that for consistency all generic entity hooks like
58
 *     hook_entity_load() are invoked with the entities keyed by numeric id,
59
 *     while entity-type specific hooks like hook_{entity_type}_load() are
60
 *     invoked with the entities keyed by name.
61
 *     Also, just as entity_load_single() entity_load() may be called
62
 *     with names passed as the $ids parameter, while the results of
63
 *     entity_load() are always keyed by numeric id. Thus, it is suggested to
64
 *     make use of entity_load_multiple_by_name() to implement entity-type
65
 *     specific loading functions like {entity_type}_load_multiple(), as this
66
 *     function returns the entities keyed by name. See entity_test_get_types()
67
 *     for an example.
68
 *     For exportable entities, it is strongly recommended to make use of a
69
 *     machine name as names are portable across systems.
70
 *     This option requires the EntityAPIControllerExportable to work.
71
 *   - module: (optional) A key for the module property used by the entity CRUD
72
 *     API to save the source module name for exportable entities that have been
73
 *     provided in code. Defaults to 'module'.
74
 *   - status: (optional) The name of the entity property used by the entity
75
 *     CRUD API to save the exportable entity status using defined bit flags.
76
 *     Defaults to 'status'. See entity_has_status().
77
 *   - default revision: (optional) The name of the entity property used by
78
 *     the entity CRUD API to determine if a newly-created revision should be
79
 *     set as the default revision. Defaults to 'default_revision'.
80
 *     Note that on entity insert the created revision will be always default
81
 *     regardless of the value of this entity property.
82
 * - export: (optional) An array of information used for exporting. For ctools
83
 *   exportables compatibility any export-keys supported by ctools may be added
84
 *   to this array too.
85
 *   - default hook: What hook to invoke to find exportable entities that are
86
 *     currently defined. This hook is automatically called by the CRUD
87
 *     controller during entity_load(). Defaults to 'default_' . $entity_type.
88
 * - admin ui: (optional) An array of optional information used for providing an
89
 *   administrative user interface. To enable the UI at least the path must be
90
 *   given. Apart from that, the 'access callback' (see below) is required for
91
 *   the entity, as well as the 'ENTITY_TYPE_form' for editing, adding and
92
 *   cloning. The form gets the entity and the operation ('edit', 'add' or
93
 *   'clone') passed. See entity_ui_get_form() for more details.
94
 *   Known keys are:
95
 *   - path: A path where the UI should show up as expected by hook_menu().
96
 *   - controller class: (optional) A controller class name for providing the
97
 *     UI. Defaults to EntityDefaultUIController, which implements an admin UI
98
 *     suiting for managing configuration entities. Other provided controllers
99
 *     suiting for content entities are EntityContentUIController or
100
 *     EntityBundleableUIController (which work fine despite the poorly named
101
 *     'admin ui' key).
102
 *     For customizing the UI inherit from the default class and override
103
 *     methods as suiting and specify your class as controller class.
104
 *   - file: (optional) The name of the file in which the entity form resides
105
 *     as it is required by hook_menu().
106
 *   - file path: (optional) The path to the file as required by hook_menu. If
107
 *     not set, it defaults to entity type's module's path, thus the entity
108
 *     types 'module' key is required.
109
 *   - menu wildcard: The wildcard to use in paths of the hook_menu() items.
110
 *     Defaults to %entity_object which is the loader provided by Entity API.
111
 * - rules controller class: (optional) A controller class for providing Rules
112
 *   integration, or FALSE to disable this feature. The given class has to
113
 *   inherit from the class EntityDefaultRulesController, which serves as
114
 *   default in case the entity type is not marked as configuration. For
115
 *   configuration entities it defaults to FALSE.
116
 * - metadata controller class: (optional) A controller class for providing
117
 *   entity property info. By default some info is generated out of the
118
 *   information provided in your hook_schema() implementation, while only read
119
 *   access is granted to that properties by default. Based upon that the
120
 *   Entity tokens module also generates token replacements for your entity
121
 *   type, once activated.
122
 *   Override the controller class to adapt the defaults and to improve and
123
 *   complete the generated metadata. Set it to FALSE to disable this feature.
124
 *   Defaults to the EntityDefaultMetadataController class.
125
 * - extra fields controller class: (optional) A controller class for providing
126
 *   field API extra fields. Defaults to none.
127
 *   The class must implement the EntityExtraFieldsControllerInterface. Display
128
 *   extra fields that are exposed that way are rendered by default by the
129
 *   EntityAPIController. The EntityDefaultExtraFieldsController class may be
130
 *   used to generate extra fields based upon property metadata, which in turn
131
 *   get rendered by default by the EntityAPIController.
132
 * - features controller class: (optional) A controller class for providing
133
 *   Features module integration for exportable entities. The given class has to
134
 *   inherit from the default class being EntityDefaultFeaturesController. Set
135
 *   it to FALSE to disable this feature.
136
 * - i18n controller class: (optional) A controller class for providing
137
 *   i18n module integration for (exportable) entities. The given class has to
138
 *   inherit from the class EntityDefaultI18nStringController. Defaults to
139
 *   FALSE (disabled). See EntityDefaultI18nStringController for more
140
 *   information.
141
 * - views controller class: (optional) A controller class for providing views
142
 *   integration. The given class has to inherit from the class
143
 *   EntityDefaultViewsController, which is set as default in case the providing
144
 *   module has been specified (see 'module') and the module does not provide
145
 *   any views integration. Else it defaults to FALSE, which disables this
146
 *   feature. See EntityDefaultViewsController.
147
 * - access callback: (optional) Specify a callback that returns access
148
 *   permissions for the operations 'create', 'update', 'delete' and 'view'.
149
 *   The callback gets optionally the entity and the user account to check for
150
 *   passed. See entity_access() for more details on the arguments and
151
 *   entity_metadata_no_hook_node_access() for an example.
152
 *   This is optional, but suggested for the Rules integration, and required for
153
 *   the admin ui (see above).
154
 * - form callback: (optional) Specfiy a callback that returns a fully built
155
 *   edit form for your entity type. See entity_form().
156
 *   In case the 'admin ui' is used, no callback needs to be specified.
157
 * - entity cache: (optional) Whether entities should be cached using the cache
158
 *   system. Requires the entitycache module to be installed and enabled and the
159
 *   module key to be specified. As cached entities are only retrieved by id key,
160
 *   the cache would not apply to exportable entities retrieved by name key.
161
 *   If enabled and the entitycache module is active, 'field cache' is obsolete
162
 *   and is automatically disabled. Defaults to FALSE.
163
 *
164
 * @see hook_entity_info()
165
 * @see entity_metadata_hook_entity_info()
166
 */
167
function entity_crud_hook_entity_info() {
168
  $return = array(
169
    'entity_test' => array(
170
      'label' => t('Test Entity'),
171
      'entity class' => 'Entity',
172
      'controller class' => 'EntityAPIController',
173
      'base table' => 'entity_test',
174
      'module' => 'entity_test',
175
      'fieldable' => TRUE,
176
      'entity keys' => array(
177
        'id' => 'pid',
178
        'name' => 'name',
179
        'bundle' => 'type',
180
      ),
181
      'bundles' => array(),
182
    ),
183
  );
184
  foreach (entity_test_get_types() as $name => $info) {
185
    $return['entity_test']['bundles'][$name] = array(
186
      'label' => $info['label'],
187
    );
188
  }
189
  return $return;
190
}
191

    
192
/**
193
 * Provide additional metadata for entities.
194
 *
195
 * This is a placeholder for describing further keys for hook_entity_info(),
196
 * which are introduced the entity API in order to support any entity type; e.g.
197
 * to make entity_save(), entity_create(), entity_view() and others work.
198
 * See entity_crud_hook_entity_info() for the documentation of additional keys
199
 * for hook_entity_info() as introduced by the entity API for providing new
200
 * entity types with the entity CRUD API.
201
 *
202
 * Additional keys are:
203
 * - plural label: (optional) The human-readable, plural name of the entity
204
 *   type. As 'label' it should start capitalized.
205
 * - description: (optional) A human-readable description of the entity type.
206
 * - access callback: (optional) Specify a callback that returns access
207
 *   permissions for the operations 'create', 'update', 'delete' and 'view'.
208
 *   The callback gets optionally the entity and the user account to check for
209
 *   passed. See entity_access() for more details on the arguments and
210
 *   entity_metadata_no_hook_node_access() for an example.
211
 * - creation callback: (optional) A callback that creates a new instance of
212
 *   this entity type. See entity_metadata_create_node() for an example.
213
 * - save callback: (optional) A callback that permanently saves an entity of
214
 *   this type.
215
 * - deletion callback: (optional) A callback that permanently deletes an
216
 *   entity of this type.
217
 * - revision deletion callback: (optional) A callback that deletes a revision
218
 *   of the entity.
219
 * - view callback: (optional) A callback to render a list of entities.
220
 *   See entity_metadata_view_node() as example.
221
 * - form callback: (optional) A callback that returns a fully built edit form
222
 *   for the entity type.
223
 * - token type: (optional) A type name to use for token replacements. Set it
224
 *   to FALSE if there aren't any token replacements for this entity type.
225
 * - configuration: (optional) A boolean value that specifies whether the entity
226
 *   type should be considered as configuration. Modules working with entities
227
 *   may use this value to decide whether they should deal with a certain entity
228
 *   type. Defaults to TRUE to for entity types that are exportable, else to
229
 *   FALSE.
230
 *
231
 * @see hook_entity_info()
232
 * @see entity_crud_hook_entity_info()
233
 * @see entity_access()
234
 * @see entity_create()
235
 * @see entity_save()
236
 * @see entity_delete()
237
 * @see entity_view()
238
 * @see entity_form()
239
 */
240
function entity_metadata_hook_entity_info() {
241
  return array(
242
    'node' => array(
243
      'label' => t('Node'),
244
      'access callback' => 'entity_metadata_no_hook_node_access',
245
      // ...
246
    ),
247
  );
248
}
249

    
250
/**
251
 * Allow modules to define metadata about entity properties.
252
 *
253
 * Modules providing properties for any entities defined in hook_entity_info()
254
 * can implement this hook to provide metadata about this properties.
255
 * For making use of the metadata have a look at the provided wrappers returned
256
 * by entity_metadata_wrapper().
257
 * For providing property information for fields see entity_hook_field_info().
258
 *
259
 * @return
260
 *   An array whose keys are entity type names and whose values are arrays
261
 *   containing the keys:
262
 *   - properties: The array describing all properties for this entity. Entries
263
 *     are keyed by the property name and contain an array of metadata for each
264
 *     property. The name may only contain alphanumeric lowercase characters
265
 *     and underscores. Known keys are:
266
 *     - label: A human readable, translated label for the property.
267
 *     - description: (optional) A human readable, translated description for
268
 *       the property.
269
 *     - type: The data type of the property. To make the property actually
270
 *       useful it is important to map your properties to one of the known data
271
 *       types, which currently are:
272
 *        - text: Any text.
273
 *        - token: A string containing only lowercase letters, numbers, and
274
 *          underscores starting with a letter; e.g. this type is useful for
275
 *          machine readable names.
276
 *        - integer: A usual PHP integer value.
277
 *        - decimal: A PHP float or integer.
278
 *        - date: A full date and time, as timestamp.
279
 *        - duration: A duration as number of seconds.
280
 *        - boolean: A usual PHP boolean value.
281
 *        - uri: An absolute URI or URL.
282
 *        - entities - You may use the type of each entity known by
283
 *          hook_entity_info(), e.g. 'node' or 'user'. Internally entities are
284
 *          represented by their identifieres. In case of single-valued
285
 *          properties getter callbacks may return full entity objects as well,
286
 *          while a value of FALSE is interpreted like a NULL value as "property
287
 *          is not set".
288
 *        - entity: A special type to be used generically for entities where the
289
 *          entity type is not known beforehand. The entity has to be
290
 *          represented using an EntityMetadataWrapper.
291
 *        - struct: This as well as any else not known type may be used for
292
 *          supporting arbitrary data structures. For that additional metadata
293
 *          has to be specified with the 'property info' key. New type names
294
 *          have to be properly prefixed with the module name.
295
 *        - list: A list of values, represented as numerically indexed array.
296
 *          The list<TYPE> notation may be used to specify the type of the
297
 *          contained items, where TYPE may be any valid type expression.
298
 *     - bundle: (optional) If the property is an entity, you may specify the
299
 *       bundle of the referenced entity.
300
 *     - options list: (optional) A callback that returns a list of possible
301
 *       values for the property. The callback has to return an array as
302
 *       used by hook_options_list().
303
 *       Note that it is possible to return a different set of options depending
304
 *       whether they are used in read or in write context. See
305
 *       EntityMetadataWrapper::optionsList() for more details on that.
306
 *     - getter callback: (optional) A callback used to retrieve the value of
307
 *       the property. Defaults to entity_property_verbatim_get().
308
 *       It is important that your data is represented, as documented for your
309
 *       data type, e.g. a date has to be a timestamp. Thus if necessary, the
310
 *       getter callback has to do the necessary conversion. In case of an empty
311
 *       or not set value, the callback has to return NULL.
312
 *     - setter callback: (optional) A callback used to set the value of the
313
 *       property. In many cases entity_property_verbatim_set() can be used.
314
 *     - validation callback: (optional) A callback that returns whether the
315
 *       passed data value is valid for the property. May be used to implement
316
 *       additional validation checks, such as to ensure the value is a valid
317
 *       mail address.
318
 *     - access callback: (optional) An access callback to allow for checking
319
 *       'view' and 'edit' access for the described property. If no callback
320
 *       is specified, a 'setter permission' may be specified instead.
321
 *     - setter permission: (optional) A permission that describes whether
322
 *       a user has permission to set ('edit') this property. This permission
323
 *       is only be taken into account, if no 'access callback' is given.
324
 *     - schema field: (optional) In case the property is directly based upon
325
 *       a field specified in the entity's hook_schema(), the name of the field.
326
 *     - queryable: (optional) Whether a property is queryable with
327
 *       EntityFieldQuery. Defaults to TRUE if a 'schema field' is specified, or
328
 *       if the deprecated 'query callback' is set to
329
 *       'entity_metadata_field_query'. Otherwise it defaults to FALSE.
330
 *     - query callback: (deprecated) A callback for querying for entities
331
 *       having the given property value. See entity_property_query().
332
 *       Generally, properties should be queryable via EntityFieldQuery. If
333
 *       that is the case, just set 'queryable' to TRUE.
334
 *     - required: (optional) Whether this property is required for the creation
335
 *       of a new instance of its entity. See
336
 *       entity_property_values_create_entity().
337
 *     - field: (optional) A boolean indicating whether a property is stemming
338
 *       from a field.
339
 *     - computed: (optional) A boolean indicating whether a property is
340
 *       computed, i.e. the property value is not stored or loaded by the
341
 *       entity's controller but determined on the fly by the getter callback.
342
 *       Defaults to FALSE.
343
 *     - entity views field: (optional) If enabled, the property is
344
 *       automatically exposed as views field available to all views query
345
 *       backends listing this entity-type. As the property value will always be
346
 *       generated from a loaded entity object, this is particularly useful for
347
 *       'computed' properties. Defaults to FALSE.
348
 *     - sanitized: (optional) For textual properties only, whether the text is
349
 *       already sanitized. In this case you might want to also specify a raw
350
 *       getter callback. Defaults to FALSE.
351
 *     - sanitize: (optional) For textual properties, that are not sanitized
352
 *       yet, specify a function for sanitizing the value. Defaults to
353
 *       check_plain().
354
 *     - raw getter callback: (optional) For sanitized textual properties, a
355
 *       separate callback which can be used to retrieve the raw, unprocessed
356
 *       value.
357
 *     - clear: (optional) An array of property names, of which the cache should
358
 *       be cleared too once this property is updated. As a rule of thumb any
359
 *       duplicated properties should be avoided though.
360
 *     - property info: (optional) An array of info for an arbitrary data
361
 *       structure together with any else not defined type, see data type
362
 *       'struct'. Specify metadata in the same way as defined for this hook.
363
 *     - property info alter: (optional) A callback for altering the property
364
 *       info before it is used by the metadata wrappers.
365
 *     - property defaults: (optional) An array of property info defaults for
366
 *       each property derived of the wrapped data item (e.g. an entity).
367
 *       Applied by the metadata wrappers.
368
 *     - auto creation: (optional) Properties of type 'struct' may specify
369
 *       this callback which is used to automatically create the data structure
370
 *       (e.g. an array) if necessary. This is necessary in order to support
371
 *       setting a property of a not yet initialized data structure.
372
 *       See entity_metadata_field_file_callback() for an example.
373
 *     - translatable: (optional) Whether the property is translatable, defaults
374
 *       to FALSE.
375
 *     - entity token: (optional) If Entity tokens module is enabled, the
376
 *       module provides a token for the property if one does not exist yet.
377
 *       Specify FALSE to disable this functionality for the property.
378
 *   - bundles: An array keyed by bundle name containing further metadata
379
 *     related to the bundles only. This array may contain the key 'properties'
380
 *     with an array of info about the bundle specific properties, structured in
381
 *     the same way as the entity properties array.
382
 *
383
 *  @see hook_entity_property_info_alter()
384
 *  @see entity_get_property_info()
385
 *  @see entity_metadata_wrapper()
386
 */
387
function hook_entity_property_info() {
388
  $info = array();
389
  $properties = &$info['node']['properties'];
390

    
391
  $properties['nid'] = array(
392
    'label' => t("Content ID"),
393
    'type' => 'integer',
394
    'description' => t("The unique content ID."),
395
  );
396
  return $info;
397
}
398

    
399
/**
400
 * Allow modules to alter metadata about entity properties.
401
 *
402
 * @see hook_entity_property_info()
403
 */
404
function hook_entity_property_info_alter(&$info) {
405
  $properties = &$info['node']['bundles']['poll']['properties'];
406

    
407
  $properties['poll-votes'] = array(
408
    'label' => t("Poll votes"),
409
    'description' => t("The number of votes that have been cast on a poll node."),
410
    'type' => 'integer',
411
    'getter callback' => 'entity_property_poll_node_get_properties',
412
  );
413
}
414

    
415
/**
416
 * Provide entity property information for fields.
417
 *
418
 * This is a placeholder for describing further keys for hook_field_info(),
419
 * which are introduced by the entity API.
420
 *
421
 * For providing entity property info for fields each field type may specify a
422
 * property type to map to using the key 'property_type'. With that info in
423
 * place useful defaults are generated, which suffice for a lot of field
424
 * types.
425
 * However it is possible to specify further callbacks that may alter the
426
 * generated property info. To do so use the key 'property_callbacks' and set
427
 * it to an array of function names. Apart from that any property info provided
428
 * for a field instance using the key 'property info' is added in too.
429
 *
430
 * @see entity_field_info_alter()
431
 * @see entity_metadata_field_text_property_callback()
432
 */
433
function entity_hook_field_info() {
434
  return array(
435
    'text' => array(
436
      'label' => t('Text'),
437
      'property_type' => 'text',
438
      // ...
439
    ),
440
  );
441
}
442

    
443
/**
444
 * Alter the handlers used by the data selection tables provided by this module.
445
 *
446
 * @param array $field_handlers
447
 *   An array of the field handler classes to use for specific types. The keys
448
 *   are the types, mapped to their respective classes. Contained types are:
449
 *   - All primitive types known by the entity API (see
450
 *     hook_entity_property_info()).
451
 *   - options: Special type for fields having an options list.
452
 *   - field: Special type for Field API fields.
453
 *   - entity: Special type for entity-valued fields.
454
 *   - relationship: Views relationship handler to use for relationships.
455
 *   Values for all specific entity types can be additionally added.
456
 *
457
 * @see entity_views_field_definition()
458
 * @see entity_views_get_field_handlers()
459
 */
460
function hook_entity_views_field_handlers_alter(array &$field_handlers) {
461
  $field_handlers['duration'] = 'example_duration_handler';
462
  $field_handlers['node'] = 'example_node_handler';
463
}
464

    
465
/**
466
 * @} End of "addtogroup hooks".
467
 */