{stash:embed}

Embed a Stash template file in your template. This is similar to an EE embed, but with the following advantages:

• Control over the process stage (when in the parse order of the host template that the embed is included)
• Control over the parse stage (whether the template is parsed and cached, or cached then parsed on retrieval, or both)
• Non caching regions of the template can be demarcated with {stash:nocache}{/stash:nocache} tag pairs
• Precisely control the order of processing of embeds with the priority parameter
• Precisely control the parse depth when a template is parsed (the number of passes made by EEs template parser)
• Set caching duration per embed
• Use multiple instances of the same template without extra overhead
• Embed different filetypes (permitted file extensions are defined by the stash_file_extensions config value).
• Optional static caching of a template.

Setting up

• Make sure you follow the setup guide to set up a Stash template folder
• During development, set stash_file_sync = TRUE to keep your Stash template files in sync with the database
• For production use it is recommended to set stash_file_sync = FALSE so that cached Stash templates are served from your database, unless you have added the replace="yes" parameter for a particular embed.

Example use

{!-- Stash template file at /path/to/stash_templates/test.html --}
{stash:embed name="test"}

{!-- ...or using the shortcut syntax --}
{stash:embed:test}

{!-- Stash template file at /path/to/stash_templates/foo/bar.html --}
{stash:embed name="foo:bar" process="start" stash:my_var="value"}

{!-- could also be written as... --}
{stash:embed context="foo" name="bar" process="start" stash:my_var="value"}

{!-- ...or using the shortcut syntax --}
{stash:embed:foo:bar process="start" stash:my_var="value"}

Parameters

name = [ string ]

The name of the template instance and the filename of your template, if file_name parameter is not set. If you omit the suffix, .html is assumed. Otherwise your files may use one of the extensions defined by the stash_file_extensions configuration parameter.

context = [ string ]

The variable namespace, which must have a corresponding subfolder in the Stash template folder if file_name parameter is not set. Use @URI to use the current page URI as the context.

file_name = [ string ]

The file name (without the suffix) if different from the variable name, e.g. 'my_file' or 'my_context:my_file'.

refresh = [ int ]

How long to cache the template output for in minutes (default='1440').

replace = [ yes | no ]

Do you want the cache to be recreated if it already exists? (default='no') Note: set stash_file_sync = true in your EE config to override this value globally. You will need to do this during development.

process = [ start | inline | end | static ]

When in the parse order of your EE template do you want the embed to be included (default='end').

process="start"

Embed the template before any other variables and tags in your template are parsed (similar to an EE snippet).

process="inline"

Embed the template in the natural parse order of the template.

process="end"

Embed the template at the end of template parsing after other tags and variables have been parsed (like a standard EE embed).

process="static"

Cache the template as a static file. Note that this only makes sense if the stash embed is the only tag in the template, since the static cache file will contain only the rendered output of the embed.

priority = [ int ]

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

parse_stage = [ set | get | both ]

When to parse the template: parse and cached, or cache then parsed on retrieval, or do both (default="get").

parse_stage="set"

Parse the template the first time it is read from the file, and cache the rendered result. Subsequent retrievals will return the cached template from the database and not the original template file (unless replace="yes" or stash_file_sync = true).

parse_stage="get"

Read the template file and cache it to the database. When output to the template on the first and subsequent retrievals the template will be parsed. This is similar to how EE templates work.

parse_stage="both"

Parse the template before caching AND after it is retrieved. This can be very useful when enclosing regions of your template with {stash:nocache}{/stash:nocache}. On SET the template code inside {stash:nocache} will not be parsed, but everything else will. On GET it will be parsed. This provides a way to partially cache some of your template code while leaving other areas dynamic.

parse_tags = [ yes | no ]

Do you want to parse any tags (modules or plugins) contained inside the embed template (optional, default is 'yes')

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 template? (optional, default is 'yes')

parse = [ yes | no ]

Set the value of parse_tags, parse_vars and parse_conditionals with one parameter (optional, default is 'yes')

parse_depth = [ int ]

How many passes of the template to make by the parser? (default is 4)

stash:my_variable="value"

Pass variables to the Stash template as parameters in the form stash:my_variable="value":

{exp:stash:embed name="my_template" stash:my_var="my_value"}

{!-- inside my_template inline variables can be accessed like so --}
{stash:my_var}	

Examples

{!-- file at stash_templates/my_context/my_template.html --}

{!-- standard embed syntax --}
{stash:embed name="my_context:my_template"}

{!-- shortcut embed syntax --}
{stash:embed:my_context:my_template}

{!-- set embed name dynamically from a Stash variable --}
{stash:embed name="{stash:layout}"}
{exp:stash:set_value name="layout" value="my_context:my_template"}

{!-- using the static context pointer '@' --}
{exp:stash:context name="my_context"}
{stash:embed name="my_template" context="@"}

{!-- or use the pointer in the name parameter --}
{stash:embed name="@:my_template"}

{!-- for multiple cached instances of same base template, use the file_name parameter --}
{stash:embed name="another_instance_of_my_template" file_name="@:my_template"}

{!-- 'template partials' example using dynamic context --}
{stash:embed name="my_layout" context="@"}

{exp:switchee variable="{segment_1}" parse="inward"}

   {!-- left to right layout for latin languages --}
   {case value="en|fr|it"}
      {!-- template at stash_templates/ltr/my_layout.html --}
      {exp:stash:context name="ltr"}
      {exp:stash:set name="content"}My language specific content{/exp:stash:set}
   {/case}

   {!-- right to left layout for arabic --}
   {case value="ar"}
      {!-- template at stash_templates/rtl/my_layout.html --}
      {exp:stash:context name="rtl"}
      {exp:stash:set name="content"}بلدي محتوى لغة معينة{/exp:stash:set}
   {/case}
{/exp:switchee}