From ada2a87d8c092064d15e5ca7555fa33e03021383 Mon Sep 17 00:00:00 2001 From: Tetsuro Date: Wed, 26 Aug 2015 19:06:07 -0400 Subject: [PATCH] Started adding Basics section --- _basics/handle.md | 96 ++++++++++++++++++ _basics/operators.md | 123 +++++++++++++++++++++++ _basics/temp-index.md | 40 ++++++++ _basics/true-and-false.md | 121 ++++++++++++++++++++++ _basics/types.md | 204 ++++++++++++++++++++++++++++++++++++++ _config.yml | 8 +- basics/index.html | 12 +++ 7 files changed, 598 insertions(+), 6 deletions(-) create mode 100644 _basics/handle.md create mode 100644 _basics/operators.md create mode 100644 _basics/temp-index.md create mode 100644 _basics/true-and-false.md create mode 100644 _basics/types.md create mode 100644 basics/index.html diff --git a/_basics/handle.md b/_basics/handle.md new file mode 100644 index 0000000..55e0e63 --- /dev/null +++ b/_basics/handle.md @@ -0,0 +1,96 @@ +--- +title: Handles +--- + +# Handles + + + + + + +## 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 about-us as shown below: + +{% highlight html %}{% raw %} + +{{ 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. + +

Input

+
+{% highlight html %}{% raw %} +{{ pages.about-us.title }} +{{ pages["about-us"].title }} +{% endraw %}{% endhighlight %} +
+ +

Output

+
+{% highlight html %}{% raw %} +About Us +About Us +{% endraw %}{% endhighlight %} +
+ +In the example above, notice that we are using pages as opposed to page. + +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. + +

Input

+
+{% highlight html %}{% raw %} +{% for product in collections[settings.home_featured_collection].products %} + {{ product.title }} +{% endfor %} +{% endraw %}{% endhighlight %} +
+ +

Output

+
+{% highlight html %}{% raw %} +Awesome Shoes +Cool T-Shirt +Wicked Socks +{% endraw %}{% endhighlight %} +
+ + + + diff --git a/_basics/operators.md b/_basics/operators.md new file mode 100644 index 0000000..0f5b7cc --- /dev/null +++ b/_basics/operators.md @@ -0,0 +1,123 @@ +--- +title: Operators +--- + +# Operators + + + +Liquid has access to all of the logical and comparison operators. These can be used in tags such as if and unless. + + +## Basic Operators + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
==
equals
!=
does not equal
>
greater than
<
less than
>=
greater than or equal to
<=
less than or equal to
or
condition A or condition B
and
condition A and condition B
+ +**Examples:** + +
+{% highlight html %}{% raw %} +{% if product.title == "Awesome Shoes" %} + These shoes are awesome! +{% endif %} +{% endraw %}{% endhighlight %} +
+ +Operators can be chained together. + +
+{% highlight html %}{% raw %} +{% if product.type == "Shirt" or product.type == "Shoes" %} + This is a shirt or a shoe. +{% endif %} +{% endraw %}{% endhighlight %} +
+ + + + + + + + + +## Contains operator + +contains 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 %} + + +contains 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 %} + + \ No newline at end of file diff --git a/_basics/temp-index.md b/_basics/temp-index.md new file mode 100644 index 0000000..ae46193 --- /dev/null +++ b/_basics/temp-index.md @@ -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. + + + +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 Theme Development. + +## 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' }} +{% endraw %} +

+Read more › +

\ No newline at end of file diff --git a/_basics/true-and-false.md b/_basics/true-and-false.md new file mode 100644 index 0000000..a3ef1d5 --- /dev/null +++ b/_basics/true-and-false.md @@ -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 nil and false. + +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 settings.fp_heading is empty: + +

Input

+{% highlight html %}{% raw %} +{% if settings.fp_heading %} +

{{ settings.fp_heading }}

+{% endif %} +{% endraw %}{% endhighlight %} + + +

Output

+{% highlight html %}{% raw %} +

