Notes:
= MasterView - Rails-optimized (x)html friendly template engine
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 @ gmail.com
Rubyforge project:: masterview
Website:: http://masterview.org
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.
- Use one master file to drive all related sections, simplifying editing.
- 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.
== Installation
Install in one of the two following ways depending on whether you can use gems or not.
=== Installation using gems (if you are able to use gems)
If you can use gems you may simply do the following
gem install masterview_gem_pack
Now your gem is installed and you can skip these steps in the future. After creating your rails directory, change directory to it and run the following to create a very lightweight plugin instance for this application mainly consisting of an init.rb file which will get loaded at runtime. This init.rb refers to the gem for everything but allows you to override any constants or setup that has been provided. See MasterView module masterview.rb for a list of the available constants.
script/generate masterview_plugin
After this MasterView is ready for use. Skip down to the Usage section for more details.
=== Installation without using gems, install as plugin
script/plugin install svn://rubyforge.org/var/svn/masterview
This will copy entire MasterView system into your vendor/plugin/masterview directory. You may tweak its init.rb to override any MasterView constants at runtime. See MasterView module masterview.rb for a list of available constants. Note that if you don't have svn (subversion) installed, you may also retrieve the plugin package (masterview_plugin.tgz or masterview_plugin.zip) from http://rubyforge.org/projects/masterview and simply extract into vendor/plugins/masterview
== Usage
You may add MasterView attributes to existing (x)html or you may use the masterview generator to create a complete working application. The generator can create controllers, models, and the MasterView template file similar to how the built-in generator works. Simply change directory to your rails application and run the following
script/generate masterview YourModelName [YourControllerName] [--show-all | --show-only list] [--style [cssStylesheet]]
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.
Changes:
0.0.17 - May 4, 2006 - Added some additional css style and generator options, change the showOne option
0.0.16 - April 28, 2006 - Corrected gem version dependencies
0.0.15 - April 28, 2006 - Added gem version dependencies spec for masterview_gem_pack so that pack pulls the appropriate versions
0.0.14 - April 28, 2006 - Fixed a preview problem introduced by design time stylesheet inclusion. Show and Destroy content was hidden. Clarified design time message.
0.0.13 - April 27, 2006 - Cleaned up generated template improving indentation and simplified css. Added design time css to hide sections. Preview javascript was changed to be less invasive to generated code.
0.0.12 - April 24, 2006 - Fixed generator to use Controller name for files it generates, added attr directive, added more default styles to css, added styles to generator templates
0.0.11 - April 22, 2006 - Changed the main load file to rescue LoadErrors from log4r and tidy
0.0.6 - April 18, 2006 - Working on generator packaging
0.0.5 - April 18, 2006 - Changed packaging
0.0.4 - April 18, 2006 - Updated documentation
0.0.3 - April 18, 2006 - Repackaging
0.0.2 - April 16, 2006 - First public release
|
