MasterView User's Guide

MasterView is designed to be easy for a developer and designer to work together. By keeping the template in an html friendly format, designers can apply style, layout changes, wording changes, without causing havoc on the rails view code. The designer can be involved at anytime during the development cycle including being able to change style and layout after the system is built. This is great for allowing design or wording changes without reinvolving the developers. One can even start from a designer created prototype and add MasterView tags to make it become real. Whichever way you prefer to work, MasterView accomodates you.

Creating MasterView Templates

You may add MasterView attributes to existing (x)html or you may use the masterview generator to create a complete working application.

Writing MasterView Template Attribute Markup

MasterView template processing directives are encoded in an (x)html template using attribute markup. A MasterView directive is an element attribute in the mv: namespace. By convention, Masterview directive attribute names use lower-case letters with underscore as a separator, e.g., mv:generate, mv:link_to.

Note: use of the mv: namespace used for MasterView directives in an (x)html template can be modified by a configuration setting. See the MasterView Configuration Guide for details. However, we recommend that you do not change this namespace convention unless truly necessary - it's easier to understand your templates when they follow the standard markup convention.

MasterView provides a number of built-in directives for general use. See the MasterView Directives Reference for details on the standard set of masterview directives that are available. You can also create your own custom directives to extend the power of the MasterView template processing with markup notation and processing directives that support standard uses for your particular application.

Using the MasterView Generator

The masterview generator can create controllers, models, and MasterView template files in your Rails app directory, similar to how the built-in Rails generator works.

To use the masterview generator, open a command shell and change directory to your rails application. Then run the masterview generator using a command of the form:

script/generate masterview YourModelName [YourControllerName] [—style
[cssStylesheet]] [—single-file] [—show-all | —show-only
list]

(Note for Windows users: you will need to explicitly specify the Ruby interpreter to run the masterview generator, i.e., the expression above becomes ruby script/generate masterview ...) in a DOS command window.

The generator by default will generate five masterview template files, one for each distinct page, list, new, edit, show, and destroy. They exist in the app/views directory with the filename controller_action.html. The layout and message partial are defined in the list template file and imported into the others. Similarly the new template defines the form partial which is imported into edit, and finally the show file defines a _show partial which is imported into destroy. Thus there is one definition of each part (layout and partial) and they are imported into the other files where needed to provide accurate WYSIWYG design time editing. By generating separate files, teams can work on a project easier, however MasterView also supports generating all parts to a single file for the ultimate in DRY.

For example, if our generated Controller name is Store and the Model is Product this is what would be generated.

By adding the —single-file switch MasterView will create a single file and to make it easier to use this template at design time, some design time css stylesheets are included in the file to hide all sections except one. By default the NEW section is the only one shown. Other options are —show-all which makes all sections visible or [—show-only list] which shows only the LIST section. When you are editing the masterview file you may comment/uncomment one of the other css files to show a different section. The —style param allows you to suppress default style generation and specify an existing stylesheet to use, if you exlude the stylesheet none will be used, if you include this option multiple times with different stylesheets each will be used.

Once it is done generating, the generated MasterView template file will be created in app/views/CONTROLLER directory. This file is html and can be edited with any standard html editor. The rails specific logic is contained in simple attributes which are ignored by html editors. The syntax for these attributes is heavily derived from the rails helper tags themselves so it should feel natural to the rails developer.

Another interesting thing to know is that while all of the pages for this Model have been bundled up into a few html file for ease of editing, at runtime these templates gets rendered into the exact same layouts and partials that you would use if you were building from scratch. Its jsut that now you can see what your pages will render like in your wysiwyg html editor and change and layout accordingly. Additionally MasterView supplies some javascript to show only one action view at time (list, new, show, edit, destroy) so you can view in your browser without running in Rails. Dummy html can be included to improve the accuracy of the page which can be easily removed at runtime. To make it easier to work with in an editor, design time stylesheets are included in the file to allow you to hide all sections except the one you are working on, simply uncomment the appropriate stylesheet for the section you would like to work with.

Using the MasterView Admin Controller

The MasterView admin controller/view is used by a MasterView developer to obtain a birds-eye view of all your masterview templates, the status of those templates (OK, Invalid xhtml, Conflicts, Imports outdated), the details regarding the status, and the ultimate erb files generated from each template. The admin controller also displays a summary of your current configuration.

The MasterView admin controller is enabled or disabled in your application by the Master enable_admin_pages configuration setting. By default, the admin controller is enabled. See the MasterView Configuration Guide for details.

When enabled, the MasterView admin controller is available in your application at http://yourserver/masterview. The Admin home page displays an overview of your application's templates and links to admin information and operations.

Since it can be difficult to import a layout by hand into a new file, the MasterView admin controller has a link where you can copy the layout into a new file by providing the new files Action. It will take the layout from the template chosen and create a new file controller_action.html with the layout imported and a shell for the new Action code.

As described in the following section, youcan also do this from command line using rake:

rake mv:copy_layout TEMPLATE=foo_list.html ACTION=newaction

Using Rake for MasterView Admin Operations

All of the power of the MasterView admin controller is also available via a set of rake commands. MasterView includes a masterview.rake file in your vendor/plugins/masterview/tasks directory which is automatically included by the top level Rails Rakefile, so the masterview mv: admin tasks are automatically available in your application's rake tasks when the MasterView plugin is installed.

In a command shell, cd to your Rails application directory and use rake commands of the form:

rake mv:clean_mv_rhtml

rake mv:copy_layout

rake mv:generate_all_rhtml

rake mv:list

rake mv:list_all

rake mv:rebuild

rake mv:rebuild_all

rake mv:view_rhtml

To obtain further information about the supported commands, run the standard rake tasks report using the --tasks (-T) option:

rake -T