MasterView - Configuration Guide

MasterView supports a number of options for configuring its operation.

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 generate rhtml into the RAILS_ROOT/app/views directory from template files in RAILS_ROOT/app/views/masterview. 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 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)