RubyGems - masterview - Versions diffs - 0.2.5 → 0.3.0 - Mend

masterview 0.2.5 → 0.3.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.

Files changed (155) hide show

data/CHANGELOG +31 -1
data/README +70 -69
data/RELEASE_NOTES +70 -64
data/Rakefile +26 -27
data/TODO +13 -29
data/doc/about.html +246 -0
data/doc/configuration.html +49 -36
data/doc/developer.html +423 -41
data/doc/directives.html +139 -51
data/doc/guide.html +19 -9
data/doc/index.html +90 -224
data/doc/installation.html +36 -28
data/doc/media_list.html +30 -20
data/doc/simple_diagram.html +3 -5
data/doc/stylesheets/masterview.css +16 -1
data/examples/rails_app_config/masterview/settings.rb +2 -1
data/init.rb +1 -1
data/lib/#ChangeLog# +6 -0
data/lib/masterview/analyzer.rb +48 -34
data/lib/masterview/attr_string_parser.rb +5 -1
data/lib/masterview/case_insensitive_hash.rb +69 -0
data/lib/masterview/{pathname_extensions.rb → core_ext/pathname.rb} +0 -0
data/lib/masterview/{string_extensions.rb → core_ext/string.rb} +0 -0
data/lib/masterview/deprecated/directive_base.rb +362 -0
data/lib/masterview/directive_base.rb +201 -179
data/lib/masterview/directive_dsl.rb +457 -0
data/lib/masterview/directive_helpers.rb +28 -141
data/lib/masterview/directive_load_path.rb +388 -0
data/lib/masterview/directive_metadata.rb +377 -0
data/lib/masterview/directive_registry.rb +259 -69
data/lib/masterview/directives/.metadata +16 -0
data/lib/masterview/directives/attr.rb +9 -8
data/lib/masterview/directives/block.rb +11 -14
data/lib/masterview/directives/check_box.rb +13 -18
data/lib/masterview/directives/collection_select.rb +15 -29
data/lib/masterview/directives/content.rb +9 -3
data/lib/masterview/directives/else.rb +15 -13
data/lib/masterview/directives/elsif.rb +14 -13
data/lib/masterview/directives/eval.rb +20 -0
data/lib/masterview/directives/form.rb +56 -9
data/lib/masterview/directives/form_remote.rb +26 -0
data/lib/masterview/directives/global_inline_erb.rb +10 -14
data/lib/masterview/directives/hidden_field.rb +11 -20
data/lib/masterview/directives/if.rb +13 -12
data/lib/masterview/directives/image_tag.rb +20 -28
data/lib/masterview/directives/import.rb +5 -12
data/lib/masterview/directives/import_render.rb +7 -19
data/lib/masterview/directives/insert_generated_comment.rb +8 -11
data/lib/masterview/directives/javascript_include.rb +21 -12
data/lib/masterview/directives/link_to.rb +14 -8
data/lib/masterview/directives/link_to_function.rb +22 -0
data/lib/masterview/directives/link_to_if.rb +15 -13
data/lib/masterview/directives/link_to_remote.rb +13 -8
data/lib/masterview/directives/omit_tag.rb +32 -16
data/lib/masterview/directives/password_field.rb +10 -22
data/lib/masterview/directives/radio_button.rb +11 -22
data/lib/masterview/directives/replace.rb +7 -8
data/lib/masterview/directives/select.rb +11 -24
data/lib/masterview/directives/stylesheet_link.rb +20 -12
data/lib/masterview/directives/submit.rb +11 -5
data/lib/masterview/directives/text_area.rb +10 -23
data/lib/masterview/directives/text_field.rb +10 -22
data/lib/masterview/exceptions.rb +21 -0
data/lib/masterview/extras/app/controllers/masterview_controller.rb +102 -75
data/lib/masterview/extras/app/views/layouts/masterview_admin.rhtml +24 -23
data/lib/masterview/extras/app/views/layouts/masterview_admin_config.rhtml +81 -0
data/lib/masterview/extras/app/views/masterview/admin/configuration.rhtml +5 -1
data/lib/masterview/extras/app/views/masterview/admin/create.rhtml +2 -2
data/lib/masterview/extras/app/views/masterview/admin/directives.rhtml +5 -0
data/lib/masterview/extras/app/views/masterview/admin/features.rhtml +5 -79
data/lib/masterview/extras/app/views/masterview/admin/interact.rhtml +5 -0
data/lib/masterview/extras/app/views/masterview/admin/list.rhtml +3 -71
data/lib/masterview/extras/init_mv_admin_pages.rb +42 -23
data/lib/masterview/filter_helpers.rb +26 -0
data/lib/masterview/initializer.rb +99 -53
data/lib/masterview/io.rb +19 -15
data/lib/masterview/keyword_expander.rb +7 -2
data/lib/masterview/masterview_info.rb +229 -23
data/lib/masterview/masterview_version.rb +2 -2
data/lib/masterview/parser.rb +275 -105
data/lib/masterview/parser_helpers.rb +54 -0
data/lib/masterview/rails_ext/action_controller_erb_direct.rb +29 -0
data/lib/masterview/rails_ext/action_controller_reparse_checking.rb +27 -0
data/lib/masterview/{extras/init_rails_erb_mv_direct.rb → rails_ext/action_view_erb_direct.rb} +12 -59
data/lib/masterview/template_spec.rb +3 -2
data/lib/masterview.rb +21 -12
data/lib/rexml/parsers/baseparser_with_doctype_fix.rb +473 -0
data/lib/rexml/parsers/sax2parser_with_doctype_fix.rb +243 -0
data/test/directive_test_helper.rb +135 -0
data/test/fixtures/directives/id_check.rb +18 -0
data/test/fixtures/directives/test_directive_events.rb +70 -0
data/test/test_helper.rb +18 -5
data/test/tmp/views/layouts/product.rhtml +10 -10
data/test/tmp/views/product/_form.rhtml +4 -4
data/test/tmp/views/product/_product.rhtml +3 -3
data/test/tmp/views/product/destroy.rhtml +5 -5
data/test/tmp/views/product/edit.rhtml +4 -4
data/test/tmp/views/product/list.rhtml +3 -3
data/test/tmp/views/product/new.rhtml +4 -4
data/test/tmp/views/product/show.rhtml +2 -2
data/test/unit/attr_string_parser_test.rb +105 -0
data/test/unit/case_insensitive_hash_mod_test.rb +104 -0
data/test/unit/config_settings_test.rb +13 -1
data/test/unit/default_generate_mio_filter_test.rb +3 -3
data/test/unit/deprecated_directive_base_test.rb +30 -0
data/test/unit/directive_attr_test.rb +111 -35
data/test/unit/directive_base_test.rb +520 -1
data/test/unit/directive_block_test.rb +30 -22
data/test/unit/directive_content_test.rb +24 -11
data/test/unit/directive_else_test.rb +18 -15
data/test/unit/directive_elsif_test.rb +17 -15
data/test/unit/directive_form_remote_test.rb +59 -0
data/test/unit/directive_form_test.rb +31 -39
data/test/unit/directive_global_inline_erb_test.rb +28 -17
data/test/unit/directive_grid_test_notready.rb +38 -0
data/test/unit/directive_helpers_test.rb +39 -0
data/test/unit/directive_hidden_field_test.rb +44 -29
data/test/unit/directive_if_test.rb +10 -7
data/test/unit/directive_image_tag_test.rb +69 -61
data/test/unit/directive_import_render_test.rb +28 -38
data/test/unit/directive_import_test.rb +16 -14
data/test/unit/directive_insert_generated_comment_test.rb +32 -0
data/test/unit/directive_javascript_include_test.rb +40 -43
data/test/unit/directive_link_to_function_test.rb +40 -0
data/test/unit/directive_link_to_if_test.rb +52 -12
data/test/unit/directive_link_to_remote_test.rb +58 -0
data/test/unit/directive_link_to_test.rb +46 -31
data/test/unit/directive_load_path_test.rb +257 -0
data/test/unit/directive_metadata_test.rb +313 -0
data/test/unit/directive_omit_tag_test.rb +73 -21
data/test/unit/directive_password_field_test.rb +44 -38
data/test/unit/directive_registry_test.rb +44 -0
data/test/unit/directive_replace_test.rb +28 -12
data/test/unit/directive_stylesheet_link_test.rb +43 -36
data/test/unit/directive_submit_test.rb +29 -30
data/test/unit/directive_text_area_test.rb +40 -36
data/test/unit/directive_text_field_test.rb +44 -38
data/test/unit/example_directive_child_events_test.rb +41 -0
data/test/unit/example_test.rb +31 -4
data/test/unit/file_mio_test.rb +18 -13
data/test/unit/filter_helpers_test.rb +10 -8
data/test/unit/find_directive_parent_test.rb +174 -0
data/test/unit/keyword_expander_test.rb +4 -2
data/test/unit/mio_test.rb +18 -11
data/test/unit/mtime_string_hash_mio_tree_test.rb +5 -1
data/test/unit/parser_test.rb +41 -29
data/test/unit/pathname_extensions_test.rb +1 -1
data/test/unit/run_parser_test.rb +2 -2
data/test/unit/simplified_directive_base_test.rb +256 -0
data/test/unit/string_hash_mio_test.rb +5 -1
data/test/unit/template_file_watcher_test.rb +2 -2
data/test/unit/template_test.rb +221 -46
metadata +86 -45
data/lib/masterview/directives/testfilter.rb +0 -55
data/lib/masterview/extras/init_rails_reparse_checking.rb +0 -62

