Entities 101Understanding Data Structures in Drupal

Ron NorthcuttSolutions Architect

Who am I?Ron NorthcuttSolutions Architect, Acquia

● using Drupal since 4.7 ● freelance developer● small dev shop● sr. developer & tech lead● solutions architect

Find me online:

https://www.drupal.org/u/rlnorthcutt

https://www.linkedin.com/in/rlnorthcutt

https://twitter.com/rlnorthcutt

https://plus.google.com/+RonNorthcutt

But, before we begin...

What is an entity?

Where does the entity come from?

History● D3 and earlier - Nodes only

● D4 - Flexinode

● D5 - Content Construction Kit

● D6 - Node types + CCK (fields) = “node all the things in contrib”

○ content_profile, nodecomment, taxonomy_node

● D7 - Start entity work with Entity API (limited in core, contrib fleshed it out)○ "However, also users, taxonomy terms and comments are entities and entities can immediately

plug-in to the Field API and have fields added to them."

● D8 - Finish it up and truly entity all the things!

Two kinds of entitiesCurve ball! There are actually two main kinds of entities now: content and configuration. The main difference between configuration entities and Drupal 7-style content entities is that configuration entities use the configuration system for storage, rather than the database.

We have been and will continue to focus on content entities.

Content entities ● Fieldable● DB Schema (uses hook_schema)● Revisionable● Nodes, users, terms, blocks

Config entities ● Integrates with CMI API for exportability● No fields● Schema file● Image styles, views, custom menu

“Entities, in Drupal, are objects that are used for persistent storage of content and configuration information.”

-- Entity API Documentation

“First of all, naming. In this patch I went with ‘entity’ for a ‘loadable thingy, that can optionally be fieldable’. I.e. nodes, users, taxonomy terms, taxonomy vocabularies, files.

I am not sure if this is the best name, but it was the best I could come up with. Please don't yet start bikeshedding on the name, I am willing to change it but first I'd like some serious reviews.”

-- Frando, in the issue where he adds the first patch for entitieshttps://www.drupal.org/node/460320

May 2009

So….. what is an entity?

An entity is… a thingy.● A single “unit” of structured data

○ Could be a blog post or article○ Could be a single user account○ Could be a single taxonomy term and its metadata○ Could be some other structured data that you create

○ Content is not an entity, a node is an entity type… but the article on space monkey jumpsuits IS an entity.

An entity is… loadable.● Common set of methods for managing structured data

○ Create - $entity = entity_create($entity_type, $data_array)○ Read - $entity = entity_load($entity_type, $id)○ Update - $entity->save()○ Delete - $entity->delete()

○ Common properties:■ $entity->id()■ $entity->isNew()

○ Views and services integration

DB

UI API

An entity is … optionally fieldable● Entity type - nodes, users, terms

○ Entities of the same type share properties

○ Only a node has a title○ Only a user has a password○ Only a term has a parent

● Properties○ Information that is the same across all

the bundles of a specific type○ Ex. all content types have a nid, vid,

status, uid, title○ Those are all Node properties

● Bundle (like a subtype)○ Article, Page, Blog post, Event, etc.○ Collection of fields applied to a an entity

type○ Some entities don’t have bundles, but

then you can’t attach fields

● Field API○ Configurable slots of information○ Can be shared○ Stored outside the entity base table

● Entity validation API

Entity Type - Node

Article Blog post Event Page

Node properties (nid, uid, status, etc.)

Body Body Body Body

Tags Tags Tags

Hero image Hero image Date

Related event

Field API

Entity Validation

Bundles

(5 Fields)

A loadable thingy that can optionally

be fieldable

Great! So, how do I use

entities?

Core entities● Node/Content

○ For content!○ Things that need to be displayed or read○ Data that needs to be revisionable○ Generic content data

● Users○ User account information and management○ User profile collection

● Custom Blocks○ Reusable page components○ Structured and styled content like slideshow,

hero banner with button, etc.○ Use within Panels

● Vocabulary and Terms○ Organizing other entities○ Sorting/filtering other entities○ Managing metadata around your taxonomy

● Comments○ Commenting, surely○ Attaching structured data to another entity in a

timeline

● Files○ Store and manage files○ Organizational and metadata around files

Example - Project management system● Node/Content

○ Customer profile○ Project○ Ticket

● Users○ User accounts and login

● Custom Blocks or Views○ Reusable page components○ Structured and styled content like slideshow,

hero banner with button, etc.○ Use within Panels

● Vocabulary and Terms○ Categories for projects○ Organization for tickets○ Categorize customers

● Comments○ Notes about customer profile○ Add comments and time tracking to Tickets

● Files○ Store and manage project files○ Organizational and metadata around files

Custom entities● When you need a very specific type

of entity ○ Specific properties○ Specific methods in addition to the normal

ones○ Specific data storage or workflow needs

● When you don’t want to use an existing entity

○ You may want to “clone” another entity to avoid side effects

○ Example : making a “time report” entity that is based on comment, but you don’t want other modules to mess with it

● When you need total control over the structure

○ Example : properties of a non-fieldable entity can not be altered from the UI

● When it extends your data model○ Its much easier to create the entities

you need when you have a more complex or intricate data model

○ Example : Drupal commerce, Paragraphs

● When it makes sense

External entities“This module allow you to connect to datasets from external databases and use it in your Drupal 8 website. While content lives external, Drupal sees those remote entities as internal. This makes it possible to alter the field displays, add references, comments, pathaliases, share buttons, webshop products and more.”

https://www.drupal.org/project/external_entities

Let’s see what they “look” like*

*Thanks to the ERD module: https://www.drupal.org/project/erd

So….. what is an entity?

all together now...

A loadable thingythat can optionally

be fieldable

Thank you!