Class: Tilt::Template

### Home Classes Methods

### In Files

- lib/tilt/template.rb

### Parent

Object

### Methods

- ::new
- #allows_script?
- #basename
- #compiled_method
- #default_encoding
- #eval_file
- #evaluate
- #initialize_engine
- #name
- #precompiled
- #precompiled_postamble
- #precompiled_preamble
- #precompiled_template
- #prepare
- #read_template_file
- #render
- #require_template_library

### Class/Module Index

Quicksearch

- Tilt
- Tilt::AsciidoctorTemplate
- Tilt::BlueClothTemplate
- Tilt::BuilderTemplate
- Tilt::CSVTemplate
- Tilt::Cache
- Tilt::CoffeeScriptTemplate
- Tilt::CompileSite
- Tilt::CreoleTemplate
- Tilt::ERBTemplate
- Tilt::ErubisTemplate
- Tilt::EtanniTemplate
- Tilt::HamlTemplate
- Tilt::KramdownTemplate
- Tilt::LessTemplate
- Tilt::LiquidTemplate
- Tilt::MarkabyTemplate
- Tilt::MarukuTemplate
- Tilt::NokogiriTemplate
- Tilt::PlainTemplate
- Tilt::RDiscountTemplate
- Tilt::RDocTemplate
- Tilt::RadiusTemplate
- Tilt::RedClothTemplate
- Tilt::RedcarpetTemplate
- Tilt::RedcarpetTemplate::Redcarpet1
- Tilt::RedcarpetTemplate::Redcarpet2
- Tilt::SassTemplate
- Tilt::ScssTemplate
- Tilt::StringTemplate
- Tilt::Template
- Tilt::WikiClothTemplate
- Tilt::YajlTemplate

No matching classes.

# Tilt::Template

Base class for template implementations. Subclasses must implement the prepare method and one of the evaluate or precompiled_template methods.

### Attributes

default_mime_type[RW]
engine_initialized[RW]
engine_initialized?[RW]
data[R]

Template source; loaded from a file or given directly.

file[R]

The name of the file where the template data was loaded from.

line[R]

The line number in file where template data was loaded from.

options[R]

A Hash of template engine specific options. This is passed directly to the underlying engine and is not used by the generic template interface.

### Public Class Methods

new(file=nil, line=1, options={}, &block) click to toggle source

Create a new template with the file, line, and options specified. By default, template data is read from the file. When a block is given, it should read template data and return as a String. When file is nil, a block is required.

All arguments are optional.

    # File lib/tilt/template.rb, line 38
    def initialize(file=nil, line=1, options={}, &block)
      @file, @line, @options = nil, 1, {}

      [options, line, file].compact.each do |arg|
        case
        when arg.respond_to?(:to_str)  ; @file = arg.to_str
        when arg.respond_to?(:to_int)  ; @line = arg.to_int
        when arg.respond_to?(:to_hash) ; @options = arg.to_hash.dup
        when arg.respond_to?(:path)    ; @file = arg.path
        else raise TypeError
        end
      end

      raise ArgumentError, "file or block required" if (@file || block).nil?

      # call the initialize_engine method if this is the very first time
      # an instance of this class has been created.
      if !self.class.engine_initialized?
        initialize_engine
        self.class.engine_initialized = true
      end

      # used to hold compiled template methods
      @compiled_method = {}

      # used on 1.9 to set the encoding if it is not set elsewhere (like a magic comment)
      # currently only used if template compiles to ruby
      @default_encoding = @options.delete :default_encoding

      # load template data and prepare (uses binread to avoid encoding issues)
      @reader = block || lambda { |t| read_template_file }
      @data = @reader.call(self)

      if @data.respond_to?(:force_encoding)
        @data.force_encoding(default_encoding) if default_encoding

        if !@data.valid_encoding?
          raise Encoding::InvalidByteSequenceError, "#{eval_file} is not valid #{@data.encoding}"
        end
      end

      prepare
    end

### Public Instance Methods

allows_script?() click to toggle source

Whether or not this template engine allows executing Ruby script within the template. If this is false, `scope` and `locals` will generally not be used, nor will the provided block be avaiable via `yield`. This should be overridden by template subclasses.

    # File lib/tilt/template.rb, line 126
    def allows_script?
      true
    end

basename(suffix='') click to toggle source

The basename of the template file.

    # File lib/tilt/template.rb, line 107
    def basename(suffix='')
      File.basename(file, suffix) if file
    end

default_encoding() click to toggle source

The encoding of the source data. Defaults to the default_encoding-option if present. You may override this method in your template class if you have a better hint of the data's encoding.

    # File lib/tilt/template.rb, line 86
    def default_encoding
      @default_encoding
    end

eval_file() click to toggle source

The filename used in backtraces to describe the template.

    # File lib/tilt/template.rb, line 117
    def eval_file
      file || '(__TEMPLATE__)'
    end

name() click to toggle source

The template file's basename with all extensions chomped off.

    # File lib/tilt/template.rb, line 112
    def name
      basename.split('.', 2).first if basename
    end

