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

The current version of the library is checked into the dist directory.

To re-build from source, follow these steps:

1. Clone the repository somewhere locally and go into the folder; i.e. git clone gitgithub.com:/mattmccray/liquid.js.git@.
2. Run bundle install to install the necessary Gemfiles.
3. Compile the JavaScript files with the default rake task; i.e. bundle exec rake.
4. 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 really 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

Development

1. Fork the project on github.
2. Follow the installation steps with your repository.
3. Load the test/liquid-tests.html file to execute the tests; i.e. in a web browser load ‘file:///home/username/projects/liquid.js/test/liquid-tests.html’.
4. Load the test/liquid-console.html to debug specific templates or test scenarios; i.e. in a web browser load ‘file:///home/username/projects/liquid.js/test/liquid-tests.html’.
5. NOTE: It is recommended to use Chrome or Firefox (with Firebug) for development so you can see javascript errors in detail.

Todo

• Add support for console-based testing?
• Move the Class OOP support (that replaced Prototype) into Liquid.Class so it won’t conflict with other implementations.
• Look at the Object extensions and consider making a Liquid.Hash class similar to Prototype.
• Look into making into a gem or something that has the auto-compiled JS file in the workflow somewhere.