Repository files navigation

Liquor is a safe and extensible templating language that compiles to Ruby.It can be thought of as a replacement ofLiquid,though it does not provide a migration path.

Add this line to your application's Gemfile:

gem 'liquor'

And then execute:

$ bundle

Or install it yourself as:

$ gem install liquor

The language is described inthe specification.

The Liquor templates are rendered in two stages. First, you need to compile them usingLiquor::Manager. Assumingtemplates is a hash mapping template names to contents and predefined variables, the following code demonstrates the usage ofLiquor::Manager:

manager=Liquor::Manager.newtemplates.eachdo |name,(body,predefined)|ifmanager.partial?namemanager.register_partialname,bodyelsemanager.register_templatename,body,predefinedendendunlessmanager.compilemanager.errors.eachdo |error|source, *=templates[error.location[:file]]putserror.decorate(source)endend

Theerror.decorate call will extract the corresponding line from the source and highlight the character range that caused the error.

Thecontext is a hash that is shared between the layout and the inner template. Thelayout_environment andinner_environment contain the list of variables initially provided to corresponding template; it must match the value ofpredefined of the template at compilation time.

context ||={}# Production-mode codediagnostics=Liquor::Runtime.capture_diagnosticsdoinner=manager.render(template_name,inner_environment,context)manager.render(layout_name,layout_environment,context.merge(_inner_template:inner))end# Development-mode codeLiquor::Runtime.with_fatal_deprecationsdo# idemend

The difference between development-mode and production-mode code is that in development mode, all runtime errors are raised asLiquor::Diagnostic exceptions, and in production mode, they are returned fromLiquor::Runtime.capture_diagnostics instead.

The code to perform decoration of the errors is the same as for compile-time errors.

Additionally, both development-mode and production-mode code can raiseLiquor::HostError at render time, reserved for uncaught Ruby exceptions inside Liquor code.

Liquorfunctions are similar to Ruby functions. They should not have any side effects. To learn how to define your own Liquor functions, seelib/stdlib/builtin_functions.rb.

Liquortags provide means for inserting arbitrary Ruby code in the compiled output. They can do almost anything, and can have side effects. To learn how to define your own Liquor tags, seelib/stdlib/builtin_tags.rb.

Both functions and tags are organized inlibraries. A Liquor library looks like this:

moduleLiquorFooincludeLiquor::Libraryfunction# ...tag# ...end

The libraries should be provided to theLiquor::Manager constructor, e.g.Liquor::Manager.new(import: [LiquorFoo]).

Liquor represents primitive Liquor objects (null, booleans, integers, strings and tuples) using the corresponding primitive Ruby objects, so they can be passed as-is. Liquor does not extend core Ruby classes.

All other objects must includeLiquor::External in order to be accessible from Liquor. They need to callexport on module level to explicitly mark functions as accessible to Liquor. The functions always receive two arguments: the unnamed argument and the hash of keyword arguments, e.g.:

classFooExternalincludeLiquor::Externaldefmeth(arg,kwargs)# ...endexport:meth

Additionally, external methods can be deprecated usingdeprecate :meth, date: '2014-11-11', message: 'meth is deprecated, use meth1 instead'. Thedate (i.e. the intended date of final removal) andmessage will appear in the message of the emittedLiquor::Diagnostic. The diagnostic will only be emitted when the method is actually called.

Liquor contains code to integrate with some popular libraries

Liquor contains built-in support for passing ActiveRecord scopes and model instances as externals. To use it,require 'liquor/dropable', theninclude Liquor::Dropable in the model, and then simply pass the scope or model instance to the template.

Liquor contains a Rails renderer for Liquor templates that supports layouts. To use it `require 'liquor/extensions/rails', then use the following code in your actions:

renderliquor:{manager:manager,template:template_name,layout:layout_name,environment:environment,}

See the section "Renering templates" for the meaning of the renderer arguments.

To use Kaminari integration,require 'liquor/extensions/kaminari'. This will monkey-patchKaminari::PaginatableArray and allow to pass any object paginated by Kaminari to Liquor templates.

To use Tire integration,require 'liquor/extensions/tire'. This will monkey-patchTire::Results::Collection andTire::Search::Search and allow to pass any object generated by Tire to Liquor templates.

To use ThinkingSphinx integration,require 'liquor/extensions/thinking_sphinx'. This will monkey-patchThinkingSphinx::Search and allow to pass any object generated by ThinkingSphinx to Liquor templates.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Liquor is distributed under the terms ofMIT license.