Last updated October 18, 2011. Created by fago on January 10, 2011.
Edited by gagarine. Log in to edit this page.
For a general introduction of metadata about entity properties and its purpose, check this blog post.
In short hook_entity_property_info() is for collecting information about all that available entity properties - regardless whether they are fields or not - in order to make them accessible the same way. For simply making use of that information, the entity API provides the so called "Entity metadata wrappers".
Provide information about entity properties
To provide information about properties (including fields) you'll have to implement hook_entity_property_info(). You may put your hook implementations in the include yourmodule.info.inc, however any callbacks have to reside in files that are always included.
Let's consider the node module integration as example:
<?php
/**
* Implements hook_entity_property_info() on top of node module.
* @see entity_metadata_entity_property_info()
*/
function entity_metadata_node_entity_property_info() {
$info = array();
// Add meta-data about the basic node properties.
$properties = &$info['node']['properties'];
$properties['nid'] = array(
'label' => t("Node ID"),
'type' => 'integer',
'description' => t("The unique ID of the node."),
'schema field' => 'nid',
);
$properties['language'] = array(
'label' => t("Language"),
'description' => t("The language the node is written in."),
'setter callback' => 'entity_metadata_verbatim_set',
'options list' => 'entity_metadata_language_list',
'schema field' => 'nid',
'setter permission' => 'administer nodes',
);
$properties['author'] = array(
'label' => t("Author"),
'type' => 'user',
'description' => t("The author of the node."),
'getter callback' => 'entity_metadata_node_get_properties',
'setter callback' => 'entity_metadata_node_set_properties',
'setter permission' => 'administer nodes',
'required' => TRUE,
'schema field' => 'uid',
);
// ...
return $info;
}
?>As you can see you have to specify a label and optionally a description for each property. Properties may be read only, like the 'edit-url' or may support writing like 'author'. Check the docs of hook_entity_property_info() or this page for a complete list of supported keys and data types.
Handling entity references
In case of properties containing entity references like "uid" one should not expose an "uid" integer property, but a property that exposes the entity relationship. Just expose a property "user" or "author" of type "user", as seen in the example above.
Then, do not expose both the id and the entity reference, only expose the entity relationship. The id is accessible via the referenced entity (without having to load it) anyway.
Internally, an entity property is represented by its identifier, thus the setter callback has to accept the entity id as value. The getter callback may return the id or the full entity object though.
Comments
property_callbacks
It's really unclear what should happen in a function set as property_callback. There isn't an example or documentation available.
You should return the value
You should return the value of your property. The value has to be formatted has documented for your data type (see the data types page), e.g. if you implement a 'date' property you have to return it as a timestamp.
The best documentation i
The best documentation i found is this blog post (3 part) http://www.istos.it/blog/drupal/drupal-entities-part-1-moving-beyond-nodes
Callbacks are only used by wrappers
Note that the "getter callback" and "setter callback" functions are only used by Entity metadata wrappers.
Not by entity_load or Views and such.
You can not use these to convert a different timestamp format in a database to a timestamp for use with the 'date' type unless you specifically create a wrapper for each of your entity instances.
I tried to get my (int)yyyymmdd values from the database to show up in Views as dates and mistakenly thought I could use the "getter callback" for the transformation.
Example of when callback is and is not used:
<?php$entity = entity_load('myentity', array(1));
print $entity->day; // this gives 20110721 (from the database)
$item = entity_metadata_wrapper('myentity', $entity);
print $item->day->value(); // this gives 1311206400 (from the "getter callback")
?>
In Views my day shows up as "08/21/1970 - 19:18" ...
so if someone can point me in the right direction to get my "days" as timestamps, I'm all ears.
Properties may be read only,
I do not see 'edit-url' anywhere. Am I missing something?