class Rote::Page

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:

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:

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:

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.

Attributes

base_path[R]

The base path for template resolution.

layout_path[R]

The base path for layout resolution

layout_text[R]

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.

page_filters[R]

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.

post_filters[R]

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.

template_name[R]

The basename from which this page’s template was read, relative to the base_path.

template_text[R]

The text of the template to use for this page.

Public Class Methods

new(template_name, pages_dir = '.', layout_dir = pages_dir) { |self| ... } click to toggle source

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
def initialize(template_name, pages_dir = '.', layout_dir = pages_dir) 
  @template_text = nil
  @template_name = nil
  @layout_names = []
  @content_for_layout = nil
  @result = nil
  @layout_defext = File.extname(template_name)
  @layout_path = layout_dir[STRIP_SLASHES,1]
  @layout_text = nil
  @base_path = pages_dir[STRIP_SLASHES,1]
  
  @page_filters, @post_filters = [], []

  # read in the template. Layout _may_ get configured later in page code
  # We only add the pages_dir if it's not already there, because it's
  # easier to pass the whole relative fn from rake...
  # template_name always needs with no prefix.
  tfn = template_name
  read_template(tfn)
  
  # Yield to the (extension mapping) block
  yield self if block_given?
  
  # Eval COMMON.rb's
  eval_common_rubys
  
  # get script filenames, and eval them if found
  tfn = ruby_filename # nil if no file      
  instance_eval(File.read(tfn),tfn) if tfn         
end

Public Instance Methods

base_layout_filename() click to toggle source

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

# File lib/rote/page.rb, line 236
def base_layout_filename
  layout_fn(layout_name)
end
Also aliased as: layout_filename
base_layout_name() click to toggle source

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.

# File lib/rote/page.rb, line 165
def base_layout_name; layout_names.first; end
Also aliased as: layout_name
layout(basename) click to toggle source

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
def layout(basename)
  if basename
    self.layout_names << "#{basename}#{@layout_defext if File.extname(basename).empty?}"
  end
end
layout_filename() click to toggle source
layout_name() click to toggle source
Alias for: base_layout_name
page_filter(filter = nil, &block) click to toggle source

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
def page_filter(filter = nil, &block)
  if filter
    page_filters << filter
  else
    if block
      page_filters << Filters::TextFilter.new(&block)
    end
  end
end
post_filter(filter = nil, &block) click to toggle source

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
def post_filter(filter = nil, &block)
  if filter
    post_filters << filter
  else
    if block
      post_filters << Filters::TextFilter.new(&block)
    end
  end
end
render() click to toggle source

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.

# File lib/rote/page.rb, line 277
def render
  @result or do_render!   # sets up result for next time...
end
Also aliased as: to_s
ruby_filename() click to toggle source

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
def ruby_filename
  fn = Page::page_ruby_filename(template_filename) 
  File.exists?(fn) ? fn : nil
end
template_filename() click to toggle source

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
def template_filename
  File.join(base_path,template_name) if template_name
end
to_s() click to toggle source
Alias for: render