data/doc/developer.html CHANGED Viewed

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html
+<!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>
@@ -11,6 +11,16 @@
   <meta http-equiv="Content-Script-Type" content="text/javascript" />
   <link href="./stylesheets/masterview.css" rel="stylesheet" type="text/css" />
+<style type="text/css">
+table.eventDescription {
+  margin-left: 20px;
+  margin-right: 20px;
+}
+table.eventDescription th, table.eventDescription td {
+  text-align: left;
+  padding-right: 8px;
+}
+</style>
 </head>
 <body>
@@ -24,6 +34,8 @@
 &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>
@@ -32,7 +44,9 @@
 &nbsp;|&nbsp;
 <a href="./directives.html">Directives</a>
 &nbsp;|&nbsp;
-<a href="./media_list.html">Media (Videos/Illustrations)</a>
+<a href="./developer.html">Developers</a>
+&nbsp;|&nbsp;
+<a href="./media_list.html">Screencasts</a>
 &nbsp;&middot;
 </div>
 </div>
@@ -49,7 +63,7 @@ It is also designed to be easily extensible by adding custom directives, as desc
 <p>
 Before undertaking implementation of your own custom directive, we recommend that
-you review the <a href="#processing_overview">Overview of Template Processing and Directives</a> section, which explains the processing context within which a directive implementation executes.
+you review the <a href="#processing_overview">Overview of Template Processing and Directives</a> section, which discusses the processing context within which a directive implementation executes.
 Then read the <a href="#directive_framework">Directive Implementation Framework</a>
 for a guide to the facilities provided by MasterView to
 simplify the development effort required to implement a new directive.
