Class: Tilt::Template

Inherits:
Object
  • Object
show all
Defined in:
lib/tilt/template.rb

Overview

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file = nil, line = 1, options = {}, &block) ⇒ Template

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.

Raises:

  • (ArgumentError) 


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/tilt/template.rb', line 51

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
    when arg.respond_to?(:to_path) ; @file = arg.to_path
    else raise TypeError, "Can't load the template file. Pass a string with a path " +
      "or an object that responds to 'to_str', 'path' or 'to_path'"
    end
  end

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

  # 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)
    if default_encoding
      @data = @data.dup if @data.frozen?
      @data.force_encoding(default_encoding)
    end

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

  prepare
end

Instance Attribute Details

#data ⇒ Object (readonly)

Template source; loaded from a file or given directly.



14
15
16
 
# File 'lib/tilt/template.rb', line 14

def data
  @data
end

#file ⇒ Object (readonly)

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



17
18
19
 
# File 'lib/tilt/template.rb', line 17

def file
  @file
end

#line ⇒ Object (readonly)

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



20
21
22
 
# File 'lib/tilt/template.rb', line 20

def line
  @line
end

#options ⇒ Object (readonly)

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



25
26
27
 
# File 'lib/tilt/template.rb', line 25

def options
  @options
end

Class Method Details

.default_mime_type ⇒ Object

Deprecated.

Use ‘.metadata` instead.



35
36
37
 
# File 'lib/tilt/template.rb', line 35

def default_mime_type
  metadata[:mime_type]
end

.default_mime_type=(value) ⇒ Object

Deprecated.

Use ‘.metadata = val` instead.



40
41
42
 
# File 'lib/tilt/template.rb', line 40

def default_mime_type=(value)
  metadata[:mime_type] = value
end

.metadata ⇒ Object

An empty Hash that the template engine can populate with various metadata.



30
31
32
 
# File 'lib/tilt/template.rb', line 30

def metadata
  @metadata ||= {}
end

Instance Method Details

#basename(suffix = '') ⇒ Object

The basename of the template file.



106
107
108
 
# File 'lib/tilt/template.rb', line 106

def basename(suffix='')
  File.basename(file, suffix) if file
end

#eval_file ⇒ Object

The filename used in backtraces to describe the template.



116
117
118
 
# File 'lib/tilt/template.rb', line 116

def eval_file
  file || '(__TEMPLATE__)'
end

#metadata ⇒ Object

An empty Hash that the template engine can populate with various metadata.



122
123
124
125
126
127
128
 
# File 'lib/tilt/template.rb', line 122

def metadata
  if respond_to?(:allows_script?)
    self.class.metadata.merge(:allows_script => allows_script?)
  else
    self.class.metadata
  end
end

#name ⇒ Object

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



111
112
113
 
# File 'lib/tilt/template.rb', line 111

def name
  basename.split('.', 2).first if basename
end

#render(scope = nil, locals = {}, &block) ⇒ Object

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.



96
97
98
99
100
101
102
103
 
# File 'lib/tilt/template.rb', line 96

def render(scope=nil, locals={}, &block)
  scope ||= Object.new
  current_template = Thread.current[:tilt_current_template]
  Thread.current[:tilt_current_template] = self
  evaluate(scope, locals || {}, &block)
ensure
  Thread.current[:tilt_current_template] = current_template
end