diff --git a/_basics/handle.md b/_basics/handle.md index 2538fa3..e348450 100644 --- a/_basics/handle.md +++ b/_basics/handle.md @@ -2,54 +2,37 @@ title: Handles --- -### What is a handle +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 (-). -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 (-). +For example, a page with the title "About Us" can be accessed in Liquid via its handle `about-us` as shown below: -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 %} +{% highlight liquid %} +{% raw %} {{ pages.about-us.content }} -{% endraw %}{% endhighlight %} +{% endraw %} +{% endhighlight %} -### How are my handles created? +## Creating handles -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. +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. -{{ '/themes/handle-2.jpg' | image }} +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`. -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 }} +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 (how?) ## 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. +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 }} {{ pages["about-us"].title }} {% endraw %}{% endhighlight %}
@@ -62,9 +45,9 @@ About Us {% endraw %}{% endhighlight %} -In the example above, notice that we are using pages as opposed to page. +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. +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

@@ -83,7 +66,3 @@ Cool T-Shirt Wicked Socks {% endraw %}{% endhighlight %}
- - - - diff --git a/index.md b/index.md index 55ba52b..5fa664e 100644 --- a/index.md +++ b/index.md @@ -4,13 +4,95 @@ layout: default {% include home-banner.html %} +Liquid is an open-source template language created by [Shopify](https://www.shopify.com) and written in Ruby. It is the backbone of Shopify themes and is used to load dynamic content on storefronts. Liquid is also used in static site genrators like [Jekyll](http://jekyllrb.com). +Liquid has been in production use since June 2006 and is now used by many other hosted web applications. +It was developed for usage in Ruby on Rails web applications and integrates seamlessly as a plugin but it also works well as a stand alone library. -## What is Liquid? +## Introduction -Liquid is an open-source, Ruby-based template language created by [Shopify](http://www.shopify.com). It is the backbone of Shopify themes and is used to load dynamic content on storefronts. +Liquid is a language for writing and rendering templates. This means that you can reduce code duplication by displaying and manipulating content on web pages without changing a site's code. -Liquid has been in production use since June 2006 and is now used by many other hosted web applications. +### Objects -It was developed for usage in Ruby on Rails web applications and integrates seamlessly as a plugin but it also works excellently as a stand alone library. \ No newline at end of file +**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 %}`. + +For example, you can show basic content like a page title using a Liquid object: + +| Liquid | Output | +|:----------------------------------------|:---------| +| {% raw %}`{{ page.title }}`{% endraw %} | Overview | + +In this case, Liquid is rendering the content of an object called `page.title`, and that object contains the text `Overview`. + +[Filters](/filters) can change the way objects are printed. + +### Tags + +**Tags** create the logic for your template, including variable assignment, conditionals, and loops. + +Tags are denoted by curly braces and percent signs: `{% raw %}{%{% endraw %}` and `{% raw %}%}{% endraw %}`. + +Tag markup does not resolve to text. This means that you can assign variables and create conditionals and loops without showing any of the Liquid logic on the page. + +#### Conditionals + +For example, you can change what information Liquid shows using conditionals: + +

Liquid

+
+{% highlight liquid %} +{% raw %} + +{% if user %} + Hello {{ user.name }}! +{% endif %} + +{% endraw %} +{% endhighlight %} +
+ +

Output

+
+{% highlight text %} +Hello Adam! +{% endhighlight %} +
+ +This conditional statement `if user` checks to see if an object called `user` exists. If the condition is *true* (that is, if `user` exists), Liquid shows any content that is contained between the `if` and `endif` tags. + +In this case, our user's `name` is Adam, so the template prints `Hello Adam!`. + +#### Loops + +You can also use tags to loop over a list or array of objects: + +

Liquid

+
+{% highlight liquid %} +{% raw %} + +{% for item in collection %} + I have a {{ item }} +{% endfor %} + +{% endraw %} +{% endhighlight %} +
+ +

Output

+
+{% highlight text %} +I have a shirt +I have a pants +I have a banana +I have a bucket +{% endhighlight %} +
+ +The statement `for item in collection` tells Liquid to show the content between the `for` and `endfor` tags one time for every `item` in the `collection` object. + +You can use any arbitrary name (this example used `item`) to reference the items to loop through.