Skip to content

amberframework/liquid.cr

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

liquid - Liquid template engine for Crystal

Build Status Version License

Liquid templating language: http://shopify.github.io/liquid/

Installation

Add this to your application's shard.yml:

dependencies:
  liquid:
    github: amberframework/liquid.cr

Usage

require "liquid"

txt = "
    {% if kenny.sick %}
      Kenny is sick.
    {% elsif kenny.dead %}
      You killed Kenny!  You ***!!!
    {% else %}
      Kenny looks okay --- so far
    {% endif %}
    "
ctx = Liquid::Context.new
ctx.set "kenny", Any{ "sick" => false, "dead" => true}

tpl = Liquid::Template.parse txt  # tpl can be cached and reused

result = tpl.render ctx

# result = "
#      You killed Kenny!  You ***!!!
#
#    "

Tags can be escaped:

\{% assign myvar = 15 %}

# or

{% raw %}
{% assign myvar = 15 %}
{% endraw %}

will both render {% assign myvar = 15 %}.

Blocks

Cache block (only supports caching using Redis): https://github.com/TechMagister/liquid-cache.cr

Filters

  • abs
  • append
  • at_least
  • at_most
  • capitalize
  • ceil
  • compact
  • concat
  • date
  • default
  • divided_by
  • downcase
  • escape
  • escape_once
  • first
  • floor
  • join
  • last
  • lstrip
  • map
  • minus
  • modulo
  • newline_to_br
  • plus
  • prepend
  • remove
  • remove_first
  • replace
  • replace_first
  • reverse
  • round
  • rstrip
  • size
  • slice
  • sort
  • sort_natural
  • split
  • strip
  • strip_html
  • strip_newlines
  • times
  • truncate
  • truncatewords
  • uniq
  • upcase
  • url_decode
  • url_encode
  • where

Helper Methods

  • size (for Array and String)
  • present / blank (added)
  • first / last

Development

TODO:

  • Basic For loops
  • if/elsif/else/endif
  • unless/endunless
  • Raw and comment blocks ({% raw %} and {% comment %})
  • Add variable assignment ({% assign var = "Hello World" %})
  • Add support for multiple operator (no operator precedence support (for now))
  • Add support for Array into for loop
  • Add support for Hash into for loop ({% for val in myhash %}, access as val[0] and val[1])
  • Add support for Hash into for loop ({% for key, val in myhash %}) (new)
  • Add support for Float
  • Add iteration over Arrays
  • Improve data interface
  • Add Filter support
  • Add capture block
  • Add increment block
  • Add decrement block
  • Add support for Array in expressions
  • Add support for Hash in expressions
  • Add "secret" empty Array ([]) for use in comparisons (equivalent to #blank helper method)
  • Add contains operator
  • Add cycle keyword
  • Add starts_with keyword (new)
  • Add ends_with keyword (new)
  • Add continue keyword
  • Add break keyword
  • Add case/when
  • Add syntax checking
  • Improve expression parsing
  • Add optional strict mode on Context (see below)
  • Add Everything that's missing [https://shopify.github.io/liquid/]

Context Strict Mode

NOTE: Will eventually use this to implement a strict_variables rendering flag (planning to implement strict_filters as well).

Enable at initialization:

ctx = Liquid::Context.new(:strict)

Or on an existing Context:

ctx.error_mode = :strict

Raises Liquid::InvalidExpression on missing keys and silently emit nil on array out of bounds.

Append ? to emit nil in strict mode (very simplistic, just checks for ? at the end of the identifier)

ctx = Liquid::Context.new(:strict)
ctx["obj"] = { something: "something" }
{{ missing }}          -> nil, but generates a UndefinedVariable errors if not in Lax mode.
{{ obj.missing }}      -> InvalidExpression
{{ missing.missing? }} -> generates a UndefinedVariable error, evaluates `missing` to nil then raises a InvalidExpression due to `nil.missing` call.

Contributing

  1. Fork it ( https://github.com/amberframework/liquid.cr/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors