Liquid.js

General

This is a complete port of Liquid from Ruby to JavaScript. Any template that Ruby Liquid can compile and render, Liquid.js should too.

This tries to be javascript framework agnostic (i.e. doesn’t use jQuery nor Prototype). This adds a little extra code as it implements its own helpers like clear, first, last on Array, and a Class OOP implementation; this tradeoff is made to allow the code to be portable across many systems.

Liquid.js does not use eval or with, so it’s pretty clean and really safe.

Installation

Currently the js files are not checked under source control since they are generated. In order to install, follow these steps:

1. Clone the repository somewhere locally and go into the folder; i.e. ‘git clone git@github.com:edfuh/liquid.js.git’.
2. Compile the javascripts with the bundled rake task; i.e. ‘bundle exec rake’.
3. Copy the distribution files to your desired location; i.e. ‘cp dist/liquid*.js ~/projects/my_project/public/javascripts/’.

Differences

1. Ranges. JavaScript doesn’t have Ranges like Ruby does. So when Liquid.js comes across a range “(1..5)”, it creates an Array with the values 1 through 5. In addition ranges like (a..z) should work.
2. ‘replace’ and ‘replace_first’ filters build RegExps from the input, so you can actually define a regexp to use in your replacement.
3. ‘include’ tag. By default, this will return a Liquid error (but not an exception). To use the ‘include’ tag, you’ll need to implement your own ‘filesystem’ support. Which, in Liquid.js, just means you override the Liquid.readTemplateFile function to suit your own needs. Here’s an example:

<script>
  
  Liquid.readTemplateFile = function(path) {
    var elem = $(path);
    if(elem) {
      return elem.innerHTML;
    } else {
      return path +" can't be found."; 
      // Or throw and error, or whatever you want...
    }
  }
  
  var src = "{% include 'myOtherTemplate' with current_user %}";

  var tmpl = Liquid.parse( src );
  
  alert( tmpl.render({ current_user:'M@' }));
  
</script>
<!-- Browsers ignore script blocks with an unrecognized type.  -->
<!-- Makes for pretty good inline template storage.  -->
<script type="text/liquid" id="myOtherTemplate">
  Hello, {{ current_user }}!
</script>

Known Issues

1. Known to work in Safari 3.1+ and FireFox 3+.
2. IE 7: passes tests but needs more actual usage testing

References:

• http://wiki.shopify.com/UsingLiquid

Contributing

1. Fork project
2. Make changes
3. Add tests
4. Pull request
5. ????
6. Profit!!!!

Todo

• Add full Node support
• Look at the Object extensions and consider making a Liquid.Hash class similar to Prototype.
• Replace YUI with Uglify
• Use grunt instead of rake