modules/nodequeue/README.txt

$Id$
The Node Queue module allows an administrator to arbitrarily put nodes in a
group for some purpose; examples of this might be to highlight one particular
node, as in a typical news site's Lead Article. Another use 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 group of nodes, and then have a block or the
front page offer one of these randomly.

Queues can be set to allow only certain types of nodes to be added to the
queue. Queue can be a fixed size or of infinite length. And the admin can
select which roles have permission to add nodes to a given 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 edit permissions--to add or
remove that node from the queue. Queue admins can view the nodes in the queue,
and can modify the order of items already in the queue. Items may also appear
in a nodes links area to add/remove them from the queue.

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

Nodequeue has support for nodes with i18n Internationalizations.
You must install the Translation Helpers module from http://drupal.org/project/translation_helpers to use this functionality.

It is highly recommended that you use the Views module to display your queues.
However, if you choose not to, here is an alternative: Writing a PHP snippet.

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:

   <?php print nodequeue_node_titles(QUEUEID); ?>

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

   <?php print nodequeue_node_titles(QUEUEID, '', 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.

Programatically displaying nodes from a Queue
===================================================
The following funcitons can be used to display nodes from a subqueue, based on their position.
For more customized displays of content from a queue, please use the Views module (http://drupal.org/project/views).
For the most up to date Nodequeue API information, see http://drupal.org/node/293117.
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:

<?php
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:

<?php
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:

<?php
print nodequeue_view_nodes($subqueue_id);
?>

With Nodequeue 5.x-2.x

<?php
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:
<?php
$node = nodequeue_load_front($subqueue_id);
$rendered_node = node_view($node);
 
?>

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

Or

With Nodequeue 6.x-2.x:

<?php
$node = nodequeue_load_back($subqueue_id);
$rendered_node = node_view($node);
 
?>

With Nodequeue 5.x-2.x:
<?php
$rendered_node = nodequeue_fetch_back($subqueue_id);
?>
To render a random node from a queue

With Nodequeue 6.x-2.x:

<?php
$node = nodequeue_load_random_node($subqueue_id);
$rendered_node = node_view($node);
?>

With Nodequeue 5.x-2.x:

<?php
$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.

Actions Module Integration
==========================

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


1	$Id$
2	The Node Queue module allows an administrator to arbitrarily put nodes in a
3	group for some purpose; examples of this might be to highlight one particular
4	node, as in a typical news site's Lead Article. Another use might be to create
5	a block listing teasers for 5 forum posts that the admin thinks are important.
6	Another use might be to create a group of nodes, and then have a block or the
7	front page offer one of these randomly.
8
9	Queues can be set to allow only certain types of nodes to be added to the
10	queue. Queue can be a fixed size or of infinite length. And the admin can
11	select which roles have permission to add nodes to a given queue.
12
13	Once a queue is set up, a new tab will appear on eligible nodes for eligible
14	users. This tab will allow the user--regardless of edit permissions--to add or
15	remove that node from the queue. Queue admins can view the nodes in the queue,
16	and can modify the order of items already in the queue. Items may also appear
17	in a nodes links area to add/remove them from the queue.
18
19	When a node is added to the queue, it is added to the back of the queue. If a
20	queue is full when a node is added, the front of the queue is removed.
21
22	Nodequeue has support for nodes with i18n Internationalizations.
23	You must install the Translation Helpers module from http://drupal.org/project/translation_helpers to use this functionality.
24
25	It is highly recommended that you use the Views module to display your queues.
26	However, if you choose not to, here is an alternative: Writing a PHP snippet.
27
28	To Create a Block to Display Node Titles of a Queue
29	===================================================
30
31	You'll need the Queue ID, which is easily extracted from the URL on the
32	queue administration page.
33
34	Create a new block, and insert the following PHP snippet into the block:
35
36	<?php print nodequeue_node_titles(QUEUEID); ?>
37
38	If you want this queue to be printed in the reverse order, you can tell it
39	to print backward:
40
41	<?php print nodequeue_node_titles(QUEUEID, '', true); ?>
42
43	The '' in the line above is an optional title field. Feel free to put
44	something here, but it's not terribly necessary in a block.
45
46	Programatically displaying nodes from a Queue
47	===================================================
48	The following funcitons can be used to display nodes from a subqueue, based on their position.
49	For more customized displays of content from a queue, please use the Views module (http://drupal.org/project/views).
50	For the most up to date Nodequeue API information, see http://drupal.org/node/293117.
51	Programmatic Ways of Displaying Content from a Queue
52
53	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.
54
55	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.
56	To Create a Block to Display Node Titles of a Queue
57
58	You'll need the Queue ID, which is easily extracted from the URL on the queue administration page.
59
60	Create a new block, and insert the following PHP snippet into the block:
61
62	<?php
63	print nodequeue_node_titles($subqueue_id);
64	?>
65
66	If you want this queue to be printed in the reverse order, you can tell it to print backward:
67
68	<?php
69	print nodequeue_node_titles($subqueue_id, '', TRUE);
70	?>
71
72	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.
73	To Display a list of teasers from a queue:
74
75	Like above, you'll need the Queue ID.
76
77	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:
78
79	With Nodequeue 6.x-2.x:
80
81	<?php
82	print nodequeue_view_nodes($subqueue_id);
83	?>
84
85	With Nodequeue 5.x-2.x
86
87	<?php
88	print nodequeue_nodes($subqueue_id);
89	?>
90
91	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.
92	To render the first or last node from a queue
93
94	With Nodequeue 6.x-2.x:
95	<?php
96	$node = nodequeue_load_front($subqueue_id);
97	$rendered_node = node_view($node);
98
99	?>
100
101	With Nodequeue 5.x-2.x:
102	<?php
103	$rendered_node = nodequeue_fetch_front($subqueue_id);
104	?>
105
106	Or
107
108	With Nodequeue 6.x-2.x:
109
110	<?php
111	$node = nodequeue_load_back($subqueue_id);
112	$rendered_node = node_view($node);
113
114	?>
115
116	With Nodequeue 5.x-2.x:
117	<?php
118	$rendered_node = nodequeue_fetch_back($subqueue_id);
119	?>
120	To render a random node from a queue
121
122	With Nodequeue 6.x-2.x:
123
124	<?php
125	$node = nodequeue_load_random_node($subqueue_id);
126	$rendered_node = node_view($node);
127	?>
128
129	With Nodequeue 5.x-2.x:
130
131	<?php
132	$rendered_node = nodequeue_fetch_random($subqueue_id);
133	?>
134
135	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.
136
137	Actions Module Integration
138	==========================
139
140	The node queue module provides two actions, so that workflow can add and
141	remove items from queues.
142
143
144