{exp:stash:get_list}

Retrieve a list and apply a custom order, sort, limit and offset. Lists can be paginated, split by fractions, or filtered by regular expressions.

{exp:stash:get_list name="product_entries" orderby="item_title" sort="asc" limit="10"}
	<h2 class="{switch="one|two|three"}">{item_title}</h2>
	<p>{item_teaser}</p>
	<p>This is item {count} of {total_results} rows curently being displayed.</p>
	<p>This is item {absolute_count} of {absolute_results} rows saved in this list</p>
{/exp:stash:get_list}

Parameters

Accepts the same parameters as {exp:stash:get}, and the following:

orderby = [ column | random | random:col_1[,col_2] ]

orderby="column"

The name of the column to order the list by, e.g. orderby="title"

orderby="random"

Shuffle the list.

orderby="random:col_1,col_2"

Shuffle one or more named columns of the list, e.g. orderby="random:title,image"

sort = [ asc | desc ]

The sort order, either ascending (asc) or descending (desc) (optional, default is "asc").

sort_type = [ string | numeric | lowercase ]

The data type of the column you are ordering by, either 'string', 'numeric' or 'lowercase' (optional, default is "string").

Multiple orders and sorts

The orderby=, sort= and sort_type= parameters can accept multiple values using the pipe character. This allows you to have multiple levels of ordering and then specify the sort rules for those levels.

For example, if you wish to order by screen_name alphabetically and then have the most recent entries first, you would use the following parameters:

orderby="screen_name|date" sort="asc|desc" sort_type="string|numeric"

offset = [ int | fraction ]

Offset from 0. Pass a fraction, e.g. 1/3 to offset from a fraction of the absolute count (default is 0).

limit = [ int | fraction]

Limit the number of rows returned. Pass a fraction, e.g. 1/3 to limit to a fraction of the absolute count. (optional).

slice = [ int offset [,int length] ]

Slice the list array before limit/offset and other filters are applied, but after orderby/sort has been applied.

If offset is non-negative, the sequence will start at that offset in the array. If offset is negative, the sequence will start that far from the end of the array.

If length is given and is positive, then the sequence will have up to that many elements in it. If the array is shorter than the length, then only the available array elements will be present. If length is given and is negative then the sequence will stop that many elements from the end of the array. If it is omitted, then the sequence will have everything from offset up until the end of the array.

