Check your version

This video covers a topic in Drupal 7 which may or may not be the version you're using. We're keeping this tutorial online as a courtesy to users of Drupal 7, but we consider it archived.

Alternate resources: 

Entities

What are Drupal Entities?

Video loading...

  • 0:00
    [What are Drupal Entities? Working with Entities in Drupal 7]
  • 0:06
    One of the things that's challenging about learning the entity API
  • 0:09
    is all of the terminology you need to understand first.
  • 0:12
    In this lesson, we're going to go through a bunch of different terms
  • 0:16
    —entity type, bundle, field, property, and even entity itself—
  • 0:19
    and try to understand what each of those things mean.
  • 0:23
    We're also going to take a little bit of a look at why the entity API
  • 0:28
    exists, and in order to do that, we have to kind of look at a little
  • 0:31
    of Drupal's history to understand where it came from and why it's important.
  • 0:35
    So let's go ahead and get started understanding all of the
  • 0:39
    base components that we need in order to build things with entity API.
  • 0:45
    What you're seeing on the screen here is a list of terms
  • 0:47
    that we think are important to understand in order to
  • 0:50
    fully grok the entity system in Drupal,
  • 0:52
    though it's a little bit hard to explain these terms,
  • 0:55
    because we have kind of a chicken-and-egg problem.
  • 0:58
    It's hard to understand what an entity type is if you don't
  • 1:01
    already understand what an entity is, and vice-versa.
  • 1:05
    So we're going to go through and explain each of these terms,
  • 1:07
    and if you stick with us, by the end, you should have
  • 1:10
    a better understanding of what each 1 of these means.
  • 1:13
    We'll try to go through them in order, but I'm sure
  • 1:15
    there will be a little hopping around as well.
  • 1:19
    An entity type can be thought of as a way of grouping like entities
  • 1:23
    together under a common umbrella and allowing the system to
  • 1:27
    understand that while all entities may share some common properties,
  • 1:31
    they are not all equal.
  • 1:33
    Nodes, users, and files are all types of entities in Drupal,
  • 1:38
    and all 3 of these have things like a unique ID.
  • 1:42
    But only nodes have titles, and only users have user names and passwords.
  • 1:47
    They share some properties, but in some cases, they differ as well.
  • 1:52
    So the entity API provides us with ways to define new entity types—
  • 1:58
    like node or user, or any that we can think of—
  • 2:03
    or augment the existing ones by using a common set
  • 2:05
    of functions and classes, which we'll be exploring
  • 2:08
    throughout the rest of this series.
  • 2:12
    The next term we need to understand is bundles.
  • 2:15
    Bundles are an implementation of an entity type to which fields can be attached.
  • 2:21
    They're kind of like subtypes.
  • 2:23
    The most common and familiar use is content types,
  • 2:26
    or also known as node types, like article, page, and blog post,
  • 2:30
    or whatever other custom content type you can come up with via the UI.
  • 2:34
    Each of these is a bundle of the node entity type.
  • 2:38
    Note that some entity types only have a single bundle.
  • 2:43
    Users, for example, don't have multiple different types of user.
  • 2:47
    You just have the user entity type and a single user bundle.
  • 2:52
    And some entity types don't have bundles at all.
  • 2:55
    Files, for example, are just an entity type without bundles.
  • 3:00
    The thing to remember here is that bundles are sub-types of an entity,
  • 3:04
    and without bundles, you cannot attach fields to an entity of that type.
  • 3:09
    Bundles, in fact, are what field instances are attached to,
  • 3:13
    not the entity type itself.
  • 3:15
    So bundles are collections of fields applied to an entity.
  • 3:20
    And as you flesh it out a little more, it starts to look something like this.
  • 3:23
    We've got our entity type of node, which has, in this case,
  • 3:28
    3 different bundles—basic page, article, and then our custom bundle type.
  • 3:33
    When you go and view an article in Drupal,
  • 3:38
    or you load an article from the database and you're interacting
  • 3:41
    with it in your module's code, you're interacting with
  • 3:44
    either properties or fields of that article.
  • 3:47
    That's the actual data that's stored for that piece of content or that piece of data.
  • 3:53
    Properties are pieces of information that are the same
  • 3:57
    for all entities of a given entity type, regardless of what bundle.
  • 4:03
    An example of that is something like the title.
  • 4:06
    For nodes, which is an entity type, every node type—
  • 4:11
    basic page, article, and any that we create—all have a title property.
  • 4:16
    This is the same for all nodes, no matter what the bundle.
  • 4:21
    Another example of that is something like the
  • 4:23
    unique ID that you can use in order to identify a node.
  • 4:27
    Every single entity in Drupal has a unique ID, and if they're
  • 4:32
    revisionable entities, they also have a version ID.
  • 4:35
    So these are things that are common across all entities,
  • 4:38
    and in most cases, across all entities of a given type.
  • 4:42
    We call those properties.
  • 4:44
    And then there's fields.
  • 4:46
    Fields are bits of information that are configurable per bundle.
  • 4:50
    We think of fields as sort of data primitives.
  • 4:53
    Anytime I add a field to a content type via the UI,
  • 4:58
    I'm attaching that field to a bundle, and fields don't have to be
  • 5:01
    the same for all entity types or for all bundles.
  • 5:05
    This is the part that's configurable, but remember,
  • 5:07
    if you don't have bundles, you've got nothing to attach fields to.
  • 5:10
    Like files, for example, which are an entity type with no bundles,
  • 5:15
    so I can't attach fields to a file entity.
  • 5:19
    Put it all together and we've got this concept of an entity.
  • 5:23
    An entity is sort of like a discreet piece of data of a
  • 5:26
    specified entity type with a set of common properties
  • 5:29
    and some type specific properties—if you've got
  • 5:34
    bundles implemented for example—and if you do
  • 5:36
    have bundles, it may contain fields as well.
  • 5:38
    Another way to think of it is an entity is 1 single node.
  • 5:42
    It's 1 single blog post.
  • 5:45
    When I fill out the form and create a blog post and hit save,
  • 5:47
    I've just created 1 new entity, and that entity consists of
  • 5:51
    the data that was entered into each of the property fields
  • 5:54
    and each of the UI fields that were attached to that blog post bundle.
  • 5:58
    In addition to that, you could also think of an entity as
  • 6:01
    a common interface that other modules can implement
  • 6:05
    in order to gain access to the data without having to
  • 6:08
    rewrite the code for every possible type of entity.
  • 6:11
    For example, an entity implements a save method.
  • 6:15
    That means that if I have an entity, even if I don't know
  • 6:19
    what type of entity it is, I can call the save method,
  • 6:23
    and that entity will take care of whatever it needs to do
  • 6:26
    in order to save that data to the database.
  • 6:29
    I can call save onto user, save on a file, save on a node—it doesn't matter.
  • 6:36
    That entity is capable of saving it's information, it's properties,
  • 6:40
    and it's fields if it has them, into the database.
  • 6:43
    It's also capable of retrieving them and so forth.
  • 6:46
    This makes it really easy to create code in Drupal
  • 6:49
    that's reusable across lots of different entity types.
  • 6:52
    Fields are a really good example of this scenario.
  • 6:56
    You can create a module that implements a new field,
  • 6:59
    and that field can be attached to any bundle throughout all of Drupal.
  • 7:03
    This creates a really powerful system, and it's kind of why
  • 7:06
    the entity system exists in the first place.
  • 7:08
    I think that it can also help to have a little bit of history about
  • 7:11
    how this whole system came into being.
  • 7:14
    If you've been doing Drupal development for a while, or even just
  • 7:17
    working with Drupal sites, you're probably familiar with
  • 7:20
    a lot of these concepts, though may know them as something different.
  • 7:23
    In Drupal 6, we had this concept of nodes and node types,
  • 7:27
    and we had the ability for someone to create a new node type
  • 7:30
    like we do today, with bundles on entity types.
  • 7:34
    At that time however, nodes was the only system that
  • 7:37
    allowed that kind of abstraction.
  • 7:39
    And then there was CCK, or the content construction kit,
  • 7:42
    which allowed you to add fields to all these different node types,
  • 7:45
    and this was viewed as a really powerful solution.
  • 7:48
    It was a really powerful solution, and you could do all kinds of things
  • 7:51
    by combining the ability to create your own new node types
  • 7:56
    and add any field that you downloaded and installed to those node types.
  • 8:00
    So it ended up in a scenario where all of a sudden,
  • 8:03
    everyone was trying to turn everything into a node so that
  • 8:06
    they'd get the power of the full flexibility of a tool like the content construction kit.
  • 8:10
    All these modules were trying to do things, like make comments
  • 8:14
    into nodes and make users into nodes, store them in the database
  • 8:18
    as nodes so that we get the flexibility of CCK.
  • 8:22
    And it kind of worked, but at the same time, you had all
  • 8:26
    of the additional baggage of the node system, even if you didn't need it.
  • 8:29
    Users, for example, don't really need to have commenting applied to them.
  • 8:32
    But if you're turning your users into nodes, all of sudden
  • 8:35
    you have the ability to leave comments on your users.
  • 8:38
    So for Drupal 7, that concept was abstracted even further.
  • 8:41
    Rather than have just nodes which you can apply fields to,
  • 8:45
    Drupal now allows you to have entity types, and fields can be
  • 8:48
    attached to bundles on any entity type, and a user can be
  • 8:51
    a type of entity, and a node can be a type of entity,
  • 8:54
    and comments and so forth.
  • 8:56
    So now we have the power of the field system and we can apply it
  • 8:59
    to all of these other content types or data points, like users in Drupal,
  • 9:05
    without having to try to turn those things into nodes
  • 9:07
    or force them to be something that they're really not.
  • 9:10
    What I'd like to do next is take a look at some of these things in a Drupal website—
  • 9:14
    navigate though and look at a node and a user, and talk about
  • 9:17
    the properties and fields that make those things up.
  • 9:19
    So let's go ahead and do that.
  • 9:21
    What I've got here is a simple Drupal 7 site with
  • 9:23
    a couple of additional modules installed, and I've gone through
  • 9:26
    and generated a bunch of content using the Devel module
  • 9:29
    so we have something to look at.
  • 9:31
    First thing I want to do is take a look at this node here.
  • 9:36
    I view the node with the Devel module enabled; I get this tab
  • 9:38
    up at the top here which allows me to basically view a more
  • 9:43
    detailed output of the node itself.
  • 9:45
    Looking at this node object, which is of type standard class,
  • 9:48
    I see a whole set of properties and fields.
  • 9:53
    This, what we're looking at right now, is an entity.
  • 9:56
    It's an entity of the type node, it's an entity with
  • 10:00
    the bundle of page since this is just a simple page node,
  • 10:05
    and it has a set of properties, like for example, the user ID
  • 10:10
    of the author that created this node, and some fields,
  • 10:13
    like for example, the body of the node.
  • 10:15
    I can close that, and let's take a look at another node, like this 1.
  • 10:23
    Same thing. I've got an object that is an entity.
  • 10:28
    It's an entity of the type node.
  • 10:31
    You can even see that right here.
  • 10:33
    It's a node with a bundle article, it has some properties like the UID,
  • 10:41
    which we see again and we saw on the previous node,
  • 10:44
    which was of the bundle type page, and some fields.
  • 10:48
    Still has a body field, but it also has a couple of additional fields
  • 10:51
    that weren't present on the other entity type.
  • 10:55
    I can also look at my user account.
  • 10:58
    Same thing.
  • 11:00
    This object is an entity and the entity type is user,
  • 11:06
    and the bundle in this case is actually just user.
  • 11:09
    So we said there's not configurable bundle types for users.
  • 11:13
    There's just 1 bundle to which you can attach fields.
  • 11:16
    But it's got properties, just like our node entity type—UID, name, etc.—
  • 11:22
    and we could also optionally attach some fields
  • 11:25
    to this entity type if we wanted to.
  • 11:27
    In addition to the entity types that come with Core,
  • 11:30
    there's also some that are provided by additional modules.
  • 11:33
    I've got the BEAN module installed on my site right now.
  • 11:38
    The BEAN in this case is a acronym that stands for block entities aren't nodes.
  • 11:45
    Essentially what it is, is it's a module that allows me to create
  • 11:48
    new blocks using the entity system.
  • 11:53
    And what this has given me is the ability to go to the structure tab,
  • 11:58
    and I've now got this block types option up here.
  • 12:01
    Block types are a bundle.
  • 12:05
    They're attached to the BEAN entity type.
  • 12:10
    When I create a new block type, I'm creating a new bundle.
  • 12:13
    I'll go ahead and do that.
  • 12:18
    Once my block type has been created, I've now got
  • 12:21
    a new bundle named block bundle, to which I could attach fields,
  • 12:25
    and then I can create a new block.
  • 12:28
    I go to content.
  • 12:30
    Up here at the top, I've got a new tab for blocks,
  • 12:33
    and I can add a new block entity.
  • 12:35
    When I create a new block
  • 12:42
    and give it a title, I'm filling in a couple of properties
  • 12:46
    for this block entity and saving it, and now I've created
  • 12:50
    a new entity in my system.
  • 12:52
    This entity's treated as a block though, so I could place it
  • 12:55
    places using the block configuration screen.
  • 12:58
    There's lots of other examples of entities from Drupal contrib as well.
  • 13:02
    The file entity module is neat.
  • 13:04
    It takes the file entities that already exist in Drupal Core
  • 13:09
    and extends them in order to make them fieldable.
  • 13:13
    Essentially what it does is it adds the ability to have
  • 13:16
    configurable bundles to the file entity type,
  • 13:19
    which means you can then attach fields to it.
  • 13:21
    There's also the Recurly module, and this one's interesting in that
  • 13:24
    it doesn't provide a new entity type, but it works with
  • 13:28
    the entity API and the entire entity system
  • 13:30
    in order to do some pretty neat things.
  • 13:33
    What it does is it allows you to create a Recurly subscription
  • 13:37
    and attach it to any entity type in Drupal.
  • 13:40
    And it can do this because all entities in Drupal
  • 13:44
    implement this common interface of save, update, load, delete.
  • 13:49
    There's 1 set of functions that you can call that will work on all of them.
  • 13:54
    So a module like the Recurly module can write its code once
  • 13:57
    and allow some configuration where you choose,
  • 14:00
    "I'd like to have this applied to the user entity type,"
  • 14:03
    but the code will just work, no matter what the entity type is.
  • 14:08
    And finally, modules like Drupal Commerce are making
  • 14:11
    heavy use of the entity system in Drupal in order to
  • 14:14
    make their modules even more flexible.
  • 14:16
    In Drupal Commerce, almost everything is an entity type,
  • 14:20
    including things like the shopping cart.
  • 14:22
    An order that's made when somebody checks out products
  • 14:26
    in the system are all entities, which means all of those things
  • 14:29
    are fieldable, so you're adding all kinds of additional flexibility,
  • 14:33
    but you're also limiting the amount of code that
  • 14:35
    people need to write in order to work with your system.
  • 14:37
    I could write code like the Recurly module that implements
  • 14:41
    the common save functionality for all entities,
  • 14:45
    and you could make use of that code on any entity type,
  • 14:49
    including those provided by a module like Commerce
  • 14:51
    or like we're going to do throughout this series when
  • 14:54
    we create out own we create out own entity type, that code would work with those as well.
  • 14:58
    [Drupalize.Me]

Working with Entities in Drupal 7

Loading ...

What Are Drupal Entities?

Loading...
15 minutes 2 seconds // Drupal 7 // HDCC //

In this lesson Joe will explain what an entity is and provide a little bit of history about how they came into being. We’ll also learn about some of the differences between custom entities and nodes (which happen to be a type of entity) and when, and why you might want to choose to write your own custom entities instead of using the node system or a more traditional datastore.

Additional resources:
There are no resources for this video. If you believe there should be, please contact us.

Share