Entity Lister

Entity Lister provides a class (EntityLister) for querying and theming entities. Entities are queried using EntityFieldQuery and themed according to your specified view mode.

This module is for developer use. It provides no GUI, unless you count the pager and cache viewer.

Why?

If you work with EntityFieldQuery often, you are no doubt familiar with this common routine: (1) query for the entity IDs with EntityFieldQuery; (2) load the entities with entity_load(); (3) pass each entity to a view function (e.g. entity_view(), node_view(), etc.) and specify a view mode; (4) call drupal_render().

The EntityLister class encapsulates this common routine so you don't have to repeat yourself as much in your code. By using this class, you also get some other (optional) things for free, such as caching, a configurable pager, Node View Permissions integration, etc.

Entity Lister is well suited for rapidly developing filtered tabular lists of data, such as in admin interfaces. For an example of a tabular list with filters, see the Entity Lister Example module.

Dependencies

Entity API (entity)

Features

• Conforms strictly to Drupal coding standards.
• Configure the number of items, bundles, view mode, multiple levels of sorting, pager behavior and position, caching, table headers (for tabular displays), etc. For a complete list of config options, see the documentation in the class.
• EntityLister supports querying all entity types. You can include only one entity type per list, but can combine multiple bundles.
• EntityLister provides caching with cache_set and cache_get. Lists are cached per list config and per role(s). A user assigned to roles foo and bar will not share a cache entry with a user assigned to foo. The cache is invalidated per entity type. That is, if a node of any bundle is saved or deleted, all node list cache entries are deleted. If a user is saved or deleted, all user list cache entries are deleted. And so on.
• Lists can be configured to include a standard pager or AJAX pager. The pager can be positioned above or below the container, or both. The AJAX pager calls scrollTop() and animate() to reset the scroll to the top of the container.
• EntityLister includes a Node View Permissions integration.
• EntityLister has built-in access control for nodes, users and comments. To control access to more entity types (or remove the access control for the aforementioned types), extend the class and override accessCheck().

Extending the Class

If you extend EntityLister, please see the addAllowedClass and removeAllowedClass methods at the end of the class.

For an example of a module that extends the EntityLister class, see Entity List Field.

Developer Documentation

Please see the EntityLister class for documentation of functions and variables.

The Entity Lister Example module demonstrates how to create a tabular list.

When and how to supply a custom AJAX pager for your list.

Example Use

This is a simple example. See the doc block above the class constructor for the full list of config options.

$config['type'] = 'user';
$config['numitems'] = '6';

// Sort by username in reverse alphabetical order.
$config['sort'] = array(
  array(
    'method' => 'propertyOrderBy',
    'args' => array(
      'property' => 'name',
      'direction' => 'DESC',
    ),
  ),
);

$config['view_mode'] = 'staff_bio';

// The $delta must be unique among all lists appearing
// on this page, and must be an integer.
$delta = 0;

$obj = new EntityLister($config, $delta);
$list = $obj->getList();

// Place the list in a renderable element in your page or block function.
$array['entity-lister-' . $delta] = $obj->element($list);

For more examples, see the demo page that comes with the module. When you install the module, the demo page is at www.your-site.com/entity_lister/demo.