match = [ #regex# ]

Match a column in the list against a regular expression. Only rows in the list that match will be returned.

against = [ list column ]

Column to match against. If against is not specified or is not a valid list column, match="#regex#" will be applied to the whole string return by get_list.

unique = [ yes | no | list column ]

Remove duplicate list rows (optional, default is 'no')

process = [ inline | end ]

When in the parse order of your EE template do you want the variable to be retrieved (default is 'inline')

process="inline"

Retrieve the variable in the natural parse order of the template (like a standard EE tag)

process="end"

Retrieve the variable at the end of template parsing after other tags and variables have been parsed

priority = [ int ]

Determines the order in which the variable is retrieved when using process="end". Lower numbers are parsed first (default="1")

paginate = [ bottom | top | both ]

This parameter is for use with list pagination and determines where the pagination code will appear.

paginate="top"

The navigation text and links will appear above your list.

paginate="bottom"

The navigation text and links will appear below your list.

paginate="both"

The navigation text and links will appear both above and below your list.

paginate_base = [ string ]

Override the normal paginati on link locations and point instead to the explicitly stated uri. This parameter is essential when using query string style pagination with pagination_param=""

paginate_param = [ string ]

A parameter containing the page offset value. If set to a value, query-string style pagination links are created (e.g, ?page=P10) instead of the default segment style links (/P10); this can be useful when working with Structure / Page module uris.

prefix = [ string ]

Prefix for list variables and common iteration variables such as {count}, {total:results}, {switch} and {if no_results}. Useful when outputting a list inside another tag.

require_prefix = [ yes | no ]

When using the prefix="" parameter, only list variables that use the prefix will be parsed unless you set require_prefix="no". (optional, default is 'yes')

Single variables

• {count} - The "count" out of the row being displayed. If five rows are being displayed, then for the fourth row the {count} variable would have a value of "4".
• {total_results} - the total number of rows in the list currently being displayed
• {absolute_count} - The absolute "count" of the current row being displayed by the tag, regardless of limit / offset.
• {absolute_results} - the absolute total number of rows in the list, regardless of limit / offset.
• {switch="one|two|three"} - this variable permits you to rotate through any number of values as the list rows are displayed. The first row will use "one", the second will use "two", the third "option_three", the fourth "option_one", and so on.

Pagination variables

Pagination variables use the same syntax as Channel Entry pagination.

The {paginate}{/paginate} tag pair can optionally be prefixed, if using prefix=""

Examples

Pagination & prefix

{exp:stash:get_list 
	name="recent_discussion_topics" 
	parse_tags="yes" 
	parse_conditionals="yes" 
	process="end" 
	prefix="my_prefix"
	paginate="bottom"
}
	{if my_prefix:count == 1}
	<table class="data" cellpadding="0" cellspacing="0">

		<thead>
			<tr>
				<th class="left first">Title</th>
				<th>Last post</th>
				<th>Date</th>
			</tr>
		</thead>

		<tbody>
	{/if}
			<tr class="{my_prefix:switch='|rowAlt'}">
				<td class="left first"><a href="{my_prefix:topic_url}"><strong>{my_prefix:topic_title}</strong></a></td>
				<td><a href="{last_author_url}">{my_prefix:last_author_name}</a></td>
				<td>{last_post_date}</td>
			</tr>
	{if my_prefix:count == my_prefix:total_results}
		</tbody>
	</table>
	<p><a href="/forum/viewforum">View all topics in this forum &raquo;</a></p>
	{/if}
	
	{if my_prefix:no_results}
	<p>No forum topics yet. <a href="/forum/newtopic">Start a discussion &raquo;</a></p>
	{/if}
	
	{my_prefix:paginate}
		{pagination_links}
	    <ul>
			{first_page}
			        <li><a href="{pagination_url}" class="page-first">First Page</a></li>
			{/first_page}

			{previous_page}
			        <li><a href="{pagination_url}" class="page-previous">Previous Page</a></li>
			{/previous_page}

			{page}
			        <li><a href="{pagination_url}" class="page-{pagination_page_number} {if current_page}active{/if}">{pagination_page_number}</a></li>
			{/page}

			{next_page}
			        <li><a href="{pagination_url}" class="page-next">Next Page</a></li>
			{/next_page}

			{last_page}
			        <li><a href="{pagination_url}" class="page-last">Last Page</a></li>
			{/last_page}
	    </ul>
		{/pagination_links}
	{/my_prefix:paginate}

{/exp:stash:get_list}	

Using fractions to split lists

{!-- split into three --}
<ul class="col-a">
    {exp:stash:get_list name="my_list" orderby="title" sort="asc" limit="1/3"}
        <li><a href="#" data-marker="{url_title}">{title}</a></li>
    {/exp:stash:get_list}
</ul>
<ul class="col-b">
    {exp:stash:get_list name="my_list" orderby="title" sort="asc" offset="1/3" limit="1/3"}
        <li><a href="#" data-marker="{url_title}">{title}</a></li>
    {/exp:stash:get_list}
</ul>
<ul class="col-c">
    {exp:stash:get_list name="my_list" orderby="title" sort="asc" offset="2/3"}
        <li><a href="#" data-marker="{url_title}">{title}</a></li>
    {/exp:stash:get_list}
</ul>

{!-- split into two --}
<ul class="col-a">
    {exp:stash:get_list name="my_list" orderby="title" sort="asc" limit="1/2"}
        <li><a href="#" data-marker="{url_title}">{title}</a></li>
    {/exp:stash:get_list}
</ul>
<ul class="col-b">
    {exp:stash:get_list name="my_list" orderby="title" sort="asc" offset="1/2"}
        <li><a href="#" data-marker="{url_title}">{title}</a></li>
    {/exp:stash:get_list}
</ul>