README.md

Liquid-Rails

It allows you to render .liquid templates with layout and partial support. It also provides filters, tags, drops class to be used inside your liquid template.

Installation

Add this line to your application's Gemfile:

gem 'liquid-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install liquid-rails

Usage

In order to render with layout, in your layout file app/views/layouts/application.liquid, put this:

{{ content_for_layout }}

# It will render app/views/home/_partial.liquid when the current controller is `HomeController`.
{% include 'partial' %}

# It will render app/views/shared/_partial.liquid.
{% include 'shared/partial' %}

Template Rendering

By default, Liquid-Rails makes all instance variables from controller available to liquid template. To limit only some instance variables, do this inside your controller:

def liquid_assigns
  { 'listing' => current_listing, 'content_for_header' => content_for_header, 'current_account' => current_account }
end

By default, Liquid-Rails makes all your helper methods inside your rails app available to liquid template. To limit only some helpers, do this inside your controller:

def liquid_filters
  []
end

You can render liquid templates from other template engines, eg. erb, haml, ...

= render 'shared/partial.liquid'

Filter

Filters are simple methods that modify the output of numbers, strings, variables and objects. They are placed within an output tag {{ }} and are separated with a pipe character |.

Currently, Liquid-Rails adds only the followings:

1. AssetTagFilter
2. AssetUrlFilter
3. DateFilter
4. NumberFilter
5. SanitizeFilter
6. TextFilter
7. TranslateFilter
8. UrlFilter
9. MiscFilter

Tag

Liquid tags are the programming logic that tells templates what to do. Tags are wrapped in: {% %}.

Currently, Liquid-Rails adds only the followings:

1. csrf_meta_tags
2. google_analytics_tag
3. javascript_tag
4. paginate
5. content_for

Drop Class

Drops let you provide the user with custom functionality. They are very much like a standard Ruby class, but have all unused and potentially dangerous methods removed. From the user's perspective a drop acts very much like a Hash, though methods are accessed with dot-notation as well as element selection. A drop method cannot be invoked with arguments. Drops are called just-in-time, thus allowing you to lazily load objects.

Given two models, a Post(title: string, body: text) and a Comment(name:string, body:text, post_id:integer), you will have two drops:

class PostDrop < Liquid::Rails::Drop
  attributes :id, :title, :body

  has_many :comments
end

and

class CommentDrop < Liquid::Rails::Drop
  attributes :id, :name, :body

  belongs_to :post
end

Check out more examples.

It works for any ORMs. The PORO should include Liquid::Rails::Droppable. That's all you need to do to have your POROs supported.

RSpec

In spec_helper.rb, you'll need to require the matchers:

require 'liquid-rails/matchers'

Example:

describe PostDrop do
  it { should have_attribute(:id) }
  it { should have_attribute(:title) }
  it { should have_attribute(:body) }
  it { should have_many(:comments) }
end

describe CommentDrop do
  it { should have_attribute(:id) }
  it { should have_attribute(:name) }
  it { should have_attribute(:body) }
  it { should belongs_to(:post) }
end

Contributors

• Radin Reth

Authors

• Chamnap Chhorn