mirror of
https://github.com/kemko/liquid.git
synced 2026-01-04 17:25:41 +03:00
Started adding Basics section
This commit is contained in:
Tetsuro
96
_basics/handle.md
Normal file
96
_basics/handle.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Handles
|
||||
---
|
||||
|
||||
# Handles
|
||||
|
||||
|
||||
<a id="topofpage"></a>
|
||||
|
||||
|
||||
|
||||
## What is a handle
|
||||
|
||||
The handle is used to access the attributes of a Liquid object. By default, it is the object's title in lowercase with any spaces and special characters replaced by hyphens (-). Every object in Liquid (product, collection, blog, link list) has a handle.
|
||||
|
||||
For example, a page with the title "About Us" can be accessed in Liquid via its handle <tt>about-us</tt> as shown below:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
<!-- the content of the About Us page -->
|
||||
{{ pages.about-us.content }}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
## How are my handles created?
|
||||
|
||||
A product with the title "Shirt" will automatically be given the handle **shirt**. If there is already a product with the handle "Shirt", the handle will auto-increment. In other words, all "Shirt" products created after the first one will receive the handle **shirt-1**, **shirt-2**, and so on.
|
||||
|
||||
{{ '/themes/handle-2.jpg' | image }}
|
||||
|
||||
Whitespaces in a title are replaced by hyphens in the handle. For example, the title "*My Shiny New Title*" will result in a handle called **my-shiny-new-title**.
|
||||
|
||||
{{ '/themes/handle-3.jpg' | image }}
|
||||
|
||||
The handle will also determine the URL of that object. For example, a page with the handle "about-us" would have the url: [http://yourshop.myshopify.com/pages/about-us](http://yourshop.myshopify.com/pages/about-us)
|
||||
|
||||
Shop designs often rely on a static handle for a page, product, or linklist. In order to preserve design elements and avoid broken links, if you modify the title of an object, **Shopify will not automatically update the handle.**
|
||||
|
||||
For example, if you were to change your page title from "About Us" to "About Shopify" ...
|
||||
|
||||
{{ '/themes/handle-4.jpg' | image }}
|
||||
|
||||
... your handle will still be **about-us**.
|
||||
|
||||
{{ '/themes/handle-5.jpg' | image }}
|
||||
|
||||
However, you can change an object's handle manually by changing the value for the "URL & Handle" text box.
|
||||
|
||||
{{ '/themes/handle-6.jpg' | image }}
|
||||
|
||||
|
||||
|
||||
## Accessing attributes via the handle", "attributes-handle
|
||||
|
||||
|
||||
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 html %}{% raw %}
|
||||
{{ pages.about-us.title }}
|
||||
{{ pages["about-us"].title }}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<p class="output">Output</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
About Us
|
||||
About Us
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
In the example above, notice that we are using <code>pages</code> as opposed to <code>page</code>.
|
||||
|
||||
You can also pass in Customize theme page objects using this notation. This is handy for theme designers who wish to give the users of their themes the ability to select which content to display in their theme.
|
||||
|
||||
<p class="input">Input</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
{% for product in collections[settings.home_featured_collection].products %}
|
||||
{{ product.title }}
|
||||
{% endfor %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<p class="output">Output</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
Awesome Shoes
|
||||
Cool T-Shirt
|
||||
Wicked Socks
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
123
_basics/operators.md
Normal file
123
_basics/operators.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Operators
|
||||
---
|
||||
|
||||
# Operators
|
||||
|
||||
<a id="topofpage"></a>
|
||||
|
||||
Liquid has access to all of the logical and comparison operators. These can be used in tags such as <a href="/themes/liquid-documentation/tags/control-flow-tags/#if">if</a> and <a href="/themes/liquid-documentation/tags/control-flow-tags/#unless">unless</a>.
|
||||
|
||||
|
||||
## 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>condition A <strong>or</strong> condition B</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><pre>and</pre></td>
|
||||
<td>condition A <strong>and</strong> condition B</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
**Examples:**
|
||||
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
{% if product.title == "Awesome Shoes" %}
|
||||
These shoes are awesome!
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
Operators can be chained together.
|
||||
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
{% if product.type == "Shirt" or product.type == "Shoes" %}
|
||||
This is a shirt or a shoe.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Contains operator
|
||||
|
||||
<code>contains</code> checks for the presence of a substring inside a string.
|
||||
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% if product.title contains 'Pack' %}
|
||||
This product's title contains the word Pack.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
|
||||
<code>contains</code> can also check for the presence of a string in an array of strings.
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% if product.tags contains 'Hello' %}
|
||||
This product has been tagged with 'Hello'.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
|
||||
You **cannot** check for the presence of an object in an array of objects using contains. This will not work:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% if product.collections contains 'Sale' %}
|
||||
One of the collections this product belongs to is the Sale collection.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
This will work:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% assign in_sale_collection = false %}
|
||||
{% for collection in product.collections %}
|
||||
{% if in_sale_collection == false and collection.title == 'Sale' %}
|
||||
{% assign in_sale_collection = true %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% if in_sale_collection %}
|
||||
One of the collections this product belongs to is the Sale collection.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
|
||||
40
_basics/temp-index.md
Normal file
40
_basics/temp-index.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Basics
|
||||
---
|
||||
|
||||
|
||||
# Introduction
|
||||
|
||||
Liquid is an open-source, Ruby-based template language created by Shopify. It is the backbone of Shopify themes and is used to load dynamic content on storefronts.
|
||||
|
||||
<iframe width="560" height="315" src="//www.youtube.com/embed/tZLTExLukSg" frameborder="0" allowfullscreen style="margin: 0 auto 24px auto; width: 70%; display: block; padding: 20px 15%; background: #f9f9f9;"></iframe>
|
||||
|
||||
Liquid uses a combination of _tags_, _objects_, and _filters_ to load dynamic content. They are used inside Liquid _template files_, which are a group of files that make up a theme. For more information on the available templates, please see <a href="/themes/theme-development/templates/">Theme Development</a>.
|
||||
|
||||
## Tags
|
||||
|
||||
Tags make up the programming logic that tells templates what to do.
|
||||
|
||||
{% raw %}
|
||||
{% if user.name == 'elvis' %}
|
||||
Hey Elvis
|
||||
{% endif %}
|
||||
{% endraw %}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Filters
|
||||
|
||||
Filters are used to modify the output of strings, numbers, variables, and objects.
|
||||
|
||||
{% raw %}
|
||||
{{ 'sales' | append: '.jpg' }} <!-- Output: sales.jpg -->
|
||||
{% endraw %}
|
||||
<p class="tr">
|
||||
<a class="themes-article-cta" href="/themes/liquid-documentation/filters">Read more ›</a>
|
||||
</p>
|
||||
121
_basics/true-and-false.md
Normal file
121
_basics/true-and-false.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Truthy and Falsy
|
||||
---
|
||||
|
||||
# Truthy and Falsy in Liquid
|
||||
|
||||
|
||||
|
||||
In programming, we describe “truthy” and “falsy” as anything that returns true or false, respectively, when used inside an if statement.
|
||||
|
||||
## What is truthy?
|
||||
|
||||
All values in Liquid are truthy, with the exception of <tt>nil</tt> and <tt>false</tt>.
|
||||
|
||||
In the example below, the text “Tobi” is not a boolean, but it is truthy in a conditional:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% assign tobi = 'Tobi' %}
|
||||
{% if tobi %}
|
||||
This will always be true.
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
[Strings](/themes/liquid-documentation/basics/types/#strings), even when empty, are truthy. The example below will result in empty HTML tags if <code>settings.fp_heading</code> is empty:
|
||||
|
||||
<p class="input">Input</p>
|
||||
{% highlight html %}{% 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 %}
|
||||
|
||||
To avoid this, you can check to see if the string is <code>blank</code>, as follows:
|
||||
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
{% unless settings.fp_heading == blank %}
|
||||
<h1>{{ settings.fp_heading }}</h1>
|
||||
{% endunless %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
An [EmptyDrop](/themes/liquid-documentation/basics/types/#empty-drop) is also truthy. In the example below, if <code>settings.page</code> is an empty string or set to a hidden or deleted object, you will end up with an EmptyDrop. The result is an undesirable 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 %}
|
||||
|
||||
|
||||
## What is falsy?
|
||||
|
||||
The only values that are falsy in Liquid are <tt>nil</tt> and <tt>false</tt>.
|
||||
|
||||
[nil](/themes/liquid-documentation/basics/types/#nil) is returned when a Liquid object doesn't have anything to return. For example, if a collection doesn't have a collection image, collection.image will be set to <tt>nil</tt>. Since that is “falsy”, you can do this:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% if collection.image %}
|
||||
<!-- output collection image -->
|
||||
{% endif %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
The value <tt>false</tt> is returned through many Liquid object properties such as <tt>product.available</tt>.
|
||||
|
||||
## Summary
|
||||
|
||||
The table below summarizes what is truthy or falsy in Liquid.
|
||||
|
||||
| | truthy | falsy |
|
||||
| ------------- |:-------------:|:-------------:|
|
||||
| true | × | |
|
||||
| false | | × |
|
||||
| nil | | × |
|
||||
| string | × | |
|
||||
| empty string | × | |
|
||||
| 0 | × | |
|
||||
| 1 or 2 or 3.14 | × | |
|
||||
| array | × | |
|
||||
| empty array | × | |
|
||||
| collection | × | |
|
||||
| collection with no products | × | |
|
||||
| page | × | |
|
||||
| EmptyDrop | × | |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
204
_basics/types.md
Normal file
204
_basics/types.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
title: Types
|
||||
---
|
||||
|
||||
# Types
|
||||
|
||||
Liquid objects can return one of six types: String, Number, Boolean, Nil, Array, or EmptyDrop. Liquid variables can be initialized by using the <a href="/themes/liquid-documentation/tags/variable-tags/#assign">assign</a> or <a href="/themes/liquid-documentation/tags/variable-tags/#capture">capture</a> tags.
|
||||
|
||||
|
||||
|
||||
## Strings
|
||||
|
||||
Strings are declared by wrapping the variable's value in single or double quotes.
|
||||
|
||||
<div>
|
||||
{% raw %}
|
||||
{% assign my_string = "Hello World!" %}
|
||||
{% endraw %}
|
||||
</div>
|
||||
|
||||
|
||||
## Numbers
|
||||
|
||||
Numbers include floats and integers.
|
||||
|
||||
<div>
|
||||
{% raw %}
|
||||
{% assign my_num = 25 %}
|
||||
{% endraw %}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
## Booleans
|
||||
|
||||
Booleans are either true or false. No quotations are necessary when declaring a boolean.
|
||||
|
||||
<div>
|
||||
{% raw %}
|
||||
{% assign foo = true %}
|
||||
{% assign bar = false %}
|
||||
{% endraw %}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
## Nil
|
||||
|
||||
Nil is an 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 for the truthfulness of a statement. The example below shows a situation where a fulfillment does not yet have a tracking number entered. The if statement would not render the included text within it.
|
||||
|
||||
{% raw %}
|
||||
{% if fulfillment.tracking_numbers %}
|
||||
We have a tracking number!
|
||||
{% endif %}
|
||||
{% endraw %}
|
||||
|
||||
Any tags or outputs that return nil will not show anything on the screen.
|
||||
|
||||
<p class="input">Input</p>
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
Tracking number: {{ fulfillment.tracking_numbers }}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
<p class="output">Output</p>
|
||||
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
Tracking number:
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Arrays
|
||||
|
||||
Arrays hold a list of variables of all types.
|
||||
|
||||
#### Accessing all items in an array
|
||||
|
||||
To access items in an array, you can loop through each item in the array using a <a href="/themes/liquid-documentation/tags/#for">for</a> tag or a <a href="/themes/liquid-documentation/tags/#tablerow">tablerow</a> tag.
|
||||
|
||||
<p class="input">Input</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
<!-- if product.tags = "sale", "summer", "spring", "wholesale" -->
|
||||
{% for tag in product.tags %}
|
||||
{{ tag }}
|
||||
{% endfor %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<p class="output">Output</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
sale summer spring wholesale
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
|
||||
#### Accessing a specific item in an array
|
||||
|
||||
You can use square brackets ( [ ] ) notation to access a specific item in an array. Array indexing starts at zero.
|
||||
|
||||
<p class="input">Input</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
<!-- if product.tags = "sale", "summer", "spring", "wholesale" -->
|
||||
{{ product.tags[0] }}
|
||||
{{ product.tags[1] }}
|
||||
{{ product.tags[2] }}
|
||||
{{ product.tags[3] }}
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<p class="output">Output</p>
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
sale
|
||||
summer
|
||||
spring
|
||||
wholesale
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
|
||||
#### Initializing an array
|
||||
|
||||
It is not possible to initialize an array in Liquid. For example, in Javascript you could do something like this:
|
||||
|
||||
<div>
|
||||
{% highlight html %}{% raw %}
|
||||
<script>
|
||||
var cars = ["Saab", "Volvo", "BMW"];
|
||||
</script>
|
||||
{% endraw %}{% endhighlight %}
|
||||
</div>
|
||||
|
||||
In Liquid, you must instead use the <code>split</code> filter to break a single string into an array of substrings. See <a href="/themes/liquid-documentation/filters/string-filters/#split">here</a> for examples.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## EmptyDrop
|
||||
|
||||
An EmptyDrop object is returned whenever you try to access a non-existent object (for example, a collection, page or blog that was deleted or hidden) by [handle](/themes/liquid-documentation/basics/handle). In the example below, <code>page_1</code>, <code>page_2</code> and <code>page_3</code> are all EmptyDrop objects.
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% assign variable = "hello" %}
|
||||
{% assign page_1 = pages[variable] %}
|
||||
{% assign page_2 = pages["i-do-not-exist-in-your-store"] %}
|
||||
{% assign page_3 = pages.this-handle-does-not-belong-to-any-page %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
EmptyDrop objects only have one attribute, <code>empty?</code>, which is always true.
|
||||
|
||||
Collections and pages that _do_ exist do not have an <code>empty?</code> attribute. Their <code>empty?</code> is “falsy”, which means that calling it inside an if statement will return <tt>false</tt>. When using an unless statement on existing collections and pages, <code>empty?</code> will return <tt>true</tt>.
|
||||
|
||||
#### Applications in themes
|
||||
|
||||
Using the <code>empty?</code> attribute, you can check to see if a page exists or not _before_ accessing any of its other attributes.
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% unless pages.frontpage.empty? %}
|
||||
<!-- We have a page with handle 'frontpage' and it's not hidden.-->
|
||||
<h1>{{ pages.frontpage.title }}</h1>
|
||||
<div>{{ pages.frontpage.content }}</div>
|
||||
{% endunless %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
It is important to see if a page exists or not first to avoid outputting empty HTML elements to the page, as follows:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
<h1></h1>
|
||||
<div></div>
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
You can perform the same verification with collections as well:
|
||||
|
||||
{% highlight html %}{% raw %}
|
||||
{% unless collections.frontpage.empty? %}
|
||||
{% for product in collections.frontpage.products %}
|
||||
{% include 'product-grid-item' %}
|
||||
{% else %}
|
||||
<p>We do have a 'frontpage' collection but it's empty.</p>
|
||||
{% endfor %}
|
||||
{% endunless %}
|
||||
{% endraw %}{% endhighlight %}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@ url: "http://liquidmarkup.org" # the base hostname & protocol for your site
|
||||
markdown: kramdown
|
||||
permalink: /:year/:month/:day/:basename:output_ext
|
||||
collections:
|
||||
basics:
|
||||
output: true
|
||||
filters:
|
||||
output: true
|
||||
tags:
|
||||
@@ -13,9 +15,3 @@ exclude:
|
||||
- CNAME
|
||||
- node_modules
|
||||
keep_files: ['css']
|
||||
defaults:
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
values:
|
||||
layout: "default"
|
||||
|
||||
12
basics/index.html
Normal file
12
basics/index.html
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
||||
{% for doc in site.collections["basics"].docs %}
|
||||
<div id="{{ doc.title }}" class="content__item">
|
||||
<h2>{{ doc.title }}</h2>
|
||||
<div class="content">
|
||||
{{ doc.content }}
|
||||
</div>
|
||||
</div>
|
||||
{% endfor %}
|
||||
Reference in New Issue
Block a user