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

Use collections for the sections of the site

Browse Source
This commit is contained in:
Zakary Kamal Ismail
2019-07-28 16:27:13 -04:00
parent d4159b6069
commit 061dabed98
61 changed files with 13 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_basics/introduction.md
+85
View File
@@ -0,0 +1,85 @@
---
title: Introduction
description: An overview of objects, tags, and filters in the Liquid template language.
redirect_from: /basics/
---
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 %}`.
<p class="code-label">Input</p>
```liquid
{% raw %}
{{ page.title }}
{% endraw %}
```
<p class="code-label">Output</p>
```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.
<p class="code-label">Input</p>
```liquid
{% raw %}
{% if user %}
Hello {{ user.name }}!
{% endif %}
{% endraw %}
```
<p class="code-label">Output</p>
```text
Hello Adam!
```
Tags can be categorized into three types:
- [Control flow]({{ "/tags/control-flow" | prepend: site.baseurl }})
- [Iteration]({{ "/tags/iteration" | prepend: site.baseurl }})
- [Variable assignments]({{ "/tags/variable" | prepend: site.baseurl }})
You can read more about each type of tag in their respective sections.
## Filters
**Filters** change the output of a Liquid object. They are used within an output and are separated by a `|`.
<p class="code-label">Input</p>
```liquid
{% raw %}
{{ "/my/fancy/url" | append: ".html" }}
{% endraw %}
```
<p class="code-label">Output</p>
```text
{{ "/my/fancy/url" | append: ".html" }}
```
Multiple filters can be used on one output. They are applied from left to right.
<p class="code-label">Input</p>
```liquid
{% raw %}
{{ "adam!" | capitalize | prepend: "Hello " }}
{% endraw %}
```
<p class="code-label">Output</p>
```text
Hello Adam!
```
_basics/operators.md
+89
View File
@@ -0,0 +1,89 @@
---
title: Operators
description: Using operators to perform calculations in the Liquid template language.
---
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
+65
View File
@@ -0,0 +1,65 @@
---
title: Truthy and falsy
description: An overview of boolean logic in the Liquid template language.
---
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 %}
This condition will always be true.
{% endif %}
{% endraw %}
```
[Strings]({{ "/basics/types/#string" | prepend: site.baseurl }}), even when empty, are truthy. The example below will result in empty HTML tags if `settings.fp_heading` is empty:
<p class="code-label">Input</p>
```liquid
{% raw %}
{% if settings.fp_heading %}
<h1>{{ settings.fp_heading }}</h1>
{% endif %}
{% endraw %}
```
<p class="code-label">Output</p>
```html
<h1></h1>
```
## Falsy
The falsy values in Liquid are [`nil`]({{ "/basics/types/#nil" | prepend: site.baseurl }}) and [`false`]({{ "/basics/types/#boolean" | prepend: site.baseurl }}).
## 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
+128
View File
@@ -0,0 +1,128 @@
---
title: Types
description: An overview of data types in the Liquid template language.
---
Liquid objects can have one of five types:
- [String](#string)
- [Number](#number)
- [Boolean](#boolean)
- [Nil](#nil)
- [Array](#array)
You can initialize Liquid variables with the [assign]({{ "/tags/variable/#assign" | prepend: site.baseurl }}) or [capture]({{ "/tags/variable/#capture" | prepend: site.baseurl }}) 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" | prepend: site.baseurl }}) 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.
<p class="code-label">Input</p>
```liquid
{% raw %}
The current user is {{ user.name }}
{% endraw %}
```
<p class="code-label">Output</p>
```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" | prepend: site.baseurl }}).
<p class="code-label">Input</p>
```liquid
{% raw %}
<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{% for user in site.users %}
{{ user }}
{% endfor %}
{% endraw %}
```
<p class="code-label">Output</p>
```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.
<p class="code-label">Input</p>
```liquid
{% raw %}
<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[3] }}
{% endraw %}
```
<p class="code-label">Output</p>
```text
Tobi
Laura
Adam
```
### Initializing arrays
You cannot initialize arrays using only Liquid.
You can, however, use the [split]({{ "/filters/split" | prepend: site.baseurl }}) filter to break a string into an array of substrings.
_basics/variations.md
+24
View File
@@ -0,0 +1,24 @@
---
title: Variations of Liquid
description: An overview of the different installations of Liquid and how Liquid can change depending on where you're using it.
---
Liquid is a flexible, safe language, and is used in many different environments. Liquid was created for use in [Shopify](https://www.shopify.com) stores, and is also used extensively on [Jekyll](https://jekyllrb.com) websites. Over time, both Shopify and Jekyll have added their own objects, tags, and filters to Liquid. The most popular versions of Liquid that exist are **Liquid**, **Shopify Liquid**, and **Jekyll Liquid**.
This site documents the latest version of **Liquid** including betas and release candidates — that is, Liquid as it exists outside of Shopify and Jekyll. If you download the Liquid repository or install it as a [gem](https://rubygems.org/gems/liquid), you will get access to whatever objects, tags, and filters are in the version of Liquid that you chose.
## Shopify
Shopify always uses the latest version of Liquid as a base, but Shopify adds a significant number of objects, tags, and filters to Liquid for use in merchants' stores. These include objects representing store, product, and customer information, and filters for displaying store data and manipulating storefront assets like product images.
Shopify's version of Liquid is documented in the [Shopify Help Center](https://help.shopify.com/themes/liquid). If you want to try out Shopify's version of Liquid, you can create a development store through the [Shopify Partner Dashboard](https://help.shopify.com/en/partners/dashboard/development-stores).
## Jekyll
[Jekyll](https://jekyllrb.com) is a static site generator, a command-line tool that creates websites by merging templates with content files. Jekyll uses Liquid as its template language, and adds a few objects, tags, and filters. These include objects representing content pages, tags for including snippets of content in others, and filters for manipulating strings and URLs.
Jekyll also powers [GitHub Pages](https://pages.github.com/), a web hosting service that lets you push a Jekyll installation to a GitHub repository and have the resulting website published. This website is built using GitHub Pages.
Jekyll might not be using the latest version of Liquid. This means that the tags and filters listed on this site may not work in Jekyll. Often the Jekyll project will wait for a stable release of Liquid rather than using a beta or release candidate version. To see what version of Liquid Jekyll is using, check the **runtime dependencies** section of [Jekyll's gem page](https://rubygems.org/gems/jekyll).
Jekyll's version of Liquid is documented in the [Templates section of Jekyll's documentation](http://jekyllrb.com/docs/templates/). If you want to try out Jekyll's version of Liquid, you can clone the Jekyll project or install Jekyll as a gem and test Liquid on a static site.
_basics/whitespace.md
+80
View File
@@ -0,0 +1,80 @@
---
title: Whitespace control
description: An overview of controlling whitespace between code in the Liquid template language.
---
In Liquid, you can include a hyphen in your tag syntax `{% raw %}{{-{% endraw %}`, `{% raw %}-}}{% endraw %}`, `{% raw %}{%-{% endraw %}`, and `{% raw %}-%}{% endraw %}` to strip whitespace from the left or right side of a rendered tag.
Normally, even if it doesn't output text, any line of Liquid in your template will still output a blank line in your rendered HTML:
<p class="code-label">Input</p>
{% raw %}
``` liquid
{% assign my_variable = "tomato" %}
{{ my_variable }}
```
{% endraw %}
Notice the blank line before "tomato" in the rendered template:
<p class="code-label">Output</p>
``` text
{% assign my_variable = "tomato" %}
{{ my_variable }}
```
By including hyphens in your `assign` tag, you can strip the generated whitespace from the rendered template:
<p class="code-label">Input</p>
{% raw %}
``` liquid
{%- assign my_variable = "tomato" -%}
{{ my_variable }}
```
{% endraw %}
<p class="code-label">Output</p>
``` text
tomato
```
If you don't want any of your tags to output whitespace, as a general rule you can add hyphens to both sides of all your tags (`{% raw %}{%-{% endraw %}` and `{% raw %}-%}{% endraw %}`):
<p class="code-label">Input</p>
{% raw %}
``` liquid
{% assign username = "John G. Chalmers-Smith" %}
{% if username and username.size > 10 %}
Wow, {{ username }}, you have a long name!
{% else %}
Hello there!
{% endif %}
```
{% endraw %}
<p class="code-label">Output without whitespace control</p>
``` text
{% assign username = "John G. Chalmers-Smith" %}
{% if username and username.size > 10 %}
Wow, {{ username }}, you have a long name!
{% else %}
Hello there!
{% endif %}
```
<p class="code-label">Input</p>
{% raw %}
``` liquid
{%- assign username = "John G. Chalmers-Smith" -%}
{%- if username and username.size > 10 -%}
Wow, {{ username }}, you have a long name!
{%- else -%}
Hello there!
{%- endif -%}
```
{% endraw %}
<p class="code-label">Output with whitespace control</p>
``` text
Wow, John G. Chalmers-Smith, you have a long name!
```