http://masterview.org/installation.html

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

  <title>MasterView - Installation Guide</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />

  <link href="./stylesheets/masterview.css" rel="stylesheet" type="text/css" />
  <link href="./stylesheets/mv-config.css" rel="stylesheet" type="text/css" />
</head>

<body>

<div id="pageHeader">
<a href="index.html"><img id="logo" src="images/masterview_logo.png" alt="MasterView Rails-optimized (x)html friendly template engine"/></a>
</div>

<div id="headerNav">
<div>
&middot;&nbsp;
<a href="./index.html">Doc Home</a>
&nbsp;|&nbsp;
<a href="./about.html">About</a>
&nbsp;|&nbsp;
<a href="./installation.html">Installation</a>
&nbsp;|&nbsp;
<a href="./configuration.html">Configuration</a>
&nbsp;|&nbsp;
<a href="./guide.html">Usage</a>
&nbsp;|&nbsp;
<a href="./directives.html">Directives</a>
&nbsp;|&nbsp;
<a href="./developer.html">Developers</a>
&nbsp;|&nbsp;
<a href="./media_list.html">Screencasts</a>
&nbsp;&middot;
</div>
</div>

<div id="pageBody">
<div id="bodyContent">

<h1>MasterView Installation Guide</h1>

<p>
<span class="productName">MasterView</span> 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.
</p>

<p>
<span class="productName">MasterView</span> 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
<b>or</b> you can simply install a complete copy as a self-contained plugin
in your application.
</p>

<p class="explanation">
If you are new to Ruby and not yet familiar with <code>gem</code>,
the standard Ruby package manager, see the
<a href="#gem_tips">MasterView Gem Tips</a> section at the end of this document
for additional information and links to the <code>RubyGems</code> documentation.
</p>

<!--
<p class="explanation">###TODO: TOC here: Supported Platforms, Prerequisites, Installation [as gem, as complete plugin], Gem Tips####</p>

<p class="explanation">###TODO: add a little "Quick Start" for experienced ruby-ists here - repeat the gem install and the plugin install incantations ###</p>
-->

<h2>Supported Platforms</h2>

<p><span class="productName">MasterView</span> has been tested
on Ruby 1.8.4 and Rails 1.1.6 on *nix and Windows.
</p>


<h2>Prerequisites</h2>
<table summary="prerequisites">
<tbody>
<tr class="subheader">
<td colspan="2">Required:</td>
</tr>
<tr>
<td>&nbsp;</td>
<td class="explanation">No required external dependencies</td>
</tr>
<tr class="subheader">
<td colspan="2">Optional:</td>
</tr>
<tr>
<td class="package">tidy</td>
<td>
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 <a href="http://tidy.sourceforge.net/" target="_blank">HTML Tidy project on sourceforge</a> to download and install tidy on your system.
To install the Ruby gem tidy library:
<pre class="code">gem install tidy</pre>
</td>
</tr>
<tr>
<td class="package">Log4r</td>
<td>A flexible logging library for Ruby that will be used by Masterview if installed.
(If not, the standard ruby library <code>Logger</code> is used).
Visit the <a href="http://log4r.sourceforge.net/" target="_blank">Log4r project on sourceforge</a> for more information.
To install the Ruby gem Log4r library:
<pre class="code">gem install log4r</pre>
</td>
</tr>
</tbody>
</table>

<p class="explanation">(see the
<a href="#gem_tips">MasterView Gem Tips</a> section below if you need more information about the <code>RubyGem</code> package manager)</p>

<h2>Installation</h2>

<p>
You can install <span class="productName">MasterView</span> either
by using the standard Ruby <code>gem</code> package manager
to <a href="#install_gem">install the MasterView gem</a>
<b>or</b>
you can <a href="#install_plugin">install a copy of the MasterView plugin</a> in your application.
Masterview releases are published on
<a href="http://rubyforge.org/projects/masterview/" target="_blank">rubyforge.org</a>
and can be downloaded and installed manually or installed using the standard procedures described here.
</p>

<p class="explanation"><b>Tip:</b>
Installing <span class="productName">MasterView</span> as a gem is generally
easier to manage and maintain.
The <code>gem</code> 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.
</p>

<a name="install_gem"></a>
<h3>Installation of the MasterView gem</h3>

<p>To install the current release of <span class="productName">MasterView</span> as a gem,
run the Ruby <code>gem</code> package manager from the command line:
</p>

<pre class="code">gem install masterview_gem_pack</pre>

<p class="explanation">(answer <b>Yes</b> when prompted whether to install the dependent masterview component gems)</p>

<p>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.
</p>

<h4>Installing the MasterView gem as a Rails Plugin</h4>

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

<pre class="code">
cd /path/to/myrailsapp
</pre>

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

<pre class="code">
cd /path/to/myrails
mkdir mynewapp
cd mynewapp
rails
</pre>

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

<p>Use one of the following two forms of running the generator.
<span class="explanation">
(On Windows, you need to explicitly invoke Ruby to run the script)
</span>
</p>
<pre class="code">
ruby script/generate masterview_plugin
</pre>

<p>
The lightweight <code>masterview</code> 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 <code>config/masterview</code> directory.
</p>

<p>Congratulations - you are now ready to use MasterView in your application!</p>

<p>To run <span class="productName">MasterView</span> with the default
configuration settings, which are designed to be appropriate for a
typical Rails application, simply start creating <code>.html</code>
template views containing MasterView <code>mv:</code> attribute markup
and run your application.
</p>

<p>For information about customizing <span class="productName">MasterView</span>
configuration settings, see the
<a href="configuration.html">MasterView Configuration Guide</a>.
</p>