@@ -58,7 +72,7 @@ simplify the development effort required to implement a new directive.
 <a name="processing_overview"></a>
 <h2>Overview of Template Processing and Directives</h2>
-<p>A MasterView template is an <a href="http://www.w3.org/TR/xhtml1/" target="_blank">XHTML</a> document
+<p>A MasterView template is an <a href="http://www.w3.org/TR/xhtml1/" target="_blank">XHTML</a> document
 which uses attribute markup on the standard document elements to encode processing directives for the template engine.
 The <a href="http://www.w3.org/TR/REC-xml-names/" target="_blank">XML namespace</a> facility is used to identify attributes containing processing instructions.
 </p>
@@ -72,12 +86,14 @@ the <span class="directiveName">mv:</span> namespace name using the
 <code>namespace_prefix</code> configuration setting.)
 </p>
-<p class="explanation">Note: an XML schema definition of the builtin MasterView directives namespace will be published Real Soon Now.
-This will enable a proper declaration of the MasterView attribute namespace
+<div class="todo">
+Note: an XML schema definition of the builtin MasterView directives namespace
+should be published on the <code>masterview.org</code> site.
+This would enable a proper declaration of the MasterView attribute namespace
 on your <code>&lt;html&gt;</code> elements of the form
 <code>xmlns:mv='http://masterview.org/schema/2006/directives'</code>
 (specific URI tba when published), which is useful as a documentary aide as well as to enable validation.
-</p>
+</div>
 <p>In addition to the builtin MasterView directives, custom directives can be
 used by appending one or more directories containing directive implementation classes
