Drupal 7 Module Development

Chapter 6
The return value from the callback is an array with two keys: path, which is the
Drupal path where the entity lives, and options, which defines other parameters to
the url() and l() functions for things such as page anchors or GET query values. It
is safe to omit the options key if it's not needed. Although our implementation is
trivial, alternative implementations could, for instance, put all entities of a given
type on a single page and have an anchor for each one.
When creating a link to an entity, always use entity_uri($type,
$entity) to generate the parameters to pass to either the url() or
l() functions.
Note that these array keys assume we are using the default controller for our entity.
A "controller" is an object that handles the loading of the entity object for us. The
controller is defined as a PHP class, and can be written to load our entity from
anywhere, not just the local database. In our case, we are defining a custom controller
called ArtworkController that will extend from DrupalDefaultEntityController,
so it uses the same keys. DrupalDefaultEntityController is a generic controller
for entities that are stored in the local database and behave, more or less, like nodes. If
we were pulling data from an entirely different system we would implement our own
controller from scratch that implements the DrupalEntityControllerInterface
interface, and we might then need different keys defined in the entity hook.
Two other important keys are the cacheable and fieldable flags:
• static cache indicates that the controller should keep a copy of an entity in
memory after it's been requested so that if we try to load it a second time in
the same page request we can just use that cached copy.
• fieldable indicates to the Field API that we can attach fields to this entity,
in the same fashion as nodes. That's very important, as it is one of the main
reasons to define a new entity type in the first place.
The second part of the hook is a little more involved. It is primarily there to support
the Field API, which will be covered in the next chapter. Since we have multiple
bundles, we need to tell the Field API what bundles we have and at what paths to
put the extra field management interfaces for our entity. To do that, we define, for
each of our bundles, a label that is shown to the user and the menu information that
the Field API will need to add itself into the menu. The keys here, under admin, are
fairly self explanatory. path defines the path that should be used in hook_menu()
for the Field UI's pages, while real path is the exact path that should be used when
generating links within the admin interface.
[ 159 ]