Keys
What’s a key?
At its simplest, a key is a container for a value.
Imagine a box labeled favorite_cake. You open the box, and inside is a red velvet cake. In this analogy, the box is the key, and “Red Velvet Cake” is the value. In Liquid, it looks like this:
{{ favorite_cake}}Red Velvet CakeKeys can also contain other keys. This time, imagine a box labelled dessert. Inside it, you might find seven boxes, with labels like, pie, cake, ice_cream, and so on—all those desserts are keys inside the dessert key. Nestled inside the cake box, you would find many additional boxes with different kinds of cake, including one labeled favorite_cake. In this situation, here’s how it would look in Liquid if you want to output the value of favorite_cake:
{{ dessert.cake.favorite_cake }}Red Velvet CakeFYI, when we use keys that contain other keys, we’ll be dealing with JavaScript Object Notation (JSON). JSON is just the format used for the code; we’ll look at it in more detail in the Intermediate Keys module.
Now let’s apply this delicious metaphor to the real-life scenario from the How Liquid Works lesson: the customer who’s just ordered a dog leash from your online store, Tip Top Pets.
You’re preparing a confirmation email to go out whenever a customer makes a purchase, which will have both static (always the same) and dynamic (personalized for each individual email) content. You have the following keys, or “boxes” of information, about your client. In this example, each box of information contains other boxes of information (i.e., each key contains several other keys, like we saw in the desserts example above).
| key | key | value |
|---|---|---|
| customer | first_name | lee |
| last_name | leeson |
| key | key | value |
|---|---|---|
| pet | pet_type | dog |
| pet_name | Spot | |
| Senior |
As you can see, some keys contain a collection of keys (like the pet key), and other keys point to individual values (like the pet_name key). So if you want to output the value of the pet_name key, you have to first open the big box (the pet key), then open the little box inside (the pet_name key) to get the value (Spot) that you want to output. You can also think of it like a parent-child relationship—you reference the “parent” key to get to the “child” key.
Let’s see that in action. To include the dog’s name in your email, you must reference both pet and pet_name. Here’s our Liquid code and output:
Hope {{ pet.pet_name }} loves your purchase!Hope Spot loves your purchase!Practice problem
Ready to test your skills with a practice problem? Let’s say hi to both our customer and our doggy friend Spot in the salutation. Select the right Liquid code from the options below:
That’s not right; try again!
The right answer is A!
Now we’ll run the code and see what happens:
Hi {{ customer.first_name }} and {{ pet.pet_name }}!Hi lee and Spot !Our email is coming along! You’ve probably noticed the problems with capitalization and extra whitespace, and we’re going to fix them in the next section with a filter. But before we do, let’s talk about key notation in Liquid.
Key notation
When we say notation, we’re referring to the specific format—like punctuation and spaces—that you must use for your keys. In Liquid, keys are surrounded by double curly brackets, like this:
{{ key }}The double curly brackets cue Liquid to display the key’s value in your email. It’s common to put a space on either side of the key because it makes your code easier to read, but you can leave the spaces out without breaking anything.
If you are referencing a key that contains other keys, use dot notation—that is, include a period to separate each key, like this:
{{ pet.pet_type }}Key names must be made up of letters and numbers only, and we strongly recommend that you use an underscore instead of a space when creating key names, like this: pet_name. Why the spacebar hate? If you include spaces in key names, you must enclose the key in square brackets every time you reference it or your code will break. Here’s how that looks:
{{ pet.[pet name] }}But why give yourself more work and increase the risk of broken code? Replace those spaces and have one fewer thing to worry about!
Now you know how to use simple keys, and you understand key notation. Now let’s fix up our text with a basic filter.