Tag Definitions %LIST%

Creates a list of items

This tag is used to create lists, either standard html lists, block-level lists, or non-html specific lists. These can be dynamically or manually generated, and depending on which, the component that calls this snippet needs to have its 'editable' property set to either 'yes' or 'no'. There are three types of manual list; one where the enduser is able to pick any items from a site to populate a list with, second, using the _user attribute that allows the End User to specify a source page - any changes to its subpages are dynamically updated, and lastly using _udp where a list is constructed based on tags.

There is a concept of lists that is not always very clear; Lists are built within components, with each component able to hold one 'primary' set of list items. This enables you to have more than one list tag in a snippet, and as long as each list element is saved in a unique location you can build and render multiple lists from one snippet using the Modulo attribute to populate each list.

Remember that a List tag builds just that; A List. With no styling, the only aspect of a list that is usually seen on a page is the list items, so if no, or the incorrect, itemtemplate is specified, nothing will be seen on the screen leading to the (wrong!) conclusion that the list isn't working.

Attribute Definitions
ParameterTypeDescription
type

ul

ol

dl

The type of HTML element that is rendered for the list. Use UL, OL or DL for normal lists, or any block level element for user-defined lists.
When Type is omitted then no entangling HTML element is rendered.

captionStringThe caption to label the input field, default is 'List of links'
classStringThe 'class' attribute to add to the rendered HTML tag
idStringThe 'id' attribute to add to the rendered HTML tag.
startitemIntegerThe first item to be displayed from the list of items found, default is '1'
maxitemsIntegerThe maximum number of items to be rendered from the list. Default value is 100.
moduloIntegerStore and Display only the nth element from a list. i.e. if your startitem = 2 and you use a modulo of 3, your list will store and display from the 2nd, 5th, 8th, 11th, etc items of the component list.
itemtemplateStringThe snippet that is used to render each item in the list.
firstitemtemplateStringThe snippet that is used to render the first item in the list.
lastitemtemplateStringThe snippet that is used to render the last item in the list.
currentitemtemplateStringThe snippet that is used to render an item in a list, if that list item equates to the page being viewed in the browser (i.e. page highlighting).

In Template Editor mode, the renderer will automatically apply this attribute to the second item in the list - but only if the list has more than 2 items. This allows for previewing the currentitemtemplate in a list during design time.
nextitembuttontemplate
[NEW in 4.5.4]
StringThe snippet that is used to display the 'Next' link when paginating a manual list.
previtembuttontemplate [NEW in 4.5.4]StringThe snippet that is used to display the 'Previous' link when paginating a manual list.
queryfieldStringURL parameter to be used when LIST is used with search.
offsetparamfieldString
URL parameter to be used when LIST is used with search.
pageparamfieldStringThe name of the parameter in the URL that contains the value of the current page number. Default is 'pagenr'. Change this parameter in the event that there are multiple lists with paginators on the template.
usepaginatoryes
no		Set this parameter to 'yes' whenever this list has a Paginator tag attached. Default is 'no'
src

uri
_self
_parent
_ancestor
_user
_search
_udp


The source of the items in the list:

uri: The uri of a page within the site

_self: Child pages or linked items of the page. When no src is specified, _self is assumed.

_parent: The parent of this page.

_ancestor: The nearest parent or grandparent item to the root.

_user: The End User can specify a list's source page

_search: The list of items generated by search.

_udp: The End User can specify common meta data values as the source of a list (see also: UDP tag). As meta data values can be assigned to pages and also links and files, the generated list can contain links to any or a combination of all the three types.

The arguments provided by this tag are:
'=' - meta data is an exact match to the value
'!=' - meta data does not match the value
'like' = meta data contains the value

allow

subpage

link

Subpage: renders a list of subpages of the page indicated in 'src'.

Link: renders a list of pages, link assets and downloads related to the page indicated in 'src'.


When src=_self then allow=link will open an  editor for manual population of the list, otherwise items are dynamically generated.


Only used in conjunction with src, and when omitted, 'link' is assumed.

sorttypemanual
editorial date
publication date
name

manual: The items are sorted using the sequence of the items in the editor (default setting).

name: The items are sorted by name.

editorial date: The items are sorted by editorial date.

publication date: The items are sorted by publication date.

sortorderasc
desc		Sets the default sort order for the list of links. This setting can be overruled by the editor. When omitted 'asc' is assumed.*

*Rendering rules for SORTORDER & SORTTYPE:

1a. When the developer has set the SORTTYPE to anything then that type is used.
1b. When the developer has set the SORTORDER to anything then that type is used.

2a. When the developer has set the SORTTYPE to empty or is omitted then the EndUser setting is used.
2b. When the developer has set the SORTORDER to empty or is omitted then the EndUser setting is used.

3a. When no SORTTYPE is set (at either level) then the system uses 'Manual'.
3b. When no SORTORDER is set  (at either level) then the system uses 'asc'.



Most of the examples below do not feature rendered output, as what will be written to the page is determined by the pages and files in any particular site

Example 1 - A basic dynamic list

In this example we show the minimum attributes required to build dynamic primary navigation. Type defines the type of list, itemtemplate tells the system which snippet holds the template for the list items we want to use in this list, src here is specifying a uri, so that is a fixed page - the 'index,html' page (homepage), and allow tells the system to use all direct subpages (child pages) of the source page.

  1. %LIST(type=ul, itemtemplate=listitem, src=/index.html, allow=subpage)%

Example 2 - A basic manual list

In this example we show the minimum attributes required to construct a list that can be populated, via the component editor, by the End User:

  1. %LIST(type=ul, itemtemplate=listitem)%

Example 3 - Using the MODULO attribute to store and render two lists from one component

Both of these manual tags are written in one snippet, the first will use the odd elements of the component list (items 1, 3, 5, 7, etc...), while the second will use the even elements of the same component (2, 4, 6, 8, etc...) Ensure when using the modulo function that your patterns of numbers do not use numbers from a different pattern as you will encounter unexpected results.

While this example uses manual lists, modulo also works with dynamic lists (the 'See Also" lists at the top of this page use this technique).

  1. %LIST(type=ol, itemtemplate=listitem, startitem=1, modulo=2)%
  2. %LIST(type=ol, itemtemplate=listitem, startitem=2, modulo=2)%

Example 4 - Adding 'Next' and 'Previous' to a list

Here we provide the ability to progress through a list using 'Next' and 'Previous' elements. These attributes refer to separate snippets and these snippets could contain text, images, or a mixture of both.



  1. %LIST(
  2. type=ol,
  3. itemtemplate=listitem,
  4. sortorder=desc,
  5. nextitembuttontemplate=next,
  6. previtembuttontemplate=prev)%

Example 5 - Using udp to display lists based on their meta data tags

Pages, links and files in Pepperio can all have meta data associated with them. Using the _udp tag we can present the End User with a component editor in to which a formula can be entered. The results of this formula form a list


Here is the minimum required to construct this type of list:



  1. %LIST(type=ul, itemtemplate=listitem, src=_udp)%

In our example, we have items tagged with two fields; Region and Language.


To display in a list only those items whose region is 'North', the End User must enter this formula into the dialog box they are presented with:



  1. (region = 'north')

To display those items whose region value contains 'North', i.e. Northeast, the End User must enter this formula:



  1. (region like 'north')

And to display any items whose region does not contain 'North' in the value, the End User must use this formula:



  1. (region != 'north')

We can also mix it up and display any items whose region is either 'North' or 'South':


  1. (region = 'north') or (region = 'south')

Or what about any 'South' regions that speak french?



  1. (region like 'south') and (language = 'fr')


Example 6 - Pagination

In this example, we have two Lists, both controlled by a Paginator. Note that the Paginator tag must follow the List tag, and we have one Paginator per List.  The results per page are limited by the maxitems attribute of each list.



  1. %LIST(id=list1, type=ul, itemtemplate=listitem, startitem=1, modulo=2, usepaginator=yes, pageparamfield=leftlistpager, maxitems=10)%
  2. %LIST(id=list2, type=ul, itemtemplate=listitem, startitem=1, modulo=2, usepaginator=yes, pageparamfield=rightlistpager, maxitems=15)%

See that the paginators use the id reference from the list to make the association:



  1. %PAGINATOR(listid=list1, type=ul, itemtemplate=paglink, activetemplate=paginatoractive, previoustemplate=paginatorprevious, nexttemplate=paginatornext, noresultstemplate=paginatornoresults, hasresultstemplate=paginatorhasresults)%
  2. %PAGINATOR(listid=list2, type=ul, itemtemplate=paglink, activetemplate=paginatoractive, previoustemplate=paginatorprevious, nexttemplate=paginatornext, noresultstemplate=paginatornoresults, hasresultstemplate=paginatorhasresults)%