masterview 0.2.2 → 0.2.3

data/lib/masterview/directive_base.rb

@@ -1,9 +1,82 @@
 module MasterView
 
-  # establish the module into which directives define themselves
-  module Directives #:nodoc
+  # Namespace module for built-in directive implementations
+  # that are standard with the MasterView template engine.
+  # 
+  module Directives
   end
 
+  # Base class for directive implementations.
+  # 
+  # The standard technique for implementing a directive
+  # is to subclass DirectiveBase.  The builtin
+  # MasterView directives are implemented in
+  # module namespace MasterView::Directives.
+  # 
+  # If you create a directive implementation class
+  # elsewhere in the class hierarchy, it is recommended
+  # that you include the DirectiveHelpers mixin.
+  # If you do not include the PluginLoadTracking mixin,
+  # you will need to manually register your directive
+  # class using the MasterView.register_directive service.
+  # either the PluginLoadTracking mixin or
+  # 
+  # 
+  #--
+  #TODO: add docs here on responsibilities and techniques for
+  # implementing directives.  Subclass DirectiveBase, define
+  # within MasterView::Directives module namespace.
+  # 
+  # mumble - class methods: 
+  #    attr_name is the directive's attribute markup name - def. is class name
+  #    full_attr_name(ns) is the qualified name (name-space prefixed)
+  # 
+  # Directive can optionally implement class method :on_load to initialize
+  # itself prior to processed for the directive registry
+  # 
+  #TODO: establish protocol convention for additional namespaces
+  #
+  # mumble: :global_directive? predicate indicates... what??  (inline erb)
+  # 
+  # Directives implement <code>priority</code> to control the processing
+  # order when multiple directive attributes are used on a template
+  # document element.
+  # 
+  #TODO: document the priority hierarchy and convention for level usage
+  # 
+  # Discuss operational context: describe how/when MasterView parser
+  # invokes a directive handler in the course of parsing the elements
+  # and attributes of a template document node hierarchy.
+  # Notion of directive call stack; what state is the world in and
+  # information is available to a directive when invoked;
+  # what services are available in order to produce some effect
+  # on the results of the template parse.
+  # 
+  # Two general flavors on content directives: those which operate on attribute
+  # values of the containing element and those which operate on the
+  # entire containing element, sometimes by supplying or modifying its
+  # content, in other cases by replacing the template element with something
+  # else. 
+  # 
+  # Third flavor: eval-only directive.  Expression which is evaluate for its
+  # effect on the directive processing context or the overall state of processing
+  # the template document element tree.
+  # 
+  # Directive implementation typically wants to implement either or both of
+  # the methods <code>stag(dcs)</code> and <code>etag(dcs)</code> to hook
+  # up its processing on the start/end tags of the element on which the
+  # attribute is defined.
+  # 
+  # When a directive attribute is used on a template document element,
+  # the directive class is instantiated with the attribute_value provided
+  # to its constructure.  All directives used on an element are sorted 
+  # into processing order according to their <code>priority</code>
+  # (default is <code>Medium</code>.  The directive processor is invoked
+  # when the element start tag is encountered and when the element end
+  # tag is completed, allowing the implementation to control when and
+  # how its processing is hooked up to effect the template output.
+  #++
+  #
   class DirectiveBase
     include PluginLoadTracking
     include DirectiveHelpers
@@ -12,9 +85,50 @@ module MasterView
     # Classes which derive from DirectiveBase will automatically be registered as they are
     # loaded.
     def self.register_directive(directive_class)
-      self.register_class(directive_class)
+        #ISSUE: do we really need both PluginLoadTracking.register_class 
+        #and DirectiveBase.register_directive, in addition to MasterView.register_directive???
+        #[DJL 04-Jul-2006]
+      MasterView.register_directive(directive_class)
     end
 
