Stash: core principles

Presentation to #eeconf 14 October 2013

Transcript

1. Stas CORE PRINCIPLES A PRESENTATION BY Mark Croxton, Hallmark Design
2. H , I' Mar
3. Variable
4. Capture text and fragments of code to be re-used elsewhere in your templates. Pass the output of one or more tags as the input to other tags. Change the order in which template tags and variables are parsed. Cache fragments of data, so that the tags that generated it do not need to be re-run on subsequent views. Variable
5. Set a variable - tag pair {exp:stash:set name="foo"}bar{/exp:stash:set} OR {exp:stash:foo}bar{/exp:stash:foo} Set a variable - single tag {exp:stash:set_value name="foo" value="bar"} Set a multiple variables at once {exp:stash:set} {stash:title}A title{/stash:title} {stash:content}Some content{/stash:content} {/exp:stash:set} Se
6. Set variable 'foo' {exp:stash:set name="foo"}Romans{/exp:stash:set} Append to 'foo' {exp:stash:append name="foo"} ever done for us? {/exp:stash:append} Prepend to 'foo' {exp:stash:prepend_value name="foo" value="What have the "} Appen & prepen
7. Get a variable - prints 'bar' {exp:stash:get name="foo"} OR {exp:stash:foo} Get a variable, provide a default value {exp:stash:get name="foo" default="bar"} Get a variable into a block {exp:stash:block name="foo"} Where are you two from, nose city? {/exp:stash:block} Ge
8. {!-- set a variable --} {exp:stash:set name="url_title"}brian{/exp:stash:set} {!-- pass the variable to a tag as a parameter... --} {exp:channel:entries url_title="{exp:stash:get name='url_title'}" channel="people" parse="inward"} {/exp:channel:entries} {!-- ...or, replace the variable into a tag --} {exp:stash:parse} {exp:channel:entries url_title="{stash:url_title}"} channel="people" {/exp:channel:entries} {/exp:stash:parse}
9. Determines which session array a variable is stored in. type="variable" (default) The native Stash array. Can be ouput with placeholder {stash:my_var} inside Stash embeds & Stash tags. type="snippet" An EE snippet. Like other snippets, access as {my_var} inside EE embeds and use in advanced conditionals. Variabl t
10. Advance Conditional
11. {!-- Set a native stash variable --} {exp:stash:set name="person"}Brian{/exp:stash:set} {!-- Comparison - watch out for quotes! --} {if "{exp:stash:get name='person'}" == "Brian"} You silly sods! {/if} {!-- Is the variable empty? --} {if "{exp:stash:not_empty name='person'}"} He's not the Messiah. He's a very naughty boy! {/if} {!-- Switchee has native support --} {exp:switchee variable="stash:person" parse="inward"} {case value="Brian"} Blessed are the cheesemakers. {/case} {/exp:switchee}
12. {!-- Set a snippet variable --} {exp:stash:set name="person" type="snippet"} Brian{/exp:stash:set} {!-- Comparison --} {if person == "Brian"} You silly sods! {/if} {!-- Is the variable empty? --} {if person} He's not the Messiah. He's a very naughty boy! {/if} {!-- in an embed or inside {exp:stash:parse} --} {if person == "Brian"} I'm {person}, and so's my wife! {/if}
13. Wha i th cont ?
14. Provides a 'namespace' for related variables. Contexts may be environmental (a URI segment or entry_id), arbitrary ('my_context'), or an @ pointer: context="@URI" Points to the full URI of the current page. context="@" Points to the current static context set by the {exp:stash:context name="my_context"} tag. Cont
15. {!-- {cf_dept} is the department the person works in --} {exp:channel:entries channel="staff"} {exp:stash:append name="staff" context="{cf_dept}"} {cf_first_name} {cf_last_name}, {/exp:stash:append} {/exp:channel:entries} {!-- get staff members in the 'dogsbody' dept --} {exp:stash:get name="staff" context="dogsbody"} {!-- context is just a prefix. Same output: --} {exp:stash:get name="dogsbody:staff"} {!-- use @ pointers to make your code DRY --} {exp:stash:context name="dogsbody"} {exp:stash:get name="@:staff"}
16. Di yo sa pars order?
17. {exp:channel:entries channel="{segment_1}"} {exp:stash:set name="content"} {exp:word_limit total="4"} {cf_content} {/exp:word_limit} {/exp:stash:set} {/exp:channel:entries} {!-- why doesn't this work? --} {exp:stash:get name="content" default="if you can see this, it's not working!"}
18. Parsed from template root inwards Outermost layer of tags are parsed, top to bottom Nested tags are exposed Repeated passes made until all layers are parsed Modul ta pars order
19. Look inside tagdata for immediate descendents If a module tag is found, parse it first If a plugin tag is found, check for descendents... Results in parse order from innermost outwards Parse="inward" makes plugin behave like a module Plugi ta pars order
20. {exp:channel:entries channel="{segment_1}"} {exp:stash:set name="content"} {exp:word_limit total="4"} {cf_content} {/exp:word_limit} {/exp:stash:set} {/exp:channel:entries} {!-- this is parsed before the variable is set --} {exp:stash:get name="content" default="if you can see this, it's not working!"} 1 1 2 3
21. {exp:channel:entries channel="{segment_1}"} {exp:stash:set name="content"} {exp:word_limit total="4"} {cf_content} {/exp:word_limit} {/exp:stash:set} {/exp:channel:entries} {!-- this is parsed before the variable is set --} {exp:stash:get name="content" default="if you can see this, it's not working!"} 1 1
22. {exp:stash:set name="content"} {exp:word_limit total="4"} He's not the messiah, he's a very naughty boy! {/exp:word_limit} {/exp:stash:set} {!-- this is parsed before the variable is set --} if you can see this, it's not working! 2
23. if you can see this, it's not working!
24. Stash: process="start" (embeds only) Snippets, config, segment, date and embed vars Simple conditionals PHP on input Preload replace vars {exp:tag}tag vars{/exp:tags} (Stash: process="inline") PHP on output Advanced conditionals Embeds (recursive) Stash: process="end" Redirect, user defined & standard globals Templat pars order 1 2 3 4 5 6 7 8 9
25. {exp:channel:entries channel="{segment_1}"} {exp:stash:set name="content"} {exp:word_limit total="4"} {cf_content} {/exp:word_limit} {/exp:stash:set} {/exp:channel:entries} {!-- if this doesn't work, the kitten gets it --} {exp:stash:get name="content" default="if you can see this, it's not working!" process="end"}
26. {exp:word_limit total="4"} He's not the messiah, he's a very naughty boy! {/exp:word_limit}
27. Stash: process="start" (embeds only) Snippets, config, segment, date and embed vars Stash vars, Stash embed vars Simple conditionals {exp:tag}tag vars{/exp:tags} Advanced conditionals Stash: process="end" Stas pars order 1 2 3 4 5 6 7
28. {exp:channel:entries channel="{segment_1}"} {exp:stash:set name="content" parse_tags="yes"} {exp:word_limit total="20"} {cf_content} {/exp:word_limit} {/exp:stash:set} {/exp:channel:entries} {!-- by jove, it works! Unbag the kittens! --} {exp:stash:get name="content" default="if you can see this, it's not working!" process="end"}
29. He's not the messiah
30. parse_depth="X" (1) How many layers of the onion to peel off. parse_tags="yes|no" (no) Parse {exp:tags} recursively. parse_vars="yes|no" (no) Parse stash and other global variables recursively. parse_conditionals="yes|no" (no) Parse simple and advanced conditionals. Tunin th Stas parser
31. Cache variable
32. save="yes|no" ("no") Cache a variable. replace="yes|no" ("yes") Regenerate the cached variable if it already exists? refresh="X" (1440) Number of minutes to cache the variable until it expires. {stash:nocache}Don't cache me{/stash:nocache} Region remains unparsed until it is retrieved. Cachin option
33. Determines the visibility of saved variables. scope="local" (default) Exists in memory. Expires once the page has rendered. scope="site" Globally visible to all. Set once until expires or replaced. scope="user" Linked to the user's session ID, only visible to that user. Expires when the user’s browser session ends. Scop
34. {!-- cache the footer nav for a day --} {exp:stash:set name="footer" scope="site" save="yes" refresh="1440" replace="no" parse_tags="yes"} {exp:taxonomy:nav tree_id="4" display_root="no" style="linear" depth="1"} <li><a href="{node_url}">{node_title}</a></li> {/exp:taxonomy:nav} {/exp:stash:set}
35. <form method="post"> <label>Adjust contrast</label> <select name="contrast"> <option value="s">Standard</option> <option value="hc">High contrast</option> </select> </form> {!-- save the form value for the user's session --} {exp:stash:get name="contrast" scope="user" save="yes" match="#^s$|^hc$#" default="s" dynamic="yes"}
36. List
37. Structured data that can be cached and re-used to improve template performance. Sort, randomise, paginate, fractionalise and filter with regular expressions, in ways that go far beyond what is possible with standard tag pairs such as channel entries. Nested lists allow you to capture multi-dimensional arrays, such as a Playa tag nested within a Matrix. List
38. 1 dimensio Name: Brian Cohen Age: 32 2 dimension 1 Name: Brian Cohen Age: 32 Job: Not the Messiah 1 Name: Mr Creosote Age: 62 Job: Gluttony 2 Name: Norwegian Blue Age: 20 Job: Parrot (deceased) 3 Job: Not the Messiah
39. Set a one-dimensional list of key-value pairs {exp:stash:set_list name="characters"} {stash:name}Mr Creosote{/stash:name} {stash:job}Gluttony{/stash:job} {/exp:stash:set_list} Append / prepend a row to create a two-dimensional list {exp:stash:append_list name="characters"} {stash:name}Norwegian Blue{/stash:name} {stash:job}Parrot (deceased){/stash:job} {/exp:stash:append_list} Se on dimensiona lis
40. Capturing a 2D list with append {exp:channel:entries channel="characters"} {exp:stash:append_list name="characters"} {stash:name}{cf_name}{/stash:name} {/exp:stash:append_list} {/exp:channel:entries} Parsing wrapped tags, then capturing a 2D list {exp:stash:set_list name="characters" parse_tags="yes"} {exp:channel:entries channel="characters"} {stash:name}{cf_name}{/stash:name} {/exp:channel:entries} {/exp:stash:set_list} Se tw dimensiona lis 1 1 2 2
41. Output a 1 or 2 dimensional list {exp:stash:get_list name="characters"} <div class="{switch='one|two'}"> <h1>Character {count}: {name}</h1> <p>Job: {job}</p> <p>{absolute_count} of {absolute_results}</p> </div> {if no_results} {redirect="site/404"} {/if} {/exp:stash:get_list} Ge lis
42. Order/sort {exp:stash:get_list name="characters" orderby="age" sort="asc" sort_type="string"} {name} - {job} {/exp:stash:get_list} Randomize specific columns {exp:stash:get_list name="characters" orderby="random:name,job"} {name} - {job} {/exp:stash:get_list} Sortin
43. Fraction {exp:stash:get_list name="characters" limit="1/3"} <li>{name}</li> {/exp:stash:get_list} {exp:stash:get_list name="characters" limit="1/3" offset="1/3"} <li>{name}</li> {/exp:stash:get_list} {exp:stash:get_list name="characters" offset="2/3"} <li>{name}</li> {/exp:stash:get_list}
44. 3+ dimension Name: Brian Cohen 31:items 32:items Age: 32 Unique ID: 31 1 Name: Mr Creosote Age: 62 Unique ID: 32 2 Object: Gourd Used for: Holy water Value: Half a dinare 1 Item: Stone Used for: Heretics Value : About one stone 2 Object: Wafer-thin mint Used for: Scoffing Value: Complimentary 1 Object: Chocolate frog Used for: Eating Value : 1 million pounds 2 Job: Not the Messiah Job: Gluttony
45. {exp:stash:set_list name="characters" parse_tags="yes" parse_depth="2"} {exp:channel:entries channel="characters" limit="2"} {stash:name}{title}{/stash:name} {stash:entry_id}{entry_id}{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="{entry_id}"} {cf_items} {stash:item}{title}{/stash:item} {/cf_items} {/exp:stash:set_list:nested} {/exp:channel:entries} {/exp:stash:set_list}
46. {exp:stash:set_list name="characters" parse_tags="yes" parse_depth="2"} {exp:channel:entries channel="characters" limit="2"} {stash:name}{title}{/stash:name} {stash:entry_id}{entry_id}{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="{entry_id}"} {cf_items} {stash:item}{title}{/stash:item} {/cf_items} {/exp:stash:set_list:nested} {/exp:channel:entries} {/exp:stash:set_list} 1 2 3 4
47. {exp:stash:set_list name="characters" parse_tags="yes" parse_depth="2"} {exp:channel:entries channel="characters" limit="2"} {stash:name}{title}{/stash:name} {stash:entry_id}{entry_id}{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="{entry_id}"} {cf_items} {stash:item}{title}{/stash:item} {/cf_items} {/exp:stash:set_list:nested} {/exp:channel:entries} {/exp:stash:set_list} 1
48. {exp:stash:set_list name="characters" parse_tags="yes" parse_depth="2"} {stash:name}Brian Cohen{/stash:name} {stash:entry_id}1{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="1"} {exp:playa:children entry_id="1" field="cf_items"} {stash:item}{title}{/stash:item} {/exp:playa:children} {/exp:stash:set_list:nested} {stash:name}Mr Creosote{/stash:name} {stash:entry_id}2{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="2"} {exp:playa:children entry_id="2" field="cf_items"} {stash:item}{title}{/stash:item} {/exp:playa:children} {/exp:stash:set_list:nested} {/exp:stash:set_list} 2 2
49. {exp:stash:set_list name="characters" parse_tags="yes" parse_depth="2"} {stash:name}Brian Cohen{/stash:name} {stash:entry_id}1{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="1"} {stash:item}Gourd{/stash:item} {stash:item}Stone{/stash:item} {/exp:stash:set_list:nested} {stash:name}Mr Creosote{/stash:name} {stash:entry_id}2{/stash:entry_id} {exp:stash:set_list:nested name="items" parse_tags="yes" context="2"} {stash:item}Wafer thin mint{/stash:item} {stash:item}Chocolate frog{/stash:item} {/exp:stash:set_list:nested} {/exp:stash:set_list} 3 3
50. {exp:stash:set_list name="characters" parse_tags="yes" parse_depth="2"} {stash:name}Brian Cohen{/stash:name} {stash:entry_id}1{/stash:entry_id} {stash:name}Mr Creosote{/stash:name} {stash:entry_id}2{/stash:entry_id} {/exp:stash:set_list} 4
51. {!-- Get the list of entries --} {exp:stash:get_list name="characters"} <h1>{count}: {name}</h1> <ul> {!-- Get the related entries list for each row --} {exp:stash:get_list:nested name="items" context="{entry_id}" prefix="related"} <li>{related:count} : {item}</li> {/exp:stash:get_list:nested} </ul> {/exp:stash:get_list}
52. {!-- Get the list of entries --} {exp:stash:get_list name="characters"} <h1>{count}: {name}</h1> <ul> {!-- Get the related entries list for each row --} {exp:stash:get_list:nested name="items" context="{entry_id}" prefix="related"} <li>{related:count} : {item}</li> {/exp:stash:get_list:nested} </ul> {/exp:stash:get_list} 2 1
53. lterin list
54. {-- Filter a list by a regular expression --} {exp:stash:get_list name="people" match="#^A#" against="last_name"} {last_name}, {first_name} {/exp:stash:get_list} {!-- NOT matching a pattern (negative lookahead) --} {exp:stash:get_list name="people" match="#^(?!(A|B|C)).*#" against="last_name"} {last_name}, {first_name} {/exp:stash:get_list} {!-- Unique list rows --} {exp:stash:get_list name="people" unique="yes"} {last_name}, {first_name} {/exp:stash:get_list}
55. 100 Brian Litzinger 9.8 Anna Brown 10.1 John D. Wells 10.6 Lodewijk Schutte 11.1 Eric Lamb 12.8 Runner Time Mrs Flinger 19.1 Eric Lamb 19.3 Justin Kimbrell 20.6 Carl W Crawley 21.1 Erik Reagan 22.2 Runner Time Brandon Kelly 43.2 Steven Grant 43.7 Jack McDade 44.6 Paulo Elias 46.8 Adrian Macneil 47.2 Runner Time m 400m Adrienne L. Travis 1:40.9 Iain Urquhart 1:41.5 Nicholas Bottari 1:42.4 Rob Sanchez 1:45.8 Ryan Masuga 5:25.5 Runner Time 800m 200m
56. {!-- for a given event, capture and cache related race data --} {exp:stash:set_list name="race_data" parse_tags="yes" parse_depth="2" save="yes" scope="site" replace="no"} {exp:playa:parents entry_id="{segment_3}" field="cf_race"} {stash:runner}{cf_runner}{/stash:runner} {stash:distance}{cf_distance}{/stash:distance} {stash:time}{cf_time}{/stash:time} {/exp:playa:parents} {/exp:stash:set_list} {!-- our list looks something like this --} 1 runner: Brian Litzinger distance: 100 time: 9.8 2 runner: Mrs Flinger distance: 200 time: 19.1 3 runner: Eric Lamb distance: 100 time: 12.8
57. {!-- get a list of the unique race distances, e.g. 100m, 200m, 400m --} {exp:stash:get_list name="race_data" scope="site" unique="distance"} <table> <caption>Results for {distance}</caption> <tr> <th>Runner</th> <th>Time</th> </tr> {!-- for each unique distance show runners and their time in order --} {exp:stash:get_list:nested name="race_data" scope="site" prefix="result" orderby="time" match="#^{distance}$#" against="distance"} <tr> <td>{result:runner}</td> <td>{result:time}</td> </tr> {/exp:stash:get_list:nested} </table> {/exp:stash:get_list}
58. Summar
59. Take time to understand parse order. It’s essential to using Stash effectively. Set, get, append and prepend template variables; pass to tags, use in conditionals. Use scope to determine variable visibility, context and @pointers to namespace and re-use variables. Subvert parse order with post-processing & Stash parsing. Capture multi-dimensional lists from looping tag pairs and use nesting and filtering to group and multi-sort your data. Cache variables and lists to speed up your templates. Summar
60. http ://github.co /cr to /Stas /wik