class Liquid::Template

Templates are central to liquid. Interpretating templates is a two step process. First you compile the source code you got. During compile time some extensive error checking is performed. your code should expect to get some SyntaxErrors.

After you have a compiled template you can then render it. You can use a compiled template over and over again and keep it cached.

Example:

template = Liquid::Template.parse(source)
template.render('user_name' => 'bob')

Constants

DEFAULT_OPTIONS

Attributes

error_mode[W]

Sets how strict the parser should be. :lax acts like liquid 2.5 and silently ignores malformed tags in most cases. :warn is the default and will give deprecation warnings when invalid syntax is used. :strict will enforce correct syntax.

taint_mode[W]

Sets how strict the taint checker should be. :lax is the default, and ignores the taint flag completely :warn adds a warning, but does not interrupt the rendering :error raises an error when tainted output is used

profiler[R]
resource_limits[RW]
root[RW]

Public Class Methods

default_resource_limits() click to toggle source
# File lib/liquid/template.rb, line 99
def default_resource_limits
  @default_resource_limits ||= {}
end
error_mode() click to toggle source
# File lib/liquid/template.rb, line 85
def error_mode
  @error_mode || :lax
end
file_system() click to toggle source
# File lib/liquid/template.rb, line 69
def file_system
  @@file_system
end
file_system=(obj) click to toggle source
# File lib/liquid/template.rb, line 73
def file_system=(obj)
  @@file_system = obj
end
new() click to toggle source
# File lib/liquid/template.rb, line 112
def initialize
  @resource_limits = self.class.default_resource_limits.dup
end
parse(source, options = {}) click to toggle source

creates a new Template object from liquid source code To enable profiling, pass in profile: true as an option. See Liquid::Profiler for more information

# File lib/liquid/template.rb, line 106
def parse(source, options = {})
  template = Template.new
  template.parse(source, options)
end
register_filter(mod) click to toggle source

Pass a module with filter methods which should be available to all liquid views. Good for registering the standard library

# File lib/liquid/template.rb, line 95
def register_filter(mod)
  Strainer.global_filter(mod)
end
register_tag(name, klass) click to toggle source
# File lib/liquid/template.rb, line 77
def register_tag(name, klass)
  tags[name.to_s] = klass
end
tags() click to toggle source
# File lib/liquid/template.rb, line 81
def tags
  @tags ||= TagRegistry.new
end
taint_mode() click to toggle source
# File lib/liquid/template.rb, line 89
def taint_mode
  @taint_mode || :lax
end

Public Instance Methods

assigns() click to toggle source
# File lib/liquid/template.rb, line 136
def assigns
  @assigns ||= {}
end
errors() click to toggle source
# File lib/liquid/template.rb, line 144
def errors
  @errors ||= []
end
instance_assigns() click to toggle source
# File lib/liquid/template.rb, line 140
def instance_assigns
  @instance_assigns ||= {}
end
parse(source, options = {}) click to toggle source

Parse source code. Returns self for easy chaining

# File lib/liquid/template.rb, line 118
def parse(source, options = {})
  @options = options
  @profiling = options[:profile]
  @line_numbers = options[:line_numbers] || @profiling
  @root = Document.parse(tokenize(source), DEFAULT_OPTIONS.merge(options))
  @warnings = nil
  self
end
registers() click to toggle source
# File lib/liquid/template.rb, line 132
def registers
  @registers ||= {}
end
render(*args) click to toggle source

Render takes a hash with local variables.

if you use the same filters over and over again consider registering them globally with Template.register_filter

if profiling was enabled in Template#parse then the resulting profiling information will be available via Template#profiler

Following options can be passed:

* <tt>filters</tt> : array with local filters
* <tt>registers</tt> : hash with register variables. Those can be accessed from
  filters and tags and might be useful to integrate liquid more with its host application
# File lib/liquid/template.rb, line 162
def render(*args)
  return ''.freeze if @root.nil?

  context = case args.first
  when Liquid::Context
    c = args.shift

    if @rethrow_errors
      c.exception_handler = ->(e) { true }
    end

    c
  when Liquid::Drop
    drop = args.shift
    drop.context = Context.new([drop, assigns], instance_assigns, registers, @rethrow_errors, @resource_limits)
  when Hash
    Context.new([args.shift, assigns], instance_assigns, registers, @rethrow_errors, @resource_limits)
  when nil
    Context.new(assigns, instance_assigns, registers, @rethrow_errors, @resource_limits)
  else
    raise ArgumentError, "Expected Hash or Liquid::Context as parameter"
  end

  case args.last
  when Hash
    options = args.pop

    if options[:registers].is_a?(Hash)
      self.registers.merge!(options[:registers])
    end

    if options[:filters]
      context.add_filters(options[:filters])
    end

    if options[:exception_handler]
      context.exception_handler = options[:exception_handler]
    end
  when Module
    context.add_filters(args.pop)
  when Array
    context.add_filters(args.pop)
  end

  begin
    # render the nodelist.
    # for performance reasons we get an array back here. join will make a string out of it.
    result = with_profiling do
      @root.render(context)
    end
    result.respond_to?(:join) ? result.join : result
  rescue Liquid::MemoryError => e
    context.handle_error(e)
  ensure
    @errors = context.errors
  end
end
render!(*args) click to toggle source
# File lib/liquid/template.rb, line 220
def render!(*args)
  @rethrow_errors = true
  render(*args)
end
warnings() click to toggle source
# File lib/liquid/template.rb, line 127
def warnings
  return [] unless @root
  @warnings ||= @root.warnings
end

Private Instance Methods

calculate_line_numbers(raw_tokens) click to toggle source
# File lib/liquid/template.rb, line 240
def calculate_line_numbers(raw_tokens)
  return raw_tokens unless @line_numbers

  current_line = 1
  raw_tokens.map do |token|
    Token.new(token, current_line).tap do
      current_line += token.count("\n")
    end
  end
end
tokenize(source) click to toggle source

Uses the Liquid::TemplateParser regexp to tokenize the passed source

# File lib/liquid/template.rb, line 228
def tokenize(source)
  source = source.source if source.respond_to?(:source)
  return [] if source.to_s.empty?

  tokens = calculate_line_numbers(source.split(TemplateParser))

  # removes the rogue empty element at the beginning of the array
  tokens.shift if tokens[0] and tokens[0].empty?

  tokens
end
with_profiling() { || ... } click to toggle source
# File lib/liquid/template.rb, line 251
def with_profiling
  if @profiling && !@options[:included]
    @profiler = Profiler.new
    @profiler.start

    begin
      yield
    ensure
      @profiler.stop
    end
  else
    yield
  end
end