+    # Returns the fully qualified attribute name of the directive,
+    # consisting of the directive namespace and the directive attribute name.
+    # 
+    # The default MasterView namespace_prefix is used if the directive does not
+    # specify a separate namespace.
+    # 
+    #--
+    #TODO: clarify the mechanism by which alternate namespaces are defined.
+    # Is this done by a code value or configured as part of the directory
+    # path specifications, or some combination thereof to allow ovverides
+    # in the event of namespace collisions?
+    #++
+    # 
+    def self.full_attr_name( namespace_prefix )
+      #TODO: fix this so that directives can override to define their own namespace separate from mv:
+      namespace_prefix + self.attr_name
+    end
+
+    # Returns the attribute name of the directive.
+    # 
+    # Use full_attr_name to obtain the fully-qualified name
+    # of the directive attribute with the qualifying namespace prefix.
+    # 
+    # The default attribute name of a directive is formed
+    # from the simple class name (without any module prefix qualifier),
+    # with the first character downcased.
+    # 
+    def self.attr_name()
+      self.default_attr_name()
+    end
+
+    def self.default_attr_name()  #:nodoc:
+      self.name.split(':').last.downcase_first_letter
+    end
+
+    # Construct a directive processor for the attribute_value
+    # of a directive attribute on a document template element.
+    # 
     def initialize(attribute_value)
       @attribute_value = attribute_value
     end
@@ -24,18 +138,12 @@ module MasterView
       @directive_call_stack = directive_call_stack
     end
 
-    # returns the full attribute name which is the mv_ns prefix + attr_name if that method has been provided, otherwise
-    # it default to the class name (without any module prefix) and it downcases the first letter
-    def self.full_attr_name(namespace_prefix)
-      namespace_prefix + (self.respond_to?(:attr_name) ? self.attr_name : self.name.split(':').last.downcase_first_letter)
-    end
-    
-    #get the directives attribute value string
+    # Returns the directive's attribute value string being processed.
     def attr_value
       @attribute_value
     end
 
-    #set the directives attribute value string
+    # Set the directive's attribute value string to be processed.
     def attr_value=(attribute_value)
       @attribute_value = attribute_value
     end
@@ -66,14 +174,30 @@ module MasterView
       (attrs_lckv[lckey] && attrs_lckv[lckey] == lcmatch.downcase) ? true : false
     end
 
+    #DEPRECATED - going away
     #output '<% '+str+' %>'
-    def erb(str)
+    def erb(str) #:nodoc:
+      #ISSUE: convert clients to erb_eval and drop.  Ya oughta have a point of view. [DJL 04-Jul-2006]
       ERB_START + str + ERB_END
     end
 
-    #output '<%= '+str+' %>
+    # Compose an Erb expression which produces content in the containing document.
+    # The expression may also have effects on the processing context of
+    # the template document
+    # 
+    # output '<%= '+str+' %>
+    # 
     def erb_content(str)
-      ERB_EVAL + str + ERB_END
+      ERB_CONTENT_START + str + ERB_CONTENT_END
+    end
+
+    # Compose an Erb expression which is evaluated for its effect on the processing context
+    # but does not produce content in the containing document.
+    # 
+    # output '<% '+str+' %>'
+    # 
+    def erb_eval(str)
+      ERB_EVAL_START + str + ERB_EVAL_END
     end
     
     #get tag_name
@@ -118,6 +242,13 @@ module MasterView
       '\''+str+'\''
     end
 
+    # adds single quotes around string if it is a simple
+    # word [a-zA-Z0-9_]* otherwise return existing string
+    # also quote if empty string
+    def quote_if(str)
+      (str =~ /^\w*$/) ? quote(str) : str
+    end
+
     def remove_strings_from_attr_value!
       self.attr_value = remove_prepended_strings(attr_value)
     end
@@ -153,6 +284,7 @@ module MasterView
     # check for common html options and return the hash
     def common_html_options(attrs_lck)
       options = {}
+      options[:id] = attrs_lck['id'] if attrs_lck['id']
       options[:class] = attrs_lck['class'] if attrs_lck['class']
       options[:style] = attrs_lck['style'] if attrs_lck['style']
       options[:tabindex] = attrs_lck['tabindex'] if attrs_lck['tabindex']

data/lib/masterview/directive_helpers.rb

@@ -1,10 +1,27 @@
 module MasterView
 
+  # Mixin services for directive implementation classes.
+  # 
+  # Subclasses of MasterView::DirectiveBase inherit this mixin.
+  # 
   module DirectiveHelpers
+
     CRLF = "\r\n"
