Creating custom entities

by Gisle Hannemyr

In Drupal, entities are bundles of related data. All the predefined data objects in Drupal 7 (e.g. nodes, taxonomy terms, comments and users) are entities. It is possible for site designers to create new custom entities and include those in a site design. This chapter is a tutorial about creating and working with custom entities in Drupal 7.

Introduction
Final word

Introduction

æøå

Daniel Sipos: part 1, part 2 (used below).
Drupal.org: How to create a node in code
Drupal.org: Entity property information

Question about Sipos' tutorial at SE: http://drupal.stackexchange.com/questions/146854/entity-create-always-returns-false

There is a small bug when saving entity. Need to use wrapper to get a save method:

$ew = entity_metadata_wrapper('booking', $entity);
$ew->save();

In Drupal 7, there are already the Field API that makes it possible for the site designer to extend existing entities such as nodes and users with new, typed data fields. This is frequently used to enhance a Drupal site with custom types. And prior to Drupal 7, one of the core design paradigms used by site developers was to expand the node content type by adding fields to it.

You can still do that in Drupal 7. But in addition to expanding the node content type, Drupal 7 provides entities (a node is now just one type of entity), and the tools to create custom entities from scratch. The result is similar to the expanded node. I.e.: you manufacture a data object consisting of a bundle of related data fields. However, there are some differences:

Existing enities, such as nodes comes with a lot of baggage, such as authorship, timestamps, comment settings, menu location and revisions. This is great if you need these things, but if you don't: This is just overhead for very little benefit.
Custom entities let you bundle just the data fields you need, while at the same time having access to Drupal features such as the ability to add fields and built-in Views integration.

Whether to create a new entity or expand an existing depends on the use case. If the use case is similar enough to an existing enitity, expand it. If not, create a custom one.

Setting up

Before starting, please download and enable the contributed module Entity API. This module will be used to do some of the heavy lifting below. If you haven't done so already, do:

$ drush dl entity -y
$ drush en entity -y

In this tutorial, you'll be shown how to create and manipulate a custom entity type called “project”. This entity type will be used to represent just two pieces of information about projects: title and deadline.

The custom entity is created using a custom module that shall have the machine name “demo”. Start by creating the file demo.info and make sure you set “entity” (machine name of the Entity API project) as a dependency:

name = Demo
description = "A custom project entity."
core = 7.x
dependencies[] = entity

Demo:Task
Project:Task
demo_schema:task_schema
name:task
description:-
deadline:duedate

Tutorial outline

Define schema for the custom entity.
Register it with Drupal.
Override the default EntityAPIController to build up a display for the entity.
Set up pages to display the individual entity instances.
Build an interface to manipulate the entity.
Make the entity class fieldable in order to add fields through the core fields user interface.
Expose the entity to Views so that you can create entity listings.

Define schema for the custom entity

Register it with Drupal

Entity class and controller

Overriding the entity classes

Individual entity pages

Admin user interface

Fields

Exposing the entity type to Views

Final word

This is the end of the introduction to Drupal entities.

This chapter first explained how to write a schema defintion for a custom Drupal entity type, and how to register this as a entity type with Drupal. It then introduced the the contributed Entity API module to access to a set of object oriented tools for working with the entities, including a CRUD (create, read, update, delete) interface.

The four main aspects of working with entities described in this chapter are:

How to show (read) the instances of an entity.
How to create an admin interface for creating, updating and deleting entity instances.
How to make an entity class fieldable through the UI.
How to expose entities to Views to do queries and listings.

While some ground has been covered, there's more you can do to perfect and customize your entity types: view modes, revisions, etc.

DEBUGGING

function entity_get_info

Last update: 2014-11-26 [gh].