<p>For an overview and information about using MasterView templates, see the
<!--##TODO: factor out guide.html and convert following to link -->
<i>MasterView User's Guide</i>
and the detailed
<!--##TODO: factor out directives.html and convert following to link -->
<i>MasterView Directives Reference</i>.
For information about using the <code>masterview_generator</code>
to assist you in creating templates, see the
<!--##TODO: factor out guide.html and convert following to link -->
<i>MasterView User's Guide</i>.
</p>

<a name="install_plugin"></a>
<h3>Installation of the complete MasterView plugin</h3>

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

<p>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, <code>cd</code> to the directory containing
your rails application and run the standard Rails
<code>plugin</code> script.
<span class="explanation">
(On Windows, you need to explicitly invoke Ruby to run the script)
</span>
</p>

<pre class="code">
ruby script/plugin install svn://rubyforge.org/var/svn/masterview/tags/masterview
</pre>

<p>This will copy the complete MasterView
system into your <code>vendor/plugins/masterview</code> directory.
</p>

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

<p>Congratulations - you are now ready to use MasterView in your application!</p>

<p>To run <span class="productName">MasterView</span> with the default
configuration settings, which are designed to be appropriate for a
typical Rails application, simply start creating <code>.html</code>
template views containing MasterView <code>mv:</code> attribute markup
and run your application.
</p>

<p>For information about customizing <span class="productName">MasterView</span>
configuration settings, see the
<a href="configuration.html">MasterView Configuration Guide</a>.
</p>

<p>For an overview and information about using MasterView templates, see the
<!--##TODO: factor out guide.html and convert following to link -->
<i>MasterView User's Guide</i>
and the detailed
<!--##TODO: factor out directives.html and convert following to link -->
<i>MasterView Directives Reference</i>.
For information about using the <code>masterview_generator</code>
to assist you in creating templates, see the
<!--##TODO: factor out guide.html and convert following to link -->
<i>MasterView User's Guide</i>.
</p>


<a name="gem_tips"></a>
<h2>MasterView Gem Tips</h2>

<p><code>RubyGems</code> 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
<a href="http://docs.rubygems.org/" target="_blank">rubygems.org</a>.
</p>

<ul>
<li><a href="http://docs.rubygems.org/read/book/1" target="_blank">RubyGems  User Guide</a></li>
<li><a href="http://docs.rubygems.org/read/book/2" target="_blank">gem Command Reference</a></li>
</ul>

<a name="gem_roadmap"></a>
<h3>Roadmap to the MasterView gem packages</h3>

<p><span class="productName">MasterView</span> releases are published on the
<a href="http://rubyforge.org/projects/masterview/" target="_blank">MasterView project on rubyforge</a>.
</p>

<p>There are 3 components published as gems in a <span class="productName">MasterView</span> release:</p>
<ul>
<li><code>masterview</code> - the MasterView template engine</li>
<li><code>masterview_gem_plugin_generator</code> - a Rails generator for creating the necessary entry (a small loader stub) in your rails application's <code>vendor/plugins</code> directory to load the MasterView template engine gem as a Rails plugin in your application</li>
<li><code>masterview_generator</code> - Rails generator for creating MasterView templates in your application <span class="explanation">[### NEEDS MORE EXPLANATION###]</span></li>
</ul>

<p>Most of the time you'll want to simply install the all-in-one easy-install gem that brings in everything:
</p>
<ul>
<li><code>masterview_gem_pack</code> - the MasterView value-pak for easy install - installs the base MasterView template engine plus the supporting Rails generators</li>
</ul>

<p class="explanation"><b>Tip:</b> the gems named <code>masterview_parser</code>
and <code>masterview_gem_plugin_generator</code> are obsolete versions from early alpha
releases.  They are obsolete and should be ignored.
</p>

<h3>Useful Gem Expressions</h3>
<ul>
<li>list the installed version(s) of MasterView
<div class="cmdLine">gem list masterview</div>
</li>
<li>list the available versions of Masterview
<div class="cmdLine">gem query -r -n ^masterview</div>
</li>
<li>install the current release of MasterView
<div class="cmdLine">gem install masterview_gem_pack</div>
</li>
<li>uninstall MasterView gems (all versions)
<!--
<div class="cmdLine">gem uninstall masterview_gem_pack</div>
<div class="cmdLine">gem uninstall masterview_generator</div>
<div class="cmdLine">gem uninstall masterview_plugin_generator</div>
<div class="cmdLine">gem uninstall masterview</div>
-->
<div class="cmdLine">gem uninstall masterview -a -x -i</div>
</li>
</ul>

</div>  <!-- bodyContent -->
</div>

<div id="pageFooter">
<div>
&middot;&nbsp;
<a href="./index.html">Doc Home</a>
&nbsp;|&nbsp;
<a href="./about.html">About</a>
&nbsp;|&nbsp;
<a href="./installation.html">Installation</a>
&nbsp;|&nbsp;
<a href="./configuration.html">Configuration</a>
&nbsp;|&nbsp;
<a href="./guide.html">Usage</a>
&nbsp;|&nbsp;
<a href="./directives.html">Directives</a>
&nbsp;|&nbsp;
<a href="./developer.html">Developers</a>
&nbsp;|&nbsp;
<a href="./media_list.html">Screencasts</a>
&nbsp;&middot;
</div>
<table summary="layout area">
<tbody>
<tr>
<td class="copyright">&copy;&nbsp;Copyright MasterView 2006</td>
<td class="validators">
  <a href="http://validator.w3.org/check/referer"><img
          src="http://www.w3.org/Icons/valid-xhtml10" class="w3c_validator"
          title="Valid XHTML 1.0!" alt="Valid XHTML 1.0!" /></a>
</td>
</tr>
</tbody>
</table>
</div>

</body>
</html>