Great Ocean Media
website design - editorial & pr services - freelance journalism

adi_list – Use lists like arrays

This plugin enables you to use lists like you would arrays:

What’s the difference between adi_list and smd_each or rah_repeat?

smd_each and rah_repeat both drive the iteration loop through a list. adi_list doesn’t – it’s designed to be used in conjunction with some other looping process, e.g. <txp:article>, and you nudge through the list manually.

adi_list can also extend the “life” of a list by repeating it, supplying a default value, or by jumping backwards & forwards at will.

Have a look at the examples to see what’s possible.

Usage summary

To set up a list, adi_list may be used as a single or container tag:

<txp:adi_list name="mylist" value="a,b,c" />

<txp:adi_list name="mylist">a,b,c</txp:adi_list>

- these are functionally equivalent and both initialise the list.

To access items in the list or to move through the list, use adi_list as a single tag, for example:

<txp:adi_list name="mylist" />

- returns the whole list

<txp:adi_list_item name="mylist" />

- returns the value of the current item

<txp:adi_list_next name="mylist" />

- moves the pointer forward through the list

Tags

Setting up or displaying information about lists:

Retrieving list item values:

Moving through lists:

Conditionals:

Setting up the list

Use the adi_list tag for this.

Attributes:

name="list name"

- the name of the list. This attribute is mandatory.

Give the list some values using one of the following (or use it as a container tag):

value="list items"

- the contents of the list.

txpvar="TXP variable name"

- set the contents of the list from a TXP variable.

field="value"

- set the contents of the list from an article’s custom field or article image field.

separator="text"

- this separates the different elements of the list. Default = “,” (comma).

default_separator="text"

- used to delineate the default value from the other items in the list. Default = “|” (bar). For example: value="a,b,c|z" – is a list “a,b,c” with a default value of “z”.

Examples:

<txp:adi_list name="mylist" value="a,b,c" />

- simple list set up

<txp:adi_list name="mylist" txpvar="myvar" />

- get list from previously assigned TXP variable

Accessing items in the list

You can access items iteratively:

- when the list is set up a pointer will point at the first item
- the pointer can then be moved through the list using adi_list tags

Or directly:

- access a list item according to its index
- access the first or last items

To get the current item value in the list:

<txp:adi_list_item name="mylist" />

To get a specific item value from the list, using index:

<txp:adi_list_item name="mylist" index="1" />

- returns the second item (indexes start at zero), without moving pointer

Get the first item value:

<txp:adi_list_first name="mylist" />

- returns first item value, without moving pointer

Get the last item value:

<txp:adi_list_last name="mylist" />

- returns last item value, without moving pointer

Moving through the list

Move the list pointer forward:

<txp:adi_list_next name="mylist" />

Move the list pointer backward:

<txp:adi_list_prev name="mylist" />

Move the list pointer to the start:

<txp:adi_list_reset name="mylist" />

Move the list pointer to the end:

<txp:adi_list_end name="mylist" />

Manipulating the list

To repeat the list sequence indefinitely use:

<txp:adi_list name="mylist" value="a,b,c" repeat="1" />

- the list becomes: “a,b,c,a,b,c,a,b,c,a,b,c …”

You can set a default value as a fallback in two ways, firstly using an attribute:

<txp:adi_list name="mylist" value="a,b,c" default="z" />

- the list becomes: “a,b,c,z,z,z,z,z …”

and secondly, by embedding it at the end of the list:

<txp:adi_list name="mylist">a,b,c|z</txp:adi_list>

- the default default-separator is “|” but can be changed using the ‘default_separator’ attribute.

Randomising the list:

<txp:adi_list name="mylist" value="a,b,c,d,e" random="1" />

- the list becomes: “a,e,d,c,b” or “c,a,e,d,b” or “c,d,e,b,a” … etc. etc.

Getting information about the list

To get the original list:

<txp:adi_list name="mylist" />

The number of items in list:

<txp:adi_list_count name="mylist" />

The list’s default value:

<txp:adi_list_default name="mylist" />

A list of notes

Examples

As mentioned before, adi_list doesn’t do the looping. The following example uses an article tag for this.

Accessing a simple repeating list

List set up:

<txp:adi_list name="mylist" value="red,green,blue" repeat="1" />

Using the list:

<txp:article>
	<h2 class="<txp:adi_list_item name="mylist" />"><txp:title /></h2>
	<txp:adi_list_next name="mylist" />
</txp:article>

The article titles will have classes of “red”, “green”, “blue”, “red”, “green”, “blue” and so on.

In real life you’d probably use CSS selectors to assign classes, but it works as an illustration.

A more likely scenario

Where adi_list comes into it’s own is when you’re dealing with a non-sequential list and/or you want to output different content or markup at different positions.

Consider the following:

<txp:adi_list name="mylist" value="a,c,b,b,a,a,d" repeat="1" />

<txp:article>
	<txp:adi_if_list name="mylist" value="a">
		... tags for "a"
	<txp:else />
		<txp:adi_if_list name="mylist" value="b">
			... tags for "b"
		<txp:else />
			... tags for others
		</txp:adi_if_list>
	</txp:adi_if_list>
	<txp:adi_list_next name="mylist" />
</txp:article>

Here you can alter what’s output based on criteria which is independent of the content.

Additional information

Support and further information can be obtained from the Textpattern support forum. A copy of this help is also available online. More adi_plugins can be found here.

Version 0.2Download (Uncompressed) SupportTXP 4.5, 4.6