by Jeff Eaton on October 17, 2011 // Short URL

Module Monday: Entity Construction Kit

How to Create Custom Entities and Define Entity Types in Drupal 7

The introduction of "entities" in Drupal 7 heralded a new era of flexibility and abstract nouns. The entity system allows existing Drupal data like comments, taxonomy terms, and user accounts to share much of the flexibility that nodes have long enjoyed, without forcing every type of data to adopt Node module's idiosyncrasies. Entities can use custom fields, but don't necessarily require robust content features like version tracking, translation support, and so on.

While programmers can define custom entities using their own modules, however, there's no way for site builders to create them from scratch. No way, that is, save the Entity Construction Kit.

Screenshot of administration screen

The Entity Construction Kit gives site builders a central screen in the Structure administration area of the site where they can define new entity types. Each entity type can have several built-in properties like creation dates, a simple on/off status flag, so on. Each entity type can also have multiple bundles -- when testing, I created a "Muppet" entity type with "Monster" and "Normal" bundles. Like any other entity type, you can attach custom fields to them to store whatever data you'd like: the "simple properties" are managed automatically by the Entity Construction Kit.

Once you've defined them, administrators and site builders with entity management permissions can create and edit individual entities. The resulting entities can be displayed to normal users, included in Views, and pointed to by other fields using the Entity Reference module.

For developers interested in taking the next step, it provides custom hooks for managing the entity types' display in code, and offers template code to override any entity type's controller class. By doing that, a developer can easily piggyback custom behaviors onto their newly defined entities without having to build them from scratch in code.

Screenshot of an entity being created

The Entity Reference Kit is still in early development: the Alpha 3 version of the module was just released, and a handful of known bugs can make using it bumpy for certain use cases. It's a great module to keep an eye on, though, and if you're tired of shoe-horning your data into nodes and taxonomy terms "just because they're there," it's a great way to explore the world of defining your own custom entity types!

Jeff Eaton

Senior Digital Strategist

Want Jeff Eaton to speak at your event? Contact us with the details and we’ll be in touch soon.



I understand that a node is

I understand that a node is an entity.
But for the afforementioned example why create a new entity and not a new content type?
When should we create just new content types (of nodes), and when is better to create a new entity?

Is a different type of entity needed when a relation between entities must exist?
like node with taxonomy or node with comments?



I don't believe..

I don't believe that the need to connect things is some sort of rule of thumb to decide when to create an entity type vs creating a content type, but the fact that you might want to connect something to some other objects (like users, or nodes) does tell me that this is a different and contained piece of data, and entities allow you to create that distinction.

If you wanted a foreign key relationship between one of your data objects, and others, it would be easier to create that with entities than with node. If you were to use node you will have to add a new column to the node db table, and this will be there for all node types, not just for the node type that is using that column. This is not a terrible amount of bloat, but why force nodes to be what they are not, when we have entities available.



when you want a separate db table

For my site building purposes, the ability to put content into a separate table is the big reason. For security and data sharding purposes I have separate subdomains run by entirely separate code and databases. But I want to share a few things like classified ads with a subset of those sites.

One way is to push the node. But the other way is to share a table. When all content is a node, sharing the node table defeats the purpose of splitting the sites up. But when one particular type of content is contained in it's own table, AND if it's not a high write volume item, it can make a lot more sense to share the table than to push the node.

A second reason is to do crazy things like the with the Relation module (

In my mind this boils down to three reasons: needing a separate table, creating entirely different data structures, and interacting programmatically with it.



Any real life examples ....

What is this kit used for? Any real life examples of how to use this module? And what is difference between using a nod type and an entity?



one example

One specific example in which I use entities in a useful way was to manage some images that I used for the web and an iPhone app. With image styles, you can crop and scale images for display, but that only happens when someone visits the page the image is being displayed at. I needed multiple formats of one image when it was being uploaded, and a little bit of metadata (photographer credit, rating, etc). So I created an entity type with ECK and added the necessary fields. Then in a custom module using the hooks that the entity api makes available for all entity types, I created and saved the different formats of the image. I am sure this same thing would have been possible to do with nodes, but nodes offer more functionality and properties than I needed for this entity, and by using an entity type instead of a content type, IMHO it was easier to isolate this functionality for the cases that I needed it.



I am not sure I fully

I am not sure I fully understand the differences between ECK and CCK. Can you further elaborate?

By the sound of it, it appears that by creating entities, as opposed to content types, this adds another layer of possible properties, is that right?

For example:

Group>name,number of members,type,location

Group>type_commercial>name,number of members, product,income
Group>type_government>name,number of members,agency
Group>type_non-profit>name,number of members,mission

Is that kind of the idea? I am trying to understand more of the benefit of entities, versus content types.

Additionally, what effect will this have on creating relationships/views between different entity types versus content types?


Taihao Zhang


With CCK (and core Node, obviously), you can create content types, configure different fields for each type, and create content under a particular type.

With ECK, you can create ____ types, configure different fields for each type, and create ____ for a particular type.

There are other nuances, such as not having the concept of types and just have a uniform entity (without being tied down by the complexity of handling nodes), but you get the idea.


Diwant Vaidya

Entity vs Content

Entity has
Entity Bundles which have

Content is a type of Entity. So,

Content has
Content Bundles (Article, Page) which have
Fields (body, article image)




It's a spectrum, but here's some clues...

I think about Entities vs Node (Content Types) this way.

Nodes are for Content that behaves a lot like standard "documents", where you want lots of types of fields, long text etc., and may want "documenty" features like revisions, translations, comments etc.

One might consider using a new entity type for things that are less documenty and more "behaviory" like the "Bookable Unit" entities representing a night in a hotel room in the drupal "Rooms" distribution. They have to be "bookable" and have lots of characteristics and rules on them, but are not very "documenty." Another good example are the Product SKUs in Drupal Commerce. They have to be "buyable" and trigger lots of calculations. Sure they have fields and whatnot, but they are less like a document and more like a inventory system workflow unit. A User entity has a very different role than a document, because its most important characteristic is not what's in the fields, but that it's a data bookeeping bridge enabling the website to know a little about those interacting wit it.

Does your content stand alone, is it viewable alone by website visitors at an url and needs to be edited there? Does it make sense to think of it as a document? Do you have any reason it shouldn't be a node? It MIGHT be a node!

Does your content have a specialized purpose, like categorizing, commenting, linking other content, or is it simply a data placeholder for some type of state in a specialized system? Do you not need some of the helping hand the node system gives you? Do you want to do things differently? Your content MIGHT be a taxonomy vocab/term entity, or a Comment entity or a User entity or another weird type for your special purpose or special data. Most entites that aren't nodes have special sauce that makes them different or more or less than individual web documents.

OR you might decide your data might not be CONTENT at all, and it might be feature CONFIGURATION, in which case you COULD use entites for it, but you probably should just store it in code or a custom table somewhere.

I think this whole new set of capabilities are going to give rise to some abuses and the pendulum will swing too far in some directions, but we will work it out in the end, just in time for the introduction of another ueber meta concept! Maybe the entity construction kit is not gonna be the best influence on all of this, because it's going to encourage a lot of folks to use the interface to create a whole lot of "documenty" entities that could be node types. It doesn't help you write the special sauce code that makes your entity more or less than a document. It certainly will help folks get off the ground even for those projects which go on to write that code, so more power to it!

To think there was a time when the most vexing problem was deciding between a taxonomy vocab and a cck field to store that one select list on your node :)