@@ -88,12 +104,17 @@ the fully qualified name of the directive attribute (namespace + simple attribut
 and the directive implementation class which is instantiated to process a directive attribute.
 </p>
-<p class="explanation">TODO: include recommendation on namespace usage for custom directives.</p>
+<div class="todo">
+TODO: include recommendation on namespace usage for custom directives.
+Believe we should use <span class="directiveName">mvx:</span> namespace
+as the default for extension directives, to distinguish from the builtin directives namespace.
+</div>
 <h3>Template Document Processing</h3>
 <p>When MasterView processes a template document, the document is processed
-as a DOM node hierarchy of elements and attributes.
+as a
+<a href="http://xml.coverpages.org/dom.html" target="_blank">DOM</a> node hierarchy of elements and attributes.
 Template processing is essentially a tree transformation process: the elements and their attributes from the template source document are processed and emitted onto the output.
 </p>
@@ -101,61 +122,416 @@ Template processing is essentially a tree transformation process: the elements a
 in the output.  The addition of MasterView directive attributes to an element allows for transformation and substitution to occur between the template source and the generated output.
 </p>
+<p>It can be useful to think of directives as providing several typical flavors of processing:</p>
+<dl>
+<dt>attribute modifiers</dt>
+<dd>the directive operates on the attributes of the element (adds or removes attributes or changes values of existing attributes)</dd>
+<dt>content modifiers</dt>
+<dd>the directive operates on the content of the element (modifies or replaces the content of the element)</dd>
+<dt>eval-only</dt>
+<dd>the directive is evaluated such that it has some effect on the overall state of the document processing, but does not directly affect the attributes or content of its element in the output</dd>
+</dl>
+<p>Some directives provide combinations of these processing flavors.
+<!--??, e.g., a simple directive may simply modify the value of a standard attribute on the element (e.g., <span class="directiveName">mv:attr</span>), while a more complex directive may generate ... blah blah... ??-->
+</p>
+<h3>Template Directive Processing</h3>
 <p>
-As each element in the document is processed, any attributes which are MasterView
-directives are collected and sorted into processing order according to the
-<code>priority</code> order defined for each directive.
+As each element in the source document is processed, any attributes in the element start tag
+which are MasterView directives are collected and sorted into processing order
+according to the <code>priority</code> order defined for each directive.
 The <code>MasterView::DirectivePriorities</code> range from
 <code>Lowest</code> to <code>Highest</code>, with
 <code>DirectivePriorities::Medium</code> the default.
-In most cases, you do not need to be concerned with priority; the default order
-works for most usage.
+In most cases, you do not need to be concerned with priority - the default priority order
+is acceptable for most directives.
 </p>
 <p>For each MasterView directive attribute on a document element,
 the template engine creates an instance of the directive's implementation class to provide the directive processing for that element.
-The directive handler is provided with the attribute value from the document element when it is created so that it has access to the information needed to perform its operation.
+The directive handler is provided with its attribute value from the document element when it is constructed so that it has access to any parameters provided to control its operation.
 </p>
-<h3>Template Processing Directives</h3>
-<p>Directives can be thought of as providing several flavors of processing:</p>
-<dl>
-<dt>attribute modifiers</dt>
-<dd>the directive operates on the attributes of the element (adds or removes attributes or changes values of existing attributes></dd>
-<dt>content modifiers</dt>
-<dd>the directive operates on the content of the element (modifies or replaces the content of the element)</dd>
-<dt>eval-only</dt>
-<dd>the directive is evaluated such that it has some effect on the overall state of the document processing, but does not directly affect the attributes or content of its element in the output</dd>
-</dl>
+<div class="todo">TODO: add note about "global directives" that can be activated
+on all elements in the document or on selected elements,
+e.g., all elements of a specific type (all &lt;img&gt; elements, all &lt;table&gt; elements...).
+This may be something that we want to control on a per-document basis,
+so we're considering the need for a masterview directive which would configure doc-specific options
+</div>
-<p>Some directives provide combinations of these processing flavors.
-<!--??, e.g., a simple directive may simply modify the value of a standard attribute on the element (e.g., <span class="directiveName">mv:attr</span>), while a more complex directive may generate ... blah blah... ??-->
+<p>
+A directive handler can be invoked to perform its processing at several points during the processing of the document element on which it is defined:
 </p>
+<ul>
+<li>during the start tag processing for the element</li>
+<li>when the complete content of the document element is available from the source</li>
+<li>during the end tag processing for the element</li>
+<li>when the complete document element (start/end tags + content) is available</li>
+</ul>
-<p class="explanation">TODO: fill in a bit here with description of the range of invocation points at which a directive may hook up to perform its processing; typically either start or end of the element tag to which it is attached</p>
+<p class="explanation">(The possible invocation points are actually slightly more detailed, but this simplified list of processing points is sufficient for discussing the behavior of most directives.)</p>
+<p>By implementing processing logic at these various points during the overall document processing, a directive can accomplish its objectives by affecting the element attributes that are emitted to the output document, by manipulating the element content that is rendered, or by controlling the entire element (if any) that is rendered onto the output from the source.
+</p>
+<p>Recall also that a document element can contain other elements, in addition to or instead of text content.  Directives on nested elements are processed along with the child elements in the source document, so a directive on an ancestor element sees the result of any nested directives at the point where it operates on the resulting element and its content.
+</p>
 <a name="directive_framework"></a>
 <h2>Directive Implementation Framework</h2>
-<p class="explanation">Under construction... provide an overview of MasterView::DirectiveBase and the DirectiveHelpers mixin</p>
+<p>
+When you create a custom MasterView template directive, you need to do several things:
+</p>
+<ul>
+<li>define the directive - its name and purpose (semantics)</li>
+<li>define the attribute syntax - what parameters, if any, are specified in the attribute value</li>
+<li>define the processing logic - determine at what points in the source element processing your directive handler should be invoked and define the logic which determines its effect on the output document</li>
+</ul>
+<h3>Creating the Directive Implementation Class</h3>
+<p>
+A directive implementation extends the <code>MasterView::DirectiveBase</code> base class,
+which provides the standard infrastructure for directives.
+</p>
+<pre class="code">
+module MyAppDirectives
+  class MyDirective < MasterView::DirectiveBase
+    # ... directive metadata declarations ...
+    # ... directive attribute value argument definitions ...
+    # ... template element processing event handlers ...
+  end
+end
+</pre>
+<p class="explanation">
+<b>Note:</b> it is not mandatory to subclass <code>DirectiveBase</code> to implement a directive class, but it'll certainly make your life easier.
+The key mixin classes which provide the essence of directive-nesss
+in the <code>DirectiveBase</code> implementation framework
+are <code>DirectiveMetadata</code> and <code>DirectiveDSL</code>, along with
+some convenience services from <code>DirectiveHelpers</code>.
+</p>
+<h3>Directive Metadata Specification</h3>
+<p>A directive is described by various standard properties which are associated
+with the directive implementation class as metadata properties.
+Some of the metadata properties affect the processing operations of the template engine,
+while others are descriptive information for documentation purposes.
+</p>
+<p>The standard directive metadata properties recognized by MasterView are:</p>
+<ul>
+<li><code>:namespace</code> - the namespace used for the directive in template markup</li>
+<li><code>:attribute_name</code> - the attribute name used for the directive in template markup</li>
+<li><code>:priority</code> - processing priority level of the directive</li>
+<li><code>:description</code> - a short (1-liner) description of the directive</li>
+</ul>
+<!--PUNT: not yet clear what we want to say about this [DJL 17-Oct02006]
+<p class="explanation">(Note: the documentation metadata attributes are not yet fully exploited in ways that we might like.  The <code>:summary</code> attribute is used on the Directives information page by the MasterView Admin controller; we would like in the future to provide easier access automate the directive documentation to build rdoc-style)
+</p>
+-->
+<p>The default attribute name for a directive is derived from the class name,
+similar to the name association schemes used by Rails for controllers, helpers, and views,
+so this metadata attribute typically does not need an explicit declaration.
+By default, directive class <code>Foo</code> is associated with attribute <code>foo</code> in template markup, while <code>FooBar</code> is associated with attribute <code>foo_bar</code>, etc.
+</p>
+<p>The default directive priority level is <code>Medium</code>, on the spectrum ranging from
+<code>Highest</code>...<code>VeryHigh</code>...<code>High</code>...<code>Medium</code>...<code>Low</code>...<code>VeryLow</code>...<code>Lowest</code>.
+</p>
+<p>Directive metadata can be specified in several ways, with a precedence hierarchy allowing for application-specific customization:</p>
+<ul>
+<li><code>metadata</code> declaration in the directive class
+<div>typically used for <code>:summary</code> and optionally to modify the default <code>:priority</code>; used to specify <code>:attribute_name</code> if necessary
+</div>
+</li>
+<li><code>.metadata</code> specification file in the directory on the load path
+<div>YAML notation specification of the <code>default:</code> metadata values for directive classes contained in this directory.  Typically used to specify the <code>:namespace</code> for a set of directives.</div>
+</li>
+<li><code>metadata settings hash associated with a directive load path directory entry</code>
+<div>hash containing <code>default:</code> hash for metadata defaults.
+Allows a client application to override the metadata defaults; can be used to modify the namespace for the directives used in template document markup by this application (e.g., to mediate directive namespace collisions if multiple sources of addon directives are used)
+</div>
+</li>
+</ul>
+<h4>Directive Argument Definition Examples</h4>
+<pre class="code">
+module MyAppDirectives
+  class MyDirective < MasterView::DirectiveBase
+    metadata :priority => 'High',
+      :description => 'My really cool directive'
+    # ... directive attribute value argument definitions ...
+    # ... template element processing event handlers ...
+  end
+end
+</pre>
+<p>A <code>.metadata</code> file in the directory containing directive class .rb code files:</p>
+<pre class="code">
+# MasterView directive metadata specifications
+# Built-in MasterView directives
+# default metadata values for directives loaded from this directory
+# template document attribute qnames: &lt;xxx coolops:foo="bar"&gt;...&lt;/xxx&gt;
+default:
+  namespace: coolops
+</pre>
+<p>An application-specific override of the default namespace for the directives loaded from a directory specified in the application's <code>masterview/settings.rb</code> configuration:</p>
+<pre class="code">
+config.add_directive_path '/path/to/custom/directives', { :default: => {:namespace => 'xops'}, }
+</pre>
+<h3>Directive Attribute Syntax Specification</h3>
+<p>
+When you create a directive, you need to specify the syntax that will be used for
+writing the directive attribute and its value in template document markup.
+Your directive will generally need to be provided with arguments which control the
+processing of the document element on which the directive attribute is defined.
+</p>
+<p>In some cases, the entire directive attribute value is used as a single argument.
+For example, the <code>mv:content</code> directive which replaces the content of the element on which it is defined with the results of evaluating a ruby expression uses its attribute value string to generate an embedded ruby block <code>&lt;%= ...attr value... %&gt;</code> in the output.
+A directive implementation can access its attribute value using the <code>attr_value</code> accessor.
+</p>
+<p>
+A directive can also use its attribute value as an argument list, just as arguments are used when invoking a Ruby method.
+The MasterView directive implementation framework provides a simple declarative notation
+for defining the argument list signature of an attribute.  Each argument that you declare is mapped to an instance variable in your directive class, with parsing of the attribute value string into the variable value handled automatically by the directive framework facilities of MasterView.
+</p>
+<p>
+As with parameters to a Ruby method, directive arguments obtained from the attribute value string in the template souurce document can
+be expressed as a sequence of positional parameters, optionally with a default value.
+Keyword values can be specified using Ruby hash literal notation <code>{ key1 => value1, key2 => value2, ...}</code>.
+Trailing values in a variable-length argument list can be collected in a single array value argument.
+Finally, an optional block argument can be provided with an argument definition to provide custom processing on the value.
+</p>
+<p>To define the parameters for your directive and the parsing rules for extracting each value from the directive attribute value string, use the <code>attr_arg</code> declaration in your directive implementation class.  The first argument to <code>attr_arg</code> is a symbol with the name of the argument, which is used to create an accessor method for an instance variable that will contain the argument value.
+Argument values extracted from the attribute value are strings.
+</p>
+<p>
+Additional options can be specified in the form <code><i>:option_name</i> => <i>value</i></code>
+to indicate how the value should be obtained. By default, an omitted argument value is parsed as an empty string.
+</p>
+<!--####
+Keyword args must be wrapped in hash literal brackets *unless* they are the last arg.
+###test array lits....
+###-->
+<ul>
+<li><code>attr_arg <i>:argname</i>, :quote => true</code> - wrap  the argument value in (single) quotes
+</li>
+<li><code>attr_arg <i>:argname</i>, :default => <i>value</i></code> - specify default value if the argument is omitted
+</li>
+<li><code>attr_arg <i>:argname</i>, :varargs => true</code> - collect remaining args (if any) as an array (like *params in ruby)
+</li>
+<li><code>attr_arg <i>:argname</i>, :append_element_attrs => [<i>attrName1</i>, <i>attrName1</i>,...]</code> - merge the specified attributes from the element into a hash value
+<div>Specify <code>:common_html</code> as shorthand for collecting common html attributes (id, class, style, alt, title, width, height, etc)</div>
+</li>
+</ul>
+<p>An <code>attr_arg <i>:argname</i></code> directive argument definition can also be specified with an block argument which allows for arbitrary processing to determine the value.
+</p>
+<ul>
+<li><code>attr_arg <i>:argname</i> {...}</code> - set the argument value to the the result of evaluating the block with no arguments
+</li>
+<li><code>attr_arg <i>:argname</i> {|value| ... }</code> -  pass arg value into block to allow additional manipulation of the value
+</li>
+<li><code>attr_arg <i>:argname</i> {|value args| ... }</code> -  pass value and remaining args array to the block
+</li>
+<li><code>attr_arg <i>:argname</i> {|value args directive| ... }</code> -  pass value, remaining args array, and the directive instance for which the argument value is being obtained to the block
+</li>
+</ul>
+<h4>Directive Argument Definition Examples</h4>
+<pre class="code">
+module MyAppDirectives
+  class MyDirective < MasterView::DirectiveBase
+    # wrap the value parsed from the attribute value in string quotes
+    attr_arg :string_lit_arg, :quote => true
+    # a value that we want to normalize
+    attr_arg :some_option { |value| value.downcase }
+    # a value with a default if not specified
+    attr_arg :other_option, :default => 'normal'
+    # collect attributes from the element
+    attr_arg :html_options, :append_element_attrs => [:common_html, :size]
+    # ... template element processing event handlers ...
+  end
+end
+</pre>
+<h4>Directive Attribute Value Processing</h4>
-<h3>Construction</h3>
 <p>When a directive attribute is encountered while processing a document element node,
-an instance of the implementation class registered for that directive is constructed to process the element attribute.  The value of the directive attribute from the document element is passed to the initializer as a <code>String</code> value.
-A directive attribute of the form <code>mv:some_directive="attr_value"</code> in the template
-results in a directive processor being instantiated for that element by an constructor of the form <code>SomeDirective.new(attr_value)</code>.
+an instance of the implementation class registered for that directive is constructed for processing the element.  The value of the directive attribute from the document element is passed to the directive's initializer as a <code>String</code> value
+and is available to the directive handler
+using the <code>attr_value</code> accessor.
+</p>
+<p>The directive argument definitions from the <code>attr_arg</code> specifications in the directive implementation are applied in declaration order to initialize the instance variable values of the directive handler from the attribute value.</p>
+<h3>Document Element Processing</h3>
+<p>
+A directive implementation specifies its effect on processing the document element to which it is attached by declaring one or more event handlers using the <code>event</code> declaration.
+An event handler definition specifies a processing event at which it is to be invoked
+and the action to be taken.
+</p>
+<h4>Document Processing Event Registration</h4>
+<p>The general form of an event handler declaration is <code>event <i>:eventname</i> <i>action</i></code>.</p>
+<p>
+A directive can specify an action to be performed at any of the following events which are notified during the processing of a document element:
+</p>
+<table class="eventDescription" summary="detailed list of processing events">
+<thead>
+<tr><th>Event</th><th>Description</th><th>Default Action</th></tr>
+</thead>
+<tbody>
+<tr>
+<td><code>:before_stag</code></td>
+<td><i>tbs</i></td>
+<td>&nbsp;</td>
+</tr>
+<tr>
+<td><code>:stag</code></td>
+<td>element start tag and attributes are available</td>
+<td>Append the start tag to the rendering output for this element</td>
+</tr>
+<tr>
+<td><code>:after_stag</code></td>
+<td><i>tbs</i></td>
+<td>&nbsp;</td>
+</tr>
+<tr>
+<td><code>:content</code></td>
+<td>the element content (text and/or child elements) is available</td>
+<td>Append the source element content to the rendering output for this element</td>
+</tr>
+<tr>
+<td><code>:before_etag</code></td>
+<td><i>tbs</i></td>
+<td>&nbsp;</td>
+</tr>
+<tr>
+<td><code>:etag</code></td>
+<td>the element end tag has been reached</td>
+<td>Append the element end tag to the rendering output for this element</td>
+</tr>
+<tr>
+<td><code>:after_etag</code></td>
+<td><i>tbs</i></td>
+<td>&nbsp;</td>
+</tr>
+<tr>
+<td><code>:element</code></td>
+<td>the complete document element (start/end tags + content) is available</td>
+<td>Append the accumulated element rendering to the output document</td>
+</tr>
+</tbody>
+</table>
+<p>
+As noted in the overview, most directive processing is associated with the <code>:stag</code> event, when the directive can manipulate the attributes of the element, or with the <code>:content</code> or <code>:element</code> events when performing transformations which involve the element content or the entire (tags+content) element output.
+Processing done on the <code>:etag</code> event is used by conditional directives that control the presence or absence of the element in the output document.
+An <code>:etag</code> handler is also used in combination with <code>:stag</code> when providing directive processing which wraps the element in some fashion (e.g., the <code>mv:block</code> directive which wraps a document element with ruby erb inserts to form a block evaluation context).
+</p>
+<p>The <code>before_</code> and <code>after_</code> events can be used to insert additional content or elements into the document, as well as being useful for initializing or updating the state of the directive handler itself.  However, when used to append additional output these processing events should be used with care to ensure that the resulting output is a properly-defined document structure.
 </p>
-<p>Helper functions are provided to simplify parsing several standard attribute encoding notations to convert the string value of the directive atttribute to a usable object.
-In particular, methods <code>parse_eval_into_array</code> evaluates the string as if it was the content of an array literal, while <code>parse_eval_into_hash</code> returns a Ruby hash containing the <code>key => value</code> pairs from the attribute value.
+<p>The action for an event handler can be defined by specifying an option which indicates a standard processing action or by providing a block containing the processing logic.
 </p>
-<h3>Operation</h3>
+<pre class="code">
+module MyAppDirectives
+  class MyDirective < MasterView::DirectiveBase
+    # ... directive attribute value argument definitions ...
+   event :stag {
+       # ... add/change/transform element attributes...
+   }
+   event :content do
+      #... modify the element content before it is emitted onto the output
+   end
+  end
+end
+</pre>
+<div class="todo">TODO: add an example of a handler which specifies its action using a standard <code>:render</code> option</div>
+<h4>Document Processing Event Actions</h4>
+<p>
+An event handler block in a directive implementation can reference any of its attribute arguments using the accessor named in an <code>attr_arg :argname</code> declaration
+or its complete atribute value string using the <code>attr_value</code> accessor.
+It can also access information about its document element in the source template
+using <code>element_attrs</code> to access a hash of the element attributes
+and <code>element_tag</code> to obtain the name of the element to which it is attached.
+</p>
+<p>
+At each event during the course of processing a template source document element,
+the output content being accumulated for that element can be affected.
+The principal service used by a directive handler to specify its contribution to the accumulated rendering of the element is the <code>render</code> service.
+As with Rails controllers and views, a directive event handler can actively specify the <code>render</code> output it wishes to produce.  If no rendering operation is performed by an event handler, the default rendering is provided automatically.
+</p>
+<p>
+The argument for a <code>render</code> operation is the symbol <code>:nothing</code> to specify that no output should be produced for this event.
+This option can be used by conditional processing directives to suppress content from the output.
+</p>
+<p>
+More commonly, a directive handler will invoke <code>render</code> to cause either text content, possibly including html tag markup as well as element content, or erb markup to be appended to the element output.
+The default rendering for the element is available from the <code>render_result</code> accessor.
+This default rendering can be modified or used with erb markup.
+The helper function <code>erb_eval</code> generates output wrapped in erb evaluation markup
+<code>&lt;% ...ruby expression(s)... %&gt;</code> which causes the content to be evaluated as ruby code without affecting the content of the view.
+The companion helper function <code>erb_content</code> generates output wrapped in erb evaluation markup
+<code>&lt;%= ...ruby expression(s)... %&gt;</code> which causes the content to be evaluated as ruby code and the resulting value inserted in the final view content.
+</p>
-<p class="explanation">TODO: fill in here with details on how the directive hooks up its processing (typically either start or end of the element tag to which it is attached), the context available to it when invoked (what can you get from the dcs arg), and how output is emitted</p>
 </div>  <!-- bodyContent -->
 </div>
@@ -165,6 +541,8 @@ In particular, methods <code>parse_eval_into_array</code> evaluates the string a
 &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>
@@ -173,15 +551,19 @@ In particular, methods <code>parse_eval_into_array</code> evaluates the string a
 &nbsp;|&nbsp;
 <a href="./directives.html">Directives</a>
 &nbsp;|&nbsp;
-<a href="./media_list.html">Media (Videos/Illustrations)</a>
+<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">[Valid XHTML]</a>
+  <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>