Simple data modeling example: vehicle listings

Let's say that we want to create a site for a car dealership, and the first part of the site that we want to develop is the vehicle listings. These vehicle listings will eventually give the users all of the information that they need to make an informed decision on what to buy.

We start with the most basic information a buyer would want about individual vehicles: make, model, and year. As we go, we realize we also want to add some information relevant only to trucks: whether their bed is covered or open.

Clearly the type of bed needs a place in our plan. Since type of bed applies only to trucks, we end up with two kinds of vehicle listing. Our content structure (also referred to as a schema or a data model) needs to allow for information that is relevant to trucks but not to cars, as well as information that is relevant to both trucks and cars.

Apply Drupal terminology to the example

The Drupal entity system is the cornerstone of Drupal's toolset for building structured content. Much of the related terminology is difficult to internalize. The most important terms are entity type, bundle, property, field, and entity.
Let's start with entity types:

Entity Type and Properties

An entity type is a grouping of objects. In Drupal core we already have some entity types defined for us: user, node, taxonomy term, etc. In our example we also have a general grouping of objects: vehicles. A grouping of objects is defined by the characteristics of those objects. For example, in Drupal core all user objects have a name and an email address. In our example, we also have certain characteristics that are relevant to our entity type (vehicles). Using Drupal terminology, we call these "properties". The properties that we defined as relevant for all our vehicle objects are: make, model, and year.

Bundles and Fields

Fields on a given entity type make up a bundle. Fields allow us to validate and store properties in a very granular way (for example, our field for collecting year of manufacture can require data to be entered with 4 digits so cars from 1914 don't end up in the list of cars from 2014).

Bundles let us create subtypes within an entity type with just the fields needed by each subtype.

In Drupal core, we already have 2 bundles defined for us in the node entity type: the article content type and the basic page content type. Both are suited to delivering content as nodes. Superficially they are not very different, but note the significantly different properties. For one, the out-of-the-box article content type has a field for an image, and basic page does not.

In our car dealership example, we mentioned having two kinds, or types, of vehicles: cars and trucks. The reason our data model distinguishes between cars and trucks is that some information is only relevant to trucks. How can we accommodate this distinction? If we merely add bed_type as a property to the entity type, all vehicles will have that property even when it is not relevant (a bed is not relevant to a car, but cars would have a field in which to enter that information). Instead, if we create a car bundle and a truck bundle in the vehicle entity type, the bed_type property can be part of the truck bundle and be left off the car bundle.

Entities

Finally, after we have created our entity type with its properties, and the bundles with their fields, we can start describing the actual things our site was built to describe: the cars and trucks. On our site, each individual vehicle description is an entity. In more general Drupal terms: each specific object of an entity type is referred to as an entity. So in our example, both a 2016 Toyota Corolla and an 1895 Benz truck (with a covered bed) can be examples of entities of our vehicle entity type.

Now we can actually implement our example by using the Entity Construction Kit (ECK) module. There are two paths for using ECK. If you like to do everything from code, follow the developers path. Otherwise, use the ECK UI to develop your data models by following the site builders path. Beyond implementing our example, the developers path also contains information on how to extend ECK and its functionality.

Comments

Anonymous’s picture

After reading this I still had difficulty understanding what a bundle is and how all this fits together.
This page is very helpful - particularly if you're a programmer: https://drupal.org/node/1261744

jpl-2’s picture

Unfortunately, that "explanation of terminology" didn't really explain much to me. I was left puzzled about the relationship between properties and fields and also entity types and bundles. Only after reading other sources my confusion was cleared (notably Ronald Ashri's Moving beyond nodes and also the second article in his series). The required clarification came from focusing my attention on the division of labor among developers of reusable modules and site builders:

In a typical scenario a new entity type would be defined by a module developer to describe module-specific data. It corresponds to an own database table, which holds the primary key and the basic, non-customizable, primitive properties of the entity type shared without exception by all entities (e.g if "node" is an entity type, then "node title" is a property). Now, the developer may declare their entity type as "fieldable", in which case site builders will be able to customize it by attaching their own fields defined by themselves through the admin UI. Alternatively, other developers may plug in their field definitions through the Field API. The data for these custom, optional, removable fields will be stored separately in joined database tables (which is another aspect that makes them different from properties defined by the entity type). But the developer may also wish to "bundle" along field definitions of his own with the entity type, not just raw properties. Thus, "bundles" can be explained as named subcategories within the entity type to which fields can be attached by site builders or developers.

