A Page object represents an individual page in the final documentation set, bringing together a source template, optional page code (in Ruby) obtained from various sources (see below), and an optional layout template (with it‘s own code) to produce rendered output as a String. Specifically, Page provides the following capabilities:

  • Read template files containing ERB code and render them to create output.
  • Locate and evaluate all common and page code in the binding of the Page instance itself.
  • Apply layout to rendered content using multiple render passes.
  • Apply user-supplied filters to the output to allow transformations and additional processing.

In normal use the instantiation and initialization of Pages will be handled internally by Rote. From the user point of view most interaction with Rote from user code takes place via the instance methods of this class.

Template lookup and evaluation

Each Page instance is provided at instantiation with base paths from which it should resolve both template and layout files when required. Usually these paths are supplied by the Rake task configuration. The attributes that provide information on template and layout paths (e.g. template_name, base_layout_name, and so on) give those paths relative to the base_path and layout_path as appropriate.

Common, page and layout code evaluation

Code applied to a given page is found and evaluated in the following order:

  • A block supplied to the <%= section_link ‘extension mappings’, ‘extension mapping’ %> that matched this page (if any).
  • Any COMMON.rb files from the filesystem root down to this directory.
  • This page‘s ruby code, basename.rb.
  • In the template itself (via ERB).

When a Page instance is created, Rote looks for these, and if found evaluates them, in order, in the Page instance binding.

Additionally, when layout is used the following evaluation takes place *after rendering the template text* and can be used to make variables available for the layout pass(es), and apply nested layout:

  • This layout‘s ruby code, layout_basename.rb.
  • In the layout itself (again, with ERB).

As mentioned, Page instances serve as the context for page code execution - All user-supplied code (COMMON.rb, page and layout code, and ERB in the templates themselves) is executed in the binding of an instance of this class.

Layout

All pages support layout, which allow common template to be applied across several pages. This is handled via multiple render passes, with each layout responsible for including the previously rendered content (via ERB).

Layout templates include the content rendered by the page (or previous layout, see below) render pass using the instance variable @content_for_layout. This should be a familar pattern for those familiar with the Rails framework.

To apply layout to a page, the layout method should be called, passing in the base-name (with extension if different from the page template). When issued from common or page code, multiple calls to this method will override any previous setting. It may be called again from layout code, however, in which case the output of the currently-rendering layout will be passed (via the @content_to_layout instance variable) to the specified layout. In this way, Rote allows layouts to be nested to any level.

Filtering

The page_filter and post_filter methods allow filters to be applied to a page. Filters can be used to support any kind of textual transformation, macro expansion (page filters), or post-render processing (post filters). Rote includes a number of filters as standard, supporting plain-text markup, syntax highlighting, HTMLTidy postprocessing, and more.

See +Rote::Filters+ for details of standard filters and their individual use.

Filters are written in Ruby, and Rote provides base-classes from which filters can be derived with just a few lines of code (See Rote::Filters::TextFilter and Rote::Filters::MacroFilter). Additionally, the page and post filter methods allow text filters to be created from a supplied block.

Rendering

Rendering occurs only once for a given page object, when the render method is first called. Once a page has been rendered, the instance it is frozen to prevent further modification, and the rendered output is cached. Future calls to render will return the cached output.

Methods
Attributes
[R] base_path The base path for template resolution.
[R] layout_path The base path for layout resolution
[R] layout_text The text of the layout to use for this page. This is read in when (if) the page source calls layout(basename).

Deprecated This has no knowledge of nested layout, and operates only on the innermost layout.

[R] page_filters The array of page filters (applied to this page during the first render pass, before layout is applied). You can use page_filter to add new page filters, which gives implicit block => Filters::TextFilter conversion and checks for nil.
[R] post_filters The array of post filters (applied to this page output after layout is applied). You can use post_filter to add new post filters, which gives implicit block => Filters::TextFilter conversion and checks for nil.
[R] template_name The basename from which this page‘s template was read, relative to the base_path.
[R] template_text The text of the template to use for this page.
Public Class methods
new(template_name, pages_dir = '.', layout_dir = pages_dir) {|self if block_given?| ...}

Reads the template, and evaluates the global and page scripts, if available, using the current binding. You may define any instance variables or methods you like in that code for use in the template, as well as accessing the predefined @template and @template_text variables.

If specified, the layout path will be used to find layouts referenced from templates.

