# Liquex
A [Liquid](https://shopify.github.io/liquid/) template parser for Elixir.
Liquid template renderer for Elixir with 100% compatibility with the
[Liquid](https://shopify.github.io/liquid/) gem by [Shopify](https://www.shopify.com/).
If you find that this library is not byte for byte equivalent to liquid, please
[open an issue](https://github.com/markglenn/liquex/issues).
## Installation
The package is [available in Hex](https://hex.pm/packages/liquex) and can be installed
by adding `liquex` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:liquex, "~> 0.15.0"}
]
end
```
Documentation can be found at [https://hexdocs.pm/liquex](https://hexdocs.pm/liquex).
## Basic Usage
```elixir
iex> {:ok, template_ast} = Liquex.parse("Hello {{ name }}!")
iex> {content, _context} = Liquex.render!(template_ast, %{"name" => "World"})
iex> content |> to_string()
"Hello World!"
```
## Supported features
Liquex is byte for byte, 100% compatible with the latest Liquid gem.
## Drops
For values that need to call out to user code on every `.` traversal —
typically database-backed objects in a Shopify-style template — implement
`Liquex.Drop` on a struct. Liquex memoizes the results of every Drop
fetch for the duration of a single render, so
```liquid
{{ products.first.category.name }}
... lots of unrelated template ...
{{ products.first.category.name }}
```
only runs the underlying database queries once.
```elixir
defmodule MyApp.ProductsDrop do
@behaviour Liquex.Drop
defstruct [:scope]
@impl true
def fetch(%__MODULE__{scope: scope}, key, _context) when key in ["first", :first] do
{:ok, MyApp.Repo.one(from p in scope, limit: 1)}
end
def fetch(_, _, _), do: :error
end
```
The cache lifetime is exactly one `Liquex.render!/2` call: it starts empty,
populates as Drop traversals happen, and is discarded when the render
returns. There is no invalidation API and no cross-render leakage — two
concurrent renders keep separate caches. `{% render %}` partials inherit
the parent's cache.
Stateful Drops (paginators, generators) opt out of memoization with one
line:
```elixir
@impl true
def cacheable?(_drop), do: false
```
Plain structs without `@behaviour Liquex.Drop` are readable from
templates via direct field access (atom or string keys) but cannot
resolve dynamic keys or compute on access.
## Lazy variables
Liquex allows resolver functions for variables that may require some extra
work to generate. For example, Shopify has variables for things like
available products. Pulling all products every time would be too expensive
to do on every render. Instead, it would be better to lazily pull that
information as needed.
Instead of adding the product list to the context variable map, you can add
a function to the variable map. If a function is accessed in the variable
map, it is executed.
```elixir
products_resolver = fn _parent -> Product.all() end
with {:ok, document} <- Liquex.parse("There are {{ products.size }} products"),
{result, _} <- Liquex.render!(document, %{products: products_resolver}) do
result
end
"There are 5 products"
```
## Indifferent access
By default, Liquex accesses your maps and structs that may have atom or
string (or other type) keys. Liquex will try a string key first. If that
fails, it will fall back to using an atom keys. This is similar to how
Ruby on Rails handles many of its hashes.
This allows you to pass in your structs without having to replace all your
keys with string keys.
```elixir
iex> {:ok, template_ast} = Liquex.parse("Hello {{ name }}!")
iex> {content, _context} = Liquex.render!(template_ast, %{name: "World"})
iex> content |> to_string()
"Hello World!"
```
## Caching
Liquex has a built in cache used specifically for the render tag currently. When
loading a partial/sub-template using the render tag, it will try pulling from
the cache associated with the context.
By default, caching is disabled, but you may use the built in ETS based cache by
configuring it in your context.
```elixir
:ok = Liquex.Cache.SimpleCache.init()
context = Context.new(%{...}, cache: Liquex.Cache.SimpleCache)
```
The simple cache is by definition quite simple. To use a more complete caching
system, such as [Cachex](https://github.com/whitfin/cachex), you can create a
module that implements the `Liquex.Cache` behaviour.
The cache system is very early on. It is expected that it will also be used to
memoize some of the variables within your context.
## 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.
```elixir
defmodule CustomFilter do
# Import all the standard liquid filters
use Liquex.Filter
def scream(value, _), do: String.upcase(value) <> "!"
end
context = Liquex.Context.new(%{}, 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.
```elixir
defmodule CustomTag do
@moduledoc false
@behaviour Liquex.Tag
import NimbleParsec
@impl true
# Parse <<Custom Tag>>
def parse() do
text =
lookahead_not(string(">>"))
|> utf8_char([])
|> times(min: 1)
|> reduce({Kernel, :to_string, []})
|> tag(:text)
ignore(string("<<"))
|> optional(text)
|> ignore(string(">>"))
end
@impl true
def render(contents, context) do
{result, context} = Liquex.render!(contents, context)
{["Custom Tag: ", result], context}
end
end
defmodule CustomParser do
use Liquex.Parser, tags: [CustomTag]
end
iex> document = Liquex.parse!("<<Hello World!>>", CustomParser)
iex> {result, _} = Liquex.render!(document, context)
iex> result |> to_string()
"Custom Tag: Hello World!"
```
## Error handling
Parse errors carry a line, a column, and a small excerpt with a caret
pointing at the failure. `Liquex.parse!/2` raises a formatted
`Liquex.Error`; `Liquex.parse/2` returns `{:error, reason, line}`.
```
** (Liquex.Error) Liquid parse error at line 3, column 1: unexpected `{% endfor %}` (expected `{% endif %}` to close block opened at line 1)
2 | hello
3 | {% endfor %}
^
```
Render-time failures (unknown filters, stray `{% break %}`/`{% continue %}`
outside an iteration) are governed by an `:error_mode` option on the
context — `:strict | :warn | :lax`, default `:lax`:
```elixir
{:ok, ast} = Liquex.parse("{{ x | upcas }}")
# :lax (default) — silent
ctx = Liquex.Context.new(%{"x" => "hi"})
{result, ctx} = Liquex.render!(ast, ctx)
# result is "hi", ctx.errors is []
# :warn — collects errors
ctx = Liquex.Context.new(%{"x" => "hi"}, error_mode: :warn)
{result, ctx} = Liquex.render!(ast, ctx)
# ctx.errors has %Liquex.Error{message: "Invalid filter upcas (did you mean `upcase`?)"}
# :strict — raises
ctx = Liquex.Context.new(%{"x" => "hi"}, error_mode: :strict)
Liquex.render!(ast, ctx)
# ** (Liquex.Error) Invalid filter upcas (did you mean `upcase`?)
```
A separate `:strict_variables` flag (default `false`) routes undefined
variable lookups through the same `:error_mode` so missing references
can be caught instead of silently rendering as empty.
## Deviations from original Liquid gem
### Whitespace is kept in empty blocks
For performance reasons, whitespace is kept within empty blocks such as
for/if/unless. The liquid gem checks for "blank" renders and throws them away.
Instead, we continue to use IO lists to combine the output and don't check for
blank results to avoid too many conversions to strings. Since Liquid is mostly
used for whitespace agnostic documents, this seemed like a decent tradeoff. If
you need better whitespace control, use `{%-`, `{{-`, `-%}`, and `-}}`.
### Multi-key hash ordering
`{{ h }}` for `%{"b" => 2, "a" => 1}` renders `{"a"=>1, "b"=>2}` in Liquex
versus `{"b"=>2, "a"=>1}` in Ruby Liquid (which preserves hash insertion
order natively). This is intentional: matching Ruby would require routing
every map-using code path through a wrapper struct with O(n) lookups,
which would slow every `{{ h.key }}` access. Liquex is built to be faster
than the Ruby Liquid engine, and that takes priority over byte-for-byte
hash-inspect parity.
If your templates rely on inspecting whole hashes (rather than reading
specific fields), pre-serialize the hash to a string before passing it
into the context, or render fields explicitly.
