pages/new-page.md

   1 ---
   2 layout: page
   3 date: 'Sat 2012-06-09 18:26:11 +0800'
   4 slug: 'New-Page'
   5 title: "Test Page"
   6 description: ""
   7 ---
   8 {% include JB/setup %}
   9
  10 Just for test ...
  11
  12 Liquid for Designers
  13 ====================
  14
  15 https://github.com/shopify/liquid/wiki/liquid-for-designers
  16
  17 There are two types of markup in Liquid: Output and Tag.
  18
  19 * Output markup (which may resolve to text) is surrounded by
  20
  21 {% highlight ruby %}
  22 {% raw %}
  23 {{ matched pairs of curly brackets (ie, braces) }}
  24 {% endraw %}
  25 {% endhighlight %}
  26
  27 * Tag markup (which cannot resolve to text) is surrounded by
  28
  29 {% highlight ruby %}
  30 {% raw %}
  31 {% matched pairs of curly brackets and percent signs %}
  32 {% endraw %}
  33 {% endhighlight %}
  34
  35 ## Output
  36
  37 Here is a simple example of Output:
  38
  39 {% highlight ruby %}
  40 {% raw %}
  41 Hello {{name}}
  42 Hello {{user.name}}
  43 Hello {{ 'tobi' }}
  44 {% endraw %}
  45 {% endhighlight %}
  46
  47 ### Advanced output: Filters
  48
  49 Output markup takes filters.  Filters are simple methods.  The first parameter
  50 is always the output of the left side of the filter.  The return value of the
  51 filter will be the new left value when the next filter is run.  When there are
  52 no more filters, the template will receive the resulting string.
  53
  54 {% highlight ruby %}
  55 {% raw %}
  56 Hello {{ 'tobi' | upcase }}
  57 Hello tobi has {{ 'tobi' | size }} letters!
  58 Hello {{ '*tobi*' | textilize | upcase }}
  59 Hello {{ 'now' | date: "%Y %h" }}
  60 {% endraw %}
  61 {% endhighlight %}
  62
  63 ### Standard Filters
  64
  65 * `date` - reformat a date [syntax reference](http://liquid.rubyforge.org/classes/Liquid/StandardFilters.html#M000012)
  66 * `capitalize` - capitalize words in the input sentence
  67 * `downcase` - convert an input string to lowercase
  68 * `upcase` - convert an input string to uppercase
  69 * `first` - get the first element of the passed in array
  70 * `last` - get the last element of the passed in array
  71 * `join` - join elements of the array with certain character between them
  72 * `sort` - sort elements of the array
  73 * `map` - map/collect an array on a given property
  74 * `size` - return the size of an array or string
  75 * `escape` - escape a string
  76 * `escape_once` - returns an escaped version of html without affecting existing escaped entities
  77 * `strip_html` - strip html from string
  78 * `strip_newlines` - strip all newlines (\n) from string
  79 * `newline_to_br` - replace each newline (\n) with html break
  80 * `replace` - replace each occurrence *e.g.* `{{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'`
  81 * `replace_first` - replace the first occurrence *e.g.* `{{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'`
  82 * `remove` - remove each occurrence *e.g.* `{{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'`
  83 * `remove_first` - remove the first occurrence *e.g.* `{{ 'barbar' | remove_first:'bar' }} #=> 'bar'`
  84 * `truncate` - truncate a string down to x characters
  85 * `truncatewords` - truncate a string down to x words
  86 * `prepend` - prepend a string *e.g.* `{{ 'bar' | prepend:'foo' }} #=> 'foobar'`
  87 * `append` - append a string *e.g.* `{{ 'foo' | append:'bar' }} #=> 'foobar'`
  88 * `minus` - subtraction *e.g.*  `{{ 4 | minus:2 }} #=> 2`
  89 * `plus` - addition *e.g.*  `{{ '1' | plus:'1' }} #=> '11'`, `{{ 1 | plus:1 }} #=> 2`
  90 * `times` - multiplication  *e.g* `{{ 5 | times:4 }} #=> 20`
  91 * `divided_by` - division *e.g.* `{{ 10 | divided_by:2 }} #=> 5`
  92 * `split` - split a string on a matching pattern *e.g.* `{{ "a~b" | split:~ }} #=> ['a','b']`
  93 * `modulo` - remainder, *e.g.* `{{ 3 | modulo:2 }} #=> 1`
  94
  95 ## Tags
  96
  97 Tags are used for the logic in your template. New tags are very easy to code,
  98 so I hope to get many contributions to the standard tag library after releasing
  99 this code.
 100
 101 Here is a list of currently supported tags:
 102
 103 * **assign** - Assigns some value to a variable
 104 * **capture** - Block tag that captures text into a variable
 105 * **case** - Block tag, its the standard case...when block
 106 * **comment** - Block tag, comments out the text in the block
 107 * **cycle** - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
 108 * **for** - For loop
 109 * **if** - Standard if/else block
 110 * **include** - Includes another template; useful for partials
 111 * **raw** - temporarily disable tag processing to avoid syntax conflicts.
 112 * **unless** - Mirror of if statement
 113
 114 ### Comments
 115
 116 Comment is the simplest tag.  It just swallows content.
 117
 118 {% highlight ruby %}
 119 {% raw %}
 120 We made 1 million dollars {% comment %} in losses {% endcomment %} this year
 121 {% endraw %}
 122 {% endhighlight %}
 123
 124 ### Raw
 125
 126 Raw temporarily disables tag processing.
 127 This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
 128
 129 <div class="highlight"><code class="ruby"><span class="nb">
 130 &#123;&#37; raw %}<br>
 131 &nbsp;&nbsp;In Handlebars, &#123;&#123; this }} will be HTML-escaped, but &#123;&#123;&#123; that }}} will not.<br>
 132 &#123;&#37; endraw %}
 133 </span></code>
 134 </div>
 135 <br>
 136
 137 ### If / Else
 138
 139 `if / else` should be well-known from any other programming language.
 140 Liquid allows you to write simple expressions in the `if` or `unless` (and
 141 optionally, `elsif` and `else`) clause:
 142
 143 {% highlight ruby %}
 144 {% raw %}
 145 {% if user %}
 146   Hello {{ user.name }}
 147 {% endif %}
 148
 149 {% if user.name == 'tobi' %}
 150   Hello tobi
 151 {% elsif user.name == 'bob' %}
 152   Hello bob
 153 {% endif %}
 154
 155 {% if user.name == 'tobi' or user.name == 'bob' %}
 156   Hello tobi or bob
 157 {% endif %}
 158
 159 {% if user.name == 'bob' and user.age > 45 %}
 160   Hello old bob
 161 {% endif %}
 162
 163 {% if user.name != 'tobi' %}
 164   Hello non-tobi
 165 {% endif %}
 166
 167 # Same as above
 168 {% unless user.name == 'tobi' %}
 169   Hello non-tobi
 170 {% endunless %}
 171
 172 # Check if the user has a credit card
 173 {% if user.creditcard != null %}
 174    poor sob
 175 {% endif %}
 176
 177 # Same as above
 178 {% if user.creditcard %}
 179    poor sob
 180 {% endif %}
 181
 182 # Check for an empty array
 183 {% if user.payments == empty %}
 184    you never paid !
 185 {% endif %}
 186
 187 {% if user.age > 18 %}
 188    Login here
 189 {% else %}
 190    Sorry, you are too young
 191 {% endif %}
 192
 193 # array = 1,2,3
 194 {% if array contains 2 %}
 195    array includes 2
 196 {% endif %}
 197
 198 # string = 'hello world'
 199 {% if string contains 'hello' %}
 200    string includes 'hello'
 201 {% endif %}
 202 {% endraw %}
 203 {% endhighlight %}
 204
 205 ### Case Statement
 206
 207 If you need more conditions, you can use the `case` statement:
 208
 209 {% highlight ruby %}
 210 {% raw %}
 211 {% case condition %}
 212 {% when 1 %}
 213 hit 1
 214 {% when 2 or 3 %}
 215 hit 2 or 3
 216 {% else %}
 217 ... else ...
 218 {% endcase %}
 219 {% endraw %}
 220 {% endhighlight %}
 221
 222 *Example:*
 223
 224 {% highlight ruby %}
 225 {% raw %}
 226 {% case template %}
 227
 228 {% when 'label' %}
 229      // {{ label.title }}
 230 {% when 'product' %}
 231      // {{ product.vendor | link_to_vendor }} / {{ product.title }}
 232 {% else %}
 233      // {{page_title}}
 234 {% endcase %}
 235 {% endraw %}
 236 {% endhighlight %}
 237
 238 ### Cycle
 239
 240 Often you have to alternate between different colors or similar tasks.  Liquid
 241 has built-in support for such operations, using the `cycle` tag.
 242
 243 {% highlight ruby %}
 244 {% raw %}
 245 {% cycle 'one', 'two', 'three' %}
 246 {% cycle 'one', 'two', 'three' %}
 247 {% cycle 'one', 'two', 'three' %}
 248 {% cycle 'one', 'two', 'three' %}
 249
 250 will result in
 251
 252 one
 253 two
 254 three
 255 one
 256 {% endraw %}
 257 {% endhighlight %}
 258
 259 If no name is supplied for the cycle group, then it's assumed that multiple
 260 calls with the same parameters are one group.
 261
 262 If you want to have total control over cycle groups, you can optionally specify
 263 the name of the group.  This can even be a variable.
 264
 265 {% highlight ruby %}
 266 {% raw %}
 267 {% cycle 'group 1': 'one', 'two', 'three' %}
 268 {% cycle 'group 1': 'one', 'two', 'three' %}
 269 {% cycle 'group 2': 'one', 'two', 'three' %}
 270 {% cycle 'group 2': 'one', 'two', 'three' %}
 271
 272 will result in
 273
 274 one
 275 two
 276 one
 277 two
 278 {% endraw %}
 279 {% endhighlight %}
 280
 281 ### For loops
 282
 283 Liquid allows `for` loops over collections:
 284
 285 {% highlight ruby %}
 286 {% raw %}
 287 {% for item in array %}
 288   {{ item }}
 289 {% endfor %}
 290 {% endraw %}
 291 {% endhighlight %}
 292
 293 During every `for` loop, the following helper variables are available for extra
 294 styling needs:
 295
 296 {% highlight ruby %}
 297 {% raw %}
 298 forloop.length      # => length of the entire for loop
 299 forloop.index       # => index of the current iteration
 300 forloop.index0      # => index of the current iteration (zero based)
 301 forloop.rindex      # => how many items are still left?
 302 forloop.rindex0     # => how many items are still left? (zero based)
 303 forloop.first       # => is this the first iteration?
 304 forloop.last        # => is this the last iteration?
 305 {% endraw %}
 306 {% endhighlight %}
 307
 308 There are several attributes you can use to influence which items you receive in
 309 your loop
 310
 311 `limit:int` lets you restrict how many items you get.
 312 `offset:int` lets you start the collection with the nth item.
 313
 314 {% highlight ruby %}
 315 {% raw %}
 316 # array = [1,2,3,4,5,6]
 317 {% for item in array limit:2 offset:2 %}
 318   {{ item }}
 319 {% endfor %}
 320 # results in 3,4
 321 {% endraw %}
 322 {% endhighlight %}
 323
 324 Reversing the loop
 325
 326 {% highlight ruby %}
 327 {% raw %}
 328 {% for item in collection reversed %} {{item}} {% endfor %}
 329 {% endraw %}
 330 {% endhighlight %}
 331
 332 Instead of looping over an existing collection, you can define a range of
 333 numbers to loop through.  The range can be defined by both literal and variable
 334 numbers:
 335
 336 {% highlight ruby %}
 337 {% raw %}
 338 # if item.quantity is 4...
 339 {% for i in (1..item.quantity) %}
 340   {{ i }}
 341 {% endfor %}
 342 # results in 1,2,3,4
 343 {% endraw %}
 344 {% endhighlight %}
 345
 346 ### Variable Assignment
 347
 348 You can store data in your own variables, to be used in output or other tags as
 349 desired.  The simplest way to create a variable is with the `assign` tag, which
 350 has a pretty straightforward syntax:
 351
 352 {% highlight ruby %}
 353 {% raw %}
 354 {% assign name = 'freestyle' %}
 355
 356 {% for t in collections.tags %}{% if t == name %}
 357   <p>Freestyle!</p>
 358 {% endif %}{% endfor %}
 359 {% endraw %}
 360 {% endhighlight %}
 361
 362 Another way of doing this would be to assign `true / false` values to the
 363 variable:
 364
 365 {% highlight ruby %}
 366 {% raw %}
 367 {% assign freestyle = false %}
 368
 369 {% for t in collections.tags %}{% if t == 'freestyle' %}
 370   {% assign freestyle = true %}
 371 {% endif %}{% endfor %}
 372
 373 {% if freestyle %}
 374   <p>Freestyle!</p>
 375 {% endif %}
 376 {% endraw %}
 377 {% endhighlight %}
 378
 379 If you want to combine a number of strings into a single string and save it to
 380 a variable, you can do that with the `capture` tag. This tag is a block which
 381 "captures" whatever is rendered inside it, then assigns the captured value to
 382 the given variable instead of rendering it to the screen.
 383
 384 {% highlight ruby %}
 385 {% raw %}
 386   {% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}
 387
 388   <label for="{{ attribute_name }}">Color:</label>
 389   <select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}">
 390     <option value="red">Red</option>
 391     <option value="green">Green</option>
 392     <option value="blue">Blue</option>
 393   </select>
 394 {% endraw %}
 395 {% endhighlight %}