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