Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Extends Rails with liquid-powered views stored in the database
tag: v0.2.1

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



Liquidizer is a gem for Ruby on Rails that allows to render pages using templates stored in the database. It uses liquid ( templating system (thus the name), because it's easy to use, extend and it's safe to edit by users.

One example of when you might want to use it is this: Let's say you want to have a blogging system where people can create their blogs about kittens, ninjas or vampires. Using this gem, you can allow them to edit the look and feel of their blog using just their browser. Every blog can have it's own set of templates.


It's hosted on Add it to your source list if you don't have it already:

sudo gem source --add

Then install:

sudo gem install liquidizer

And add this to your config/environment.rb:

config.gem 'liquidizer'

How to use

First you have to specify which actions of which controllers should be liquified (rendered with loadable liquid templates). To do that, use the liquify controller macro:

class PostController < ApplicationController
  # This will apply the templates to all actions in this controller.

If you want to liquify only some actions, but leave the others to be rendered using standard Rails means, do this:

class PostController < ApplicationController
  # Liquify only :show and :index.
  liquify :show, :index

By default, Liquidizer will infer liquid template names from the controller and action name in the same way Rails does. So action index in controller PostsController will have template called “posts/index”. Namespaced controllers work too: index in Blog::PostsController will have template “blog/posts/index”. This, however, can be overriden:

class PostController < ApplicationController
  # This will liquify only show, but will use template called "awesome_show_template"
  liquify :show, :as => 'awesome_show_template'

The liquify macro is inherited, so if you want to apply liquid templates to all actions in all controller, put it into ApplicationController. You can fine-tune it in derived controllers, if you want:

class ApplicationController < ActionController::Base

class PostsController < ApplicationController
  liquify :show,  :as => 'kickass_show'
  liquify :index, :as => 'hardcore_index'

To liquify also layouts, use the liquify_layout macro:

class ApplicationController < ActionController::Base
  # This will use layout called "layout"

  # This will use layout called "awesome_kickass_layout"
  liquify_layout :as => "awesome_kickass_layout"

The last step is to tell Liquidizer where to load the liquid templates from. The way to implement this is completely up to you. For example, you can associate the templates with the Blog model (to follow the blog example) and have something like current_blog, which is loaded by the current subdomain.

In any case, you need to provide a current_liquid_templates method, which should return collection of liquid templates to use. This method should return something that responds at least to find_by_name which returns an object that responds to content which returns a string containing the liquid template.

The easies way to do this, is to have a LiquidTemplate model and return a collections of those in the current_liquid_templates. Liquidizer provides one such model for you, but you will probably want to use your own. To make your life easier, there is a module Liquidizer::LiquidTemplate which you can include into your template model to extend it with some helpful methods (see the docs for more info):

class Blog < ActiveRecord::Base
  has_many :liquid_templates

# The 
class LiquidTemplate < ActiveRecord::Base
  include Liquidizer::LiquidTemplate
  belongs_to :blog

class ApplicationController < ActionController::Base

  def current_liquid_templates

And that's it. You are now ready to kick asses!

Instance variables

All instance variables that you assign in the controller are automatically available in the liquid templates. The variable will be automatically wrapped in a “drop”, if necessary (please check the liquid docs for more details about what types can be passed directly to liquid templates and what are drops). For a class Foo, a FooDrop will be used if it exists. If variable is not compatible with liquid and there is no corresponding drop class, it won't be passed to the template.


A controller:

class PostsController < ActiveRecord::Base

  def show
    @post = current_blog.posts.find(params[:id])

A drop:

class PostDrop < Liquid::Drop
  def initialize(post)
    @post = post

  def title

Then you can do this in your liquid template:

<h1>{{ post.title }}</h1>

<!-- more stuff ... -->

And the post.title will call PostDrop#title, filtering all nasty stuff.

The way how variables are wrapped with drops can be completelly customized by overriding the dropify method.

Default templates

The Liquidizer::LiquidTemplate module gives your model capability to fallback to a default template, if one is not found in the database. The default templates are stored in db/liquid_templates. You can configure this location by setting the Liquidizer.template_path:

Liqduidizer.template_path = Rails.root.join('app', 'views', 'liquid_templates')


There are several possible improvements to this gem:

  • Extend it so it can handle different template systems in addition (unlikely, since I don't need it and can't be bothered :) )

  • The Rails 3 has improved ActionView API and as far as I understand, abstracts away the concept of template storage. Taking advantage of this could potentialy simplify this gem. Also, support Rails 3 in general would be nice.

  • This does some nasty hacks into the ActionController::Base's render method. That method originaly has quite liberal API, allowing to specify it's parameters in many ways. To make this gem simple, some of those ways were sacrificed. Would be nice to support them too.

Potentialy many more. In any case, it's open source project (MIT), so no fear, fork me and hack away!

Legal stuff

Copyright © 2010 Adam Cigánek <>. Released under the MIT License:

Something went wrong with that request. Please try again.