read_template_file() click to toggle source

    # File lib/tilt/template.rb, line 90
    def read_template_file
      data = File.open(file, 'rb') { |io| io.read }
      if data.respond_to?(:force_encoding)
        # Set it to the default external (without verifying)
        data.force_encoding(Encoding.default_external) if Encoding.default_external
      end
      data
    end

render(scope=Object.new, locals={}, &block) click to toggle source

Render the template in the given scope with the locals specified. If a block is given, it is typically available within the template via `yield`.

    # File lib/tilt/template.rb, line 102
    def render(scope=Object.new, locals={}, &block)
      evaluate scope, locals || {}, &block
    end

### Protected Instance Methods

compiled_method(locals_keys) click to toggle source

The compiled method for the locals keys provided.

    # File lib/tilt/template.rb, line 238
    def compiled_method(locals_keys)
      @compiled_method[locals_keys] ||=
        compile_template_method(locals_keys)
    end

evaluate(scope, locals, &block) click to toggle source

Execute the compiled template and return the result string. Template evaluation is guaranteed to be performed in the scope object with the locals specified and with support for yielding to the block.

This method is only used by source generating templates. Subclasses that override render() may not support all features.

    # File lib/tilt/template.rb, line 168
    def evaluate(scope, locals, &block)
      method = compiled_method(locals.keys)
      method.bind(scope).call(locals, &block)
    end

initialize_engine() click to toggle source

Called once and only once for each template subclass the first time the template class is initialized. This should be used to require the underlying template library and perform any initial setup.

    # File lib/tilt/template.rb, line 134
    def initialize_engine
    end

precompiled(locals) click to toggle source

Generates all template source by combining the preamble, template, and postamble and returns a two-tuple of the form: [source, offset], where source is the string containing (Ruby) source code for the template and offset is the integer line offset where line reporting should begin.

Template subclasses may override this method when they need complete control over source generation or want to adjust the default line offset. In most cases, overriding the precompiled_template method is easier and more appropriate.

    # File lib/tilt/template.rb, line 182
    def precompiled(locals)
      preamble = precompiled_preamble(locals)
      template = precompiled_template(locals)
      postamble = precompiled_postamble(locals)
      source = ''

      # Ensure that our generated source code has the same encoding as the
      # the source code generated by the template engine.
      if source.respond_to?(:force_encoding)
        template_encoding = extract_encoding(template)

        source.force_encoding(template_encoding)
        template.force_encoding(template_encoding)
      end

      # https://github.com/rtomayko/tilt/issues/193
      warn "precompiled_preamble should return String (not Array)" if preamble.is_a?(Array)
      warn "precompiled_postamble should return String (not Array)" if postamble.is_a?(Array)
      source << [preamble, template, postamble].join("\n")

      [source, preamble.count("\n")+1]
    end

precompiled_postamble(locals) click to toggle source

Generates postamble code for the precompiled template source. The string returned from this method is appended to the precompiled template source.

    # File lib/tilt/template.rb, line 233
    def precompiled_postamble(locals)
      ''
    end

precompiled_preamble(locals) click to toggle source

Generates preamble code for initializing template state, and performing locals assignment. The default implementation performs locals assignment only. Lines included in the preamble are subtracted from the source line offset, so adding code to the preamble does not effect line reporting in Kernel::caller and backtraces.

    # File lib/tilt/template.rb, line 220
    def precompiled_preamble(locals)
      locals.map do |k,v|
        if k.to_s =~ /\A[a-z_][a-zA-Z_0-9]*\z/
          "#{k} = locals[#{k.inspect}]"
        else
          raise "invalid locals key: #{k.inspect} (keys must be variable names)"
        end
      end.join("\n")
    end

precompiled_template(locals) click to toggle source

A string containing the (Ruby) source code for the template. The default Template#evaluate implementation requires either this method or the precompiled method be overridden. When defined, the base Template guarantees correct file/line handling, locals support, custom scopes, proper encoding, and support for template compilation.

    # File lib/tilt/template.rb, line 211
    def precompiled_template(locals)
      raise NotImplementedError
    end

prepare() click to toggle source

Do whatever preparation is necessary to setup the underlying template engine. Called immediately after template data is loaded. Instance variables set in this method are available when evaluate is called.

Subclasses must provide an implementation of this method.

    # File lib/tilt/template.rb, line 152
    def prepare
      if respond_to?(:compile!)
        # backward compat with tilt < 0.6; just in case
        warn 'Tilt::Template#compile! is deprecated; implement #prepare instead.'
        compile!
      else
        raise NotImplementedError
      end
    end

require_template_library(name) click to toggle source

Like Kernel#require but issues a warning urging a manual require when running under a threaded environment.

    # File lib/tilt/template.rb, line 139
    def require_template_library(name)
      if Thread.list.size > 1
        warn "WARN: tilt autoloading '#{name}' in a non thread-safe way; " +
             "explicit require '#{name}' suggested."
      end
      require name
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.