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 = nil, options = nil) ⇒ 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) 


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

def initialize(file=nil, line=nil, options=nil)
  @file, @line, @options = nil, 1, nil

  process_arg(options)
  process_arg(line)
  process_arg(file)

  raise ArgumentError, "file or block required" unless @file || block_given?

  @options ||= {}

  set_compiled_method_cache

  # Force the encoding of the input data
  @default_encoding = @options.delete :default_encoding

  # Skip encoding detection from magic comments and forcing that encoding
  # for compiled templates
  @skip_compiled_encoding_detection = @options.delete :skip_compiled_encoding_detection

  # load template data and prepare (uses binread to avoid encoding issues)
  @data = block_given? ? yield(self) : read_template_file

  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.



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

def compiled_path
  @compiled_path
end

#data ⇒ Object (readonly)

Template source; loaded from a file or given directly.



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

def data
  @data
end

#file ⇒ Object (readonly)

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



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

def file
  @file
end

#line ⇒ Object (readonly)

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



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

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.



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

def options
  @options
end

Class Method Details

.default_mime_type ⇒ Object

Use ‘.metadata` instead.



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

def default_mime_type
  metadata[:mime_type]
end

.default_mime_type=(value) ⇒ Object

Use ‘.metadata = val` instead.



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

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

.metadata ⇒ Object

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



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

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

#compiled_method(locals_keys, scope_class = nil) ⇒ Object

The compiled method for the locals keys and scope_class provided. Returns an UnboundMethod, which can be used to define methods directly on the scope class, which are much faster to call than Tilt’s normal rendering.



147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/tilt/template.rb', line 147

def compiled_method(locals_keys, scope_class=nil)
  key = [scope_class, locals_keys].freeze
  LOCK.synchronize do
    if meth = @compiled_method[key]
      return meth
    end
  end
  meth = compile_template_method(locals_keys, scope_class)
  LOCK.synchronize do
    @compiled_method[key] = meth
  end
  meth
end

#eval_file ⇒ Object

The filename used in backtraces to describe the template.



118
119
120
 
# File 'lib/tilt/template.rb', line 118

def eval_file
  @file || '(__TEMPLATE__)'
end

#metadata ⇒ Object

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



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

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

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

#render(scope = nil, locals = nil, &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.



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

def render(scope=nil, locals=nil, &block)
  evaluate(scope || Object.new, locals || EMPTY_HASH, &block)
end