README.txt

   1
   2 Entity API module
   3 -----------------
   4 by Wolfgang Ziegler, nuppla@zites.net
   5
   6 This module extends the entity API of Drupal core in order to provide a unified
   7 way to deal with entities and their properties. Additionally, it provides an
   8 entity CRUD controller, which helps simplifying the creation of new entity types.
   9
  10
  11 This is an API module. You only need to enable it if a module depends on it or
  12 you are interested in using it for development.
  13
  14 This README is for interested developers. If you are not interested in
  15 developing, you may stop reading now.
  16
  17 --------------------------------------------------------------------------------
  18                                 Entity API
  19 --------------------------------------------------------------------------------
  20
  21   * The module provides API functions allowing modules to create, save, delete
  22     or to determine access for entities based on any entity type, for which the
  23     necessary metadata is available. The module comes with integration for all
  24     core entity types, as well as for entities provided via the Entity CRUD API
  25     (see below). However, for any other entity type implemented by a contrib
  26     module, the module integration has to be provided by the contrib module
  27     itself.
  28
  29   * Thus the module provides API functions like entity_save(), entity_create(),
  30     entity_delete(), entity_revision_delete(), entity_view() and entity_access()
  31     among others.
  32     entity_load(), entity_label() and entity_uri() are already provided by
  33     Drupal core.
  34
  35  *  For more information about how to provide this metadata, have a look at the
  36     API documentation, i.e. entity_metadata_hook_entity_info().
  37
  38 --------------------------------------------------------------------------------
  39                Entity CRUD API - Providing new entity types
  40 --------------------------------------------------------------------------------
  41
  42  * This API helps you when defining a new entity type. It provides an entity
  43    controller, which implements full CRUD functionality for your entities.
  44
  45  * To make use of the CRUD functionality you may just use the API functions
  46    entity_create(), entity_delete() and entity_save().
  47
  48    Alternatively you may specify a class to use for your entities, for which the
  49    "Entity" class is provided. In particular, it is useful to extend this class
  50    in order to easily customize the entity type, e.g. saving.
  51
  52  * The controller supports fieldable entities and revisions. There is also a
  53    controller which supports implementing exportable entities.
  54
  55  * The Entity CRUD API helps with providing additional module integration too,
  56    e.g. exportable entities are automatically integrated with the Features
  57    module. These module integrations are implemented in separate controller
  58    classes, which may be overridden and deactivated on their own.
  59
  60  * There is also an optional ui controller class, which assists with providing
  61    an administrative UI for managing entities of a certain type.
  62
  63  * For more details check out the documentation in the drupal.org handbook
  64    http://drupal.org/node/878804 as well as the API documentation, i.e.
  65    entity_crud_hook_entity_info().
  66
  67
  68  Basic steps to add a new entity type:
  69 ---------------------------------------
  70
  71   * You might want to study the code of the "entity_test.module".
  72
  73   * Describe your entities db table as usual in hook_schema().
  74
  75   * Just use the "Entity" directly or extend it with your own class.
  76     To see how to provide a separate class have a look at the "EntityClass" from
  77     the "entity_test.module".
  78
  79   * Implement hook_entity_info() for your entity. At least specifiy the
  80     controller class (EntityAPIController, EntityAPIControllerExportable or your
  81     own), your db table and your entity's keys.
  82     Again just look at "entity_test.module"'s hook_entity_info() for guidance.
  83
  84   * If you want your entity to be fieldable just set 'fieldable' in
  85     hook_entity_info() to TRUE. The field API attachers are then called
  86     automatically in the entity CRUD functions.
  87
  88   * The entity API is able to deal with bundle objects too (e.g. the node type
  89     object). For that just specify another entity type for the bundle objects
  90     and set the 'bundle of' property for it.
  91     Again just look at "entity_test.module"'s hook_entity_info() for guidance.
  92
  93   * Schema fields marked as 'serialized' are automatically unserialized upon
  94     loading as well as serialized on saving. If the 'merge' attribute is also
  95     set to TRUE the unserialized data is automatically "merged" into the entity.
  96
  97   * Further details can be found at http://drupal.org/node/878804.
  98
  99
 100
 101 --------------------------------------------------------------------------------
 102                 Entity Properties & Entity metadata wrappers
 103 --------------------------------------------------------------------------------
 104
 105   * This module introduces a unique place for metadata about entity properties:
 106     hook_entity_property_info(), whereas hook_entity_property_info() may be
 107     placed in your module's {YOUR_MODULE}.info.inc include file. For details
 108     have a look at the API documentation, i.e. hook_entity_property_info() and
 109     at http://drupal.org/node/878876.
 110
 111   * The information about entity properties contains the data type and callbacks
 112     for how to get and set the data of the property. That way the data of an
 113     entity can be easily re-used, e.g. to export it into other data formats like
 114     XML.
 115
 116   * For making use of this information (metadata) the module provides some
 117     wrapper classes which ease getting and setting values. The wrapper supports
 118     chained usage for retrieving wrappers of entity properties, e.g. to get a
 119     node author's mail address one could use:
 120
 121        $wrapper = entity_metadata_wrapper('node', $node);
 122        $wrapper->author->mail->value();
 123
 124     To update the user's mail address one could use
 125
 126        $wrapper->author->mail->set('sepp@example.com');
 127
 128        or
 129
 130        $wrapper->author->mail = 'sepp@example.com';
 131
 132     The wrappers always return the data as described in the property
 133     information, which may be retrieved directly via entity_get_property_info()
 134     or from the wrapper:
 135
 136        $mail_info = $wrapper->author->mail->info();
 137
 138     In order to force getting a textual value sanitized for output one can use,
 139     e.g.
 140
 141        $wrapper->title->value(array('sanitize' => TRUE));
 142
 143     to get the sanitized node title. When a property is already returned
 144     sanitized by default, like the node body, one possibly wants to get the
 145     not-sanitized data as it would appear in a browser for other use-cases.
 146     To do so one can enable the 'decode' option, which ensures for any sanitized
 147     data the tags are stripped and HTML entities are decoded before the property
 148     is returned:
 149
 150        $wrapper->body->value->value(array('decode' => TRUE));
 151
 152     That way one always gets the data as shown to the user. However if you
 153     really want to get the raw, unprocessed value, even for sanitized textual
 154     data, you can do so via:
 155
 156       $wrapper->body->value->raw();