This document summarizes the key differences between how data is represented in Drupal 6 vs Drupal 7, and provides an overview of entities, entity types, bundles, and fields in Drupal 7. It then discusses how to define a custom entity type using the Entity API module, including implementing hook_schema(), hook_entity_info(), and hook_entity_property_info(). Finally, it provides an example of defining a custom "Offer" entity type to store product pricing information from third party APIs.

1. Synapse India Reviews on
Entities in Drupal 7
& the Entity API

2. About Me
 Founder & Chief Solutions Architect
@ Modern Biz Consulting in Oakland
 Strong development background
 Working with Drupal since 2006
 Developer, architect, project manager
 Focus on complex web application development

3. Agenda
 Ways we represent data in D6 vs D7
 Entities, entity types, & bundles
 Fields (formerly CCK)
 The Entity API contrib module
 How (and why) to define a custom entity
 Using EntityFieldQuery
 Defining entity property info
 Leveraging the Entity Metadata Wrapper

4. Poll
 Who here is...
– Brand new to Drupal?
– A site builder?
– A module developer?
– On the business side of things?
 Who here has...
– Created a custom D7 entity?
– Not created a custom D7 entity?

5. D6 Data
 (Custom database table)
 User
 Comment
 File
 Taxonomy vocabulary
 Taxonomy term
 Node
– Page, Blog post, (custom content type)

6. D7 Data
 (Custom database table)
 Entity
– User
– Comment
– File
– Taxonomy vocabulary
– Taxonomy term
– Node
• Page, Blog post, (custom content type)
 (Custom entity type)

7. Entity Types
 Elemental building block for most important data in
Drupal 7
 Represents a concept or noun
 Different types store different data
– Generally in a single DB table
– Eg: Node
• Title, body, created timestamp, etc.
– Eg: User
• Username, created timestamp, last visit timestamp, etc.
 Defined using hook_entity_info()

8. Entity
 Instance of an entity type
 Examples of entities from core:
– The user jdleonard with uid 80902
– The page “Drupal Rocks” with nid 44
 Any entity can be loaded with entity_load()
– Eg: entity_load(‘node’, array(44, 65))
• Returns an array with two nodes with nids 44 and 65
– Core provides some convenience wrappers
• Eg: node_load() and user_load()

9. Entity Bundles
 Subtype of an entity
 Eg: Page and Blog post
– Two content types (bundles) of node entity type
 Not all entity types have more than one bundle
– Eg: User
• No subtypes; concept stands on its own

10. Why We Need Entity Bundles
 Each entity type stores some data in a table
– We call these pieces of data “properties”
– Eg: node
• Title, body, author (uid), created timestamp
• But not all nodes are created equal
– Page may have data beyond that captured by node
– Blog posts get tagged
– We need fields!

11. CCK: Content Construction Kit (D6)
 Contrib module
 Store additional data per content (node) content type
 Eg: Fivestar
– Contrib module leveraging contrib CCK API
– Allows nodes to be rated (think 1-5 stars)
– Eg: let users rate pages or blog posts

12. Fields (D7)
 Core concept
 Store additional data per entity type
 Applies power of CCK to all entity types
– Not just nodes!
 Eg: Fivestar
– Contrib module leveraging core Field API
– Allows entities to be rated
– Eg: let users rate pages, blog posts, users, comments,
custom entities

13. Entities in Core vs Contrib
 Entities are a Drupal 7 core concept
 Core provides the “Entity API”
– Functions and hooks to define and interact with
entities, entity types, and entity bundles
 Everything we've discussed so far is part of Drupal 7
core (no contrib modules necessary)
 Not everything “made it into” D7 core
– Thankfully there's the “Entity API” contrib module
• (confusingly named)

14. Entity API Contrib Module
 Makes dealing with entities easier
 Provides full CRUD functionality
– CReate, Update, and Delete
 Allows definition of metadata about entities
 Optionally makes entity data
– Exportable (for configuration)
– Revisionable (eg: node revisions)
 Optional administrative UI for managing entities
 Object-oriented representation of entity types

