·  Doc Home  |  About  |  Installation  |  Configuration  |  Usage  |  Directives  |  Developers  |  Screencasts  ·

MasterView Configuration Guide

MasterView supports a number of options for configuring its operation.

MasterView Configuration Options Reference

A standard set of configuration options are installed by default that are suitable for a typical Rails application. The goal is to allow Rails application developers to use the MasterView plugin "out of the box", with little or no initial setup effort: simply install the MasterView plugin in a rails application and start using the template engine facilities in its views.

Using MasterView in a Rails Application

The standard configuration of MasterView in a Rails application is to search for MasterView templates (*.html) in the normal RAILS_ROOT/app/views directory and for rails to load the generated rhtml directly from MasterView internally. If config.generate_rhtml is set to true (default is false) then MasterView will generate its intermediate rhtml to the standard RAILS_ROOT/app/views directory and Rails will pick it up from there as normal. The mv: attribute markup in the masterview templates determines the content of the generated rhtml view templates, which are then used by the Rails controller/view dispatching mechanisms in the usual fashion.

By default, all masterview templates are parsed during rails application startup to ensure that generated rhtml views are up-to-date for the application. In a development environment, when Rails is reloading changed classes to dynamically update the application code as you make changes, MasterView will automatically detect changes you make to your masterview templates and regenerate the rails rhtml views. This ability to dynamically modify your rails application during development is a key factor for the productivity of Rails developers, so the MasterView designers have ensured that you continue to have this capability when using masterview templates.

You can customize MasterView operation by modifying the standard set of configuration options. To specify your configuration, create a masterview directory in your Rails configuration directory (RAILS_ROOT/config/masterview). Within this directory, create a settings.rb file containing your application's configuration settings. Options are set by assigning values to the config instance that will be used to initialize MasterView.

Just as with your Rails configuration settings, you can optionally provide environment-specific settings to override or augment your standard application settings. To specify environment-dependent configuration settings, provide additional config files in an environments subdirectory (e.g., create RAILS_ROOT/config/masterview/environments/development.rb to configure settings specifically for your development environment).

