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

#data ⇒ Object (readonly)

Template source; loaded from a file or given directly.



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

def data
  @data
end

#file ⇒ Object (readonly)

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



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

def file
  @file
end

#line ⇒ Object (readonly)

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



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

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.



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

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