Understanding entity terminology

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.