masterview 0.1.5 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/CHANGELOG +17 -0
- data/README +36 -504
- data/RELEASE_NOTES +126 -45
- data/Rakefile +215 -86
- data/TODO +8 -3
- data/doc/configuration.html +485 -0
- data/doc/directives.html +1085 -0
- data/doc/guide.html +243 -0
- data/doc/index.html +287 -0
- data/doc/installation.html +376 -0
- data/doc/stylesheets/masterview.css +206 -0
- data/doc/stylesheets/mv-config.css +23 -0
- data/doc/stylesheets/mv-directives.css +18 -0
- data/doc/stylesheets/mv-installation.css +10 -0
- data/doc/troubleshooting.html +18 -0
- data/examples/product.html +256 -0
- data/examples/product.html.old +107 -0
- data/examples/rails_app_config/masterview/environment/development.rb +22 -0
- data/examples/rails_app_config/masterview/environment/production.rb +9 -0
- data/examples/rails_app_config/masterview/settings.rb +59 -0
- data/examples/test.import +80 -0
- data/init.rb +26 -12
- data/lib/masterview/analyzer.rb +25 -15
- data/lib/masterview/directive_base.rb +4 -0
- data/lib/masterview/directive_helpers.rb +7 -5
- data/lib/masterview/directives/import_render.rb +6 -0
- data/lib/masterview/directives/insert_generated_comment.rb +8 -8
- data/lib/masterview/extras/app/controllers/masterview_controller.rb +154 -2
- data/lib/masterview/extras/app/views/masterview/admin/create.rhtml +4 -4
- data/lib/masterview/extras/app/views/masterview/admin/empty.rhtml +1 -1
- data/lib/masterview/extras/app/views/masterview/admin/list.rhtml +14 -9
- data/lib/masterview/extras/app/views/masterview/admin/view_rhtml.rhtml +70 -0
- data/lib/masterview/extras/init_logger.rb +102 -0
- data/lib/masterview/extras/init_rails_erb_mv_direct.rb +117 -0
- data/lib/masterview/extras/init_rails_reparse_checking.rb +59 -0
- data/lib/masterview/extras/watcher.rb +17 -23
- data/lib/masterview/filter_helpers.rb +26 -0
- data/lib/masterview/initializer.rb +912 -0
- data/lib/masterview/io.rb +352 -0
- data/lib/masterview/keyword_expander.rb +116 -0
- data/lib/masterview/masterview_version.rb +2 -2
- data/lib/masterview/mtime_tracking_hash.rb +44 -0
- data/lib/masterview/parser.rb +64 -92
- data/lib/masterview/pathname_extensions.rb +33 -0
- data/lib/masterview/template_spec.rb +49 -56
- data/lib/masterview.rb +40 -85
- data/test/fixtures/configs/fake_rails_app_with_config/config/masterview/environments/development.rb +12 -0
- data/test/fixtures/configs/fake_rails_app_with_config/config/masterview/environments/production.rb +11 -0
- data/test/fixtures/configs/fake_rails_app_with_config/config/masterview/settings.rb +23 -0
- data/test/fixtures/templates/product.html +256 -0
- data/test/fixtures/templates/test.import +80 -0
- data/test/test_helper.rb +5 -3
- data/test/tmp/template/foo.txt +1 -0
- data/test/tmp/templates_src/product.html +256 -0
- data/test/tmp/views/layouts/product.rhtml +35 -0
- data/test/tmp/views/product/_form.rhtml +30 -0
- data/test/tmp/views/product/_product.rhtml +14 -0
- data/test/tmp/views/product/_show.rhtml +27 -0
- data/test/tmp/views/product/destroy.rhtml +27 -0
- data/test/tmp/views/product/edit.rhtml +26 -0
- data/test/tmp/views/product/list.rhtml +31 -0
- data/test/tmp/views/product/new.rhtml +29 -0
- data/test/tmp/views/product/show.rhtml +16 -0
- data/test/unit/config_settings_test.rb +172 -0
- data/test/{attr_test.rb → unit/directive_attr_test.rb} +2 -2
- data/test/{block_test.rb → unit/directive_block_test.rb} +2 -2
- data/test/{content_test.rb → unit/directive_content_test.rb} +2 -2
- data/test/{else_test.rb → unit/directive_else_test.rb} +2 -2
- data/test/{elsif_test.rb → unit/directive_elsif_test.rb} +2 -2
- data/test/{form_test.rb → unit/directive_form_test.rb} +2 -2
- data/test/{global_inline_erb_test.rb → unit/directive_global_inline_erb_test.rb} +2 -2
- data/test/{hidden_field_test.rb → unit/directive_hidden_field_test.rb} +2 -2
- data/test/{if_test.rb → unit/directive_if_test.rb} +2 -2
- data/test/unit/directive_import_render_test.rb +62 -0
- data/test/{import_test.rb → unit/directive_import_test.rb} +2 -2
- data/test/{javascript_include_test.rb → unit/directive_javascript_include_test.rb} +2 -2
- data/test/{link_to_if_test.rb → unit/directive_link_to_if_test.rb} +2 -2
- data/test/{link_to_test.rb → unit/directive_link_to_test.rb} +2 -2
- data/test/{omit_tag_test.rb → unit/directive_omit_tag_test.rb} +2 -2
- data/test/{password_field_test.rb → unit/directive_password_field_test.rb} +2 -2
- data/test/{replace_test.rb → unit/directive_replace_test.rb} +2 -2
- data/test/{stylesheet_link_test.rb → unit/directive_stylesheet_link_test.rb} +2 -2
- data/test/{submit_test.rb → unit/directive_submit_test.rb} +2 -2
- data/test/{text_area_test.rb → unit/directive_text_area_test.rb} +2 -2
- data/test/{text_field_test.rb → unit/directive_text_field_test.rb} +2 -2
- data/test/{example_test.rb → unit/example_test.rb} +1 -1
- data/test/unit/file_mio_test.rb +368 -0
- data/test/{filter_helpers_test.rb → unit/filter_helpers_test.rb} +1 -1
- data/test/unit/keyword_expander_test.rb +95 -0
- data/test/unit/mio_test.rb +110 -0
- data/test/unit/mtime_string_hash_mio_tree_test.rb +289 -0
- data/test/unit/mtime_tracking_hash_test.rb +38 -0
- data/test/{parser_test.rb → unit/parser_test.rb} +19 -1
- data/test/unit/pathname_extensions_test.rb +46 -0
- data/test/{run_parser_test.rb → unit/run_parser_test.rb} +7 -3
- data/test/unit/string_hash_mio_test.rb +320 -0
- data/test/unit/template_file_watcher_test.rb +107 -0
- data/test/{template_spec_test.rb → unit/template_spec_test.rb} +57 -21
- data/test/{template_test.rb → unit/template_test.rb} +123 -22
- data/test/xtras/config-mv-logger_config.rb +109 -0
- data/test/xtras/config_initialize_standalone.rb +53 -0
- metadata +111 -38
- data/lib/masterview/extras/rails_init.rb +0 -72
- data/test/import_render_test.rb +0 -30
- data/test/template_file_watcher_test.rb +0 -50
data/doc/guide.html
ADDED
@@ -0,0 +1,243 @@
|
|
1
|
+
<?xml version="1.0" encoding="iso-8859-1"?>
|
2
|
+
<!DOCTYPE html
|
3
|
+
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
4
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
5
|
+
|
6
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
7
|
+
<head>
|
8
|
+
|
9
|
+
<title>MasterView - User's Guide</title>
|
10
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
11
|
+
<meta http-equiv="Content-Script-Type" content="text/javascript" />
|
12
|
+
|
13
|
+
<link href="./stylesheets/masterview.css" rel="stylesheet" type="text/css" />
|
14
|
+
</head>
|
15
|
+
|
16
|
+
<body>
|
17
|
+
|
18
|
+
<div id="pageHeader">
|
19
|
+
<div>MasterView Template Engine</div>
|
20
|
+
<div class="description">Rails-optimized (x)html friendly template engine</div>
|
21
|
+
</div>
|
22
|
+
|
23
|
+
<div id="pageBody">
|
24
|
+
<div id="bodyContent" mv:generate="{template_path}" mv:omit_tag="">
|
25
|
+
|
26
|
+
<h1>MasterView - User's Guide</h1>
|
27
|
+
|
28
|
+
<p>
|
29
|
+
MasterView is designed to be easy
|
30
|
+
for a developer and designer to work together. By keeping the template in
|
31
|
+
an html friendly format, designers can apply style, layout changes, wording
|
32
|
+
changes, without causing havoc on the rails view code. The designer can be
|
33
|
+
involved at anytime during the development cycle including being able to
|
34
|
+
change style and layout after the system is built. This is great for
|
35
|
+
allowing design or wording changes without reinvolving the developers. One
|
36
|
+
can even start from a designer created prototype and add MasterView tags to make it become
|
37
|
+
real. Whichever way you prefer to work, MasterView accomodates you.
|
38
|
+
</p>
|
39
|
+
|
40
|
+
<h2>Creating MasterView Templates</h2>
|
41
|
+
|
42
|
+
<p>
|
43
|
+
You may add MasterView attributes
|
44
|
+
to existing (x)html or you may use the masterview generator to create a
|
45
|
+
complete working application.
|
46
|
+
</p>
|
47
|
+
|
48
|
+
|
49
|
+
<h3>Writing MasterView Template Attribute Markup</h3>
|
50
|
+
<p>MasterView template processing directives are encoded in an (x)html template
|
51
|
+
using attribute markup. A MasterView directive is an element attribute
|
52
|
+
in the <span class="directiveName">mv:</span> namespace.
|
53
|
+
By convention, Masterview directive attribute names use lower-case letters with
|
54
|
+
underscore as a separator, e.g., <span class="directiveName">mv:generate</span>, <span class="directiveName">mv:link_to</span>.
|
55
|
+
</p>
|
56
|
+
|
57
|
+
<p class="explanation">
|
58
|
+
<b>Note:</b> use of the <span class="directiveName">mv:</span> namespace
|
59
|
+
used for MasterView directives in an (x)html template can be modified
|
60
|
+
by a configuration setting. See the <a href="configuration.html">MasterView Configuration Guide</a> 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.
|
61
|
+
</p>
|
62
|
+
|
63
|
+
<p>MasterView provides a number of built-in directives for general use.
|
64
|
+
See the <a href="directives.html">MasterView Directives Reference</a>
|
65
|
+
for details on the standard set of masterview directives that are available.
|
66
|
+
You can also create your own custom directives to extend the power of the
|
67
|
+
MasterView template processing with markup notation and processing directives
|
68
|
+
that support standard uses for your particular application.
|
69
|
+
<!--TODO: add link the Directive Developer's Guide-->
|
70
|
+
</p>
|
71
|
+
|
72
|
+
|
73
|
+
<h3>Using the MasterView Generator</h3>
|
74
|
+
<p>
|
75
|
+
The masterview generator can create controllers, models,
|
76
|
+
and MasterView template files in your Rails <code>app</code> directory,
|
77
|
+
similar to how the built-in Rails generator works.
|
78
|
+
</p>
|
79
|
+
<p>
|
80
|
+
To use the masterview generator, open a command shell and
|
81
|
+
change directory to your rails application.
|
82
|
+
Then run the masterview generator using a command of the form:
|
83
|
+
</p>
|
84
|
+
<pre class="code">
|
85
|
+
script/generate masterview YourModelName [YourControllerName] [—style
|
86
|
+
[cssStylesheet]] [—single-file] [—show-all | —show-only
|
87
|
+
list]
|
88
|
+
</pre>
|
89
|
+
|
90
|
+
<p class="explanation">(Note for Windows users: you will need to explicitly specify the Ruby interpreter to run the masterview generator, i.e., the expression above becomes <code><b>ruby</b> script/generate masterview ...</code>) in a DOS command window.</p>
|
91
|
+
|
92
|
+
<p>
|
93
|
+
The generator by default will generate five masterview template files, one
|
94
|
+
for each distinct page, list, new, edit, show, and destroy. They exist in
|
95
|
+
the app/views/masterview directory with the filename
|
96
|
+
controller_action.html. The layout and message partial are defined in the
|
97
|
+
list template file and imported into the others. Similarly the new template
|
98
|
+
defines the form partial which is imported into edit, and finally the show
|
99
|
+
file defines a _show partial which is imported into destroy. Thus there is
|
100
|
+
one definition of each part (layout and partial) and they are imported into
|
101
|
+
the other files where needed to provide accurate WYSIWYG design time
|
102
|
+
editing. By generating separate files, teams can work on a project easier,
|
103
|
+
however MasterView also supports
|
104
|
+
generating all parts to a single file for the ultimate in DRY.
|
105
|
+
</p>
|
106
|
+
<p>
|
107
|
+
By adding the —single-file switch MasterView will create a single file
|
108
|
+
and to make it easier to use this template at design time, some design time
|
109
|
+
css stylesheets are included in the file to hide all sections except one.
|
110
|
+
By default the NEW section is the only one shown. Other options are
|
111
|
+
—show-all which makes all sections visible or [—show-only list]
|
112
|
+
which shows only the LIST section. When you are editing the masterview file
|
113
|
+
you may comment/uncomment one of the other css files to show a different
|
114
|
+
section. The —style param allows you to suppress default style
|
115
|
+
generation and specify an existing stylesheet to use, if you exlude the
|
116
|
+
stylesheet none will be used, if you include this option multiple times
|
117
|
+
with different stylesheets each will be used.
|
118
|
+
</p>
|
119
|
+
<p>
|
120
|
+
Once it is done generating, the generated MasterView template file will be
|
121
|
+
created in app/views/masterview/controller.html. This file is html and can
|
122
|
+
be edited with any standard html editor. The rails specific logic is
|
123
|
+
contained in simple attributes which are ignored by html editors. The
|
124
|
+
syntax for these attributes is heavily derived from the rails helper tags
|
125
|
+
themselves so it should feel natural to the rails developer.
|
126
|
+
</p>
|
127
|
+
<p>
|
128
|
+
Another interesting thing to know is that while all of the pages for this
|
129
|
+
Model have been bundled up into a few html file for ease of editing, at
|
130
|
+
runtime these templates gets rendered into the exact same layouts and
|
131
|
+
partials that you would use if you were building from scratch. Its jsut
|
132
|
+
that now you can see what your pages will render like in your wysiwyg html
|
133
|
+
editor and change and layout accordingly. Additionally MasterView supplies some javascript
|
134
|
+
to show only one action view at time (list, new, show, edit, destroy) so
|
135
|
+
you can view in your browser without running in Rails. Dummy html can be
|
136
|
+
included to improve the accuracy of the page which can be easily removed at
|
137
|
+
runtime. To make it easier to work with in an editor, design time
|
138
|
+
stylesheets are included in the file to allow you to hide all sections
|
139
|
+
except the one you are working on, simply uncomment the appropriate
|
140
|
+
stylesheet for the section you would like to work with.
|
141
|
+
</p>
|
142
|
+
|
143
|
+
|
144
|
+
<h2>Using the MasterView Admin Controller</h2>
|
145
|
+
<p>
|
146
|
+
The MasterView admin controller/view is used by a MasterView developer
|
147
|
+
to obtain a birds-eye view of all your
|
148
|
+
masterview templates, the status of those templates (OK, Invalid xhtml,
|
149
|
+
Conflicts, Imports outdated), the details regarding the status, and the
|
150
|
+
ultimate erb files generated from each template.
|
151
|
+
The admin controller also displays a summary of your current configuration.
|
152
|
+
</p>
|
153
|
+
|
154
|
+
<p>The MasterView admin controller is enabled or disabled in your application
|
155
|
+
by the Master <code>enable_admin_pages</code> configuration setting.
|
156
|
+
By default, the admin controller is enabled.
|
157
|
+
See the <a href="configuration.html">MasterView Configuration Guide</a> for details.
|
158
|
+
</p>
|
159
|
+
|
160
|
+
<p>
|
161
|
+
When enabled, the MasterView admin controller is available in your application
|
162
|
+
at <a href="http://yourserver/masterview">http://yourserver/masterview</a>.
|
163
|
+
The Admin home page displays an overview of your application's templates
|
164
|
+
and links to admin information and operations.
|
165
|
+
</p>
|
166
|
+
|
167
|
+
<p>
|
168
|
+
Since it can be difficult to import a layout by hand into a new file, the
|
169
|
+
MasterView admin controller has a
|
170
|
+
link where you can copy the layout into a new file by providing the new
|
171
|
+
files Action. It will take the layout from the template chosen and create a
|
172
|
+
new file <code><i>controller</i>_<i>action</i>.html</code> with the layout imported
|
173
|
+
and a shell for the new Action code.
|
174
|
+
</p>
|
175
|
+
<p>
|
176
|
+
As described in the following section, youcan also do this from command line using rake:
|
177
|
+
</p>
|
178
|
+
<pre class="code">
|
179
|
+
rake mv:copy_layout TEMPLATE=foo_list.html ACTION=newaction
|
180
|
+
</pre>
|
181
|
+
|
182
|
+
|
183
|
+
<h3>Using Rake for MasterView Admin Operations</h3>
|
184
|
+
|
185
|
+
<p>All of the power of the MasterView admin controller is
|
186
|
+
also available via a set of rake commands.
|
187
|
+
MasterView includes a <code>masterview.rake</code> file in your
|
188
|
+
<code>vendor/plugins/masterview/tasks</code> directory which is automatically included
|
189
|
+
by the top level Rails Rakefile, so the masterview <b>mv:</b> admin tasks
|
190
|
+
are automatically available in your application's rake tasks
|
191
|
+
when the MasterView plugin is installed.
|
192
|
+
</p>
|
193
|
+
|
194
|
+
<p>
|
195
|
+
In a command shell, cd to your Rails application directory and use rake commands of the form:
|
196
|
+
</p>
|
197
|
+
|
198
|
+
<pre class="code">
|
199
|
+
rake mv:list
|
200
|
+
rake mv:list_all
|
201
|
+
rake mv:rebuild
|
202
|
+
rake mv:rebuild_all
|
203
|
+
rake mv:copy_layout
|
204
|
+
</pre>
|
205
|
+
|
206
|
+
<p>To obtain further information about the supported commands,
|
207
|
+
run the standard rake tasks report using the <code>--tasks</code> (<code>-T</code>) option:</p>
|
208
|
+
|
209
|
+
<pre class="code">
|
210
|
+
rake -T
|
211
|
+
</pre>
|
212
|
+
|
213
|
+
</div> <!-- bodyContent -->
|
214
|
+
</div>
|
215
|
+
|
216
|
+
<div id="pageFooter">
|
217
|
+
<div>
|
218
|
+
·
|
219
|
+
<a href="./index.html">Doc Home</a>
|
220
|
+
|
|
221
|
+
<a href="./installation.html">Installation</a>
|
222
|
+
|
|
223
|
+
<a href="./configuration.html">Configuration</a>
|
224
|
+
|
|
225
|
+
<a href="./guide.html">Usage</a>
|
226
|
+
|
|
227
|
+
<a href="./directives.html">Directives</a>
|
228
|
+
·
|
229
|
+
</div>
|
230
|
+
<table summary="layout area">
|
231
|
+
<tbody>
|
232
|
+
<tr>
|
233
|
+
<td class="copyright">© Copyright MasterView 2006</td>
|
234
|
+
<td class="validators">
|
235
|
+
<a href="http://validator.w3.org/check/referer">[Valid XHTML]</a>
|
236
|
+
</td>
|
237
|
+
</tr>
|
238
|
+
</tbody>
|
239
|
+
</table>
|
240
|
+
</div>
|
241
|
+
|
242
|
+
</body>
|
243
|
+
</html>
|
data/doc/index.html
ADDED
@@ -0,0 +1,287 @@
|
|
1
|
+
<?xml version="1.0" encoding="iso-8859-1"?>
|
2
|
+
<!DOCTYPE html
|
3
|
+
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
4
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
5
|
+
|
6
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
7
|
+
<head>
|
8
|
+
|
9
|
+
<title>MasterView - Rails-optimized (x)html friendly template engine</title>
|
10
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
11
|
+
<meta http-equiv="Content-Script-Type" content="text/javascript" />
|
12
|
+
|
13
|
+
<link href="./stylesheets/masterview.css" rel="stylesheet" type="text/css" />
|
14
|
+
</head>
|
15
|
+
|
16
|
+
<body>
|
17
|
+
|
18
|
+
<div id="pageHeader">
|
19
|
+
<div>MasterView Template Engine</div>
|
20
|
+
<div class="description">Rails-optimized (x)html friendly template engine</div>
|
21
|
+
</div>
|
22
|
+
|
23
|
+
<div id="pageBody">
|
24
|
+
<div id="bodyContent" mv:generate="{template_path}" mv:omit_tag="">
|
25
|
+
|
26
|
+
<h1>MasterView - Rails-optimized (x)html friendly template engine</h1>
|
27
|
+
|
28
|
+
<p>
|
29
|
+
MasterView is a ruby/rails
|
30
|
+
optimized HTML/XHTML friendly template engine. It is designed to use the
|
31
|
+
full power and productivity of rails including layouts, partials, and rails
|
32
|
+
html helpers while still being editable/styleable in a WYSIWYG HTML editor.
|
33
|
+
</p>
|
34
|
+
<p>
|
35
|
+
MasterView is distributed as a gem
|
36
|
+
or a plugin. You may install it as a gem and then generate a lightweight
|
37
|
+
plugin which mainly refers to the gem <b>or</b> you can simply install as a
|
38
|
+
plugin which is self contained. I personally prefer installing as a gem for
|
39
|
+
ease of management, however if you are running at a shared hosting
|
40
|
+
environment you might not have authority to install this gem so you may
|
41
|
+
install as a self contained plugin.
|
42
|
+
</p>
|
43
|
+
<p>
|
44
|
+
If you are interested in the background story behind all this, it is at the
|
45
|
+
end of this page.
|
46
|
+
</p>
|
47
|
+
|
48
|
+
<table summary="project location and author information">
|
49
|
+
<tr>
|
50
|
+
<td>Author:</td>
|
51
|
+
<td>Jeff Barczewski (jeff.barczewski <span class="class"> @ </span> gmail.com)</td>
|
52
|
+
</tr>
|
53
|
+
<tr><td>Primary developers:</td><td>Jeff Barczewski, Deb Lewis</td></tr>
|
54
|
+
<tr>
|
55
|
+
<td>Website:</td>
|
56
|
+
<td><a href="http://masterview.org">masterview.org</a></td>
|
57
|
+
</tr>
|
58
|
+
<tr>
|
59
|
+
<td>Rubyforge project:</td>
|
60
|
+
<td><a href="http://rubyforge.org/projects/masterview/">masterview</a></td>
|
61
|
+
</tr>
|
62
|
+
<tr><td>License:</td><td>MIT open source license (like Rails)
|
63
|
+
</td></tr>
|
64
|
+
<tr>
|
65
|
+
<td>Mailing lists:</td>
|
66
|
+
<td>Join mailing lists at <a href="http://rubyforge.org/mail/?group_id=1290">rubyforge.org</a></td>
|
67
|
+
</tr>
|
68
|
+
<tr>
|
69
|
+
<td> </td>
|
70
|
+
<td>masterview-announce - MasterView release announcements</td>
|
71
|
+
</tr>
|
72
|
+
<tr>
|
73
|
+
<td> </td>
|
74
|
+
<td>masterview-users - Discussion, problems, ideas, suggestions for MasterView</td>
|
75
|
+
</tr>
|
76
|
+
<tr>
|
77
|
+
<td> </td>
|
78
|
+
<td>masterview-devel - MasterView project developer list</td>
|
79
|
+
</tr>
|
80
|
+
<tr><td>Videos:</td><td><a href="http://masterview.org/videos/masterview_quick_start.html">MasterView Quick Start Video</a> - demonstrating basic usage of MasterView (no audio)</td></tr>
|
81
|
+
</table>
|
82
|
+
|
83
|
+
<h2>Goals</h2>
|
84
|
+
<ul>
|
85
|
+
<li>Create/extend a template engine for rails that would be XHTML friendly and
|
86
|
+
thus could be edited/styled with a WYSIWYG HTML editor even late in
|
87
|
+
development without breaking template.
|
88
|
+
|
89
|
+
</li>
|
90
|
+
<li>Keep it simple. DRY. No extra config files, simple syntax with ruby flavor.
|
91
|
+
|
92
|
+
</li>
|
93
|
+
<li>Design it specifically for ruby and rails. Use the full power and not be
|
94
|
+
limited in its capabilities over what can be done with ERb
|
95
|
+
|
96
|
+
</li>
|
97
|
+
<li>Work nicely with layouts, partials, and rails html helpers.
|
98
|
+
|
99
|
+
</li>
|
100
|
+
<li>Reduce complexity, work with existing rails code, no extra view logic or
|
101
|
+
hashes than what is used by ERb. Scaffold generate initial templates or
|
102
|
+
work from existing html prototype.
|
103
|
+
|
104
|
+
</li>
|
105
|
+
<li>Reduce the numbers of files, simplifying editing. Define partials and
|
106
|
+
layouts naturallyl right in the template, no need to go to another file.
|
107
|
+
|
108
|
+
</li>
|
109
|
+
<li>Preview in browser without running an app. Allow for dummy data in the
|
110
|
+
template so that the page can be viewed and styled independently of the
|
111
|
+
application.
|
112
|
+
|
113
|
+
</li>
|
114
|
+
<li>Performance equal to ERb
|
115
|
+
|
116
|
+
</li>
|
117
|
+
</ul>
|
118
|
+
|
119
|
+
|
120
|
+
<h2>Prerequisites</h2>
|
121
|
+
<table summary="prerequisites summary">
|
122
|
+
<tr><td valign="top">Requires:</td><td>No external dependencies
|
123
|
+
|
124
|
+
</td></tr>
|
125
|
+
<tr><td valign="top">Optional:</td><td>tidy, log4r</td></tr>
|
126
|
+
</table>
|
127
|
+
|
128
|
+
<p>See the <a href="installation.html">MasterView Installation Guide</a> for details.</p>
|
129
|
+
|
130
|
+
|
131
|
+
<h2>Installation and Configuration</h2>
|
132
|
+
|
133
|
+
<p>See the <a href="installation.html">MasterView Installation Guide</a> for complete installation instructions.</p>
|
134
|
+
|
135
|
+
<p>See the <a href="configuration.html">MasterView Configuration Guide</a> for informatino about customizing the MasterView configuration settings for your application.</p>
|
136
|
+
|
137
|
+
<h2>Usage</h2>
|
138
|
+
|
139
|
+
<p>See the <a href="guide.html">MasterView User's Guide</a> for information on using MasterView templates and supporting services.</p>
|
140
|
+
|
141
|
+
|
142
|
+
<h2>MasterView attribute directive syntax</h2>
|
143
|
+
|
144
|
+
<p>See the <a href="directives.html">MasterView Directives Reference</a> for complete descriptions of all the standard built-in MasterView directives.</p>
|
145
|
+
|
146
|
+
|
147
|
+
<h2>Background story</h2>
|
148
|
+
<p>
|
149
|
+
I came from a Java Struts environment when I was introduced to Ruby. I was
|
150
|
+
just in the process of evaluating Tapestry and JSF when I learned about
|
151
|
+
Rails. Ruby and Rails changed my world forever. I had to however drop many
|
152
|
+
of my bad habits aquired from years of Java and C++ work. I had to embrace
|
153
|
+
the new ideas and approach things now with a different mindset. (If you
|
154
|
+
ever have a chance to hear Dave Thomas speak, you will know what I mean. He
|
155
|
+
has a wonderfully entertaining yet enlightening way of illustrating this.)
|
156
|
+
</p>
|
157
|
+
<p>
|
158
|
+
After learning the Ruby and Rails way, (Thank you Matz and DHH for such
|
159
|
+
wonderful gifts to the world) I was amazed at how productive this
|
160
|
+
environment is. Programming was fun once again, and everything you do in
|
161
|
+
Ruby or Rails is easier than any other language or framework I have ever
|
162
|
+
seen. Even taking into account having to learn something new, I was still
|
163
|
+
far more productive than ever before. The only thing that I felt that could
|
164
|
+
be done better, was to have a nice html friendly templating engine so that
|
165
|
+
designers and developers could work collaboratively together on a project.
|
166
|
+
The designers could style and layout the pages with their WYSIWYG HTML
|
167
|
+
editors and developers would have the full power of Ruby and Rails without
|
168
|
+
having to jump through extra hoops to use them. I looked at the available
|
169
|
+
html template engines to see if anything fit with my style. I was
|
170
|
+
disappointed with each of them, mainly because they all made it harder than
|
171
|
+
straigt ERb (rhtml) and were not able to use layouts and partials easily.
|
172
|
+
</p>
|
173
|
+
<p>
|
174
|
+
After all the hard work so many people have put into Ruby and Rails, I
|
175
|
+
wanted to see if there was anyway I could contribute as well, maybe
|
176
|
+
extending one of the existing template projects to have the ideal
|
177
|
+
functionality I was striving for. I wanted something to make my own web
|
178
|
+
development even more productive. However after reviewing each of them and
|
179
|
+
even getting into the source code, the closest ones seemed to be Amrita2,
|
180
|
+
Liquid, and Kwartz. Unfortunately it was not going to be easy to add the
|
181
|
+
functionality and usability I desired.
|
182
|
+
</p>
|
183
|
+
<p>
|
184
|
+
During my research I learned that many of the rails gurus were putting down
|
185
|
+
html template engines because they felt that they handicapped the developer
|
186
|
+
severely, namely by not taking advantage of rails layouts, partials, and
|
187
|
+
html helpers. After doing some projects with ERb (rhtml) I realized that
|
188
|
+
they were right. I too did not want to give up any of that power either. I
|
189
|
+
also didn’t want to create a bunch of extra code or config to use the
|
190
|
+
templates (extra view code, or data structures to pass to the templates) as
|
191
|
+
so many of the other engines relied on.
|
192
|
+
</p>
|
193
|
+
<p>
|
194
|
+
I expanded my search outside of Ruby for the best html template technology
|
195
|
+
I could find. After reviewing all the front runners I still didn’t
|
196
|
+
find anything that quite met with my goals for developing with ruby and
|
197
|
+
rails. I also didn’t find any technology that was close enough that I
|
198
|
+
could adapt it. However I did come across features in a variety of systems
|
199
|
+
that inspired me, and helped me shape the ideas that are presented here. A few
|
200
|
+
of those systems were Tapestry, Zope/PHP TAL, Kwartz, Amrita 2, Liquid,
|
201
|
+
and Web Objects.
|
202
|
+
</p>
|
203
|
+
<p>
|
204
|
+
After putting much thought into all the possible options I could not see
|
205
|
+
extending an existing template engine to meet my needs. And since I wanted
|
206
|
+
this engine to have all the power of ruby and rails, it seemed that I would
|
207
|
+
be best served by developing a html template syntax that was a thin layer
|
208
|
+
above ERb. That way it would be intuitive to use (not having to learn yet
|
209
|
+
another syntax) yet very powerful. Once I was able to come up with the
|
210
|
+
desired syntax and approach it became apparent that this would also be
|
211
|
+
fairly straightforward to build.
|
212
|
+
</p>
|
213
|
+
<p>
|
214
|
+
I ran the concept by the guys at the St. Louis Ruby Group <a
|
215
|
+
href="http://stlruby.org">stlruby.org</a> and they were excited about the
|
216
|
+
project. With their help I was able to simply some of the confusing or
|
217
|
+
complicated areas before beginning development. They also sparked some
|
218
|
+
ideas about how to make this infinitely extensible such that developers
|
219
|
+
could easily add their own attribute directives. This would give them the
|
220
|
+
power to create custom extensions that would encapsulate some of their
|
221
|
+
development work. This would serve a couple needs, it would not only make
|
222
|
+
this engine extensible, it would also allow this engine to grow easily
|
223
|
+
being composed of small pluggable attribute directives. Many thanks to the
|
224
|
+
members of this group, I continue to enjoy discussing the power of Ruby and
|
225
|
+
learning from each of them on a monthly basis.
|
226
|
+
</p>
|
227
|
+
<p>
|
228
|
+
While I am on the subject of thanks, I would like to thank my wife and
|
229
|
+
daughter for their support as I took time away from them to work on this
|
230
|
+
project and I want to thank God for bringing the right people into my life
|
231
|
+
just when I needed them and for bringing me on this wonderful journey, I am
|
232
|
+
so very blessed. May I be able to give back some of what has been given to
|
233
|
+
me.
|
234
|
+
</p>
|
235
|
+
<p>
|
236
|
+
And one more mention of tremendous thanks to Deb Lewis, the other core developer on the
|
237
|
+
team, she has spent countless hours reviewing, revising, and improving the codebase,
|
238
|
+
configuration, and documentation. The project wouldn't be half of what it is today
|
239
|
+
without all her help, inspiration, and hard work. I thoroughly enjoy working and
|
240
|
+
debating the finer points of the project with her each step of the way.
|
241
|
+
</p>
|
242
|
+
<p>
|
243
|
+
So that’s the story, I hope that many of you will find MasterView to be a useful tool for
|
244
|
+
your development. I am continuing to refine MasterView by using it daily for
|
245
|
+
Genesis Ministry sites and all my web projects. I know that there is much
|
246
|
+
more work needed in documentation, examples, test cases, additional
|
247
|
+
directives, etc., so I would appreciate any feedback and ideas that you
|
248
|
+
have. Thanks for taking the time to review MasterView!
|
249
|
+
</p>
|
250
|
+
<p>
|
251
|
+
Jeff Barczewski
|
252
|
+
(jeff.barczewski
|
253
|
+
<span class="class"> @ </span>
|
254
|
+
gmail.com)
|
255
|
+
</p>
|
256
|
+
|
257
|
+
</div> <!-- bodyContent -->
|
258
|
+
</div>
|
259
|
+
|
260
|
+
<div id="pageFooter">
|
261
|
+
<div>
|
262
|
+
·
|
263
|
+
<a href="./index.html">Doc Home</a>
|
264
|
+
|
|
265
|
+
<a href="./installation.html">Installation</a>
|
266
|
+
|
|
267
|
+
<a href="./configuration.html">Configuration</a>
|
268
|
+
|
|
269
|
+
<a href="./guide.html">Usage</a>
|
270
|
+
|
|
271
|
+
<a href="./directives.html">Directives</a>
|
272
|
+
·
|
273
|
+
</div>
|
274
|
+
<table summary="layout area">
|
275
|
+
<tbody>
|
276
|
+
<tr>
|
277
|
+
<td class="copyright">© Copyright MasterView 2006</td>
|
278
|
+
<td class="validators">
|
279
|
+
<a href="http://validator.w3.org/check/referer">[Valid XHTML]</a>
|
280
|
+
</td>
|
281
|
+
</tr>
|
282
|
+
</tbody>
|
283
|
+
</table>
|
284
|
+
</div>
|
285
|
+
|
286
|
+
</body>
|
287
|
+
</html>
|