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.

Direct Known Subclasses

AsciidoctorTemplate, BlueClothTemplate, BuilderTemplate, CSVTemplate, CoffeeScriptTemplate, CreoleTemplate, ERBTemplate, EtanniTemplate, HamlTemplate, KramdownTemplate, LessTemplate, LiquidTemplate, MarkabyTemplate, MarukuTemplate, NokogiriTemplate, PlainTemplate, RDiscountTemplate, RDocTemplate, RadiusTemplate, RedClothTemplate, Redcarpet1Template, Redcarpet2Template, RedcarpetTemplate, SassTemplate, StringTemplate, WikiClothTemplate, YajlTemplate

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Template) initialize(file = nil, line = 1, options = {}, &block)

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

- (Object) data (readonly)

Template source; loaded from a file or given directly.



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

def data
  @data
end

- (Object) file (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

- (Object) line (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

- (Object) options (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

+ (Object) default_mime_type

Deprecated.

Use `.metadata` instead.



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

def default_mime_type
  [:mime_type]
end

+ (Object) default_mime_type=(value)

Deprecated.

Use `.metadata = val` instead.



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

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

+ (Object) metadata

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

- (Object) basename(suffix = '')

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

- (Object) eval_file

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

- (Object) metadata

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

- (Object) name

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

- (Object) render(scope = Object.new, locals = {}, &block)

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