Nodequeue: Creating Arbitrarily Ordered Lists of Content

This is the documentation page for the Nodequeue module.

The original source for most of this information is the README.txt file.

You may also wish to view the Comparison of node ordering modules

The Nodequeue module allows users to put nodes in an arbitrarily ordered list. Examples of this might be to create a block listing teasers for 5 forum posts that the admin thinks are important. Another use might be to create a list of nodes, and then display a randomly selected node from the group on the frontpage of the site. This concept is extended upon with Smartqueues (see below).

Queues and Subqueues

Note: Despite the fact that this module is called "Nodequeue", there is no such thing as a nodequeue, and you'll never encounter one when working with the module. A nodequeue is like the Loch Ness monster or Big Foot or a pleasant experience with airport security: It doesn't exist.

If you see something in the module's interface or code that refers to a Nodequeue, please file a bug report.

When working with the Nodequeue module, you will encounter queues and subqueues. A subqueue is an individual list of nodes. Every subqueue belongs to a parent queue, which contains settings that affect all of the subqueues that belong to that queue. Yes, a queue can have many subqueues. When a queue has many subqueues, the subqueues are neatly listed on the Queue administration page.

Some settings that Queues can have include:

• Restriction of which types of nodes can be added to the queue's subqueues
• How long subqueues within the queue can be (how many nodes each can contain)
• Which user roles can manipulate the subqueues

The most basic way to use Nodequeue is with simple queues. A simple queue contains only one subqueue. Why have the distinction between queues and subqueues? See below on Smartqueues.

Smartqueues

Nodequeue allows companion modules to define new types of queues -- called smartqueues -- which have special behavior. For example, the Taxonomy Queue module (included with the Nodequeue package) provides a single subqueue for each term of a vocabulary.

The Smartqueue per-user module allows each user on the site to have his or her own personal subqueue.
The Smartqueue per-organic group module provides a subqueue for each organic group.

Developers can read more about the Smartqueue API below.

Embedding Content from a queue

Once a queue is set up, a new tab will appear on eligible nodes for eligible users. This tab will allow the user--regardless of node edit permissions--to add or remove that node from the queue. Queue admins can view the nodes in the queue, and can modify the items therein. Items may also appear in a node's links area to add/remove them from the queue.

When a node is added to the subqueue, it is added to the back. If a subqueue is full when a node is added, the front is removed.

Nodequeue has support for nodes with i18n Internationalizations.
You must install the Translation Helpers module.

Automatic Creation of Views

When configuring Nodequeue, you can opt to "Automatically create one view per queue" (you may wish to leave this off if you plan to create the views yourself).
The views created automatically cannot be deleted from the Views interface because they are implemented "in code". However, if you disable the auto-creation, then clear caches, these views will be removed.

It is highly recommended that you use the Views module to display your subqueues. However, if you choose not to, you can alternatively use a small PHP snippet.

To use nodequeue from views (D7), add a 'relationship' to the queue, and typically set to 'require this relationship'. Optionally add 'nodequeue: Position' to match the preset queue order.

You can embed a node that is in a particular position in a queue (without writing code) anywhere there is an input format by using the Insert View module to embed a View that takes the subqueue id and position as arguments, using the

"[view:name of view=name of display=arg1,arg2,arg3] invokes the view using the specified display and passes arg1, arg2 and arg3 to the view.]" format.

Programmatic Ways of Displaying Content from a Queue

Nodequeue provides several functions which simplify getting a loaded node object from the front, back or a random position in a queue. For more selecting or displaying content in a more specific or complicated way, the Views module is probably your best bet.

Please note that there are some differences between the functions available in the 5.x-2.x and 6.x.-2.x versions of Nodequeue.

To Create a Block to Display Node Titles of a Queue

You'll need the Queue ID, which is easily extracted from the URL on the queue administration page.

Create a new block, and insert the following PHP snippet into the block:

print nodequeue_node_titles($subqueue_id);

If you want this queue to be printed in the reverse order, you can tell it to print backward:

print nodequeue_node_titles($subqueue_id, '', TRUE);

The '' in the line above is an optional title field. Feel free to put something here, but it's not terribly necessary in a block.

To Display a list of teasers from a queue:

Like above, you'll need the Queue ID.

Create a new page (or a new dashboard!) or any node type you like, really, and set the input filter to PHP. Insert the following PHP snippet:

With Nodequeue 6.x-2.x:

print nodequeue_view_nodes($subqueue_id);

With Nodequeue 5.x-2.x

print nodequeue_nodes($subqueue_id);

There are a few more options available here; changing the order of the nodes, whether or not to use teasers or full nodes, whether or not to display the links, and how much of the queue to display. See below.

To render the first or last node from a queue

With Nodequeue 6.x-2.x:

 $node = nodequeue_load_front($subqueue_id);
 $rendered_node = node_view($node);
  

With Nodequeue 5.x-2.x:
$rendered_node = nodequeue_fetch_front($subqueue_id);

Or

With Nodequeue 6.x-2.x:

 $node = nodequeue_load_back($subqueue_id);
 $rendered_node = node_view($node);
  

With Nodequeue 5.x-2.x:
$rendered_node = nodequeue_fetch_back($subqueue_id);

To render a random node from a queue

With Nodequeue 6.x-2.x:

$node = nodequeue_load_random_node($subqueue_id);
$rendered_node = node_view($node);

With Nodequeue 5.x-2.x:

$rendered_node = nodequeue_fetch_random($subqueue_id);

Remember that the front of the queue will have the least recently added nodes (unless it was rearranged manually), and the back will have the most recently added.

Available Functions and Descriptions

NOTE: this section needs to be updated for Nodequeue 6.x-2.x

nodequeue_node_titles($qid, $title = '', $backward = TRUE, $from = 0, $count = 0)

Display a title list of the queue. If backward is TRUE (the default) the list will be from back (newest) to front (oldest).

nodequeue_nodes($qid, $backward = TRUE, $teasers = TRUE, $links = TRUE, $from = 0, $count = 0)

Display the nodes of a queue. If backward is TRUE (the default) the list will be from back (newest) to front (oldest). If $count is set to non-zero, it will use a range. For example, passing $from = 2 and $count = 2 will show the 3rd and 4th elements of the queue. ($count starts at 0, not 1.) If $teasers is TRUE, the node teaser will be shown; otherwise the full node will be shown.

nodequeue_fetch_front($qid, $teasers = TRUE, $links = TRUE)

Fetch the node at the front of the queue.

nodequeue_fetch_back($qid, $teasers = TRUE, $links = TRUE)

Fetch the node at the back of the queue.

nodequeue_fetch_random($qid, $teasers = TRUE, $links = TRUE)

Fetch a random node from the queue.

Nodequeue API

Beginning with 6.x-2.5 the following API calls will be available in Nodequeue:

hook_nodequeue_info()

Collect info about all of the possible nodequeue types from owning modules.

hook_nodequeue_add($sqid, $nid)

A node is being added to the given node queue.

hook_nodequeue_remove($sqid, $nid)

A node is being removed from the given node queue.

hook_nodequeue_swap($sqid, $nid)

A node is being swapped in a queue ie it's delta is changing.

Actions Module Integration

The node queue module provides two actions, so that workflow can add and remove items from queues.

Smartqueue API

Nodequeue provides a robust API that allows other modules to define smartqueues, which are associated with external data. For example, the included taxonomy smartqueue creates subqueues for a given queue for every term in the chosen vocabulary. Nodes are then only eligible for subqueues whose term matches the nodes terms. This makes it very easy to have queues for each category without cluttering the management page.

You might be wondering about the performance implications of a site a taxonomy smartqueue with thousands of taxonomy terms and thousands of nodes. Currently, no public benchmarks have been available, and smartqueue_taxonomy (currently smartqueue.module) includes a warning about possible performance implications, but merlinofchaos writes:

For a single vocabulary, I don't think the size matters much.

If you select multiple vocabularies, it has to process all of the possible combinations of terms, so thousands of terms could start to have a performance impact on your site. I would recommend not doing this.

I didn't do any benchmarks so I don't have specific numbers; I threw in the warning because, at the time I wrote it, it seemed like a good idea to let people know that doing something like combining two taxonomies each with a thousand terms (which leads to a million unique combinations) could really create lots of subqueue data.

Example Smartqueue API Implementation

Smartqueue API hook definitions begin with nodequeue_api -- so reading the doxygen documentation for these functions will be helpful. You can also learn about the smartqueue API by reading existing smartqueue modules. A hypothetical code example is listed below, and you can also look at the Smartqueue_og and Smartqueue_users modules.
This hypothetical smartqueue_author (or authorqueue) module demonstrates a basic implementation of the Smartqueue API. If you wish to have a Nodequeue based on node authorship, please see the Smartqueue_users module.

