For more information... RTFM!
NAVIGATION
PAGES THAT LINK HERE
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

Looping tags introduction

Certain tags are not standalone, but are dependent upon a patent tag.  The tags in this category are variously referred to as "looping tags", "sub-tags" or "pseudo-tags".  Looping tags include [item-list], [loop], [query], [search-region] and some others, such as [tree].

Looping tags are only valid for use within their container, and only accept positional parameters.

There are two types of lists, ARRAY and HASH, as explained below.

PREFIX

The word "PREFIX", in tags such as [PREFIX-code], represents the particular prefix that used by the container looping tag.

PREFIX names can be changed using the looping tag's "prefix" parameter.  The default PREFIX names are as follows:

Tag Default PREFIX Examples
[fly-list] item [item-code], [item-field price], [item-increment]
[item-list] item [item-code], [item-field price], [item-increment]
[loop] loop [loop-code], [loop-field price], [loop-increment]
[query] sql [sql-code], [sql-field price], [sql-increment]
[search-region] item [item-code], [item-field price], [item-increment]
[tree] item [item-code], [item-field price], [item-increment]

Sub-tag behaviour is consistent among the looping tags.  Sub-tags are parsed during evaluation of the enclosing loop, before any "ordinary" tags within that same loop.

See the Looping tags and sub-tags category for a list of sub-tags that are available to all looping tags.

Output control regions

For list queries (using the type=list parameter), the following output control regions can be defined:

sub-tag Usage description
[on-match]

Defines a block of text that will be shown if query results were found.  The text can contain HTML and Interchange tags.

[on-match]
    Show this if resuts were found.
[/on-match]

[no-match]

Defines a block of text that will be shown if no query results were found.  The text can contain HTML and Interchange tags.

[no-match]
    Show this if no results were found.
[/no-match]

[list]

The [list] sub-tag defines a region where you can use any of the loop sub-tags that work in the array list context.

The looping tag's list_prefix parameter renames the [list] sub-tag itself.

[list]
    Show this for each matched item.
[/list]

The [list] region can contain a sub-tag, called [sort].  The [sort] sub-tag can be used to influence the order in which the list items are given to each [list] iteration.

[more-list]

The [more-list] and [more] sub-tags are used when paginating the query results.

[more-list]
    Results [matches] of [match-count] shown<br>
    [more]
[/more-list]

[matches] is the current range of matches available to the current page.  [match-count] is the total number of matches found.  The [more] sub-tag expands to a list of links to the other pages of the query results.

This block will not show at all if one of the following is true:

  • There are no search results.
  • All of the results can be shown on one page.

See the [more-list] page for more information.

The following is a quick and dirty example of output region usage:

[query
    type=list
    more=1
    ml=10
    sql=|
        SELECT  sku, description, price
        FROM    products
        WHERE   price < [value mv_arg]
|]
[on-match]
    [L]Results found, as follows[/L]:<br>
[/on-match]

[no-match]
    [L]No results found.[/L]<br>
[/no-match]

[list]
    [sql-code], [sql-param description], [sql-price]<br>
[/list]

[more-list]
    Results [matches] of [match-count] shown<br>
    [more]<br>
[/more-list]
[/query]

The prefix and list_prefix parameters

The following quick and dirty example makes use of the prefix and list_prefix parameters to set the sub-tag PREFIX:

[query
    type=list
    more=1
    ml=10
    prefix=foo
    list_prefix=bar
    sql=|
        SELECT  sku, description, price
        FROM    products
        WHERE   price < [value mv_arg]
|]
[bar-on-match]
    [L]Results found, as follows[/L]:<br>
[/bar-on-match]

[bar-no-match]
    [L]No results found.[/L]<br>
[/bar-no-match]

[bar]
    [foo-code], [foo-param description], [foo-price]<br>
[/bar]

[bar-more-list]
    Results [matches] of [match-count] shown<br>
    [more]<br>
[/bar-more-list]
[/query]

In the above example, looping tags use "foo" as their PREFIX (as per the "prefix" parameter), whereas the various output regions use "bar" (as per the "list_prefix" parameter).

Sorting the resultset

All looping tags can contain a pseudo-tag called [sort].  The [sort] pseudo-tag can be used to influence the order in which the list items are given to each loop iteration.

Interchange has standard sorting options for sorting the search lists, loop lists, and item lists based upon the content of list data.  In addition, it adds list slices for limiting the displayed entries based upon a start value and a chunk size (or a start and end value, from which a chunk size can be determined).  The [sort] pseudo-tag must be placed on the first line of the tag's loop block:

Note

Note

If possible, we suggest that you make use of the [query] tag, along with the SQL "ORDER BY" clause, instead of sorting the resultset in this way.

If it is not possible to use SQL, then any method of pre-sorting the selection is preferable to post-sorting the resultset.

The following are examples of the [sort] pseudo-tag in action:

[loop 4 3 2 1]
    [sort -2 +2]

    [loop-code]
[/loop]
[search-region]
[search-list]
    [sort products:category:f]

    [item-price] [item-description]<br>
[/search-list]
[/search-region]
[item-list]
    [sort products:price:rn]

    [item-price] [item-code]<br>
[/item-list]
[loop search="ra=yes"]
    [sort products:category products:title]

    [loop-field category] [loop-field title]<br>
[/loop]

Sort options

All looping tags, such as [item-list], [loop], [search-region] and [tag] take sort options in the following form:

[sort table:column:option -n +n =n-n ...]

