liquex v0.2.1 Liquex View Source
Liquid template renderer for Elixir with a goal of 100% compatibility with the Liquid gem by Shopify.
Basic Usage
iex> {:ok, template_ast} = Liquex.parse("Hello {{ name }}!")
iex> context = Liquex.Context.new(%{"name" => "World"})
iex> {content, _context} = Liquex.render(template_ast, context)
iex> content |> to_string()
"Hello World!"
Supported features
Currently, all standard Liquid tags, filters, and types are fully supported. Liquex can be considered a drop in replacement of the Liquid gem, but in Elixir.
There is a caveat that must be noted:
Whitespace control is partially supported.
Whitespace control is only partially
supported. Whitespace is successfully removed after -%}
and -}}
tags. However, whitespace
isn't removed from the left side yet, before {%-
and {{-
. This is because we're using
NimbleParsec which does not support greedy matches.
Instead, we will need to do post processing to properly remove spaces. As whitespace control is
deemed of low importance for most applications, this has not been prioritized.
Custom filters
Liquex contains the full suite of standard Liquid filters, but you may find that there are still filters that you may want to add.
Liquex supports adding your own custom filters to the render pipeline. When creating the context for the renderer, set the filter module to your own module.
defmodule CustomFilter do
# Import all the standard liquid filters
use Liquex.Filter
def scream(value, _), do: String.upcase(value) <> "!"
end
context = %Liquex.Context{filter_module: CustomFilter},
{:ok, template_ast} = Liquex.parse("{{'Hello World' | scream}}",
{result, _} = Liquex.render(template_ast, context)
result |> to_string()
iex> "HELLO WORLD!"
Custom tags
One of the strong points for Liquex is that the tag parser can be extended to support non-standard tags. For example, Liquid used internally for the Shopify site includes a large range of tags that are not supported by the base Ruby gem. These tags could also be added to Liquex by extending the liquid parser.
defmodule CustomTag do
import NimbleParsec
alias Liquex.Parser.Base
# Parse <<Custom Tag>>
def custom_tag(combinator \\ empty()) do
text =
lookahead_not(string(">>"))
|> utf8_char([])
|> times(min: 1)
|> reduce({Kernel, :to_string, []})
|> tag(:text)
combinator
|> ignore(string("<<"))
|> optional(text)
|> ignore(string(">>"))
|> tag(:custom_tag)
end
def element(combinator \\ empty()) do
# Add the `custom_tag/1` parsing function to the supported element tag list
combinator
|> choice([custom_tag(), Base.base_element()])
end
end
defmodule CustomParser do
@moduledoc false
import NimbleParsec
defcombinatorp(:document, repeat(CustomTag.element()))
defparsec(:parse, parsec(:document) |> eos())
end
iex> Liquex.parse("<<Hello World!>>", CustomParser)
iex> {:ok, [custom_tag: [text: ["Hello World!"]]]}
Custom renderer
In many cases, if you are building custom tags for your Liquid documents, you probably want to use a custom renderer. Just like the custom filters, you add your module to the context object.
defmodule CustomRenderer do
def render({:custom_tag, contents}, context) do
{result, context} = Liquex.render(contents, context)
{["Custom Tag: ", result], context}
end
end
context = %Liquex.Context{render_module: CustomRenderer}
{:ok, document} = Liquex.parse("<<Hello World!>>", CustomParser)
{result, _} = Liquex.render(document, context)
result |> to_string()
iex> "Custom Tag: Hello World!"
Installation
Add the package to your mix.exs
file.
def deps do
[{:liquex, "~> 0.1.1"}]
end
Link to this section Summary
Functions
Parses a liquid template
string using the given parser
.
Renders a Liquid AST document
into an iolist
Link to this section Types
document_t()
View Sourcedocument_t() :: [ control_flow: nonempty_maybe_improper_list(), iteration: [...], object: [...], text: any(), variable: [...] ]
Link to this section Functions
parse(template, parser \\ Liquex.Parser)
View Sourceparse(String.t(), module()) :: {:ok, document_t()} | {:error, String.t(), pos_integer()}
Parses a liquid template
string using the given parser
.
Returns a liquid AST document or the parser error
render(document, context \\ %Context{})
View Sourcerender(document_t(), Liquex.Context.t()) :: {iolist(), Liquex.Context.t()}
Renders a Liquid AST document
into an iolist
A context
is given to handle temporary contextual information for
this render.