Using nodequeue module with actions and workflow module

This tutorial will show you how to use the nodequeue module on your site. The initial part of the tutorial will show manual use of the module and the later part will show how nodequeue can be integrated with actions and workflow modules.

We will build a block showing the 5 latest story posts. Initially we will add them manually, then we'll do it automaticallly, we'll add new Stories to our queue and then remove them at a predefined time in the future. (and on the way we'll show you how to create views of a nodequeue).

For some background on why nodequeue is important, read Merlin's post on his site.

You will need

Drupal 5
Views module
nodequeue module
actions module
workflow module

Ok, let's get started.

Installation

You can get the Drupal modules from the links below:

Download and install on your site. Need help installing contributed modules? look at the handbook page

Enable the modules under admin/build/modules

Actions
Node Queue
Workflow
Views

Go to admin/content/nodequeue where we can add and list nodequeues.

Click Add. Then enter the following values in the fields

Title: Latest Stories

Queue Size: 5

Link 'add to queue' text: Add Story

Link 'remove from queue' text: Remove Story

Roles: Click roles who are allowed to add/remove stories from the list

Types: Click Story

Click the Submit button

We should now see our listed with a title 'Latest Stories', Max Nodes 5, and In queue 0.

Now let's add some Stories to our nodequeue...

Using nodequeue

Add to nodequeue

Create a node of Content type Story. For example call it Story 1, add some body text and hit submit.

As you can see below we have an Add Story link showing. Click on it and it will cause the story to be added to our nodequeue.

Once clicked, notice how the link changes to Remove Story.

Now if we click on the Node queue link we can see that the node is on the queue.

We can view the queue, which will allow us to maintain position and what nodes to show in the queue. The nodequeue could be used for listing your favourite nodes, the nodequeues are system wide as Earl has mentioned so currently no user level nodequeues are possible.

Go ahead and add two more Story nodes, perhaps imaginatively called Story 2 and Story 3.

displaying a nodequeue on your site

You may think that you just need to go to admin/build/block in order to add the nodequeue as a block to your site. That's not the case, first we need to enable the nodequeue in Views, so go to admin/build/views and you will see nodequeue_1 listed (ok, mine says nodequeue_2 well I did a dry run before writing this tutorial) with Title 'Latest Stories', notice how the Status is Disabled.

Click on the Enable link under the Actions column in order to enable it.

Now go back to admin/build/block and you will see the nodequeue listed under the disabled.

Select the region where you want it to be displayed and click Save Blocks button. (Note we can configure the block which will allow us to override the Title, and do all the usual things possible with Blocks permissions etc). You should now see the nodequeue appear as a block in your chosen region.

So now we have a Block on the site which lists the content of our nodequeue, we can manually add and remove Story nodes from the queue. But what happens when we eventually have more than 5 Story nodes on our queue? The oldest story will disappear from the queue and we'll have a more link displayed at the foot of the block.

Also, if you inspect the nodequeue the In queue column will show 5 and the words QUEUE FULL.

Before we use Actions and Workflow modules, a few observations about nodequeue:

Once an item falls off the queue, ie. we exceed the maximum number of queue entries, then if you edit that node the link will once again say Add Story.
Adding a node to the nodequeue causes the added node to be placed at the bottom of the queue. It then rises to the top as more nodes are added. By default the sort order of the nodequeue is by queue position, which you'll see when we make a view of a nodequeue. A Latest Stories block really should have the newest added nodes added at the top of the list and sink down the list rather than rise. But have no fear, Views module comes to the rescue as we will see we can add a view of a nodequeue and do all the usual view things.
You can use the Theme Wizard in the Views module to theme the nodequeue, YEAH! See below

Let'smake a view of our nodequeue, so we can make the Latest Stories block list stories by the time the Story node was created.

Using nodequeue with Views

So we have a Latest Stories Block but it does not list our Stories according to the creation time of the Stories. So what do we do? Well we go back to the Views page and make a view of our nodequeue.

Go to admin/build/views then click the Add link under the Action column for nodequeue_1

Now we are in the Views edit form, scroll down to the Sort Criteria, you will see the default sort order for a nodequeue.

Change it to this, and then we will get the desired block behaviour.

Now Save, and we'll see that the nodequeue has been overridden, click on the link under the URL column to see the block. The block will also appear under admin/block menu.

So let's push on and use Actions and Workflows modules to add and remove items from the queue automatically. I think now you are starting to see the power of the nodequeue module that Earl Miles was writing about.

Using nodequeue with actions and workflow module

Earl Miles also says he hasn't tried nodequeue with the actions and workflow module. I've used those modules so thought I'd put nodequeue through its paces.

I am assuming that you have installed actions and workflow module as documented earlier in this tutorial. So what we'll now do is

Go to admin/build/actions and look at the entries in the select list, you'll see we now have Add to Node Queue and Remove from Node Queue actions. Select Add to Node Queue and click the Add New Action button. Then you will see the following and we can select the desired nodequeue, which is Latest Stories.

Click Save, and then repeat the process for adding the Remove from Node Queue action. Then we should end up with the two new actions, hightlighted in red below.

So now we have the nodequeue actions at our disposal, we can turn to the workflow module. We need to create a workflow, define states for the workflow, then finally add that workflow to a node or node types.

Go to admin/build/workflow and click Add Workflow link.

Define the workflow name as Stories then click the Add Workflow button.

Now you will see we have the workflow and we can perform some operation on that workflow. A workflow is a series of states, probably the most simple workflow would have 2 states, on and off. For our tutorial we will use two states called Added and Expired. The idea being that we want to add stories to our Latest stories list and then change their state to expired at a chosen date and time in the future.

Let's add the states to our workflow.

Now define the transitions. I'm not going to get bogged down with the detail here, I think transition logic is self explanatory.

Define Workflow actions

Once defined it should look like this.

Make sure the workflow is defined for the Story nodetype.

Now let's add a Story. Once you've added a story it should appear on the queue. Also if you Edit the story you'll notice we have Workflow and Node Queue links.

Let's define an expiry time. To do this click on the Workflow link for the Story node, set Change Stories state to Removed, and Schedule for state change at (specify some datetime in the future). (It would have been nice if we could specify an elapsed time from the creation date of the node). Click submit, then once the scheduled state change time is reached the node should disappear from the node queue, (Note the scheduled transition only happens upon the next execution of cron.php).

That about wraps up this tutorial, please post comments if you spot any errors, or ways it can be improved. Enjoy.