Sample config/masterview/settings.rb in a Rails Application

    # Application configuration settings for the MasterView template engine.
    # Run at plugin load time during Rails startup (after the base rails
    # framework is loaded and before the application's own startup logic
    # in its config/environment.rb is run).
    # Set standard application

    # change the template source directory location for this application
    # Specify relative path from RAILS_ROOT (config.root_path)
    config.template_src_dir_path = 'app/masterview/templates'  #default: 'app/masterview'

    # Only use the MasterView admin pages for development
    config.enable_admin_pages = false

    # modify the default logging level from WARN to ERROR (only want to see serious errors)
    config.logger = 'log4r'
    config.log_level = 'ERROR'
    config.after_initialize {
      # we shouldn't see any of these in the log
      MasterView.Log.debug "LOG CONFIG TEST: debug log entries suppressed at ERROR level"
      MasterView.Log.info "LOG CONFIG TEST: info log entries suppressed at ERROR level"
      MasterView.Log.warn "LOG CONFIG TEST: warning log entries suppressed at ERROR level"
      # so this is the only log message that should get through
      #MasterView.Log.error "LOG CONFIG TEST: only serious messages are reported at ERROR level"

Sample config/masterview/environments/development.rb in a Rails Application

    # Application configuration settings for the MasterView template engine.
    # Set development-mode config settings here

    # Only use the MasterView admin pages for development
    config.enable_admin_pages = true

    # include debug and all info/warning/error log messages during development
    config.log_level = 'DEBUG'

Using MasterView outside Rails

MasterView has been designed so that it can also be used independently of the Rails application context. Outside Rails, you need to explicitly run the MasterView::Initializer in your application startup code. While the Rails framework handles masterview loading automatically through its framework startup and plugin loading facilities, with configuration settings files obtained from standard locations within the overall structure of a rails application, a non-rails application using the MasterView template engine needs to initiate loading the template engine and providing it with configuration information.

    require 'masterview/initializer'
    config = MasterView::Configuration( :app_root_path = '/path/to/my/app' )
    # This app has simple config, so it won't use the config files scheme used in Rails.
    # We just specify our directory locations within the app right here.
    config.template_src_dir_path = 'masterview/templates'  # rel path from app's root_path
    config.template_dst_dir_path = 'masterview/output'
    Masterview::Initializer(:process, config)

MasterView Configuration Options

General Options

root_path RAILS_ROOT or '.' Path to the root location of the application.
config_dir_path RAILS_ROOT/config/masterview or nil Path to the directory containing the application's config settings.
Specified as a relative path from the root_path.
environment RAILS_ENV or nil The current execution environment, if applicable.
Used for locating environment-specific settings in the config directory, if available.
directive_paths   Paths of directories to load directives from.
Directory for built-in MasterView directives is included by default. Append additional directories to load custom directives (e.g., config.directive_paths << /path/to/my/directives).
logger Log4r if available, otherwise standard ruby Logger Logger which will be used to output debug, warning, and error messages.
Supported loggers:
'log4r' - the Log4r logger
'logger' - ruby standard library logger
log_level INFO for development, otherwise WARN Specify the name of the logging severity level.
Logging levels names may be logger-dependent.
after_initialize nil Optional block which will be executed after MasterView has been fully initialized.

Template Source Options

template_src_dir_path RAILS_ROOT/app/masterview (rails)
(non-rails app)
Path to the directory where masterview templates are located.
Specify the location of your template source directory as a relative path from the application's root_path directory. Use config.template_src_dir_abs_path(abs_path) to specify the template source directory as an absolute path.
template_filename_pattern *.html Filename pattern for masterview template files within the template source directory.
auto_copy_file_entries [] (empty array) - nothing is auto copied Locations of files that MasterView will autocopy to a runtime location
This autocopy feature makes it easy to have prototypes that display properly for WYSIWYG editing and design, using files (images, stylesheets, and javascript) which are not in the standard Rails locations but are automatically copied to proper place for runtime. This is commonly used in conjunction with template_src_dir_path (which changes the location of the source MasterView templates). Developers can have their templates in a non-standard location along with images, stylesheets, and javascript, and then still have everything copied to the proper runtime locations when Rails is fired up. In debug mode, timestamps are checked on every request, in production mode, copy is done only on startup.

Each entry is a hash that needs to contain
  • :source => 'path to source folder' # absolute or relative to RAILS_ROOT
  • :destination => 'path to place to copy to' # absolute or relative to RAILS_ROOT
and can optionally have a file extension filter
  • :extensions => [:gif, :GIF, :jpg, :JPG] # limit files copied to this array of extensions, case sensitive
Example usage showing three paths added to be auto copied:
config.auto_copy_file_entries << { :source => 'path_to_my_images', :destination => 'public/images' }
config.auto_copy_file_entries << { :source => 'path_to_my_scripts', :destination => 'public/javascripts', :extensions => [:js, :JS] } # only copy js files
config.auto_copy_file_entries << { :source => 'path_to_my_css', :destination => 'public/stylesheets' }

Template Generation Options

template_dst_dir_path RAILS_ROOT/app/views(rails)
(non-rails app)
Path to the directory where Masterview template output (rhtml) will be generated.
Specify the location of your template output directory as a relative path from the application's root_path. Use config.template_dst_dir_abs_path(abs_path) to specify the template output directory as an absolute path.
output_filename_extension .rhtml Filename extension to use for generated output files if not specified.
generated_file_default_extension .rhtml Filename extension to use for generated files if not specified.
include_generated_file_comment true Boolean which controls whether to include a comment in template output files indicating that the file was generated by MasterView.
By default, a warning comment is generated in template output files indicating that the file was generated by MasterView from a template and should not be directly edited, as any changes would be lost when the output file is regenerated.
generated_file_comment   Text for generated-file comment inserted in rhtml template output files generated by MasterView.
Standard comment includes the name of the master template file which contains the source to edit. Variable substitution on the comment text will replace #{template_path} with the pathname of the source template file.

Template Parsing Options

handle_parse_exceptions true Continue template parsing after logging parse exceptions.
default_parser_options hash containing parser options Options for parser operation
  :tidy => false Run tidy before processing template
(must set tidy_path)
  :escape_erb => true Escape <% %> before parsing
  :default_generate => true Ensure that a mv:generate or mv:gen_partial is present in a template, otherwise add a mv:generate="{template_path}" to the body tag if one is present or the root element. If a body tag is present and mv:generate is being added then also add mv:omit_tag="".
tidy_path   Path on this system to tidy library if :tidy parser option is enabled so that masterview templates will be run through tidy before being parsed.
namespace_prefix mv: XML name space prefix for built-in MasterView directive attributes in template html.
namespace_prefix_extensions mvx: XML name space prefix for addon MasterView directive attributes in template html.
inline_erb_start {{{ Xhtml safe substitution for <% in a masterview template.
inline_erb_end }}} Xhtml safe substitution for %> in a masterview template.
inline_erb_substitution_regex   regex used to find escaped inline_erb markup.
Needs to match inline_erb_start and inline_erb_end
use_original_rexml_sax2parser false Boolean to specify whether to use the original (unpatched) REXML sax2parser.
If this is not true and the REXML version is 3.1.4 - 3.1.6 MasterView will use a patched version of the REXML sax2parser which properly handles doctypes. If this is true or the REXML version is outside this range the original REXML sax2 parser will be used.

Rails Application Options

parse_masterview_templates_at_startup true Boolean which determines whether masterview templates are parsed during initial application startup loading.
If the auto-parse option is disabled, template parsing must be manually triggered by the application developer.
reparse_changed_masterview_templates true if both template parsing at startup and ActionController class reloading are enabled Boolean which determines whether masterview templates are automatically reparsed if the template changes after initial application loading. Note: If ActionController::Base.perform_caching is true (default true in production), compiled rhtml is cached and MasterView will not check for modified templates.
admin_auth_mixin Built-in local machine check (local_request?) Defines custom MV Admin authorization method and module.
Automatically loads app/masterview/admin_auth_mixin.rb if present.
    config.admin_auth_mixin = {
      :file => 'admin_auth_mixin', # require file in app/masterview
      :file_loc => nil  # :RAILS_ROOT or root dir path for alt load load
      :module => :MasterViewAdminAuthMixin, # mixin module name

    see examples/rails_app_admin_auth/auth_local_request_mixin.rb for more details
enable_admin_pages true for development, otherwise false Enable MasterView admin pages in the rails application.
Enables the masterview admin controller at http://yourappdomain/masterview.
enable_view_rhtml true for development, otherwise false Enable MasterView admin pages in a rails application to be able to view the generated rhtml. When enabled it creates links on the list page to click to view the rhtml source. Requires that enable_admin_pages is true.
This functionality is useful for understanding how your templates are being interpreted (i.e. what rhtml is being generated by them) and for debugging. For security reasons you would probably disable this feature in production (or disable admin pages altogether).
generate_rhtml_files false Boolean which controls whether to generate rhtml (erb) files to file system and have rails load from there, otherwise Rails will load directly from MasterView.
If this setting is false, then several methods in the rails controller and view will be enhanced to be able to read erb directly from MasterView in addition to being able to read the erb on the file system. If this setting is true then rhtml(erb) files will be generated to file system and rails will read them from there in the traditional manner.