The current item's key, as returned by the [PREFIX-code] sub-tag, will be used as the key for looking up column data in the specified table.

table

The Interchange table identifier ("products", for instance).  The table name must be supplied.

column

The column of the named table upon which the results should be sorted.

options

Any combination of, or none of, the following options:

Option Description
f Case-insensitive sort (folded) (mutually exclusive of "n").
n Numeric order (mutually exclusive of "f").
r Reverse the sort order.

-n

The starting point of the list to be displayed, numbered from 1 (not 0) for the first entry.

+n

The number of results to display.

=n-n

The starting and ending point of the list display.  This is an alternative to "-n" and "+n".

The starting and ending points should be specified in only one form.  If both forms are specified, the last one will take effect.

Multiple sort levels

More than one sort level can be specified, although it should be noted that lots of sort levels may be quite slow if you are working with a large resultset.

Multiple levels of sort are supported, and table boundaries on different sort levels can be crossed.  Cross-table sorts on the same level are not supported;  If you are using multiple product tables then you will need to sort the resultset with a block of embedded Perl.

Sort examples

Loop list

[loop 00-0011 19-202 34-101 99-102]
    [sort products:title]

    [loop-code] [loop-field title]<br>
[/loop]

Will display:

34-101 Family Portrait
00-0011 Mona Lisa
19-202 Radioactive Cats
99-102 The Art Store T-Shirt

Alternatively:

[loop 00-0011 19-202 34-101 99-102]
    [sort products:title -3 +2]

    [loop-code] [loop-field title]<br>
[/loop]

will display:

19-202 Radioactive Cats
99-102 The Art Store T-Shirt

The "[sort products:title =3-4]" specification is equivalent to the above examples.

Search region

A search of all products (perhaps with "http://www.example.com/cgi-bin/example/scan/ra=yes"):

[search-region]
[no-match]
Nothing found.
[/no-match]

[search-list]
    [sort products:artist products:title:rf]

    [item-field artist] [item-field title]<br>
[/search-list]
[/search-region]

will display:

Gilded Frame
Grant Wood American Gothic
Jean Langan Family Portrait
Leonardo Da Vinci Mona Lisa
Salvador Dali Persistence of Memory
Sandy Skoglund Radioactive Cats
The Art Store The Art Store T-Shirt
Vincent Van Gogh The Starry Night
Vincent Van Gogh Sunflowers

Note the reversed order of the title for "Van Gogh", and the presence of the "Gilded Frame" accessory item at the top of the list.  The accessory has no "artist" column and, as such, sorts first).

Adding a slice option:

[search-region]
[no-match]
Nothing found.
[/no-match]

[search-list]
    [sort products:artist products:title:rf =6-10]

    [item-field artist] [item-field title]<br>
[/search-list]
[/search-region]

will display:

Sandy Skoglund Radioactive Cats
The Art Store The Art Store T-Shirt
Vincent Van Gogh The Starry Night
Vincent Van Gogh Sunflowers

If the end value/chunk size exceeds the size of the list, only the elements that exist will be displayed, starting from the start value.

Shopping cart

[item-list]
    [sort products:price:rn]

    [item-price] [item-code]<br>
[/item-list]

The above will display the items in the shopping cart, sorted on their price, with the most expensive items shown first.

Note

Note

This is based upon the raw price column value, and therefore does not take quantity price breaks or discounts into effect.  Cart lines cannot be sorted using quantities, or other modifier values, such as "size" or "colour", etc.

Dump all rows in a table, in a sorted order

The following example shows a two-level sort that will re-order products based firstly upon the category, and then upon the title within that category:

[tag each products]
    [sort products:category products:title]

    [loop-field category] [loop-field title]<br>
[/tag]
Note

Note

Large lists may take some time to sort.  If a table contains many thousands of items, then using the above "[tag each products]" sort mechanism is not recommended.  Instead, we suggest that you use the [query] tag, along with the SQL "ORDER BY" clause.

Array lists

An array list is the normal output of a [query], a search, or a [loop] tag.  It returns from 1 or more columns per row, as defined in the mv_return_fields variable (or rf parameter) or implicitly by means of a SQL column list.  The two queries below are essentially identical:

[query sql="select foo, bar from products"]
[/query]
[loop search=|
    ra=yes
    fi=products
    rf=foo,bar
|]

Both will return an array of arrays consisting of a foo column and the bar column.  The Perl data structure would look like:

[
    ['foo0', 'bar0'],
    ['foo1', 'bar1'],
    ['foo2', 'bar2'],
    ['fooN', 'barN'],
]

Hash lists

A hash list is the normal output of the [item-list] tag.  It returns the value of all return fields in an array of hashes.  A normal [item-list] return might look like:

[
    {
        code     => '99-102',
        quantity => 1,
        size     => 'XL',
        color    => 'blue',
        mv_ib    => 'products',
    },
    {
        code     => '00-341',
        quantity => 2,
        size     => undef,
        color    => undef,
        mv_ib    => 'products',
    },
]

You can also return hash lists in queries:

[query sql="SELECT foo, bar FROM products" type="hashref"]
[/query]

Now the data structure will look like this:

[
    { foo => 'foo0', bar => 'bar0' },
    { foo => 'foo1', bar => 'bar1' },
    { foo => 'foo2', bar => 'bar2' },
    { foo => 'fooN', bar => 'barN' },
]

Last modified by: Kevin Walsh
Modification date: Tuesday 18 September 2007 at 6:22 PM (EDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us