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
# 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
    else raise TypeError
    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

#dataObject (readonly)

Template source; loaded from a file or given directly.



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

def data
  @data
end

#fileObject (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

#lineObject (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

#optionsObject (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_typeObject

Deprecated.

Use `.metadata` instead.



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

def default_mime_type
  [: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)
  [:mime_type] = value
end

.metadataObject

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



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

def 
  @metadata ||= {}
end

Instance Method Details

#basename(suffix = '') ⇒ Object

The basename of the template file.



101
102
103
# File 'lib/tilt/template.rb', line 101

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

#eval_fileObject

The filename used in backtraces to describe the template.



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

def eval_file
  file || '(__TEMPLATE__)'
end

#metadataObject

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



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

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

#nameObject

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



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

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.



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

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