+{% endraw %}{% endhighlight %} + +To avoid this, you can check to see if the string is blank, as follows: + +
+{% highlight html %}{% raw %} +{% unless settings.fp_heading == blank %} +

{{ settings.fp_heading }}

+{% endunless %} +{% endraw %}{% endhighlight %} +
+ +
+ +An [EmptyDrop](/themes/liquid-documentation/basics/types/#empty-drop) is 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 undesirable empty <div>: + +

Input

+{% highlight html %}{% raw %} +{% if pages[settings.page] %} +
{{ pages[settings.page].content }}
+{% endif %} +{% endraw %}{% endhighlight %} + + +

Output

+{% highlight html %}{% raw %} +
+{% endraw %}{% endhighlight %} + + +## What is falsy? + +The only values that are falsy in Liquid are nil and false. + +[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 nil. Since that is “falsy”, you can do this: + +{% highlight html %}{% raw %} +{% if collection.image %} + +{% endif %} +{% endraw %}{% endhighlight %} + +The value false is returned through many Liquid object properties such as product.available. + +## 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 | × | | + + + + + + + + + + + + + + + + + + + + + + diff --git a/_basics/types.md b/_basics/types.md new file mode 100644 index 0000000..4713b91 --- /dev/null +++ b/_basics/types.md @@ -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 assign or capture tags. + + + +## Strings + +Strings are declared by wrapping the variable's value in single or double quotes. + +
+{% raw %} +{% assign my_string = "Hello World!" %} +{% endraw %} +
+ + +## Numbers + +Numbers include floats and integers. + +
+{% raw %} +{% assign my_num = 25 %} +{% endraw %} +
+ + + +## Booleans + +Booleans are either true or false. No quotations are necessary when declaring a boolean. + +
+{% raw %} +{% assign foo = true %} +{% assign bar = false %} +{% endraw %} +
+ + + +## 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. + +

Input

+ +{% highlight html %}{% raw %} +Tracking number: {{ fulfillment.tracking_numbers }} +{% endraw %}{% endhighlight %} + +

Output

+ +
+{% highlight html %}{% raw %} +Tracking number: +{% endraw %}{% endhighlight %} +
+ + + + + + + +## 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 for tag or a tablerow tag. + +

Input

+
+{% highlight html %}{% raw %} + +{% for tag in product.tags %} + {{ tag }} +{% endfor %} +{% endraw %}{% endhighlight %} +
+ +

Output

+
+{% highlight html %}{% raw %} +sale summer spring wholesale +{% endraw %}{% endhighlight %} +
+ + +#### 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. + +

Input

+
+{% highlight html %}{% raw %} + +{{ product.tags[0] }} +{{ product.tags[1] }} +{{ product.tags[2] }} +{{ product.tags[3] }} +{% endraw %}{% endhighlight %} +
+ +

Output

+
+{% highlight html %}{% raw %} +sale +summer +spring +wholesale +{% endraw %}{% endhighlight %} +
+ + +#### Initializing an array + +It is not possible to initialize an array in Liquid. For example, in Javascript you could do something like this: + +
+{% highlight html %}{% raw %} + +{% endraw %}{% endhighlight %} +
+ +In Liquid, you must instead use the split filter to break a single string into an array of substrings. See here 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, page_1, page_2 and page_3 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, 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. + +#### Applications in themes + +Using the empty? 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? %} + +

{{ pages.frontpage.title }}

+
{{ pages.frontpage.content }}
+{% 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 %} +

+
+{% 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 %} +

We do have a 'frontpage' collection but it's empty.

+ {% endfor %} +{% endunless %} +{% endraw %}{% endhighlight %} + + + + + + + diff --git a/_config.yml b/_config.yml index d42a8a7..0c56828 100644 --- a/_config.yml +++ b/_config.yml @@ -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" diff --git a/basics/index.html b/basics/index.html new file mode 100644 index 0000000..bd04fd4 --- /dev/null +++ b/basics/index.html @@ -0,0 +1,12 @@ +--- +layout: default +--- + +{% for doc in site.collections["basics"].docs %} +
+

{{ doc.title }}

+
+ {{ doc.content }} +
+
+{% endfor %}