{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 | integer ]

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

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).

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 ]

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 common iteration variables such as {count}, {total:results}, {switch} and {if no_results}. Useful when outputting a list inside another tag.

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="{topic_url}"><strong>{topic_title}</strong></a></td>
				<td><a href="{last_author_url}">{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/{stash:forum}">View all topics in this forum &raquo;</a></p>
	{/if}
	
	{if my_prefix:no_results}
	<p>No forum topics yet. <a href="/forum/newtopic/{stash:forum}">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="modal-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>