Labyricorn/liquid
1
0
Fork 0
mirror of https://github.com/Shopify/liquid.git synced 2026-09-16 17:30:43 -07:00
Code Issues Packages Projects Releases Wiki Activity

Revert "Docs Update"

Browse Source
This commit is contained in:
tetchi
2016-03-18 16:18:35 -04:00
parent 6bc76a92ea
commit 70ddccd88f
82 changed files with 278 additions and 3067 deletions
Download Patch File Download Diff File Expand all files Collapse all files
basics/_handles.md
-48
View File
@@ -1,48 +0,0 @@
---
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.
<div class="code-block code-block--input">
{% highlight liquid %}
{% raw %}
{{ pages.about-us.title }}
{{ pages["about-us"].title }}
{% endraw %}
{% endhighlight %}
</div>
<div class="code-block code-block--output">
{% highlight text %}
About Us
About Us
{% endhighlight %}
</div>
In the example above, notice that we are using `pages` as opposed to `page`.
basics/index.html
-4
View File
@@ -1,4 +0,0 @@
---
layout: default
---
basics/introduction.md
-64
View File
@@ -1,64 +0,0 @@
---
title: Introduction
---
Liquid code can be categorized into [**objects**](#objects), [**tags**](#tags), and [**filters**](#filters).
## Objects
**Objects** tell Liquid where to show content on a page. Objects and variable names are denoted by double curly braces: `{% raw %}{{{% endraw %}` and `{% raw %}}}{% endraw %}`.
```liquid
{% raw %}
{{ page.title }}
{% endraw %}
```
```text
Introduction
```
In this case, Liquid is rendering the content of an object called `page.title`, and that object contains the text `Introduction`.
## Tags
**Tags** create the logic and control flow for templates. They are denoted by curly braces and percent signs: `{% raw %}{%{% endraw %}` and `{% raw %}%}{% endraw %}`.
The markup used in tags does not produce any visible text. This means that you can assign variables and create conditions and loops without showing any of the Liquid logic on the page.
```liquid
{% raw %}
{% if user %}
Hello {{ user.name }}!
{% endif %}
{% endraw %}
```
```text
Hello Adam!
```
Tags can be categorized into three types:
- [Control flow](/tags/control-flow)
- [Iteration](/tags/iteration)
- [Variable assignments](/tags/variable)
You can read more about each type of tag in their respective sections.
## Filters
**Filters** change the output of a Liquid object. They are using within an output and are separated by a `|`.
```liquid
{% raw %}
{{ "/my/fancy/url" | append: ".html" }}
{% endraw %}
```
```text
{{ "/my/fancy/url" | append: ".html" }}
```
basics/operators.md
-88
View File
@@ -1,88 +0,0 @@
---
title: Operators
---
Liquid includes many logical and comparison operators.
## Basic operators
<table>
<tbody>
<tr>
<td><code>==</code></td>
<td>equals</td>
</tr>
<tr>
<td><code>!=</code></td>
<td>does not equal</td>
</tr>
<tr>
<td><code>&gt;</code></td>
<td>greater than</td>
</tr>
<tr>
<td><code>&lt;</code></td>
<td>less than</td>
</tr>
<tr>
<td><code>&gt;=</code></td>
<td>greater than or equal to</td>
</tr>
<tr>
<td><code>&lt;=</code></td>
<td>less than or equal to</td>
</tr>
<tr>
<td><code>or</code></td>
<td>logical or</td>
</tr>
<tr>
<td><code>and</code></td>
<td>logical and</td>
</tr>
</tbody>
</table>
For example:
```liquid
{% raw %}
{% if product.title == "Awesome Shoes" %}
These shoes are awesome!
{% endif %}
{% endraw %}
```
You can use multiple operators in a tag:
```liquid
{% raw %}
{% if product.type == "Shirt" or product.type == "Shoes" %}
This is a shirt or a pair of shoes.
{% endif %}
{% endraw %}
```
## contains
`contains` checks for the presence of a substring inside a string.
```liquid
{% raw %}
{% if product.title contains 'Pack' %}
This product's title contains the word Pack.
{% endif %}
{% endraw %}
```
`contains` can also check for the presence of a string in an array of strings.
```liquid
{% raw %}
{% if product.tags contains 'Hello' %}
This product has been tagged with 'Hello'.
{% endif %}
{% endraw %}
```
`contains` can only search strings. You cannot use it to check for an object in an array of objects.
basics/truthy-and-falsy.md
-76
View File
@@ -1,76 +0,0 @@
---
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](#truthy)
- [Falsy](#falsy)
- [Summary](#summary)
## Truthy
All values in Liquid are truthy except `nil` and `false`.
In the example below, the string "Tobi" is not a boolean, but it is truthy in a conditional:
```liquid
{% raw %}
{% assign tobi = "Tobi" %}
{% if tobi == true %}
This condition will always be true.
{% endif %}
{% endraw %}
```
[Strings](/basics/types/#string), even when empty, are truthy. The example below will result in empty HTML tags if `settings.fp_heading` is empty:
```liquid
{% raw %}
{% if settings.fp_heading %}
<h1>{{ settings.fp_heading }}</h1>
{% endif %}
{% endraw %}
```
```html
<h1></h1>
```
[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`:
```liquid
{% raw %}
{% if pages[settings.page] %}
<div>{{ pages[settings.page].content }}</div>
{% endif %}
{% endraw %}
```
```html
<div></div>
```
## 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 | • | |
basics/types.md
-160
View File
@@ -1,160 +0,0 @@
---
title: Types
---
Liquid objects can have one of six types:
- [String](#string)
- [Number](#number)
- [Boolean](#boolean)
- [Nil](#nil)
- [Array](#array)
- [EmptyDrop](#emptydrop)
You can initialize Liquid variables with the [assign](/tags/#assign) or [capture](/tags/#capture) tags.
## String
Declare a string by wrapping a variable's value in single or double quotes:
```liquid
{% raw %}
{% assign my_string = "Hello World!" %}
{% endraw %}
```
## Number
Numbers include floats and integers:
```liquid
{% raw %}
{% assign my_int = 25 %}
{% assign my_float = 39.756 %}
{% endraw %}
```
## Boolean
Booleans are either `true` or `false`. No quotations are necessary when declaring a boolean:
```liquid
{% raw %}
{% assign foo = true %}
{% assign bar = false %}
{% endraw %}
```
## 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](/basics/truthy-and-falsy) 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:
```liquid
{% raw %}
{% if user %}
Hello {{ user.name }}!
{% endif %}
{% endraw %}
```
Tags or outputs that return `nil` will not print anything to the page.
```liquid
{% raw %}
The current user is {{ user.name }}
{% endraw %}
```
```text
The current user is
```
## Array
Arrays hold lists of variables of any type.
### Accessing items in arrays
To access all the items in an array, you can loop through each item in the array using an [iteration tag](/tags/iteration/).
```liquid
{% raw %}
<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{% for user in site.users %}
{{ user }}
{% endfor %}
{% endraw %}
```
```text
{% raw %}
Tobi Laura Tetsuro Adam
{% endraw %}
```
### Accessing specific items in arrays
You can use square bracket `[` `]` notation to access a specific item in an array. Array indexing starts at zero.
```liquid
{% raw %}
<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[3] }}
{% endraw %}
```
```text
Tobi
Laura
Adam
```
### Initializing arrays
You cannot initialize arrays using only Liquid.
You can, however, use the [split](/filters/split) filter to break a string into an array of substrings.
## EmptyDrop
An EmptyDrop object is returned if you try to access a deleted object by name. In the example below, `page_1`, `page_2` and `page_3` are all EmptyDrop objects.
```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 %}
```
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.
```liquid
{% raw %}
{% unless pages.about.empty? %}
<!-- This will only print if the page with handle 'about' is not empty -->
<h1>{{ pages.frontpage.title }}</h1>
<div>{{ pages.frontpage.content }}</div>
{% endunless %}
{% endraw %}
```
If you don't check for emptiness first, Liquid might print empty HTML elements to the page:
```html
<h1></h1>
<div></div>
```