15. Core or contrib Entity API?
 Documentation for core's Entity API is separate
from that for the Entity API contrib module
 In practice, you'll probably always use the Entity
API contrib module
– It provides so much awesome functionality!
 Don't get confused
– Always install the Entity API contrib module when
defining an entity
– Make sure to read the contrib module's
documentation

16. Contrib Modules Defining Entities
 Commerce
– Commerce Product, Commerce Payment Transaction
 Organic Groups
– OG Membership, OG Membership Type
 Rules
– Rules Configuration
 Message (think activity stream)
– Message, Message Type, Message Type Category
 … and many more!

17. Example Custom Entity Type
 TextbookMadness.com
– Classified listings for textbooks at schools
– Online price comparison shopping (prices from
Amazon, Textbooks.com, etc.)
 Online prices are
– Fetched from a third-party API and stored by Drupal
– Hereafter known as Offers

18. How Shall we Define an Offer?
 We could use the UI to define an offer node with a
bunch of fields to store pricing information
 But there's a lot of overhead!
– Don't need/want a page (path) per offer
– Don't need/want revisions
– Don't need/want node base table information
• Language (and translation info), Title, Author,
Published status, Created date, Commenting,
Promoting, etc.
– Don't need/want UI for adding, editing, etc.
 We want an entity!

19. Implement hook_schema()
$schema['tbm_offer'] = array( // SIMPLIFIED FOR SLIDE
'fields' => array(
'offer_id' => array('type' => 'serial'),
'isbn' => array('type' => 'int'),
'retailer_id' => array('type' => 'int'),
'price' => array('type' => 'int'),
'last_updated' => array('type' => 'int'),
),
'primary key' => array('offer_id')
);

20. Implement hook_entity_info()
$entities['tbm_offer'] = array(
'label' => t('Offer'),
'plural label' => t('Offers'),
'entity class' => 'Entity',
'controller class' => 'EntityAPIController',
'module' => 'tbm',
'base table' => 'tbm_offer',
'fieldable' => FALSE,
'entity keys' => array(
'id' => 'offer_id',
));

21. Make an Entity Type Exportable
$entities['tbm_offer'] = array(
'label' => t('Offer'),
'plural label' => t('Offers'),
'entity class' => 'Entity',
'controller class' => 'EntityAPIControllerExportable',
'module' => 'tbm',
'base table' => 'tbm_offer',
'fieldable' => FALSE, 'exportable' => TRUE,
'entity keys' => array(
'id' => 'offer_id', 'name' => 'my_machine_name'
));

22. Make an Entity Type Revisionable
$entities['tbm_offer'] = array(
'label' => t('Offer'),
'plural label' => t('Offers'),
'entity class' => 'Entity',
'controller class' => 'EntityAPIController',
'module' => 'tbm',
'base table' => 'tbm_offer', 'revision_table' => 'tbm_o_revision',
'fieldable' => FALSE,
'entity keys' => array(
'id' => 'offer_id', 'revision' => 'revision_id',
));

23. Other hook_entity_info() configuration
$entities['tbm_offer'] = array( …
'entity class' => 'TbmOfferEntity', // Extends Entity class
'controller class' => 'TbmOfferEntityController',
'access callback' => 'tbm_offer_access',
'admin ui' => array(
'path' => 'admin/structure/offers',
'file' => 'tbm.admin.inc',
),
'label callback' => 'entity_class_label',
'uri callback' => 'entity_class_uri',
); // TbmOfferEntity->defaultLabel(), defaultUri()

24. Entity Property Info
 hook_entity_property_info()
– Defines entity metadata
– Provided for core entities
 Enables all kinds of great functionality in modules
that leverage the Entity API contrib module
– Examples coming later

25. Entity Property Info
 Automatically generated from hook_schema()
– Doesn't understand foreign key relationships
(references)
– Doesn't know when an integer is actually a date (eg:
unix timestamps)
 We can fill in the gaps with
hook_entity_property_info_alter()