Andrew Lundin

This is an excellent

This is an excellent explanation. Best I've seen. The ECK project documentation needs this.



Why ECK?

I see entities as the possibility of creating anything, including a better node. Just imagine, picking and choosing which powerful pieces of functionality you want to use from the set that node offers depending on your needs. For example you might have an entity that needs the aliasing capabilities that node offers, but that don't need the sticky behavior because they are never used on a list, and that if for some reason you do want the behavior later on you can simply add the behavior to your entity, and that's it.

Before entities, everyone was trying to make everything into nodes, because nodes offered some pretty good standards and openness in the system. Well, entities have both of this things, we just need to start working on some of those powerful features that node offers, and more.

Also, dealing with entities in your own modules is repetitive, and not exactly fun (copy and paste… customize). Well, ECK makes that part easy. So, I see ECK as an on-ramp to get faster to developing cool, and general functionality that can then be used by any entity.

As a proof of concept I created a fairly complex site with mostly entities ( I use nodes for the blog and for pages that won't be changing much), everything else is build with Entities (ECK), and the relation module. Everything is working well, but now I need a "sort of" publishing workflow. It is something more complex than what node offers, so using nodes would not have solved my problem, but this will be an interesting experiment to see if I can write a flexible publishing workflow that can then be attached to any entity.


Alejandro Garza

Compatibility with contrib and core modules?

This is more a question (but could be key to whether one chooses to build a custom entity over a content type)...

If one builds an entity with ECK or whatever, would that entity be compatible/work with contrib and core modules?

For example, would you able to have, say, Fivestar votes on the new entity? How about having search, or views of them? Would they even show up in the core content administration page?



- Fivestar is a field, and

- Fivestar is a field, and fields can go on any entity.
- I think core search is nodes only, but I'm guessing that SearchAPI is entity based.
- Anything can be exposed to Views. It may require some glue code to get Views of ECK entities, but that might be handled by ECK module.
- The core content admin page lists only nodes, but you can create views to manage your new entity.



The glue code for ECK

The glue code for ECK entities to work with views is already provided by the entity API module which ECK uses. Also ECK gives you a page to manage your entities, but you could certainly use a view to do it if you want something different




dalin is right, Search API works for all entities (or at least for the ones using entity API module). ECK uses the entity API module and that gives a lot of contrib integration for free, including views, and rules. The entity API comes with a module that makes tokens available also.

Entities are new to D7 so there are lots of module that only work with nodes, but a lot of the bigger modules in Drupal do have support for nodes and other entities.


Armondo Magilli...


This sounds Darn GREAT. The one thing I hate is that I did not know that it existed before now. This will kills about 4 content types on a website I am currently working on.

For that matter I wish I had understood entities better before reading the comment thread. I am always killing comments and trying to figure out a way to reduce standard node stuff by using autonodetitle and other tricks.



I tried a simple test of ECK

I tried a simple test of ECK to create a person type, which I did. I was then able to create a simple View, but I couldn't modify it much. What ordinarily in nodes would be a "title" with a link, was an ID number with a link. I tried getting the person's name as the link (last, first), but couldn't figure this out.

I also entered a few entities, but after running cron, didn't see it show up in search results.

Perhaps I am missing something...

The URL ended up being person/person/1 vs. something that I thought would be better, i.e., person/George-Washington. I didn't see any option to modify that.

Not doing too hot if I may say so myself...


Joel Finkel

How to add data programatically

First of all, let me just say that the ECK will save me hours, if not days, of work. Creating entities in code is cumbersome and highly error-prone. This going to be a heavily used module.

This said, once I have my entities defined (which is now easy, thanks to ECK), I need to be able to create content programatically (bypassing a GUI). I do not get how to do that. Any help would be greatly appreciated.