<?php
// $Id: authorqueue.module,v 1.4 2008/10/06 15:47:34 ezrag Exp $
//This Module exists as a simple example of Nodequeue's Smartqueue API.
//For a Smarqueues based on node authorship, see http://drupal.org/project/smartqueue_user.

/**
 * Implementation of hook_nodequeue_info()
 */
function authorqueue_nodequeue_info() {
  return array('smartqueue_author' => array(
    'title' => t('Author queue'),
    'description' => t('Each user in the selected roles will be given a queue; nodequeue administrators can select nodes by that author for placement into that queue, allowing the site to easily hilight content by particular authors.'),
    ));
}

/**
 * Implementation of hook_nodequeue_form()
 */
function smartqueue_author_nodequeue_form($queue, &$form) {
  $roles = user_roles(TRUE);
  $form['placeholder']['rids'] = array(
    '#type' => 'checkboxes',
    '#title' => t('Roles'),
    '#description' => t('Select which roles a user must have to create a queue. If none are checked, all node authors will get a queue.'),
    '#options' => $roles,
  );

  $form['subqueue_title'] = array(
    '#type' => 'textfield',
    '#title' => t('Subqueue title'),
    '#default_value' => $queue->subqueue_title,
    '#size' => 50,
    '#maxlength' => 64,
    '#description' => t('What to display for the subqueue title; use %subqueue to embed the actual subqueue title. This is used to distinguish multiple nodequeues with subqueues from each other, as internal subqueue title is filled automatically.'),
  );


  if ($queue->qid && !empty($queue->reference)) {
    $form['placeholder']['rids']['#default_value'] = explode('-', $queue->reference);
  }
}

/**
 * Implementation of hook_nodequeue_form_validate()
 */
function smartqueue_author_nodequeue_form_validate(&$form, $form_state) {

  if (!isset($queue->qid)) {
    $rids = !empty($form_state['values']['rids']) ? array_keys(array_filter($form_state['values']['rids'])) : array();
    // Convert this to our reference.
    form_set_value($form['reference'], implode('-', $rids), $form_state, $form_state);
  }
}

/**
 * Implementation of hook_nodequeue_subqueues()
 */
function smartqueue_author_nodequeue_subqueues(&$queue, $node) {
  // Sorry, no anonymous nodes allowed.
  if (empty($node->uid)) {
    return;
  }

  $rids = !empty($queue->reference) ? explode('-', $queue->reference) : array();

  $account = user_load(array('uid' => $node->uid));
  if (!empty($rids) && !array_intersect($rids, array_keys($user->roles))) {
    return;
  }

  if (!nodequeue_load_subqueues_by_reference(array($queue->qid => array($node->uid)))) {
    nodequeue_add_subqueue($queue, $account->name, $node->uid);
  }

  return array($node->uid);
}

function smartqueue_author_nodequeue_subqueue_title($queue, $reference) {
  $account = user_load(array('uid' => $reference));
  if ($account) {
    return $account->name;
  }
}

// TODO:
// * Automatically delete subqueues when a user is deleted.

The example .info file:

; $Id: smartqueue_users.info,v 1.1.2.3 2008/12/26 02:00:06 ezrag Exp $
name = Smartqueue per User
description = Provides a Nodequeue for users of one or more specified roles.
dependencies = nodequeue
package = Nodequeue

Creating queues programmatically

This snippet creates queues.

 $queue_data = array(
    'queue1' => array(
      'title' => 'Name',
      'subqueue_title' => '',
      'size' => '0',
      'reverse' => 0,
      'link' => 'Add to queue',
      'link_remove' => 'Remove from queue',
      'roles' => array ( ),
      'types' => array ( 0 => 'story',),
      'i18n' => 1,
      'op' => 'Submit',
      'submit' => 'Submit',
      'owner' => 'nodequeue',
      'show_in_links' => true,
      'show_in_tab' => true,
      'show_in_ui' => true,
      'reference' => 0,
      'subqueues' => array ( ),
      'new' => true,
      'add_subqueue' => array ( 0 => 'Name',), // match title above
    ),
  );
  
  foreach ($queue_data as $q) {
    $queue = (object) $q;
    $qid = nodequeue_save($queue); // sets $queue->qid if needed.
  }