From 58e6e416eba009d262a521d19c1d67ab0b33eaf8 Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Mon, 26 Aug 2019 15:34:36 -0400 Subject: [PATCH] Add additional documentation Includes descriptions of logical operator order, `else` in a `for` loop, `sort`'s parameter, and dot notation for `first`/`last`/`size`. --- _basics/operators.md | 25 +++++++++++++++++++++++++ _filters/first.md | 10 ++++++++++ _filters/last.md | 10 ++++++++++ _filters/size.md | 4 ++-- _filters/sort.md | 13 ++++++++++++- _filters/sort_natural.md | 17 +++++++++++++++-- _tags/iteration.md | 20 ++++++++++++++++++++ 7 files changed, 94 insertions(+), 5 deletions(-) diff --git a/_basics/operators.md b/_basics/operators.md index 1b46355..1e0a414 100644 --- a/_basics/operators.md +++ b/_basics/operators.md @@ -87,3 +87,28 @@ You can use multiple operators in a tag: ``` `contains` can only search strings. You cannot use it to check for an object in an array of objects. + +## Order of operations + +In tags with more than one `and` or `or` operator, operators are checked in order *from right to left*. You cannot change the order of operations using parentheses — parentheses are invalid characters in Liquid and will prevent your tags from working. + +```liquid +{% raw %} +{% if true or false and false %} + This evaluates to true, since the 'and' condition is checked first. +{% endif %} +{% endraw %} +``` + +```liquid +{% raw %} +{% if true and false and false or true %} + This evaluates to false, since the tags are checked like this: + + true and (false and (false or true)) + true and (false and true) + true and false + false +{% endif %} +{% endraw %} +``` diff --git a/_filters/first.md b/_filters/first.md index 4d80f1e..a03ca43 100644 --- a/_filters/first.md +++ b/_filters/first.md @@ -36,3 +36,13 @@ Returns the first item of an array. {{ my_array.first }} ``` + +You can use `first` with dot notation when you need to use the filter inside a tag. + +```liquid +{% raw %} +{% if my_array.first == "zebra" %} + Here comes a zebra! +{% endif %} +{% endraw %} +``` diff --git a/_filters/last.md b/_filters/last.md index 1273078..2e99720 100644 --- a/_filters/last.md +++ b/_filters/last.md @@ -36,3 +36,13 @@ Returns the last item of an array. {{ my_array.last }} ``` + +You can use `last` with dot notation when you need to use the filter inside a tag. + +```liquid +{% raw %} +{% if my_array.last == "tiger" %} + There goes a tiger! +{% endif %} +{% endraw %} +``` diff --git a/_filters/size.md b/_filters/size.md index 797c410..1716767 100644 --- a/_filters/size.md +++ b/_filters/size.md @@ -3,7 +3,7 @@ title: size description: Liquid filter that returns the number of characters in a string or the number of items in an array. --- -Returns the number of characters in a string or the number of items in an array. `size` can also be used with dot notation (for example, `{% raw %}{{ my_string.size }}{% endraw %}`). This allows you to use `size` inside tags such as conditionals. +Returns the number of characters in a string or the number of items in an array.

Input

```liquid @@ -33,7 +33,7 @@ Returns the number of characters in a string or the number of items in an array. {{ my_array | size }} ``` -Using dot notation: +You can use `size` with dot notation when you need to use the filter inside a tag. ```liquid {% raw %} diff --git a/_filters/sort.md b/_filters/sort.md index f0074b7..f6cbd8a 100644 --- a/_filters/sort.md +++ b/_filters/sort.md @@ -3,7 +3,7 @@ title: sort description: Liquid filter that sorts an array in case-sensitive order. --- -Sorts items in an array by a property of an item in the array. The order of the sorted array is case-sensitive. +Sorts items in an array in case-sensitive order.

Input

```liquid @@ -20,3 +20,14 @@ Sorts items in an array by a property of an item in the array. The order of the {{ my_array | sort | join: ", " }} ``` + +An optional parameter specifies which property of the array's items to use for sorting. + +```liquid +{% raw %} +{% assign products_by_price = collection.products | sort: "price" %} +{% for product in products_by_price %} +

{{ product.title }}

+{% endfor %} +{% endraw %} +``` diff --git a/_filters/sort_natural.md b/_filters/sort_natural.md index d45e16f..71489b1 100644 --- a/_filters/sort_natural.md +++ b/_filters/sort_natural.md @@ -3,7 +3,7 @@ title: sort_natural description: Liquid filter that sorts an array in case-insensitive order. --- -Sorts items in an array by a property of an item in the array. +Sorts items in an array in case-insensitive order.

Input

```liquid @@ -16,5 +16,18 @@ Sorts items in an array by a property of an item in the array.

Output

```text -giraffe, octopus, Sally Snake, zebra +{% assign my_array = "zebra, octopus, giraffe, Sally Snake" | split: ", " %} + +{{ my_array | sort_natural | join: ", " }} +``` + +An optional parameter specifies which property of the array's items to use for sorting. + +```liquid +{% raw %} +{% assign products_by_company = collection.products | sort_natural: "company" %} +{% for product in products_by_company %} +

{{ product.title }}

+{% endfor %} +{% endraw %} ``` diff --git a/_tags/iteration.md b/_tags/iteration.md index ae033b4..07d6e24 100644 --- a/_tags/iteration.md +++ b/_tags/iteration.md @@ -23,6 +23,26 @@ Repeatedly executes a block of code. For a full list of attributes available wit hat shirt pants ``` +### else + +Specifies a fallback case for a `for` loop which will run if the loop has zero length. + +

Input

+```liquid +{% raw %} +{% for product in collection.products %} + {{ product.title }} +{% else %} + The collection is empty. +{% endfor %} +{% endraw %} +``` + +

Output

+```text +The collection is empty. +``` + ### break Causes the loop to stop iterating when it encounters the `break` tag.