-    ERB_START = '<% '
-    ERB_EVAL = '<%= '
-    ERB_END = ' %>'
+
+    # start of ERB which is evaluated but does not contribute content to the document
+    ERB_EVAL_START = '<% '
+    # end of ERB which is evaluated but does not contribute content to the document
+    ERB_EVAL_END = ' -%>'
+
+    # start of ERB whose evaluation results in content in the document
+    ERB_CONTENT_START = '<%= '
+    # end of ERB whose evaluation results in content in the document
+    ERB_CONTENT_END = ' %>'
+
+    ####OBSOLETE: SWEEP AND REMOVE
+    ERB_START = ERB_EVAL_START #:nodoc:  #WAS: '<% '
+    ERB_EVAL = ERB_CONTENT_START #:nodoc: #WAS: '<%= '
+    ERB_END = ERB_CONTENT_END #:nodoc:  #WAS: ' %>'
 
     #convenience constants defined to allow priority to directives
     #higher priority (lower value) will be executed first in chain
@@ -124,14 +141,11 @@ module MasterView
 
     #parse into array of strings, containing the various arguments without evaling
     #looks for %q{}, %q[], hash, array, function call using (), values deliminated by commas,
-    #it does not handle embedded quotes yet
     def parse(str)
-      return [] if str.nil? || str.strip.empty?
-      s = str.strip
-      args = []
-      s.scan( /(%q"[^"]*"|%q\{[^}]*\}|%q\[[^\]]*\]|\{?\s*\S+\s*=>[^{}]+\}?|\[[^\]]*\]|[\w\.@]+\s*\([^\)]*\)|'[^']*'|[^,]+)\s*,?\s*/  ).flatten
+      AttrStringParser.parse(str)
     end
 
+
     #remove any strings that were prepended to the hashes, typically these are overridden by other values, so 
     # we need to strip them off leaving only the hashes, returns a string with only hashes
     def remove_prepended_strings(full_string)

data/lib/masterview/directive_registry.rb

@@ -0,0 +1,169 @@
+module MasterView
+
+  # A DirectiveRegistry manages the directives available 
+  # for processing the MasterView directive attributes in 
+  # a template document.
+  # 
+  # DirectiveRegistry is an internal mechanism of the
+  # template engine, primarily used by the MasterView::Parser
+  # to support directive attribute processing.
+  # 
+  class DirectiveRegistry
+
+    # Answer the list of directive classes
+    attr_reader :loaded_classes
+
+    def initialize() #:nodoc:
+      @loaded_classes = []
+      clear_directive_maps()
+    end
+
+    # Register a directive implementation.
+    # 
+    # A directive is ordinarily a subclass of MasterView::DirectiveBase.
+    # 
+    #--
+    #TODO: A directive implementation must support the following services:....
+    #++
+    # 
+    def register_directive(directive_class)
+      #TODO: ensure that the directive impl supports required prototcol (i/f check...)?
+      @loaded_classes << directive_class
+    end
+
+    # Answer the (base) names of the loaded directive classes.
+    # 
+    # By default, strips off module prefixes and returns just the
+    # directive class name for brevity.
+    # 
+    def loaded_class_names( simpleNames=true )
+      @loaded_classes.collect do |dc| 
+        simpleNames ? simple_class_name(dc) : dc.name
+      end
+    end
+
+    # Answer the simple name of a directive class (without its module qualifier)
+    def simple_class_name( dc )
+      dc.name.split(':').last
+    end
+
+    # Answer the attribute name implemented by a directive class
+    def directive_attr_name( dc )
+      dc.respond_to?(:attr_name) ? dc.attr_name : simple_class_name(dc).downcase_first_letter
+    end
+
+    # Answer the fully qualified name of the attribute implemented by a directive class.
+    # attr_qname ::= <ns_name>:<attr_name>
+    def directive_full_attr_name( dc, mv_ns )
+      (dc.respond_to? :full_attr_name) ? dc.full_attr_name(mv_ns) : build_full_attribute_name(mv_ns, dc)
+    end
+
+    # this method is invoked to build the full attribute name (the attribute which will be watched for in 
+    # html attibutes. It concatenates the namespace prefix to the class name after first removing any module
+    # prefixes and then downcasing the first letter
+    def build_full_attribute_name(mv_ns, dc) #:nodoc:
+      #ISSUE: need to allow directives to control their name space
+      mv_ns + simple_class_name(dc).downcase_first_letter
+    end
+
+    # Ensure that all directives on the load path are loaded.
+    # Build the directive processing tables used by the template parser.
+    # 
+    def process_directives_load_path( directive_paths, mv_ns=nil )
+      load_directives( directive_paths )
+      build_directive_maps( mv_ns )
+    end
+
+    # Ensure that all directives on the load path are loaded.
+    # 
+    # require {directives_dir}/foo_directive.rb
+    def load_directives( directive_paths=nil ) #:nodoc:
+      directive_paths = MasterView::DefaultDirectiveLoadPaths if directive_paths.nil?
+      directive_paths.each do | dir |
+        # MV::Initializer now handles bad dir path entries, but leave old checks for now [DJL 04-Jul-2006]
+        next if dir.nil?
+        if File.directory?(dir)
+          Dir.open( dir ).each { |fn| require "#{dir}/#{fn}" if fn =~ /[.]rb$/ }
+        else
+          #raise InvalidPathError.new('Directive load path dir does not exist:'+dir) unless File.directory? dir
+          Log.error "Directive load path dir does not exist: '#{dir}'" if MasterView.const_defined?(:Log)  #backstop for test case startup
+        end        
+      end
+      clear_directive_maps()  # ensure we take a clean point of view on the matter at hand
+    end
+
+    # Build the directive processing tables used by the template parser.
+    def build_directive_maps( mv_ns=nil )  #:nodoc:
+
+      mv_ns = MasterView::NamespacePrefix if mv_ns.nil?
+      clear_directive_maps()  # ensure we take a clean point of view on the matter at hand
+
+      Log.debug { 'directive plugins loaded:' + loaded_class_names.inspect }  if MasterView.const_defined?(:Log)  #backstop for test case startup
+      loaded_classes.each do |dc|
+        dc.on_load if dc.respond_to?(:on_load)
+        attr_qname = directive_full_attr_name( dc, mv_ns )
+        qname_parts = attr_qname.split(':')
+        raise NameError, "Directive qname requires namespace: '#{attr_qname} - #{dc.name}" if qname_parts.length != 2
+        ns_name, attr_name = qname_parts
+        @directive_namespaces << ns_name if ! @directive_namespaces.include?( ns_name )
+        @directive_classes[attr_qname] = dc
+        ###WHAT IS THIS NOTION of auto/global directive???  currently used (only) by inline_erb_directive
+        dc_instance = dc.new(nil)
+        @auto_directives << dc if dc_instance.respond_to?(:global_directive?) && dc_instance.global_directive? 
+      end
+      Log.debug { 'directives='+@directive_classes.keys().sort!().inspect }  if MasterView.const_defined?(:Log)  #backstop for test case startup
+      Log.debug { 'auto_directives='+@auto_directives.inspect }  if MasterView.const_defined?(:Log)  #backstop for test case startup
+
+    end
+
+    # Construct directive processors needed to handle the 
+    # attributes defined on a template document element.
+    # 
+    # Constructs processors for all global directives
+    # and for any directive attributes.
+    # 
+    # 
+    def construct_directive_processors( attributes )
+      directive_processors = []
+      # always instantiate global directive handlers
+      @auto_directives.each do | dc |
+        directive_processors << dc.new(nil)
+      end
+      # instantiate the directive processor on the attribute value if its attr present
+      # remove the MV attribute from the document so that it's only effect is from the processor action
+      @directive_classes.each do | attr_qname, dc |
+        directive_processors << dc.new(attributes.delete(attr_qname)) if attributes[attr_qname]
+      end
+      directive_processors
+    end
+
+    protected
+    def clear_directive_maps() #:nodoc:
+      @directive_namespaces = []
+      @directive_classes = {} #map fully qualified directive attr name to directive_class
+      @auto_directives = []
+    end
+
+  end
+
+  # The DirectivesRegistry manages the loaded directives available 
+  # for processing template markup
+  DirectivesRegistry = DirectiveRegistry.new()
+
+  # Register a directive implementation.
+  # 
+  # Registration is handled automatically for directives
+  # implemented as subclasses of MasterView::DirectiveBase,
+  # the usual technique, or by including the PluginLoadTracking
+  # module in a directive implementation class.
+  # 
+  # Directive registration ordinarily occurs during MasterView
+  # initialization, when directive classes on the configured
+  # <code>directive_paths</code> directories are automatically
+  # loaded and registered with the template engine.
+  # 
+  def self.register_directive(directive_class)
+      DirectivesRegistry.register_directive(directive_class)
+  end
+
+end

data/lib/masterview/directives/check_box.rb

@@ -0,0 +1,31 @@
+module MasterView
+  module Directives
+
+    # create check_box helper, quoting object and method if necessary
+    # merging in any html options specified
+    class Check_box < MasterView::DirectiveBase
+      def stag(dcs)
+        #eat
+      end
+
+      def etag(dcs)
+        args = parse_attr_value
+        obj = args[0]
+        method = args[1]
+        options_and_on_off = args[2..-1].join(', ')
+
+        obj = quote_if(obj)
+        method = quote_if(method)
+
+        options_and_on_off = merge_into_embedded_hash(options_and_on_off, 0, common_html_options(attrs_lck))
+
+        a = []
+        a << 'check_box '+ obj
+        a << method
+        a << options_and_on_off if options_and_on_off && !options_and_on_off.strip.empty?
+        erb_content(a.join(', '))
+      end
+
+    end
+  end
+end

data/lib/masterview/directives/collection_select.rb

@@ -0,0 +1,44 @@
+module MasterView
+  module Directives
+
+    # creates a collection_select helper. quotes object and method if necessary, merges
+    # html options specfied on element into any html options in attr_value
+    # attr_value syntax:
+    # object, method, collection, value_method, text_method, options = {}, html_options = {}
+    class Collection_select < MasterView::DirectiveBase
+      def stag(dcs)
+        #eat
+      end
+
+      def etag(dcs)
+        args = parse_attr_value
+        obj = quote_if(args[0])
+        method = quote_if(args[1])
+        collection = quote_if(args[2])
+        value_method = quote_if(args[3])
+        text_method = quote_if(args[4])
+        options = args[5]
+        html_options = args[6]
+
+        opt = {}
+        opt[:size] = attrs_lck['size'].to_i if attrs_lck['size']
+        opt.merge! common_html_options(attrs_lck)
+        html_options = merge_into_embedded_hash(html_options, 0, opt)
+        options = '{}' if options.to_s.empty? && !html_options.to_s.empty? # if we have html_options but no options, still need empty hash
+
+        a = []
+        a << 'collection_select '+ obj
+        a << method
+        a << collection
+        a << value_method
+        a << text_method
+        a << options unless options.to_s.strip.empty?
+        a << html_options unless html_options.to_s.strip.empty?
+
+        self.content = ''
+        erb_content(a.join(', '))
+      end
+
+    end
+  end
+end

data/lib/masterview/directives/hidden_field.rb

@@ -11,8 +11,8 @@ module MasterView
         obj = args[0]
         method = args[1]
 
-        obj = quote(obj) unless obj =~ /^:|'|"/
-        method = quote(method) unless method =~ /^:|'|"/
+        obj = quote_if(obj)
+        method = quote_if(method)
 
         options = {}
         options.merge! common_html_options(attrs_lck)

data/lib/masterview/directives/image_tag.rb

@@ -8,7 +8,9 @@ module MasterView
     # If both width and height attr values are specified then it will build the :size option from them.
     # Other html attributes will be passed into image_tag options.
     class Image_tag < MasterView::DirectiveBase
-      IMAGE_SRC_EXTRACT_REGEX = /public\/images\/(.*)/
+
+      # /public\/images\/(.*)/
+      IMAGE_SRC_EXTRACT_REGEX = MasterView::ConfigSettings.template_asset_base_ref_pattern[:images]
 
       def stag(dcs)
       end
@@ -39,5 +41,6 @@ module MasterView
         erb_content('image_tag ' + image_tag_params)
       end
     end
+
   end
 end

data/lib/masterview/directives/insert_generated_comment.rb

@@ -2,11 +2,13 @@ module MasterView
   module Directives
 
     # Inserts a comment into the file that indicates that this file was generated
-    # and should not be edited, else changes could be lost. It includes the path to
-    # the original file that should be edited instead
+    # and should not be edited, else changes could be lost. The standard generated-file
+    # comment includes the path to the original file that should be edited.
+    # 
     class Insert_generated_comment < MasterView::DirectiveBase
 
-      Eval_comment_template = 'comment_text = "' + MasterView::GeneratedCommentText + '"'
+      # Configured value for generated comment text is eval'd to support #{template_path} field substitution
+      Comment_eval_template = 'comment_text = "' + MasterView::GeneratedCommentText + '"'
 
       def priority
         DirectivePriorities::VeryLow
@@ -15,10 +17,9 @@ module MasterView
       def stag(directive_call_stack)
         # do variable substitution to fill in any slots in the template
         template_path = attr_value
-        #TBD: any other std name bindings we want to support?
         comment_text = ''
-        eval(Eval_comment_template, binding)
-        comment = "\n<%\n#{comment_text}\n-%>"
+        eval(Comment_eval_template, binding)
+        comment = "\n<%\n#{comment_text}\n-%>" # "\n#{ERB_EVAL_START.strip()}\n#{comment_text}\n#{ERB_EVAL_END.strip()}"
 
         ret = []
         ret << directive_call_stack.render

data/lib/masterview/directives/javascript_include.rb

@@ -3,7 +3,9 @@ module MasterView
 
     #creates a link_to
     class Javascript_include < MasterView::DirectiveBase
-      JAVASCRIPT_SRC_EXTRACT_REGEX = /public\/javascripts\/(.*)/
+
+      # /public\/javascripts\/(.*)/
+      JAVASCRIPT_SRC_EXTRACT_REGEX = MasterView::ConfigSettings.template_asset_base_ref_pattern[:javascripts]
 
       def stag(dcs)
       end
@@ -19,5 +21,6 @@ module MasterView
         erb_content('javascript_include_tag ' + js_loc)
       end
     end
+
   end
 end

data/lib/masterview/directives/password_field.rb

@@ -11,8 +11,8 @@ module MasterView
         obj = args[0]
         method = args[1]
 
-        obj = quote(obj) unless obj =~ /^:|'|"/
-        method = quote(method) unless method =~ /^:|'|"/
+        obj = quote_if(obj)
+        method = quote_if(method)
 
         options = {}
         options[:size] = attrs_lck['size'].to_i if attrs_lck['size']

data/lib/masterview/directives/radio_button.rb

@@ -0,0 +1,35 @@
+module MasterView
+  module Directives
+
+    # create radio_button helper, quoting object and method if necessary
+    # merging in any html options specified
+    class Radio_button < MasterView::DirectiveBase
+      def stag(dcs)
+        #eat
+      end
+
+      def etag(dcs)
+        args = parse_attr_value
+        obj = args[0]
+        method = args[1]
+        tag_value = args[2]
+
+        obj = quote_if(obj)
+        method = quote_if(method)
+
+        options = {}
+        options.merge! common_html_options(attrs_lck)
+        remove_strings_from_attr_value!
+        merge_hash_attr_value!(0, options)
+
+        a = []
+        a << 'radio_button '+ obj
+        a << method
+        a << tag_value
+        a << attr_value unless attr_value.strip.empty?
+        erb_content(a.join(', '))
+      end
+
+    end
+  end
+end

data/lib/masterview/directives/select.rb

@@ -0,0 +1,38 @@
+module MasterView
+  module Directives
+
+    # creates a select helper. quotes object and method if necessary, merges
+    # html options specfied on element into any html options in attr_value
+    class Select < MasterView::DirectiveBase
+      def stag(dcs)
+        #eat
+      end
+
+      def etag(dcs)
+        args = parse_attr_value
+        obj = args[0]
+        method = args[1]
+        choices = args[2]
+
+        obj = quote_if(obj)
+        method = quote_if(method)
+
+        options = {}
+        options[:size] = attrs_lck['size'].to_i if attrs_lck['size']
+        options.merge! common_html_options(attrs_lck)
+        remove_strings_from_attr_value!
+        merge_hash_attr_value!(1, options)
+
+        a = []
+        a << 'select '+ obj
+        a << method
+        a << choices
+        a << attr_value unless attr_value.strip.empty?
+
+        self.content = ''
+        erb_content(a.join(', '))
+      end
+
+    end
+  end
+end