If a block is supplied, it is executed before the global / page code. This will be the block supplied by the file-extension mapping.

     # File lib/rote/page.rb, line 197
197:     def initialize(template_name, pages_dir = '.', layout_dir = pages_dir) 
198:       @template_text = nil
199:       @template_name = nil
200:       @layout_names = []
201:       @content_for_layout = nil
202:       @result = nil
203:       @layout_defext = File.extname(template_name)
204:       @layout_path = layout_dir[STRIP_SLASHES,1]
205:       @layout_text = nil
206:       @base_path = pages_dir[STRIP_SLASHES,1]
207:       
208:       @page_filters, @post_filters = [], []
209: 
210:       # read in the template. Layout _may_ get configured later in page code
211:       # We only add the pages_dir if it's not already there, because it's
212:       # easier to pass the whole relative fn from rake...
213:       # template_name always needs with no prefix.
214:       tfn = template_name
215:       read_template(tfn)
216:       
217:       # Yield to the (extension mapping) block
218:       yield self if block_given?
219:       
220:       # Eval COMMON.rb's
221:       eval_common_rubys
222:       
223:       # get script filenames, and eval them if found
224:       tfn = ruby_filename # nil if no file      
225:       instance_eval(File.read(tfn),tfn) if tfn         
226:     end
Public Instance methods
base_layout_filename()

Returns the full filename of the first queued layout. This is the innermost layout, usually specified by the page itself.

This method is also aliased as layout_filename
     # File lib/rote/page.rb, line 236
236:     def base_layout_filename
237:       layout_fn(layout_name)
238:     end
base_layout_name()

The filename of the innermost layout, usually specified by the page itself, relative to the layout_path. This method should not be used from COMMON.rb since its behaviour is undefined until all page code is evaluated and the final base_layout is known.

This method is also aliased as layout_name
     # File lib/rote/page.rb, line 165
165:     def base_layout_name; layout_names.first; end
layout(basename)

Sets the page‘s base-layout as specified, or applies nested layout if called during a layout render pass. The specified basename should be the name of the layout file relative to the layout_path. If the layout has the same extension as the page source template, it may be omitted.

The layout is not read by this method. It, and it‘s source, are loaded only at rendering time. This prevents multiple calls by various scoped COMMON code, for example, from making a mess in the Page binding.

This can only be called before the first call to render returns it‘s result. After that the Page instance is frozen.

     # File lib/rote/page.rb, line 296
296:     def layout(basename)
297:       if basename
298:         self.layout_names << "#{basename}#{@layout_defext if File.extname(basename).empty?}"
299:       end
300:     end
layout_filename()
layout_name()

Alias for base_layout_name

page_filter(filter = nil, &block)

Append filter to this page‘s page-filter chain, or create a new Rote::Filters::TextFilter with the supplied block. This method should be preferred over direct manipulation of the filters array if you are simply building a chain.

     # File lib/rote/page.rb, line 252
252:     def page_filter(filter = nil, &block)
253:       if filter
254:         page_filters << filter
255:       else
256:         if block
257:           page_filters << Filters::TextFilter.new(&block)
258:         end
259:       end
260:     end
post_filter(filter = nil, &block)

Append filter to this page‘s post-filter chain. Behaviour is much the same as append_page_filter.

     # File lib/rote/page.rb, line 264
264:     def post_filter(filter = nil, &block)
265:       if filter
266:         post_filters << filter
267:       else
268:         if block
269:           post_filters << Filters::TextFilter.new(&block)
270:         end
271:       end
272:     end
render()

Render this page‘s textile and ERB, and apply layout. This is only done once - after that, it‘s cached for next time. You can also circumvent rendering by setting @result yourself in your page‘s ruby.

This method is also aliased as to_s
     # File lib/rote/page.rb, line 277
277:     def render
278:       @result or do_render!   # sets up result for next time...
279:     end
ruby_filename()

Returns the full filename of this Page‘s ruby source. If no source is found for this page (not including common source) this returns nil.

     # File lib/rote/page.rb, line 243
243:     def ruby_filename
244:       fn = Page::page_ruby_filename(template_filename) 
245:       File.exists?(fn) ? fn : nil
246:     end
template_filename()

Returns the full filename of this Page‘s template. This is obtained by joining the base path with template name.

     # File lib/rote/page.rb, line 230
230:     def template_filename
231:       File.join(base_path,template_name) if template_name
232:     end
to_s()

Alias for render