Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Entities in Drupal 7 & the Entity API


Published on

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

Published in: Technology

Entities in Drupal 7 & the Entity API

  1. 1. Entities in Drupal 7 & the Entity API#sfdugMarch 11, 2013JD Leonard (@drupal_jd)
  2. 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. 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. 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. 5. D6 Data (Custom database table) User Comment File Taxonomy vocabulary Taxonomy term Node – Page, Blog post, (custom content type)
  6. 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. 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. 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. 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. 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. 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. 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. 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 weve discussed so far is part of Drupal 7 core (no contrib modules necessary) Not everything “made it into” core – Thankfully theres the “Entity API” contrib module • (confusingly named)
  14. 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. 15. A Note on Documentation Documentation for cores Entity API is separate from that for the Entity API contrib module In practice, youll probably always use the Entity API contrib module – It provides so much awesome functionality! Dont get confused – Always install the Entity API contrib module when defining an entity – Make sure to read the modules documentation
  16. 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. 17. Example Custom Entity Type – Classified listings for textbooks at schools – Online price comparison shopping (prices from Amazon,, etc.) Online prices are – Fetched from a third-party API and stored by Drupal – Hereafter known as Offers
  18. 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 theres a lot of overhead! – Dont need/want a page (path) per offer – Dont need/want revisions – Dont need/want node base table information • Language (and translation info), Title, Author, Published status, Created date, Commenting, Promoting, etc. We want an entity!
  19. 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. 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. 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. 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. 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 =>, ), label callback => entity_class_label, uri callback => entity_class_uri,); // TbmOfferEntity->defaultLabel(), defaultUri()
  24. 24. Entity Property Info hook_entity_property_info() – Defines entity metadata – Provided for core entities Automatically generated from hook_schema() – Doesnt understand foreign key relationships (references) – Doesnt know when an integer is actually a date (eg: unix timestamps) Fill in the gaps with hook_entity_property_info_alter()
  25. 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. 26. hook_entity_property_info_alter()// Define a new property to reference an offers retailer (eg:$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. 27. Entity API Integrations Views – Eg: in a view of offers, we can add a retailer relationship and include details about each offers retailer Rules Search API Features I18n Token system - Eg: [tbm_offer:retailer:name]
  28. 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. 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. 30. EntityFieldQuery Example$result = $query->execute(); // Keyed by entity typeif (isset($result[node])) { $nids = array_keys($result[node]); $pages = node_load_multiple($nids); $same_as_pages = entity_load(node, $nids);}
  31. 31. Entity Metadata Wrapper Examples// Get node authors email address (given $nid)// BEFORE$node = node_load($nid);$author = user_load($node->uid);$email = check_plain($author->mail); // AFTER $wrapper = entity_metadata_wrapper(node, $nid);$email = $wrapper->author->mail->value();
  32. 32. Entity Metadata Wrapper Examples// Set node authors email address$wrapper->author->mail =;$wrapper->save();// Iterate over a list of nodes taxonomy termsforeach ($wrapper->field_taxonomy_terms->getIterator() as $term_wrapper) { $label = $term_wrapper->label->value();}
  33. 33. More Modules! Entity Construction Kit (ECK) – CCK for entities – Create entity types in a UI Entity Cache – Integrates entities with Drupals Cache API Entity Reference – Like node reference field, but for any type of entity Automatic Entity Label – Generic successor to Automatic Node Titles
  34. 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 Follow me: @drupal_jd