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) 


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
92
93
94
95
96
97
98
99
100
 
# File 'lib/tilt/template.rb', line 60

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

#compiled_path ⇒ Object

A path ending in .rb that the template code will be written to, then required, instead of being evaled. This is useful for determining coverage of compiled template code, or to use static analysis tools on the compiled template code.



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

def compiled_path
  @compiled_path
end

#data ⇒ Object (readonly)

Template source; loaded from a file or given directly.



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

def data
  @data
end

#file ⇒ Object (readonly)

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



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

def file
  @file
end

#line ⇒ Object (readonly)

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



23
24
25
 
# File 'lib/tilt/template.rb', line 23

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.



28
29
30
 
# File 'lib/tilt/template.rb', line 28

def options
  @options
end

Class Method Details

.default_mime_type ⇒ Object

Deprecated.

Use ‘.metadata` instead.



44
45
46
 
# File 'lib/tilt/template.rb', line 44

def default_mime_type
  metadata[:mime_type]
end

.default_mime_type=(value) ⇒ Object

Deprecated.

Use ‘.metadata = val` instead.



49
50
51
 
# File 'lib/tilt/template.rb', line 49

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

.metadata ⇒ Object

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



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

def metadata
  @metadata ||= {}
end

Instance Method Details

#basename(suffix = '') ⇒ Object

The basename of the template file.



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

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

#eval_file ⇒ Object

The filename used in backtraces to describe the template.



125
126
127
 
# File 'lib/tilt/template.rb', line 125

def eval_file
  file || '(__TEMPLATE__)'
end

#metadata ⇒ Object

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



131
132
133
134
135
136
137
 
# File 'lib/tilt/template.rb', line 131

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.



120
121
122
 
# File 'lib/tilt/template.rb', line 120

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.



105
106
107
108
109
110
111
112
 
# File 'lib/tilt/template.rb', line 105

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