In more complex scenarios, one can also have entities that themselves describe individual entity types (similar to instances of metaclasses = metamodel objects in UML terminology). This is useful to provide a second level of customization in which site builders may define their own new bundles for an entity type (e.g. think about defining your own "content type" through the admin UI using CCK). For an illustration of this concept, see the last diagram in Entities and Bundles in Drupal 7).

fmizzell’s picture

I am glad that things clicked for you, but it would be a lot more helpful if you went into the details of which parts of the document do not bring clarity to the concepts, and why.

tgshannon’s picture

I found this documentation to be a great explanation. However, my first thought was that I'm not sure I would understand it without having gone through the debugging of entity wrappers before I found this.

My problem was making a custom field available to an entity wrapper. After finally getting it to work using the field_example.module and some guidance from here I wanted to see if there was something I could give back on this issue. That's when I found this article, and like I said it made perfect sense.

Like a lot of documentation, things only make sense because you already have a certain knowledge base, and if some of that is lacking the documentation can be useless. This document is not, because I think it helps me understand why I had to do what I did, and not just think "oh well, I got this to work by doing this!"

I need to check out ECK to see if there is a better way to model a problem. Thanks!

GiorgosK’s picture

I am new to eck and my question is (not answered above)
I understand properties are like author, date created, etc in node terminology
but common to all entity types but why are they not editable ?
are they ? how can they made to be editable ?

------
GiorgosK
Web Development

fmizzell’s picture

The right way to makes a property editable with ECK, is to use its behavior system. If you set a title property on your ECK entity type, you will notice that the property is editable. That is because the title behavior provides a widget to allow that property to be editable. The author, and created are things that get managed directly by the system and so they are not editable, but you could easily copy any of those behaviors and add a widget to make those properties editable (There might be a conflict there though as the system tries to manage the property and you try to manage it manually). In short, ECK's behavior system has the capability to do this for you in 2.x. In 3.x you can actually assign behaviors and widgets independently of one another, and ECK comes with a simple text widget so that virtually any property can be made editable. Widgets in 3.x are managed through the Field UI interface. I hope this helps.

mchar’s picture

Thanks for the documentation, it is really helpful and encourages the use of custom entities in Drupal, however I have a simple question. As it turns from what is written an entity is the same as a bundle, correct ?
Since a set of fields is a bundle, and the truck is a bundle - it has the bed_type field - which is also a subtype of the vehicle entity type and the 1895 Benz truck is an entity of the vehicle entity type, the name bundle is just a different name for the entity or we can say that the 1895 Benz truck is an instance-object-entity-bundle of the entity type vehicle that is makes it a bundle because it has different fields from the 2016 Toyota Corolla which is another instance-object-object-entity of the vehicle entity type.
Am I wrong? if yes please share your thoughts.

anupa.drupal’s picture

A Bundle is a subtype of an Entity type. For example, a blog is a subtype of content type/ node entity type.
An Entity is an instance/object of Entity type. Example, a blog titled 'Welcome to Drupal 8' would be an instance of a blog/ node entity type, and 'Whats new in Drupal8' would be another instance, and so on.
In our example, Car(Bundle) is a subtype of Vehicle Entity type. But Toyota Corolla (Entity) is an instance of both Vehicle Entity type and of Car(Bundle).
When you say 'Entities are bundles', its like saying, Toyota Corolla is a Car, which is absolutely right, but I think it would be more apt to understand it as 'Toyota Corolla is an instance/ object of the vehicle type Car'.
You can get more info on this here https://www.drupal.org/node/1261744

Yonat’s picture

Very helpful documentation. Your frequent use of examples validates or invalidates what I think is of a certain point raised.

And also, I agree with @tgshannon about his general observation:
"Like a lot of documentation, things only make sense because you already have a certain knowledge base, and if some of that is lacking the documentation can be useless. This document is not, because I think it helps me understand why I had to do what I did, and not just think "oh well, I got this to work by doing this!" "