Presentation I gave to the San Francisco Drupal Users Group (SFDUG) on March 11, 2013.
With every major version of Drupal comes a wealth of improvements. Some of these are easily visible to site administrators and end users, while others are more "under the hood". The concept of entities, introduced in Drupal 7, is definitely an "under the hood" improvement: one that offers Drupal developers a new set of tools to build web applications more quickly and help ensure scalability and performance.
In this interactive developer-oriented talk, we'll:
- Compare data storage options in Drupal 6 to those in Drupal 7 (there are more in Drupal 7!)
- Explore what entities are and how they relate to nodes, content types, users, taxonomies, fields, bundles, and more
- Walk through defining a custom entity
- Discuss how to leverage the Entity API contrib module to take full advantage of entities including integration with Views, Rules, and more
- Look at examples of entities in action
We'll start at a high-level (suitable for site builders) and finish looking at some code examples.
There's a YouTube video of the presentation embedded as the last slide. It's also accessible at https://www.youtube.com/watch?v=1hFrbxQTVvQ
Beginners Guide to TikTok for Search - Rachel Pearson - We are Tilt __ Bright...
Entities in Drupal 7 & the Entity API
1. Entities in Drupal 7
& the Entity API
#sfdug
March 11, 2013
JD Leonard (@drupal_jd)
ModernBizConsulting.com
2. About Me
Computer science background
Working with Drupal since 2006
Developer, architect, project manager
Freelance through my business:
Modern Biz Consulting
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” 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. A Note on Documentation
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 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.
We want an entity!
24. Entity Property Info
hook_entity_property_info()
– Defines entity metadata
– Provided for core entities
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)
Fill in the gaps with
hook_entity_property_info_alter()
25. hook_entity_property_info_alter()
$offer = &$info['tbm_offer']['properties'];
$offer['url']['type'] = 'uri'; // was a varchar in hook_schema
$offer['url']['label'] = 'URL';
$offer['last_updated']['type'] = 'date'; // integer in hook_schema
$offer['last_updated']['label'] = t('Last updated');
// Other types: text, token (machine name), integer, decimal,
duration, boolean, entity, struct, list<TYPE>
26. hook_entity_property_info_alter()
// Define a new property to reference an offer's retailer (eg:
Amazon.com)
$offer['retailer'] = array(
'label' => t('Retailer'),
'type' => 'tbm_retailer', // The tbm_retailer entity type
'description' => t('The retailer making the offer.'),
'required' => TRUE,
'schema field' => 'retailer_id', // as defined in hook_schema
);
27. Entity API Integrations
Views
– Eg: in a view of offers, we can add a retailer
relationship and include details about each offer's
retailer
Rules
Search API
Features
I18n
Token system - Eg: [tbm_offer:retailer:name]
28. EntityFieldQuery
Tool for querying entities
Can query entity properties and field data
Can query field data across entity types
– Eg: “return all pages and users tagged with
taxonomy term 456”
Returns entity IDs
– Usually you’ll then load with entity_load()
29. EntityFieldQuery Example
$query = new EntityFieldQuery();
$query
->entityCondition('entity_type', 'node')
->entityCondition('bundle', 'page')
->propertyCondition('status', 1)
->fieldCondition('field_awesome_factor', 'value', 3.2, '<')
->fieldOrderBy('field_awesome_factor', 'value', 'DESC')
->range(0, 10);
// Top 10 Published page nodes with an awesome factor < 3.2
30. EntityFieldQuery Example
$result = $query->execute(); // Keyed by entity type
if (isset($result['node'])) {
$nids = array_keys($result['node']);
$pages = node_load_multiple($nids);
$same_as_pages = entity_load('node', $nids);
}
32. Entity Metadata Wrapper Examples
// Set node author's email address
$wrapper->author->mail = 'me@example.com';
$wrapper->save();
// Iterate over a list of node's taxonomy terms
foreach ($wrapper->field_taxonomy_terms->getIterator() as
$term_wrapper) {
$label = $term_wrapper->label->value();
}
33. More Modules!
Entity Construction Kit (ECK)
– CCK for entities
– Create entity types in a UI
Entity Cache
– Integrates entities with Drupal's Cache API
Entity Reference
– Like node reference field, but for any type of entity
Automatic Entity Label
– Generic successor to Automatic Node Titles
34. More information
Entity API documentation
– Lots of information in many subpages
EntityFieldQuery documentation
Entity API contrib module page
Deck is on Slideshare
Email me: jd at ModernBizConsulting.com
Follow me: @drupal_jd