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

MasterView Installation Guide

MasterView is a Ruby/Rails optimized HTML/XHTML friendly template engine. It is designed to use the full power and productivity of Rails, including layouts, partials, and Rails html helpers while still being editable/styleable in a WYSIWYG HTML editor.

MasterView is distributed as both a gem and as a fully self-contained plugin. You may install it as a gem and then generate a lightweight plugin in your Rails application which references the gem or you can simply install a complete copy as a self-contained plugin in your application.

If you are new to Ruby and not yet familiar with gem, the standard Ruby package manager, see the MasterView Gem Tips section at the end of this document for additional information and links to the RubyGems documentation.

Supported Platforms

MasterView has been tested on Ruby 1.8.5r3 and Rails 1.1.6 on *nix and Windows.

Prerequisites

Required:
  No required external dependencies, but needs REXML 3.1.4 or higher which comes with standard Ruby 1.8.5+ install
Optional:
tidy If HTML tidy support is installed, you can use tidy to automatically clean up html in your templates into valid xhtml prior to MasterView template parsing. You will need both the tidy processor and the Ruby gem tidy library installed on your system. Visit the HTML Tidy project on sourceforge to download and install tidy on your system. To install the Ruby gem tidy library:
gem install tidy
Log4r A flexible logging library for Ruby that will be used by Masterview if installed. (If not, the standard ruby library Logger is used). Visit the Log4r project on sourceforge for more information. To install the Ruby gem Log4r library:
gem install log4r

(see the MasterView Gem Tips section below if you need more information about the RubyGem package manager)

Installation

You can install MasterView either by using the standard Ruby gem package manager to install the MasterView gem or you can install a copy of the MasterView plugin in your application. Masterview releases are published on rubyforge.org and can be downloaded and installed manually or installed using the standard procedures described here.

Tip: Installing MasterView as a gem is generally easier to manage and maintain. The gem package manager installs MasterView in your system Ruby library path, from which it is then available to all your Ruby applications. However, if you are running at a shared hosting environment you might not have authority to install this gem so you may install as a self contained plugin.

Installation of the MasterView gem

To install the current release of MasterView as a gem, run the Ruby gem package manager from the command line:

gem install masterview_gem_pack

(answer Yes when prompted whether to install the dependent masterview component gems)

This will install MasterView in the Ruby library on your system. The MasterView API documentation will be added your RubyGems documentation and made available in the installed Gems documentation that you access by running your RubyGems RDoc server.

Installing the MasterView gem as a Rails Plugin

In order to activate support for MasterView templates in a Rails application, you need to install masterview as a Rails plugin in that application. If you are adding MasterView support to an existing Rails application, open a command shell and cd to the directory containing the rails application.

cd /path/to/myrailsapp

If you are starting a new application, create a directory to contain your application and run the rails generator to generate the standard framework structure of a skeleton rails application.

cd /path/to/myrails
mkdir mynewapp
cd mynewapp
rails

Now run the masterview_plugin_generator in your Rails application directory to install MasterView as a plugin. The plugin generator will create a lightweight plugin for masterview in your rails vendor/plugins directory, consisting of an init.rb file which causes the MasterView template engine to be loaded during Rails startup.

Use one of the following two forms of running the generator. (On Windows, you need to explicitly invoke Ruby to run the script)

ruby script/generate masterview_plugin

The lightweight masterview plugin runs the template engine using the installed gem, but allows you to provide application-specific configuration settings using settings files that you can provide in your application's config/masterview directory.

Congratulations - you are now ready to use MasterView in your application!

To run MasterView with the default configuration settings, which are designed to be appropriate for a typical Rails application, simply start creating .html template views containing MasterView mv: attribute markup and run your application.

For information about customizing MasterView configuration settings, see the MasterView Configuration Guide.

For an overview and information about using MasterView templates, see the MasterView User's Guide and the detailed MasterView Directives Reference. For information about using the masterview_generator to assist you in creating templates, see the MasterView User's Guide.

Installation of the complete MasterView plugin

If you are unable or otherwise do not wish to install masterview as a gem, you can install a full copy of the template engine and its generators as a plugin in your rails application.

If you have Subversion client support installed on your system, you can install the latest release directly from the release build archive on rubyforge. In a command shell, cd to the directory containing your rails application and run the standard Rails plugin script. (On Windows, you need to explicitly invoke Ruby to run the script)

ruby script/plugin install svn://rubyforge.org/var/svn/masterview/tags/masterview

This will copy the complete MasterView system into your vendor/plugins/masterview directory.

If you do not have a Subversion (svn) client, you can manually download a copy of the masterview plugin package from rubyforge.org/projects/masterview. (Go to the Files tab and select the latest release version D.D.D) Download either masterview_plugin-D.D.D.tgz or masterview_plugin-D.D.D.zip according to the preferred compressed files format for your system. Unpack the plugin into the vendor/plugins directory of your rails application to install the masterview plugin.

Congratulations - you are now ready to use MasterView in your application!

To run MasterView with the default configuration settings, which are designed to be appropriate for a typical Rails application, simply start creating .html template views containing MasterView mv: attribute markup and run your application.

For information about customizing MasterView configuration settings, see the MasterView Configuration Guide.

For an overview and information about using MasterView templates, see the MasterView User's Guide and the detailed MasterView Directives Reference. For information about using the masterview_generator to assist you in creating templates, see the MasterView User's Guide.

MasterView Gem Tips

RubyGems is the standard package manager for Ruby. It makes it easy to download, install, and manage Ruby libraries. A nice User Guide and complete command reference are available at rubygems.org.

Roadmap to the MasterView gem packages

MasterView releases are published on the MasterView project on rubyforge.

There are 3 components published as gems in a MasterView release:

Most of the time you'll want to simply install the all-in-one easy-install gem that brings in everything:

Tip: the gems named masterview_parser and masterview_gem_plugin_generator are obsolete versions from early alpha releases. They are obsolete and should be ignored.

Useful Gem Expressions