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) 


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
 
# File 'lib/tilt/template.rb', line 52

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)
    @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

Instance Attribute Details

#data ⇒ Object (readonly)

Template source; loaded from a file or given directly.



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

def data
  @data
end

#file ⇒ Object (readonly)

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



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

def file
  @file
end

#line ⇒ Object (readonly)

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



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

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.



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

def options
  @options
end

Class Method Details

.default_mime_type ⇒ Object

Deprecated.

Use ‘.metadata` instead.



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

def default_mime_type
  metadata[:mime_type]
end

.default_mime_type=(value) ⇒ Object

Deprecated.

Use ‘.metadata = val` instead.



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

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

.metadata ⇒ Object

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



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

def metadata
  @metadata ||= {}
end

Instance Method Details

#basename(suffix = '') ⇒ Object

The basename of the template file.



103
104
105
 
# File 'lib/tilt/template.rb', line 103

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

#eval_file ⇒ Object

The filename used in backtraces to describe the template.



113
114
115
 
# File 'lib/tilt/template.rb', line 113

def eval_file
  file || '(__TEMPLATE__)'
end

#metadata ⇒ Object

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



119
120
121
122
123
124
125
 
# File 'lib/tilt/template.rb', line 119

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.



108
109
110
 
# File 'lib/tilt/template.rb', line 108

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

#render(scope = Object.new, 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.



94
95
96
97
98
99
100
 
# File 'lib/tilt/template.rb', line 94

def render(scope=Object.new, locals={}, &block)
  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