Class: Tilt::Template

External Aliases

engine_initialized -> engine_initialized?

Attributes

data	[R]	Template source; loaded from a file or given directly.
engine_initialized	[RW]
file	[R]	The name of the file where the template data was loaded from.
line	[R]	The line number in file where template data was loaded from.
options	[R]	A Hash of template engine specific options. This is passed directly to the underlying engine and is not used by the generic template interface.

Public Class methods

new(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.

[Source]

     # File lib/tilt.rb, line 93
 93:     def initialize(file=nil, line=1, options={}, &block)
 94:       @file, @line, @options = nil, 1, {}
 95: 
 96:       [options, line, file].compact.each do |arg|
 97:         case
 98:         when arg.respond_to?(:to_str)  ; @file = arg.to_str
 99:         when arg.respond_to?(:to_int)  ; @line = arg.to_int
100:         when arg.respond_to?(:to_hash) ; @options = arg.to_hash.dup
101:         else raise TypeError
102:         end
103:       end
104: 
105:       raise ArgumentError, "file or block required" if (@file || block).nil?
106: 
107:       # call the initialize_engine method if this is the very first time
108:       # an instance of this class has been created.
109:       if !self.class.engine_initialized?
110:         initialize_engine
111:         self.class.engine_initialized = true
112:       end
113: 
114:       # used to generate unique method names for template compilation
115:       @stamp = (Time.now.to_f * 10000).to_i
116:       @compiled_method_names = {}
117: 
118:       # load template data and prepare
119:       @reader = block || lambda { |t| File.read(@file) }
120:       @data = @reader.call(self)
121:       prepare
122:     end

Public Instance methods

basename(suffix='')

The basename of the template file.

[Source]

     # File lib/tilt.rb, line 132
132:     def basename(suffix='')
133:       File.basename(file, suffix) if file
134:     end

eval_file()

The filename used in backtraces to describe the template.

[Source]

     # File lib/tilt.rb, line 142
142:     def eval_file
143:       file || '(__TEMPLATE__)'
144:     end

name()

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

[Source]

     # File lib/tilt.rb, line 137
137:     def name
138:       basename.split('.', 2).first if basename
139:     end

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.

[Source]

     # File lib/tilt.rb, line 127
127:     def render(scope=Object.new, locals={}, &block)
128:       evaluate scope, locals || {}, &block
129:     end

Protected Instance methods

compiled_method_name(locals_keys)

The unique compiled method name for the locals keys provided.

[Source]

     # File lib/tilt.rb, line 245
245:     def compiled_method_name(locals_keys)
246:       @compiled_method_names[locals_keys] ||=
247:         generate_compiled_method_name(locals_keys)
248:     end

evaluate(scope, locals, &block)

Process the template and return the result. When the scope mixes in the Tilt::CompileSite module, the template is compiled to a method and reused given identical locals keys. When the scope object does not mix in the CompileSite module, the template source is evaluated with instance_eval. In any case, template executation is guaranteed to be performed in the scope object with the locals specified and with support for yielding to the block.

[Source]

     # File lib/tilt.rb, line 185
185:     def evaluate(scope, locals, &block)
186:       if scope.respond_to?(:__tilt__)
187:         method_name = compiled_method_name(locals.keys)
188:         if scope.respond_to?(method_name)
189:           scope.send(method_name, locals, &block)
190:         else
191:           compile_template_method(method_name, locals)
192:           scope.send(method_name, locals, &block)
193:         end
194:       else
195:         evaluate_source(scope, locals, &block)
196:       end
197:     end

initialize_engine()

Called once and only once for each template subclass the first time the template class is initialized. This should be used to require the underlying template library and perform any initial setup.

[Source]

     # File lib/tilt.rb, line 150
150:     def initialize_engine
151:     end

precompiled(locals)

Generates all template source by combining the preamble, template, and postamble and returns a two-tuple of the form: [source, offset], where source is the string containing (Ruby) source code for the template and offset is the integer line offset where line reporting should begin.

Template subclasses may override this method when they need complete control over source generation or want to adjust the default line offset. In most cases, overriding the precompiled_template method is easier and more appropriate.

[Source]

     # File lib/tilt.rb, line 208
208:     def precompiled(locals)
209:       preamble = precompiled_preamble(locals)
210:       parts = [
211:         preamble,
212:         precompiled_template(locals),
213:         precompiled_postamble(locals)
214:       ]
215:       [parts.join("\n"), preamble.count("\n") + 1]
216:     end

precompiled_postamble(locals)

Generates postamble code for the precompiled template source. The string returned from this method is appended to the precompiled template source.

[Source]

     # File lib/tilt.rb, line 240
240:     def precompiled_postamble(locals)
241:       ''
242:     end

precompiled_preamble(locals)

Generates preamble code for initializing template state, and performing locals assignment. The default implementation performs locals assignment only. Lines included in the preamble are subtracted from the source line offset, so adding code to the preamble does not effect line reporting in Kernel::caller and backtraces.

[Source]

     # File lib/tilt.rb, line 233
233:     def precompiled_preamble(locals)
234:       locals.map { |k,v| "#{k} = locals[:#{k}]" }.join("\n")
235:     end

precompiled_template(locals)

A string containing the (Ruby) source code for the template. The default Template#evaluate implementation requires either this method or the precompiled method be overridden. When defined, the base Template guarantees correct file/line handling, locals support, custom scopes, and support for template compilation when the scope object allows it.

[Source]

     # File lib/tilt.rb, line 224
224:     def precompiled_template(locals)
225:       raise NotImplementedError
226:     end

prepare()

Do whatever preparation is necessary to setup the underlying template engine. Called immediately after template data is loaded. Instance variables set in this method are available when evaluate is called.

Subclasses must provide an implementation of this method.

[Source]

     # File lib/tilt.rb, line 168
168:     def prepare
169:       if respond_to?(:compile!)
170:         # backward compat with tilt < 0.6; just in case
171:         warn 'Tilt::Template#compile! is deprecated; implement #prepare instead.'
172:         compile!
173:       else
174:         raise NotImplementedError
175:       end
176:     end

require_template_library(name)

Like Kernel::require but issues a warning urging a manual require when running under a threaded environment.

[Source]

     # File lib/tilt.rb, line 155
155:     def require_template_library(name)
156:       if Thread.list.size > 1
157:         warn "WARN: tilt autoloading '#{name}' in a non thread-safe way; " +
158:              "explicit require '#{name}' suggested."
159:       end
160:       require name
161:     end

Methods

External Aliases

Attributes

Public Class methods

Public Instance methods

Protected Instance methods