May 21, 2012

Anatomy of a Drupal Entity

On a recent project in which we had to create a number of different entities, I started a list of functions / classes / etc. that are required when creating an entity in Drupal 7. Rather than remembering to move it around to each project, I think it makes more sense to post it here instead

This is by no means a definitive, complete document on how the various pieces of functionality work to produce an entity, so please leave any comments / questions that you have and I'll update the content accordingly.

Also, this is not intended (yet?) as a tutorial on how to make a module from scratch or how to write each of the functions described, but rather a shopping list of all the functions you should include in your entity.

Module dependencies

Entity API
This is a big one, it offers up bunch of services and functions that the Drupal core entity API does not (such as CRUD operations).

my_entity.module

If you're creating an entity module (in this case, my_entity), you'll need at a minimum, the following functions in your my_entity.module file:

Functions

  • hook_help
    • While not specific to entity modules, this one's good to have in general and I don't see it often enough so I'm listing it here
  • hook_entity_info
    • Defines your my_entity and my_entity_type entities
  • hook_entity_info_alter
    • Provides any default bundle types
  • hook_permission
    • Defines permissions for entity / entity type administration, and view / edit / delete permissions for individual content types (think of the Content permissions section for a good idea of what to put here
  • my_entity_access / my_entity_type
    • Referenced in hook_entity_info, this checks if a user has access to perform the given operation on the entity or entity_type
  • hook_theme
    • Themes the "add content type" page of entity types to add, and the entity itself
  • hook_menu_local_tasks_alter
    • Adds the "Add" action link on the 'admin/content/my_entity' page of existing content
  • my_entity_get_types
    • Gets an array of all types (bundles) for the entity
  • my_entity_type_load
    • Gets a my_entity_type object
  • my_entity_load
    • Loads an entity, should call my_entity_load_multiple
  • my_entity_load_multiple
    • Loads multiple entities into an array, calls entity_load
  • my_entity_create
    • Creates an entity, wraps the entity controller's create() function
  • my_entity_uri
    • Provides a URI for an entity (like 'node/nid' for nodes)
  • my_entity_page_title
    • Gives the page title for a specific entity
  • my_entity_page_view
    • Renders the entity as a page

Classes

class MyEntity extends Entity
  This is the class that will represent your entity objects and is named in hook\_entity\_info().
  
  The constructor of this class should augment the passed values with any required defaults.
  
  In addition, you should override the following methods for this class:

	defaultLabel() Default label for this entity
    defaultUri() Default URI for the entity

class EntityType extends Entity
  Makes $type and $label public variables

my_entity.admin.inc

Functions

  • my_entity_form_wrapper
  • Wrapper around drupal_get_form for the add / edit entity form
  • Sets the breadcrumb of the form page
  • my_entity_delete_form_wrapper
  • Wrapper around the 'delete entity' form
  • my_entity_edit_form
  • Form for adding / editing a new entity. Make sure to attach the UI-driven fields to the to form in this step
  • my_entity_edit_form_validate
  • Validates the add / edit form submission
  • my_entity_edit_form_submit
  • Adds any entity-specific info (such as creation time, etc.), then saves the entity and redirects to the content list
  • my_entity_form_submit_delete
  • Redirects user to the delete form
  • my_entity_delete_form
  • Delete form for an entity
  • my_entity_delete_form_submit
  • Deletes an entity and redirects the user to the content list
  • my_entity_add_page
  • Takes the user to the add-entity page, which lists the available bundles
  • Wraps the UI Controller's addPage method
  • theme_my_entity_add_list
  • Themes the list of available entity types for entity creation
  • my_entity_set_breadcrumb
  • Sets the breadcrumb for administrative entity pages

Classes

class EntityUIController extends EntityDefaultUIController
  UI Controller for the entities. Recommended functions to override in this module:

  hook_menu
    Actually called hook_menu() and not a Drupal hook, this function adds menu items for the entity list, add, add/type, view, edit, and delete pages
  
  addPage
    Markup for the add overview page which displays the list of content types

my_entity_type.admin.inc

Functions

  • my_entity_type_form
  • Entity type (bundle) adding / editing form
  • my_entity_type_form_submit
  • Saves the entity, and redirects it to the admin/structury/entity_type page
  • my_entity_type_form_submit_delete
  • Processes the delete button on the entity_type_form
    Redirects to the delete page for the entity type

Classes

class EntityTypeUIController extends EntityDefaultUIController
  UI Controller for the entity types. Recommended functions to override in this module:
  
  hook_menu
    Actually called hook_menu(), this function adds menu items for the entity list, add, add/type, view, edit, and delete pages