mirror of
https://github.com/Shopify/liquid.git
synced 2026-09-17 01:40:42 -07:00
Moving to single collection
This commit is contained in:
Adam Hollett
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Handles
|
||||
---
|
||||
|
||||
A handle is used to access the attributes of a Liquid object. By default, the handle is the object's title in lowercase with any spaces and special characters replaced by hyphens (-).
|
||||
|
||||
For example, a page with the title "About Us" can be accessed in Liquid via its handle `about-us` as shown below:
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
<!-- the content of the About Us page -->
|
||||
{{ pages.about-us.content }}
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
### Creating handles
|
||||
|
||||
An object with the title "Shirt" will automatically be given the handle `shirt`. If there is already an object with the handle `shirt`, the handle will auto-increment. In other words, "Shirt" objects created after the first one will receive the handle `shirt-1`, `shirt-2`, and so on.
|
||||
|
||||
Whitespace in titles is replaced by hyphens in handles. For example, the title "My Shiny New Title" will be given the handle `my-shiny-new-title`.
|
||||
|
||||
Handles also determine the URL of their corresponding objects. For example, a page with the handle `about-us` would have the url `/pages/about-us`.
|
||||
|
||||
Websites often rely on static handles for pages, posts, or objects. To preserve design elements and avoid broken links, if you modify the title of an object, **its handle is not automatically updated**. For example, if you were to change a page title from "About Us" to "About This Website", its handle would still be `about-us`.
|
||||
|
||||
You can change an object's handle manually (TK how to change a handle manually)
|
||||
|
||||
### Accessing handle attributes
|
||||
|
||||
In many cases you may know the handle of a object whose attributes you want to access. You can access its attributes by pluralizing the name of the object, then using either the square bracket ( [ ] ) or dot ( . ) notation.
|
||||
|
||||
<p class="input">Input</p>
|
||||
<div>
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
{{ pages.about-us.title }}
|
||||
{{ pages["about-us"].title }}
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<p class="output">Output</p>
|
||||
<div>
|
||||
{% highlight text %}
|
||||
About Us
|
||||
About Us
|
||||
{% endhighlight %}
|
||||
</div>
|
||||
|
||||
In the example above, notice that we are using `pages` as opposed to `page`.
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Operators
|
||||
---
|
||||
|
||||
Liquid includes many logical and comparison operators.
|
||||
|
||||
### Basic Operators
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><pre>==</pre></td>
|
||||
<td>equals</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre>!=</pre></td>
|
||||
<td>does not equal</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre>></pre></td>
|
||||
<td>greater than</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre><</pre></td>
|
||||
<td>less than</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre>>=</pre></td>
|
||||
<td>greater than or equal to</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre><=</pre></td>
|
||||
<td>less than or equal to</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre>or</pre></td>
|
||||
<td>logical or</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre>and</pre></td>
|
||||
<td>logical and</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
For example:
|
||||
|
||||
<div>
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% if product.title == "Awesome Shoes" %}
|
||||
These shoes are awesome!
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
You can use multiple operators in a tag:
|
||||
|
||||
<div>
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% if product.type == "Shirt" or product.type == "Shoes" %}
|
||||
This is a shirt or a pair of shoes.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
### contains
|
||||
|
||||
`contains` checks for the presence of a substring inside a string.
|
||||
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% if product.title contains 'Pack' %}
|
||||
This product's title contains the word Pack.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
`contains` can also check for the presence of a string in an array of strings.
|
||||
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% if product.tags contains 'Hello' %}
|
||||
This product has been tagged with 'Hello'.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
`contains` is can only search strings. You cannot use it to check for an object in an array of objects.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Truthy and Falsy
|
||||
---
|
||||
|
||||
In programming, anything that returns `true` in a conditional is called **truthy**. Anything that returns `false` in a conditional is called **falsy**. All object types can be described as either truthy or falsy.
|
||||
|
||||
## Truthy
|
||||
|
||||
All values in Liquid are truthy except `nil` and `false`.
|
||||
|
||||
In the example below, the text "Tobi" is not a boolean, but it is truthy in a conditional:
|
||||
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% assign tobi = 'Tobi' %}
|
||||
|
||||
{% if tobi == true %}
|
||||
This condition will always be true.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
[Strings](/basics/types/#string), even when empty, are truthy. The example below will result in empty HTML tags if `settings.fp_heading` is empty:
|
||||
|
||||
<p class="input">Input</p>
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% if settings.fp_heading %}
|
||||
<h1>{{ settings.fp_heading }}</h1>
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
<p class="output">Output</p>
|
||||
{% highlight html %}{% raw %}
|
||||
<h1></h1>
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
[EmptyDrops](/basics/types/#emptydrop) are also truthy. In the example below, if `settings.page` is an empty string or set to a hidden or deleted object, you will end up with an EmptyDrop. The result is an empty `<div>`:
|
||||
|
||||
<p class="input">Input</p>
|
||||
{% highlight html %}{% raw %}
|
||||
{% if pages[settings.page] %}
|
||||
<div>{{ pages[settings.page].content }}</div>
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
<p class="output">Output</p>
|
||||
{% highlight html %}{% raw %}
|
||||
<div></div>
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
## Falsy
|
||||
|
||||
The falsy values in Liquid are [nil](/basics/types/#nil) and [false](/basics/types/#boolean).
|
||||
|
||||
## Summary
|
||||
|
||||
The table below summarizes what is truthy or falsy in Liquid.
|
||||
|
||||
| | truthy | falsy |
|
||||
| ------------- |:-------------:|:-------------:|
|
||||
| true | • | |
|
||||
| false | | • |
|
||||
| nil | | • |
|
||||
| string | • | |
|
||||
| empty string | • | |
|
||||
| 0 | • | |
|
||||
| integer | • | |
|
||||
| float | • | |
|
||||
| array | • | |
|
||||
| empty array | • | |
|
||||
| page | • | |
|
||||
| EmptyDrop | • | |
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Types
|
||||
---
|
||||
|
||||
Liquid objects can have one of six types:
|
||||
|
||||
- [string](#string)
|
||||
- [number](#number)
|
||||
- [boolean](#boolean)
|
||||
- [nil](#nil)
|
||||
- [array](#array)
|
||||
- [EmptyDrop](#emptydrop)
|
||||
|
||||
Liquid variables can be initialized by using the [assign](/tags/#assign) or [capture](/tags/#capture) tags.
|
||||
|
||||
## String
|
||||
|
||||
Strings are declared by wrapping a variable's value in single or double quotes.
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
{% assign my_string = "Hello World!" %}
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
## Number
|
||||
|
||||
Numbers include floats and integers.
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
{% assign my_int = 25 %}
|
||||
{% assign my_float = 39.756 %}
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
## Boolean
|
||||
|
||||
Booleans are either `true` or `false`. No quotations are necessary when declaring a boolean.
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
{% assign foo = true %}
|
||||
{% assign bar = false %}
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
## Nil
|
||||
|
||||
Nil is a special empty value that is returned when Liquid code has no results. It is **not** a string with the characters "nil".
|
||||
|
||||
Nil is treated as false in the conditions of `if` blocks and other Liquid tags that check the truthfulness of a statement.
|
||||
|
||||
In the following example, if the user does not exist (that is, `user` returns `nil`), Liquid will not print the greeting:
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
{% if user %}
|
||||
Hello {{ user.name }}!
|
||||
{% endif %}
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
Tags or outputs that return `nil` will not print anything to the page.
|
||||
|
||||
<p class="input">Input</p>
|
||||
|
||||
{% highlight liquid %}{% raw %}
|
||||
The current user is {{ user.name }}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
<p class="output">Output</p>
|
||||
|
||||
{% highlight text %}{% raw %}
|
||||
The current user is
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
## Array
|
||||
|
||||
Arrays hold lists of variables of any type.
|
||||
|
||||
#### Accessing items in arrays
|
||||
|
||||
To access all of the items in an array, you can loop through each item in the array using a [for](/tags/#for) or [tablerow](/tags/#tablerow) tag.
|
||||
|
||||
<p class="input">Input</p>
|
||||
{% highlight liquid %}{% raw %}
|
||||
<!-- if site.users = "Tobi", "Lina", "Tetsuro", "Adam" -->
|
||||
{% for user in site.users %}
|
||||
{{ user }}
|
||||
{% endfor %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
<p class="output">Output</p>
|
||||
{% highlight text %}{% raw %}
|
||||
Tobi Lina Tetsuro Adam
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
|
||||
#### Accessing specific items in arrays
|
||||
|
||||
You can use square bracket `[ ]` notation to access a specific item in an array. Array indexing starts at zero.
|
||||
|
||||
<p class="input">Input</p>
|
||||
{% highlight liquid %}{% raw %}
|
||||
<!-- if site.users = "Tobi", "Lina", "Tetsuro", "Adam" -->
|
||||
{{ site.users[0] }}
|
||||
{{ site.users[1] }}
|
||||
{{ site.users[3] }}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
<p class="output">Output</p>
|
||||
{% highlight text %}{% raw %}
|
||||
Tobi
|
||||
Lina
|
||||
Adam
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
#### Initializing arrays
|
||||
|
||||
You cannot initialize arrays using pure Liquid.
|
||||
|
||||
You can, however, use the [split](/filters/#split) filter to break a single string into an array of substrings.
|
||||
|
||||
## EmptyDrop
|
||||
|
||||
An EmptyDrop object is returned if you try to access a deleted object (such as a page or post) by its [handle](/basics/#Handles). In the example below, `page_1`, `page_2` and `page_3` are all EmptyDrop objects.
|
||||
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% assign variable = "hello" %}
|
||||
{% assign page_1 = pages[variable] %}
|
||||
{% assign page_2 = pages["does-not-exist"] %}
|
||||
{% assign page_3 = pages.this-handle-does-not-exist %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
EmptyDrop objects only have one attribute, `empty?`, which is always *true*.
|
||||
|
||||
Collections and pages that *do* exist do not have an `empty?` attribute. Their `empty?` is “falsy”, which means that calling it inside an if statement will return *false*. When using an unless statement on existing collections and pages, `empty?` will return `true`.
|
||||
|
||||
#### Checking for emptiness
|
||||
|
||||
Using the `empty?` attribute, you can check to see if an object exists or not before you access any of its attributes.
|
||||
|
||||
{% highlight liquid %}{% raw %}
|
||||
{% unless pages.about.empty? %}
|
||||
<!-- This content will only print if the page with handle 'about' is not empty -->
|
||||
<h1>{{ pages.frontpage.title }}</h1>
|
||||
<div>{{ pages.frontpage.content }}</div>
|
||||
{% endunless %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
If you don't check for emptiness first, Liquid may print empty HTML elements to the page:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
<h1></h1>
|
||||
<div></div>
|
||||
{% endraw %}{% endhighlight %}
|
||||
Reference in New Issue
Block a user