{exp:stash:set}

Sets a variable to a value.

{exp:stash:set name="my_var"}Value{/exp:stash:set}

Parameters

name = [ string ]

The name of your variable (optional). This should be a unique name. Use underscores for spaces and use only alphanumeric characters. Note: if you use the same variable twice the second one will overwrite the first.

type = [ variable | snippet ]

The type of variable to create (optional, default is 'variable').

type = "variable"

A variable is stored in the Stash session, and can be retrieved using {exp:stash:get name="my_var"} or {exp:stash:my_var}

type = "snippet"

A 'snippet' works just like snippets in ExpressionEngine, and can be used in the same way, e.g. {my_var}. When using snippets it is possible to overwrite existing EE global variables in the current request. Note that EE snippets can also be retrieved using {exp:stash:get name="a_snippet" type="snippet"}

scope = [ local | user | site ]

Determines if an instance of the variable is set for the current page only, for the current user, or globally (set for everyone who visits the site) (optional, default is defined by the 'stash_default_scope' config value).

scope = "local"

A 'local' variable exists in memory for the duration of the current HTTP request, and expires once the page has been rendered. It cannot be saved to the database.

scope = "user"

A 'user' variable behaves like a local variable but can optionally be saved to the database for persistence across page loads (with save="yes"). When saved, the variable is linked to the user's session id, and so it's content is only visible to that user. While a user-scoped variable can be set to expire after an arbitrary time period (with refresh=""), by default it will expire anyway once the users' session has ended. For persistence of user-scoped variables beyond the user's current browser session set the 'stash_cookie_expire' configuration setting to the desired number of seconds.

Use for pagination, search queries, or chunks of personalised content that you need to persist across pages.

scope = "site"

A 'site' variable is set only once until it expires, and is visible to ALL site visitors. Use for caching common parts of your template.

context = [ string ]

If you want to assign the variable to a context, add it here. Tip: Use '@' to refer to the current context:

{exp:stash:set name="title" context="@"}
...
{exp:stash:set}

bundle = [ string ]

Assign the variable to a named Bundle. If your bundle does not exist, it will be created (optional, default is 'default')

save = [ yes | no ]

Do you want to store the variable in the database so that it persists across page loads? Note that you should never save user data that is sensitive (optional, default is 'no')

refresh = [ int ]

The number of minutes to store the variable (optional, default is 1440 - or one day)

replace = [ yes | no ]

Do you want the variable to be overwritten if it already exists? (optional, default is 'yes')

output = [ yes | no ]

Do you want to output the content inside the tag pair (optional, default is 'no')

trim = [ yes | no ]

Remove whitespace and linebreaks from the captured value? (optional, default is 'no').

parse_tags = [ yes | no ]

Do you want to parse any tags (modules or plugins) contained inside the stash tag pair (optional, default is 'no')

parse_vars = [ yes | no ]

Parse variables inside the template? (optional, default is 'yes', IF parse_tags is 'yes')

parse_conditionals = [ yes | no ]

Parse if/else conditionals inside the variable? (optional, default is 'no')

parse_depth = [ int ]

How many passes of the template to make by the parser? (optional, default is 1) By default the parse depth is '1', meaning nested module tags would remain un-parsed. Set to a higher number to make repeated passes. More passes means more overhead (processing time).

match = [ #regex# ]

Variable will only be set if the content matches the supplied regular expression (optional)

against = [ string ]

String to match against if using the match= parameter (optional). By default, the variable content is used.

site_id = [ int ]

When using MSM specify the site id here (optional). By default, the site_id of the site currently being viewed will be used.

append = [ yes | no ]

The value is appended to the existing variable. (optional, default is 'no'). Equivalent to using {exp:stash:append}

prepend = [ yes | no ]

The value is prepended to the existing variable. (optional, default is 'no'). Equivalent to using {exp:stash:prepend}

unprefix = [ string ]

Prefix for common tag variables such as {if no_results}...{/if} for use in any nested tags:

{exp:stash:set name="content" unprefix="my_prefix" parse_tags="yes" output="yes"}
	{exp:channel:entries channel="blog" dynamic="no"}
		{if my_prefix:no_results}no results{/if}
	{/exp:channel:entries}
{/exp:stash:set}

prefix = [ string ]

Prefix to use in place of 'stash' in {stash:nocache} pairs, e.g. {my_prefix:nocache}.

Escaping content from caching

When parsing and saving, surround content you don't want to be cached with {stash:nocache}...{/stash:nocache}. Use the prefix="" parameter to namespace your escaped regions if your tag is nested within other Stash tags or Stash embeds.

Examples

Basic usage

{exp:channel:entries limit="1" disable="member_data|pagination|categories"}	
	{exp:stash:set name="title"}{title}{/exp:stash:set}
{/exp:channel:entries}	

Caching a variable

Caching the output of a channel entries tag for 60 minutes. The first time the template is viewed the channel entries tag is run and its output is captured and saved to the database. On subsequent visits within the following 60 minutes, the output is retrieved from the database and the channel entries tag does NOT run. At the end of the 60 minutes the variable expires from the database, and on the next view of the template the cache is regenerated.

This approach can save you a huge number of queries and processing time.

{exp:stash:set
	name="my_cached_blog_entries" 
	save="yes" 
	scope="site" 
	parse_tags="yes"
	replace="no" 
	refresh="60"
	output="yes"
}
	{exp:channel:entries channel="blog"}
		<p>{title}</p>
	{/exp:channel:entries}
{/exp:stash:set}

Using tag pairs to set multiple variables at once

{exp:stash:set} called WITHOUT a name="" parameter can be used to set multiple variables wrapped by tag pairs {stash:variable1}...{/stash:variable1} etc. These tag pairs can even be nested.

In this example we want to ensure that the inner {exp:channel:entries} tag is parsed so we set parse_tags="yes". Then we want to capture the the unordered list and the total count of entries so we can use them elsewhere in the same template:

{exp:stash:set parse_tags="yes"}
	{stash:content}
	<ul>
	{exp:channel:entries channel="blog"}
		<li>{title}</li>
		{stash:absolute_results}{absolute_results}{/stash:absolute_results}
	{/exp:channel:entries}
	</ul>
	{/stash:content}
{/exp:stash:set}