Lists

Lists are single or multidimensional arrays of key/value pairs. Lists can be sorted, randomized, paginated, split into fractions, cached and filtered in various useful ways.

One dimensional lists

A single row of key/value pairs.

{exp:stash:set_list name="my_list"}
    {stash:item_title}My title{/stash:item_title}
    {stash:item_summary}Summary text{/stash:item_summary}
    {stash:item_copy}Bodycopy goes here{/stash:item_copy}
{/exp:stash:set_list}

{exp:stash:get_list name="my_list"}
    <h1>{item_title}</h1>
    {if item_summary}<p>{item_summary}</p>{/if}
    {item_copy}
{/exp:stash:get_list}

Two-dimensional lists

Multiple rows of key/value pairs. Like Channel Entries, common iteration variables such as {count}, {switch="one|two|three"} and {total_results} are available when retrieving lists.

Method 1: Using append / prepend

We can capture a list by appending a row with each loop of the tag pair:

{exp:channel:entries channel="clients" limit="5"}
    {exp:stash:append_list name="my_list"}
        {stash:item_title}{title}{/stash:item_title}
        {stash:item_summary}{summary}{/stash:item_summary}
        {stash:item_copy}{copy}{/stash:item_copy}
    {/exp:stash:append_list}
{/exp:channel:entries}  

Method 2: wrapping around a looping tag pair

Alternatively, we can capture the list by wrapping around {exp:stash:set_list} around the the looping tag and parsing. Stash will detect that there are multiple rows in the output of the parsed tag(s) it encloses and capture them as a multidimensional list:

{!-- this will capture multiple rows automatically --}
{exp:stash:set_list name="my_list" parse_tags="yes"}
    {exp:channel:entries channel="clients" limit="5"}
        {stash:item_title}{title}{/stash:item_title}
        {stash:item_summary}{summary}{/stash:item_summary}
        {stash:item_copy}{copy}{/stash:item_copy}
    {/exp:channel:entries}  
{/exp:stash:set_list}

{!-- retrieve the list --}
{exp:stash:get_list name="my_list"}
    <div class="{switch='row|rowAlt'}">
        <h1>{item_title} (item {count} of {absolute_results})</h1>
        {if item_summary}<p>{item_summary}</p>{/if}
        {item_copy}
    </div>
{/exp:stash:get_list}

Three (and more) dimensional lists

Nested lists can be used to capture content from nested looping tags such as Playa and Matrix. We do this by passing a variable uniquely identifying the outer list as a context for the inner list, creating a parent-child relationship between the lists. On retrieval, prefixes can be used to preserve common iteration variables within the nested lists:

{exp:stash:set_list name="my_list" parse_tags="yes" parse_depth="2"}
    {exp:channel:entries channel="clients" limit="5"}

        {stash:item_title}{title}{/stash:item_title}
        {stash:item_entry_id}{entry_id}{/stash:item_entry_id}

        {exp:stash:set_list:nested name="related_entries" context="{entry_id}" parse_tags="yes"}
            {!-- this could be a Matrix or Playa tag pair --}
            {contact_docs}
                {stash:related_title}{mx_title}{/stash:related_title}
            {/contact_docs}
        {/exp:stash:set_list:nested}    

    {/exp:channel:entries}  
{/exp:stash:set_list}

{exp:stash:get_list name="my_list"}
    <div class="{switch='row|rowAlt'}">
        <h1>{item_title} (item {count} of {absolute_results})</h1>

        {exp:stash:get_list:nested name="related_entries" context="{item_entry_id}" prefix="nested"}
            <div class="{nested:switch='row|rowAlt'}">
                {related_title} (Related item {nested:count} of {nested:absolute_results})
            </div>
        {/exp:stash:get_list:nested}

    </div>
{/exp:stash:get_list}

###Pagination

Lists can be paginated in much the same way as Channel Entries. Prefixes can be used to namespace common iteration values, which can be handy if you are retrieving your list inside another tag:

{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}

Filtering lists

Match / against

When setting or getting a list, captured rows can be filtered by a regular expression matched against a specific column value:

{!-- Capture items where the topic title begins with 'A' only --}
{exp:stash:set_list name="recent_discussion_topics" parse_tags="yes" match="#^A#" against="topic_title"}
    {exp:forum:topic_titles 
        orderby="post_date" 
        sort="desc" 
        limit="5" 
        forums="1"
    }   
        {stash:topic_url}{thread_path='forum/viewthread'}{/stash:topic_url}
        {stash:topic_title}{title}{/stash:topic_title}
        {stash:last_author_url}{last_author_profile_path='member'}{/stash:last_author_url}
        {stash:last_author_name}{last_author}{/stash:last_author_name}
        {stash:last_post_date}{last_post_date}{/stash:last_post_date}
    {/exp:forum:topic_titles}
{/exp:stash:set_list}   

Sorting