Package Exports

liquid-to-handlebars

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (liquid-to-handlebars) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

liquid-to-handlebars

Convert liquid templates to handlebars templates.

Why use this?

If you've ever seen a jekyll boilerplate, or another project that uses liquid templates and wished it was written in handlebars, this is your solution!

100% of the tags mentioned in the shopify liquid documentation convert to handlebars syntax
easily migrate any liquid theme or boilerplate
use more powerful and flexible handlebars helpers instead of liquid filters

Please create an issue if you find a tag that doesn't convert correctly, and I'll add support. Thanks!

Usage

var convert = require('liquid-to-handlebars');
// Converts this liquid
console.log(convert('Price: ${{ product_price | default: 2.99 }}'));
// To this handlebars
//=> 'Price: ${{default product_price 2.99}}'

You will also need to include any missing handlebars helpers that provide similar functionality to the liquid filters that are being replaced. For example:

var hbs = require('handlebars');
hbs.registerHelper('default', function(a, b) {
  return a || b || '';
});
var fn = hbs.compile('Price: ${{default product_price 2.99}}');
console.log(fn());
//=> 'Price: $2.99'

console.log(fn({default_price: '4.99'}));
//=> 'Price: $4.99'

Migration debugging

Once your liquid templates are converted to handlebars, if you attempt to render all of the templates with handlebars without any additional work, it's a good bet that you'll receive a bunch of errors from missing helpers.

Save yourself a bunch of time and frustration by following these steps:

Step 1: Add starter helpers

Add the following to your app:

var hbs = require('handlebars');

// override handlebars' built-in `helperMissing` helper, 
// so that we can easily see which helpers are missing
// and get them fixed
hbs.registerHelper('helperMissing', function() {
  var opts = [].slice.call(arguments).pop();
  console.log(`missing helper {{${opts.name}}}`);
});

Step 2: Run handlebars

Now, when you run handlebars, if you see a message like this:

missing helper {{foo}}

You can either create the foo helper from scratch, or use a helper library that already includes the helpers you need.

Any of the following libraries may be used, but the [liquid-filters][] library might be most useful (during migration, at least).

[liquid-filters][] - includes a bunch of utility javascript functions that can be registered as handlebars helpers to provide parity with the built-in liquid filters
template-helpers - generic helpers that can be used with any template engine.
handlebars-helpers - more than 150 handlebars helpers

Examples

var hbs = require('handlebars');
var filters = require('liquid-filters');
var helpers = require('template-helpers');

hbs.registerHelper(filters());
hbs.registerHelper(helpers());

Examples

There are many more examples in the docs folder, as well as test/fixtures and test/expected.

Conditionals

basic operators

From this liquid:

{% if product.type == "Shirt" or product.type == "Shoes" %}
  This is a shirt or a pair of shoes.
{% endif %}

To this handlebars:

{{#if (or (is product.type "Shirt") (is product.type "Shoes"))}}
  This is a shirt or a pair of shoes.
{{/if}}

boolean

From this liquid:

{% if settings.fp_heading %}
  <h1>{{ settings.fp_heading }}</h1>
{% endif %}

To this handlebars:

{{#if settings.fp_heading}}
  <h1>{{ settings.fp_heading }}</h1>
{{/if}}

case

From this liquid:

{% case handle %}
{% when 'cake' %}
  This is a cake
{% when 'cookie' %}
  This is a cookie
{% else %}
  This is not a cookie/cake
{% endcase %}

To this handlebars:

{{#is handle 'cake'}}
  This is a cake
{{else is handle 'cookie'}}
  This is a cookie
{{ else }}
  This is not a cookie/cake
{{/is}}

Requires the "is" helper.

else

From this liquid:

{% if username and username.size > 10 %}
  Wow, {{ username }}, you have a long name!
{% else %}
  Hello there!
{% endif %}

To this handlebars:

{{#if (and username (gt username.size 10))}}
  Wow, {{ username }}, you have a long name!
{{else}}
  Hello there!
{{/if}}

contains

From this liquid:

{% if product.title contains 'Pack' %}
  This product's title contains the word Pack.
{% endif %}

To this handlebars:

{{#if (contains product.title "Pack")}}
  This product's title contains the word Pack.
{{/if}}

Arrays

Basic loops

From this liquid:

<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{% for user in site.users %}
  {{ user }}
{% endfor %}

To this handlebars:

<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{{#each site.users as |user|}}
  {{ user }}
{{/each}}

Accessing specific items in arrays

From this liquid:

<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[3] }}

To this handlebars:

<!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
{{get site.users 0}}
{{get site.users 1}}
{{get site.users 3}}

Filters

From this liquid:

{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}

To this handlebars:

{{join (reverse (split "Ground control to Major Tom." "")) ""}}

Many more examples in the docs folder and unit tests.

What is this?

This is a tool for converting projects that use liquid templates to use handlebars templates.

Why convert to handlebars?

A few reasons:

Liquid is a solid template engine, but it's more idiomatic for ruby users and IMHO is less than ideal for users in the javascript community.
Since liquid is the template engine of choice for Jekyll, GitHub's blog engine, there are numerous scaffolds, themes and boilerplates available for building blogs and gh-pages or other static sites using liquid. It would be nice if these were available in a templating language more friendly to javascript devs.
Handlebars is more powerful, is easier to use, and easier to extend and develop around.
Why re-create each boilerplate 100% hand when you can automate the vast majority of it, on demand?

The tipping point was when I recently spent a few hours converting a liquid project over to handlebars by hand, and I realized I would need to repeat that process every time I found a liquid resource I wanted to use.

This converter took me a day to create, but I can now use any liquid resource with very little if any time spent on converting templates at all.

About

assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
handlebars: Handlebars provides the power necessary to let you build semantic templates effectively with no frustration | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

License

This file was generated by verb-generate-readme, v0.6.0, on June 15, 2017.