pages/HelpLiquid.md

   1 ---
   2 layout: page
   3 date: 'Sat 2012-06-09 17:54:04 +0800'
   4 slug: 'HelpLiquid'
   5 title: "HelpLiquid"
   6 description: ""
   7 ---
   8 {% include JB/setup %}
   9
  10 <ul>
  11     <li><a href="#liquid_extensions">Jekyll Liquid Extensions</a></li>
  12     <li><a href="#liquid_for_designers">Liquid for Designers</a></li>
  13     <li><a href="/pages/Help.html#syntax_cheatsheet">On Markdown</a></li>
  14 </ul>
  15
  16 Liquid Extensions
  17 =================
  18
  19 https://github.com/mojombo/jekyll/wiki/Liquid-Extensions
  20
  21 Jekyll uses [Liquid] [L] to process templates. Along with the [standard liquid tags and filters] [s], Jekyll adds a few of its own:
  22
  23   [L]: http://www.liquidmarkup.org/
  24   [s]: http://wiki.github.com/shopify/liquid/liquid-for-designers
  25
  26 ## Filters
  27
  28 ### Date to XML Schema
  29 Convert a Time into XML Schema format.
  30 {% raw %}
  31         {{ site.time | date_to_xmlschema }} => 2008-11-17T13:07:54-08:00
  32 {% endraw %}
  33
  34 ### Date to String
  35 Convert a date in short format, e.g. “27 Jan 2011”.
  36 {% raw %}
  37         {{ site.time | date_to_string }} => 17 Nov 2008
  38 {% endraw %}
  39
  40 ### Date to Long String
  41 Format a date in long format e.g. “27 January 2011”.
  42 {% raw %}
  43         {{ site.time | date_to_long_string }} => 17 November 2008
  44 {% endraw %}
  45
  46 ### XML Escape
  47 Escape some text for use in XML.
  48 {% raw %}
  49         {{ page.content | xml_escape }}
  50 {% endraw %}
  51
  52 ### CGI Escape
  53 CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.
  54 {% raw %}
  55         {{ "foo,bar;baz?" | cgi_escape }} => foo%2Cbar%3Bbaz%3F
  56 {% endraw %}
  57
  58 ### Number of Words
  59 Count the number of words in some text.
  60 {% raw %}
  61         {{ page.content | number_of_words }} => 1337
  62 {% endraw %}
  63
  64 ### Array to Sentence
  65 Convert an array into a sentence.
  66 {% raw %}
  67         {{ page.tags | array_to_sentence_string }} => foo, bar, and baz
  68 {% endraw %}
  69
  70 ### Textilize
  71 Convert a Textile-formatted string into HTML, formatted via RedCloth
  72 {% raw %}
  73         {{ page.excerpt | textilize }}
  74 {% endraw %}
  75
  76 ### Markdownify
  77 Convert a Markdown-formatted string into HTML.
  78 {% raw %}
  79         {{ page.excerpt | markdownify }}
  80 {% endraw %}
  81
  82
  83 ## Tags
  84
  85 ### Include
  86
  87 If you have small page fragments that you wish to include in multiple places
  88 on your site, you can use the include tag.
  89 {% raw %}
  90         {% include sig.textile %}
  91 {% endraw %}
  92 Jekyll expects all include files to be placed in an `_includes` directory at the root of your source dir. So this will embed the contents of `/path/to/proto/site/_includes/sig.textile` into the calling file.
  93
  94 ### Code Highlighting
  95
  96 Jekyll has built in support for syntax highlighting of over [100 languages] [100] via [Pygments] [P]. In order to take advantage of this you’ll need to have Pygments installed, and the pygmentize binary must be in your path. When you run Jekyll, make sure you run it with [Pygments support] [Ps]
  97
  98   [100]: http://pygments.org/languages/
  99   [P]: http://pygments.org/
 100   [Ps]: https://github.com/mojombo/jekyll/wiki/Configuration
 101
 102 To denote a code block that should be highlighted:
 103 {% raw %}
 104         {% highlight ruby %}
 105         def foo
 106           puts 'foo'
 107         end
 108         {% endhighlight %}
 109 {% endraw %}
 110
 111 The argument to `highlight` is the language identifier. To find the appropriate identifier to use for your favorite language, look for the “short name” on the [Lexers](http://pygments.org/docs/lexers/) page.
 112
 113 ### Line number
 114
 115 There is a second argument to `highlight` called `linenos` that is optional. Including the `linenos` argument will force the highlighted code to include line numbers. For instance, the following code block would include line numbers next to each line:
 116 {% raw %}
 117         {% highlight ruby linenos %}
 118         def foo
 119           puts 'foo'
 120         end
 121         {% endhighlight %}
 122 {% endraw %}
 123
 124 In order for the highlighting to show up, you’ll need to include a highlighting stylesheet. For an example stylesheet you can look at [syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css). These are the same styles as used by GitHub and you are free to use them for your own site. If you use `linenos`, you might want to include an additional CSS class definition for lineno in syntax.css to distinguish the line numbers from the highlighted code.
 125
 126 ### Post Url
 127
 128 If you would like to include a link to a post on your site, you can use the `post_url` tag.
 129 {% raw %}
 130         {% post_url 2010-07-21-name-of-post %}
 131 {% endraw %}
 132
 133 There is no need to include the extension.
 134
 135 To create a link, do:
 136 {% raw %}
 137         [Name of Link]({% post_url 2010-07-21-name-of-post %})
 138 {% endraw %}
 139
 140 * * *
 141
 142 Liquid for Designers
 143 ====================
 144
 145 https://github.com/shopify/liquid/wiki/liquid-for-designers
 146
 147 There are two types of markup in Liquid: Output and Tag.
 148
 149 * Output markup (which may resolve to text) is surrounded by
 150
 151 {% highlight ruby %}
 152 {% raw %}
 153 {{ matched pairs of curly brackets (ie, braces) }}
 154 {% endraw %}
 155 {% endhighlight %}
 156
 157 * Tag markup (which cannot resolve to text) is surrounded by
 158
 159 {% highlight ruby %}
 160 {% raw %}
 161 {% matched pairs of curly brackets and percent signs %}
 162 {% endraw %}
 163 {% endhighlight %}
 164
 165 ## Output
 166
 167 Here is a simple example of Output:
 168
 169 {% highlight ruby %}
 170 {% raw %}
 171 Hello {{name}}
 172 Hello {{user.name}}
 173 Hello {{ 'tobi' }}
 174 {% endraw %}
 175 {% endhighlight %}
 176
 177 ### Advanced output: Filters
 178
 179 Output markup takes filters.  Filters are simple methods.  The first parameter
 180 is always the output of the left side of the filter.  The return value of the
 181 filter will be the new left value when the next filter is run.  When there are
 182 no more filters, the template will receive the resulting string.
 183
 184 {% highlight ruby %}
 185 {% raw %}
 186 Hello {{ 'tobi' | upcase }}
 187 Hello tobi has {{ 'tobi' | size }} letters!
 188 Hello {{ '*tobi*' | textilize | upcase }}
 189 Hello {{ 'now' | date: "%Y %h" }}
 190 {% endraw %}
 191 {% endhighlight %}
 192
 193 ### Standard Filters
 194
 195 * `date` - reformat a date [syntax reference](http://liquid.rubyforge.org/classes/Liquid/StandardFilters.html#M000012)
 196 * `capitalize` - capitalize words in the input sentence
 197 * `downcase` - convert an input string to lowercase
 198 * `upcase` - convert an input string to uppercase
 199 * `first` - get the first element of the passed in array
 200 * `last` - get the last element of the passed in array
 201 * `join` - join elements of the array with certain character between them
 202 * `sort` - sort elements of the array
 203 * `map` - map/collect an array on a given property
 204 * `size` - return the size of an array or string
 205 * `escape` - escape a string
 206 * `escape_once` - returns an escaped version of html without affecting existing escaped entities
 207 * `strip_html` - strip html from string
 208 * `strip_newlines` - strip all newlines (\n) from string
 209 * `newline_to_br` - replace each newline (\n) with html break
 210 * `replace` - replace each occurrence *e.g.* `{{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'`
 211 * `replace_first` - replace the first occurrence *e.g.* `{{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'`
 212 * `remove` - remove each occurrence *e.g.* `{{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'`
 213 * `remove_first` - remove the first occurrence *e.g.* `{{ 'barbar' | remove_first:'bar' }} #=> 'bar'`
 214 * `truncate` - truncate a string down to x characters
 215 * `truncatewords` - truncate a string down to x words
 216 * `prepend` - prepend a string *e.g.* `{{ 'bar' | prepend:'foo' }} #=> 'foobar'`
 217 * `append` - append a string *e.g.* `{{ 'foo' | append:'bar' }} #=> 'foobar'`
 218 * `minus` - subtraction *e.g.*  `{{ 4 | minus:2 }} #=> 2`
 219 * `plus` - addition *e.g.*  `{{ '1' | plus:'1' }} #=> '11'`, `{{ 1 | plus:1 }} #=> 2`
 220 * `times` - multiplication  *e.g* `{{ 5 | times:4 }} #=> 20`
 221 * `divided_by` - division *e.g.* `{{ 10 | divided_by:2 }} #=> 5`
 222 * `split` - split a string on a matching pattern *e.g.* `{{ "a~b" | split:~ }} #=> ['a','b']`
 223 * `modulo` - remainder, *e.g.* `{{ 3 | modulo:2 }} #=> 1`
 224
 225 ## Tags
 226
 227 Tags are used for the logic in your template. New tags are very easy to code,
 228 so I hope to get many contributions to the standard tag library after releasing
 229 this code.
 230
 231 Here is a list of currently supported tags:
 232
 233 * **assign** - Assigns some value to a variable
 234 * **capture** - Block tag that captures text into a variable
 235 * **case** - Block tag, its the standard case...when block
 236 * **comment** - Block tag, comments out the text in the block
 237 * **cycle** - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
 238 * **for** - For loop
 239 * **if** - Standard if/else block
 240 * **include** - Includes another template; useful for partials
 241 * **raw** - temporarily disable tag processing to avoid syntax conflicts.
 242 * **unless** - Mirror of if statement
 243
 244 ### Comments
 245
 246 Comment is the simplest tag.  It just swallows content.
 247
 248 {% highlight ruby %}
 249 {% raw %}
 250 We made 1 million dollars {% comment %} in losses {% endcomment %} this year
 251 {% endraw %}
 252 {% endhighlight %}
 253
 254 ### Raw
 255
 256 Raw temporarily disables tag processing.
 257 This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
 258
 259 <div class="highlight"><code class="ruby"><span class="nb">
 260 &#123;&#37; raw %}<br>
 261 &nbsp;&nbsp;In Handlebars, &#123;&#123; this }} will be HTML-escaped, but &#123;&#123;&#123; that }}} will not.<br>
 262 &#123;&#37; endraw %}
 263 </span></code>
 264 </div>
 265 <br>
 266
 267 ### If / Else
 268
 269 `if / else` should be well-known from any other programming language.
 270 Liquid allows you to write simple expressions in the `if` or `unless` (and
 271 optionally, `elsif` and `else`) clause:
 272
 273 {% highlight ruby %}
 274 {% raw %}
 275 {% if user %}
 276   Hello {{ user.name }}
 277 {% endif %}
 278
 279 {% if user.name == 'tobi' %}
 280   Hello tobi
 281 {% elsif user.name == 'bob' %}
 282   Hello bob
 283 {% endif %}
 284
 285 {% if user.name == 'tobi' or user.name == 'bob' %}
 286   Hello tobi or bob
 287 {% endif %}
 288
 289 {% if user.name == 'bob' and user.age > 45 %}
 290   Hello old bob
 291 {% endif %}
 292
 293 {% if user.name != 'tobi' %}
 294   Hello non-tobi
 295 {% endif %}
 296
 297 # Same as above
 298 {% unless user.name == 'tobi' %}
 299   Hello non-tobi
 300 {% endunless %}
 301
 302 # Check if the user has a credit card
 303 {% if user.creditcard != null %}
 304    poor sob
 305 {% endif %}
 306
 307 # Same as above
 308 {% if user.creditcard %}
 309    poor sob
 310 {% endif %}
 311
 312 # Check for an empty array
 313 {% if user.payments == empty %}
 314    you never paid !
 315 {% endif %}
 316
 317 {% if user.age > 18 %}
 318    Login here
 319 {% else %}
 320    Sorry, you are too young
 321 {% endif %}
 322
 323 # array = 1,2,3
 324 {% if array contains 2 %}
 325    array includes 2
 326 {% endif %}
 327
 328 # string = 'hello world'
 329 {% if string contains 'hello' %}
 330    string includes 'hello'
 331 {% endif %}
 332 {% endraw %}
 333 {% endhighlight %}
 334
 335 ### Case Statement
 336
 337 If you need more conditions, you can use the `case` statement:
 338
 339 {% highlight ruby %}
 340 {% raw %}
 341 {% case condition %}
 342 {% when 1 %}
 343 hit 1
 344 {% when 2 or 3 %}
 345 hit 2 or 3
 346 {% else %}
 347 ... else ...
 348 {% endcase %}
 349 {% endraw %}
 350 {% endhighlight %}
 351
 352 *Example:*
 353
 354 {% highlight ruby %}
 355 {% raw %}
 356 {% case template %}
 357
 358 {% when 'label' %}
 359      // {{ label.title }}
 360 {% when 'product' %}
 361      // {{ product.vendor | link_to_vendor }} / {{ product.title }}
 362 {% else %}
 363      // {{page_title}}
 364 {% endcase %}
 365 {% endraw %}
 366 {% endhighlight %}
 367
 368 ### Cycle
 369
 370 Often you have to alternate between different colors or similar tasks.  Liquid
 371 has built-in support for such operations, using the `cycle` tag.
 372
 373 {% highlight ruby %}
 374 {% raw %}
 375 {% cycle 'one', 'two', 'three' %}
 376 {% cycle 'one', 'two', 'three' %}
 377 {% cycle 'one', 'two', 'three' %}
 378 {% cycle 'one', 'two', 'three' %}
 379
 380 will result in
 381
 382 one
 383 two
 384 three
 385 one
 386 {% endraw %}
 387 {% endhighlight %}
 388
 389 If no name is supplied for the cycle group, then it's assumed that multiple
 390 calls with the same parameters are one group.
 391
 392 If you want to have total control over cycle groups, you can optionally specify
 393 the name of the group.  This can even be a variable.
 394
 395 {% highlight ruby %}
 396 {% raw %}
 397 {% cycle 'group 1': 'one', 'two', 'three' %}
 398 {% cycle 'group 1': 'one', 'two', 'three' %}
 399 {% cycle 'group 2': 'one', 'two', 'three' %}
 400 {% cycle 'group 2': 'one', 'two', 'three' %}
 401
 402 will result in
 403
 404 one
 405 two
 406 one
 407 two
 408 {% endraw %}
 409 {% endhighlight %}
 410
 411 ### For loops
 412
 413 Liquid allows `for` loops over collections:
 414
 415 {% highlight ruby %}
 416 {% raw %}
 417 {% for item in array %}
 418   {{ item }}
 419 {% endfor %}
 420 {% endraw %}
 421 {% endhighlight %}
 422
 423 During every `for` loop, the following helper variables are available for extra
 424 styling needs:
 425
 426 {% highlight ruby %}
 427 {% raw %}
 428 forloop.length      # => length of the entire for loop
 429 forloop.index       # => index of the current iteration
 430 forloop.index0      # => index of the current iteration (zero based)
 431 forloop.rindex      # => how many items are still left?
 432 forloop.rindex0     # => how many items are still left? (zero based)
 433 forloop.first       # => is this the first iteration?
 434 forloop.last        # => is this the last iteration?
 435 {% endraw %}
 436 {% endhighlight %}
 437
 438 There are several attributes you can use to influence which items you receive in
 439 your loop
 440
 441 `limit:int` lets you restrict how many items you get.
 442 `offset:int` lets you start the collection with the nth item.
 443
 444 {% highlight ruby %}
 445 {% raw %}
 446 # array = [1,2,3,4,5,6]
 447 {% for item in array limit:2 offset:2 %}
 448   {{ item }}
 449 {% endfor %}
 450 # results in 3,4
 451 {% endraw %}
 452 {% endhighlight %}
 453
 454 Reversing the loop
 455
 456 {% highlight ruby %}
 457 {% raw %}
 458 {% for item in collection reversed %} {{item}} {% endfor %}
 459 {% endraw %}
 460 {% endhighlight %}
 461
 462 Instead of looping over an existing collection, you can define a range of
 463 numbers to loop through.  The range can be defined by both literal and variable
 464 numbers:
 465
 466 {% highlight ruby %}
 467 {% raw %}
 468 # if item.quantity is 4...
 469 {% for i in (1..item.quantity) %}
 470   {{ i }}
 471 {% endfor %}
 472 # results in 1,2,3,4
 473 {% endraw %}
 474 {% endhighlight %}
 475
 476 ### Variable Assignment
 477
 478 You can store data in your own variables, to be used in output or other tags as
 479 desired.  The simplest way to create a variable is with the `assign` tag, which
 480 has a pretty straightforward syntax:
 481
 482 {% highlight ruby %}
 483 {% raw %}
 484 {% assign name = 'freestyle' %}
 485
 486 {% for t in collections.tags %}{% if t == name %}
 487   <p>Freestyle!</p>
 488 {% endif %}{% endfor %}
 489 {% endraw %}
 490 {% endhighlight %}
 491
 492 Another way of doing this would be to assign `true / false` values to the
 493 variable:
 494
 495 {% highlight ruby %}
 496 {% raw %}
 497 {% assign freestyle = false %}
 498
 499 {% for t in collections.tags %}{% if t == 'freestyle' %}
 500   {% assign freestyle = true %}
 501 {% endif %}{% endfor %}
 502
 503 {% if freestyle %}
 504   <p>Freestyle!</p>
 505 {% endif %}
 506 {% endraw %}
 507 {% endhighlight %}
 508
 509 If you want to combine a number of strings into a single string and save it to
 510 a variable, you can do that with the `capture` tag. This tag is a block which
 511 "captures" whatever is rendered inside it, then assigns the captured value to
 512 the given variable instead of rendering it to the screen.
 513
 514 {% highlight ruby %}
 515 {% raw %}
 516   {% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}
 517
 518   <label for="{{ attribute_name }}">Color:</label>
 519   <select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}">
 520     <option value="red">Red</option>
 521     <option value="green">Green</option>
 522     <option value="blue">Blue</option>
 523   </select>
 524 {% endraw %}
 525 {% endhighlight %}