ExpressionEngine Stash tutorials

Published and filed under ExpressionEngine

Published and filed under ExpressionEngine

Mark Croxton’s Stash add-on for ExpressionEngine is a powerful, flexible tool that can improve your ExpressionEngine templating. Due to its vast array of capabilities and multiple ways of achieving the same thing, it has also been met with confusion by many in the community and a reluctance to incorporate it into their workflows.

Level 1

“Variable?
What’s a variable?”

Stash is not an all-or-nothing tool: if your site is small and simple just make use of the basic Stash techniques and leave the rest.

  • Why bother?
  • Setting and getting variables
  • Practical uses without changing your approach
  • Moving data around in a single template

Can I Play Daddy? »

Level 2

“Croxton’s my
middle name”

For increased flexibility and easier maintenance, take Stash to the next level with a strict separation of content and presentation. Your future self will thank you…

  • Why bother?
  • Separation of concerns
  • Template partials
  • Caching mechanisms

They Call Me ‘The Cleaner’ »

Level 3

“I am
Croxton incarnate”

For superDRY, high performing advanced templates with full separation of concerns, push your Stash knowledge to level 3.

  • Why bother?
  • Stash Embeds
  • Context
  • Bundles
  • Stash utilities

Coming Soon!

Overview

This series of articles attempts to demystify Stash and get you using it at whatever level you feel comfortable by gradually introducing the concepts and building on top of them, whilst focusing on the reasoning behind using or avoiding various techniques in given situations.

I won’t dwell on the technical implementations of Stash techniques and syntax — there are already plenty of other articles that explain those details, as well as the Stash documentation itself. Instead, the focus here is on why you might want to consider using these new approaches (and also why not!).

Before getting to grips with Stash, it’s useful to be at least vaguely aware of 4 important facets of ExpressionEngine templating that you won’t see mentioned in the official documentation and most of which are usually overlooked by new ExpressionEngine users:

  1. The {exp:channel:entries} tag is expensive. Every time you use it you cause a large and slow set of database queries to run.
  2. The {embed} tag is expensive. Every time you use it, ExpressionEngine initialises and executes its complex template parsing engine.
  3. “Advanced conditionals” – for example those that use AND/OR or {if:else} or {if:elseif} can cause huge and hidden inefficiencies in your templates.
  4. The ExpressionEngine template engine is designed to fetch and output data in the same breath: wherever you place your tags, that’s where your content is output.

That last point seems obvious but is really important and goes to the crux of Stash’s popularity: by tightly coupling the data-fetching to the data-output, you now have no choice but to clumsily fetch the same data from the database whenever you want to output it. With Stash, you typically break apart these two aspects for unlimited control.

Setting and Getting Variables

The core functionality of Stash is to set and get variables — If you only ever use that functionality and ignore everything else Stash has to offer, you’ve already made progress.

Any variables you set in one template will be available to all embedded templates (regardless of where the embed tag is placed in your code), or later in the parsing order of the same template.

Fully understanding parse order is beyond the scope of these articles, but as you progress with Stash you’ll become acutely aware of this complication and how to deal with it consistently, and even avoid the problem entirely.

Quick history lesson

The techniques I’ll be outlining in this series are neither new nor specific to ExpressionEngine, and it’s important to say that Stash was not the first add-on to make them feasible in ExpressionEngine.

During the EE 1.x days, early adopters first started doing this with LG Replace, though it soon became clear that although you could do this perfectly well, Leevi had not really built LG Replace with this technique in mind. Soon after that came String, by eMarketSouth. String was (and still is) a fantastic little add-on (weighing in at about 100 lines of code!), you could do everything you needed to get started with these techniques. MX Jumper by Max Lazar appeared soon after and rose in popularity due to being a free alternative to String. It basically did exactly the same job in exactly the same way. At about the same time came NSM Transplant – the natural evolution of LG Replace – which refined that add-on further.

Finally, Stash came along and swept its predecessors away with a vast array of features for setting, getting and manipulating variables in just about any way imaginable.

John D Wells also highlighted the benefits of these kinds of approaches with his 2011 article, showing that the core concept is simple enough to build your own add-on to do the core of what Stash does. (I believe Croxton himself attributes John’s article as the inspiration for Stash).

Try not to be put off by the depth and the complexity of the manual. Just start with the basics and move on to the intermediate setup when you’re comfortable. If you’re dealing with a large and/or complex site, consider using some of the techniques in the advanced approach (coming soon).