= MasterView - Rails-optimized (x)html friendly template engine

== Recent changes (Release 0.3.0 - Major update - refactoring of directive API (for developing directives)
The directive API for creating directives has been refactored and simplified. This will enable directives to be developed more easily by both core developers and MasterView users. The end goal is to make it extremely simple for anyone to create their own custom directives and to share those with the community, and thus the project can live and grow into many specialty areas. The directive API refactoring is one more step towards those goals.

The old directive_base.rb which provided the API for directives has been deprecated and moved to deprecated/directive_base.rb, MasterViewdevelopers which have developed custom directives should upgrade those directives to the new API as soon as possible. During the transition period one can use the original API by requiring the deprecated/directive_base.rb file and changing their directive to inherit from DirectiveBaseOld rather than DirectiveBase.


== Recent changes (Release 0.2.5)
Fix AdminPage compatibility with Rails 1.1.5+ which uses safe_load_paths to find controllers
Fix rake mv:view_rhtml RHTML=foo/_bar.rhtml was not able to find partials
Fix rails environment not being passed into configuration
Added default generate filter which will add in a default generate directive if none is found in template
Changed default_parser_options to be merged in with original set rather than to be absolute replacement
Corrected example settings.rb win32 tidy_path to point to tidy.dll not tidy.exe.


== Recent changes (Release 0.2.4)
Maintenance release to add scgi support for MasterView.
Also introduced interactive template page to admin pages allowing
template html to be tested in MasterView showing the rendered
rhtml.

== Recent changes (Release 0.2.3)

Changed default development settings for enable_admin_pages and
enable_view_rhtml = true (false in production) to make it easy
for new users to get up and running. Added check_box, radio_button,
select, collection_select directives. Refactor attr_value parsing
to be more robust taking into account nested objects. Internal rework
of directive handling to support alternate namespaces for directives.
Std app directives dir at rails app/masterview/directives will be
automatically added to MasterView load path if exists.


== Recent changes (Release 0.2.2)

Fixes problem when rails encounters exception in either compiling or
involving RuntimeError in the generated rhtml. The rails TemplateError
class looks at the file system for the template contents. So when
generate_rhtml is false (no file is generated) rails was not able to
find source and was not outputting an error page. Rails TemplateError
class was extended to look at MasterView store first and then fallback
to file system.

== Recent changes (Release 0.2.1)

Release 0.2.1 adds Mongrel support, a new image_tag directive
and some additional illustrations and links to videos. Also
javascript_include and stylesheet_link directives can infer the
path from the src attribute if the attr_value is empty.

Also added additional logging around startup and the version of
MasterView that is running and a new admin page to visually
see what MasterView features are currently loaded (tidy,
auto parsing on change, parse on startup, reading rhtml direct
from masterview (eliminating rhtml file generation))


== Recent changes (Release 0.2.0)

Release 0.2.0 features a number of significant improvements.

MasterView templates can now be compiled directly into the Rails
view cache, just like .rhtml files in your app/views directory.
Output generation of .rhtml files from a MasterView template
is now optional.

A keyword substitution mechanism is now supported for the
mv:generate and mv:import group of template processing directives
to enable you to more easily specify standard output file names
derived from the template filename and relative path.
Template markup of the form:

  mv:generate="{template_path}"

avoids having to replicate the name of the template file itself
or its relative path within the masterview templates directory.
See the MasterView User's Guide and Directives Reference for details.

A new configuration facility has been added to allow you to
customize the MasterView configuration using settings
files in your rails app config directory, following the
same approach as the Rails framework itself.
See the new Configuration Guide documentation for details.

Configuration settings for controlling logging level have been added.
The MasterView admin controller is now disabled by default.
Use the config.enable_admin_pages setting to enable
(usually want only in your config/masterview/environments/development.rb).

The documentation has been reworked and enhanced to provide
improved documentation on installation and usage, along with
a new Configuration Guide describing how to customize the
MasterView configuration.

UPGRADE NOTES: If you have customized your MasterView configuration
in the init.rb file of your existing plugin installation, you *MUST*
migrate your configuration to the new settings file configuration mechanism
(config/masterview/settings.rb and environment settings files).

Also note that a directive was renamed from gen_render to gen_partial to
more clearly represent the functionality and eliminate future confusion.
Be sure to change any references to gen_render to gen_partial.

The default location for MasterView templates is now the standard Rails
app/views directory.  Either move your existing templates into app/views
or update the MasterView config.template_src_dir_path setting in your
config/masterview/settings.rb to reference your existing templates source
directory.

== Recent changes (Release 0.1.0)

MasterView now by default generates five masterview template files instead
of one, though you can specify the --single-file option to only generate
one file. Using one masterview template file gives the most DRY implementation
but since all the views are in one file, it can become a point of contention
and is a little more difficult for designers to work with.
This Version 0.1.0 upgrade fixes that by generating one masterview template
for each action (list, new, edit, show, destroy). The layout and message
partials are defined in the list template and are imported into the other
files so that you can have a complete page rendering when working with style
and design of page. Similarly new defines the form partial which is imported
into edit, and show defines a _show partial which is imported into destroy.

One can edit the layout or other partials in the file they are defined in,
so for instance to edit the layout, edit the list template and once finished,
you can trigger the other templates to be rebuilt with the current information.
MasterView now contains an MasterView admin controller/view to visually see
all the status and details about the templates. You can rebuild any out of sync
templates from this page. Alternatively you can view and rebuild templates from
the command line as well using the built in rake commands (mv:list, mv:list_all,
mv:rebuild TEMPLATE=foo.html, mv:rebuild_all).

To make it easy to add additional actions which also import the layout,
MasterView now has a way to generate a starter template file for your action
by simply choosing from which other template file you want to import the layout
from. For instance say you want to add an action called hello to your Product
controller. Find the masterview template you want to get the layout imported
from which could be (product_list.html, product_new.html, product_edit.html, ...),
you can choose any of the templates that have the layout you want (it doesn't
matter whether they defined the layout or simply imported it. To generate the
starter template go to the MasterView Admin page http://yourserver/masterview
and click copy link next to the appropriate template. On the next screen indicate
the name of the action you wish to add (in this case 'hello') and click the submit
button. MasterView generates a starter template file product_hello.html which
imports the layout from the template file you chose and it creates some
placeholder divs in the template that you can edit to add your hello view code.
Alternatively there is also a
    rake mv:copy_layout TEMPLATE=product_list.html ACTION=hello
command to allow you to do the same thing via command line.

Note that you don't have to use the starter or generated files to use MasterView
(you can just add MasterView attribute directives manually), but I found that
once you had things started and wanted to reuse that same information, that
having an automated way to get the layout imported makes it much easier and
quicker to get things going. You can also change the default action div that is
generated by simply creating your own file in app/views/masterview/admin/empty.rhtml
which if found the copy_layout will use it, otherwise it uses the one from the gem/plugin.

== Description

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 a gem or a plugin. You may install it as a gem and
then generate a lightweight plugin which mainly refers to the gem *or* you can
simply install as a plugin which is self contained. I personally prefer installing
as a gem for ease of management, 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.

If you are interested in the background story behind all this, it is at the end of this page.

Author:: Jeff Barczewski
Email:: jeff.barczewski (at) gmail (dot) com
Primary developers:: Jeff Barczewski, Deb Lewis
Website:: http://masterview.org
Rubyforge project:: masterview
License:: MIT open source license like Rails

== Goals

- Create/extend a template engine for rails that would be XHTML friendly and thus could be edited/styled with a WYSIWYG HTML editor even late in development without breaking template.
- Keep it simple. DRY. No extra config files, simple syntax with ruby flavor.
- Design it specifically for ruby and rails. Use the full power and not be limited in its capabilities over what can be done with ERb
- Work nicely with layouts, partials, and rails html helpers.
- Reduce complexity, work with existing rails code, no extra view logic or hashes than what is used by ERb. Scaffold generate initial templates or work from existing html prototype.
- Reduce the numbers of files, simplifying editing. Define partials and layouts naturallyl right in the template, no need to go to another file.
- Preview in browser without running an app. Allow for dummy data in the template so that the page can be viewed and styled independently of the application.
- Performance equal to ERb

== Prerequisites

Requires::
        No external dependencies

Optional::
        tidy (gem) and tidy library - if these are installed you can use tidy to cleanup html into valid xhtml for use by MasterView
        log4r (gem) - if this gem is installed then MasterView will use it for logging otherwise it defaults to using built in Logger.

== User Documentation

MasterView documentation is available online at the MasterView site:
  http://www.masterview.org
and on the rubyforge project
  http://rubyforge.org/projects/masterview/

== Installation

Detailed installation instructions for installing the masterview gems
or a self-contained copy of the plugin is provided in the MasterView
Installation Guide.

The Configuration Guide describes how to customize the configuration
of the MasterView template engine for your application.

== Usage

The MasterView User's Guide and a complete Directives Reference are provided
in the MasterView user documentation.  MasterView templates can be
created by hand simply by adding masterview directives markup to
an (x)html template, or generated for typical Rails controller/view
scenarios using the supplied masterview generator developer tool.

A MasterView Admin controller can optionally be activated in your application
to assist you during development with creating and managing your templates.