masterview 0.2.5 → 0.3.0

data/lib/masterview/directive_base.rb

@@ -2,48 +2,48 @@ module MasterView
 
   # 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.
-  # 
+  # module namespace MasterView::Directives and
+  # uses the mv: namespace in directive attribute markup.
+  #
+  # Custom directive implementations should be created
+  # in your own module namespace, according to what's
+  # appropriate for your application or component.
+  # By default, directive extensions will use the
+  # mvx: namespace to distinguish extensions from the
+  # builtin MasterView directives.
+  #
   # If you create a directive implementation class
-  # elsewhere in the class hierarchy, it is recommended
-  # that you include the DirectiveHelpers mixin.
+  # elsewhere in the class hierarchy, you include the
+  # DirectiveMetadata mixin class.  It is also is recommended
+  # that you include DirectiveHelpers and DirectiveDSL.
   # 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.
-  # 
+  # A directive can optionally implement class method :on_load to
+  # initialize itself prior to being added to the directive registry.
+  #
+  # Directives may specify a <code>priority</code> in their metadata
+  # 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.
@@ -51,25 +51,20 @@ module MasterView
   # 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. 
-  # 
+  # 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 
+  # 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
@@ -77,58 +72,25 @@ module MasterView
   # how its processing is hooked up to effect the template output.
   #++
   #
-  class DirectiveBase
+  class  DirectiveBase
     include PluginLoadTracking
+    include DirectiveMetadata
     include DirectiveHelpers
+    include DirectiveDSL
 
     # Register a class manually without regard to whether it inherits from DirectiveBase.
     # Classes which derive from DirectiveBase will automatically be registered as they are
     # loaded.
     def self.register_directive(directive_class)
-        #ISSUE: do we really need both PluginLoadTracking.register_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
+    # Construct a directive processor with the attribute_value
     # of a directive attribute on a document template element.
-    # 
+    #
     def initialize(attribute_value)
       @attribute_value = attribute_value
     end
@@ -145,88 +107,39 @@ module MasterView
 
     # Set the directive's attribute value string to be processed.
     def attr_value=(attribute_value)
+      #ISSUE: is this useful/necessary?  Believe we only want initialzer to set this [DJL 23-Sep-2006]
       @attribute_value = attribute_value
     end
 
-    #get attribute hash from tag
-    def attrs
+    # Returns the attributes hash containing the attributes
+    # defined on the template document element that is being processed.
+    def element_attrs
       @directive_call_stack.context[:tag].attributes
     end
 
-    #set attribute hash for tag
-    def attrs=(attributes)
+    # Set the attributes hash containing the attributes
+    # for the template document element that is being processed.
+    def element_attrs=(attributes)
       @directive_call_stack.context[:tag].attributes = attributes
     end
 
-    #get attribute hash with lowercased keys and values, and cache it
-    def attrs_lckv
-      @attrs_lckv ||= lowercase_attribute_keys_and_values(attrs)
-    end
-
-    #get attribute hash with lowercased keys (and original values) and cache it
-    def attrs_lck
-      @attrs_lck ||= lowercase_attribute_keys(attrs)
-    end
-
-    #returns true if the value for lckey of the attribute hash with lowercased keys and values
-    #matches (lowercase) lcmatch string
-    def attr_lckv_matches(lckey, lcmatch)
-      (attrs_lckv[lckey] && attrs_lckv[lckey] == lcmatch.downcase) ? true : false
-    end
-
-    #DEPRECATED - going away
-    #output '<% '+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
-
-    # 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_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
-    def tag_name
+    # Returns the tag of the template document element that is being processed.
+    def element_tag
       @directive_call_stack.context[:tag].tag_name
     end
 
-    #set tag_name
-    def tag_name=(tag_name)
+    # Set the tag of the template document element that is being processed.
+    def element_tag=(tag_name)
       @directive_call_stack.context[:tag].tag_name = tag_name
     end
 
-    #inside characters, cdata, or comment you can call this to get the characters passed
-    def data
-      @directive_call_stack.context[:content_part]
-    end
-
-    #set the data that will be passed to characters, cdata, or comment directives
-    def data=(data)
-      @directive_call_stack.context[:content_part]=data
-    end
-
     # rolled up content from all children of the tag, note this will not be complete until hitting the end tag method :etag
-    def content
+    def content_array
       @directive_call_stack.context[:tag].content
     end
 
     #return rolled up content from all children as string, note this will not be complete until hitting the end tag method :etag
-    def content_str
+    def content_string
       content = @directive_call_stack.context[:tag].content
       content = content.join if content.respond_to? :join
       content
@@ -237,63 +150,172 @@ module MasterView
       @directive_call_stack.context[:tag].content = content
     end
 
-    #add single quotes around string
-    def quote(str)
-      '\''+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
+    # 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.
+    #
+    # Enhanced allowing args to be passed in. If args are present then they will
+    # be assumed to be parameters for the method. A space will be appended to str
+    # and each argument will be appended joined with commas. Additionally if
+    # argument is a symbol then it will check for the existence of an instance variable
+    # with that name and if so substitutes its value. If any non-nil values are
+    # passed after it, then it will use its :default if that was specified
+    # in arg call, otherwise simply nil.
+    #
+    # output '<%= '+str+' %>
+    #
+    # erb_content(content, :a, :b, :c) where @a = 1, @b = nil (with optional_default of {}) and @c = {:hello => :world}
+    # becomes '<%= '+content+' 1, {}, {:hello => :world}'+' %>
+    #
+    def erb_content(str, *args)
+      ERB_CONTENT_START + prepare_output(str,*args) + ERB_CONTENT_END
     end
 
-    def remove_strings_from_attr_value!
-      self.attr_value = remove_prepended_strings(attr_value)
+    # Compose an Erb expression which is evaluated for its effect on the processing context
+    # but does not produce content in the containing document.
+    #
+    # Enhanced allowing args to be passed in. If args are present then they will
+    # be assumed to be parameters for the method. A space will be appended to str
+    # and each argument will be appended joined with commas. Additionally if
+    # argument is a symbol then it will check for the existence of an instance variable
+    # with that name and if so substitutes its value. If any non-nil values are
+    # passed after it, then it will use its :default if that was specified
+    # in arg call, otherwise simply nil.
+    #
+    # output '<% '+str+' %>
+    #
+    # erb_eval(str, :a, :b, :c) where @a = 1, @b = nil (with optional_default of {}) and @c = {:hello => :world}
+    # becomes '<% '+str+' 1, {}, {:hello => :world}'+' %>
+    #
+    def erb_eval(str, *args)
+      ERB_EVAL_START + prepare_output(str,*args) + ERB_EVAL_END
     end
 
-    #prepend string to attribute value adding a comma if attribute value was not empty
-    def prepend_to_attr_value!(str)
-      return attr_value if str.nil? || str.strip.empty?
-      av = str
-      av << ', ' << attr_value unless attr_value.strip.empty?
-      self.attr_value = av
+    # convert arg symbols to instance_variable values if exist
+    # Enhanced allowing args to be passed in. If args are present then they will
+    # be assumed to be parameters for the method. A space will be appended to str
+    # and each argument will be appended joined with commas. Additionally if
+    # argument is a symbol then it will check for the existence of an instance variable
+    # with that name and if so substitutes its value. If any non-nil values are
+    # passed after it, then it will use its :default if that was specified
+    # in arg call, otherwise simply nil.
+    #
+    # output '<%= '+str+' %>
+    #
+    # prepare_output(content, :a, :b, :c) where @a = 1, @b = nil (with optional_default of {}) and @c = {:hello => :world}
+    # becomes '<%= '+content+' 1, {}, {:hello => :world}'+' %>
+    #
+    # returns string of output
+    def prepare_output(str, *args)
+      out = str
+      non_nil_found = false
+      arg_values = []
+      args.reverse_each do |arg|
+        value = nil
+        invar_name = name_to_instance_var_name(arg)
+        var_sym_name = (invar_name.to_s.starts_with?('@')) ? invar_name.to_s[1..-1].to_sym : invar_name
+        attr_arg_def = self.class.directive_class_def.find_attr_arg_def_by_name(var_sym_name)
+        if instance_variable_exists?(invar_name)
+          value = self.instance_variable_get(invar_name)
+        else # symbol instance variable not found, assume need to use literal arg value
+          value = arg
+        end
+        if attr_arg_def and attr_arg_def.options and attr_arg_def.options[:varargs] # arg contains array of values that need to be expanded
+          if value.nil? or value.empty?
+            value = nil
+          else
+            value = value.join(', ') # expand these values out to foo, bar, baz
+          end
+        end
+        if non_nil_found # insure that the preceding values are specified
+          if value.nil?
+            value = attr_arg_def.optional_default unless attr_arg_def.nil? #try to use optional_default if exists
+          end
+
+          value = 'nil' if value.nil? or (value.is_a?(String) and value.strip.empty?) # finally we will be outputing the string word nil if value is still nil
+          if(value.is_a?(String))
+            value = '{ '+value+' }' if value =~ /^[^\{]+=>/
+          end
+        else # no non_nil_found previously, check this one
+          value = nil if value.is_a?(String) and value.strip.empty?
+          non_nil_found = true unless value.nil?
+        end
+        unless value.nil?
+          value = value.inspect unless value.is_a?(String)  # insure is string inspect works for many things
+          arg_values.unshift(value) # if values are non-nil at this point add them to arg_values (to end first)
+        end
+      end
+      out = out + '( ' + arg_values.join(', ') + ' )' unless arg_values.empty?
+      out
     end
 
-    #append string to attribute value adding a comma if attribute value was not empty
-    def append_to_attr_value!(str)
-      return attr_value if str.nil? || str.strip.empty?
-      av = attr_value
-      av << ', ' unless av.strip.empty?
-      av << str
-      self.attr_value = av
+    # check for common html options and return the hash
+    def common_html_options
+      options = {}
+      if (v = element_attrs[:id]) : options[:id] = v; end
+      if (v = element_attrs[:class]) : options[:class] = v; end
+      if (v = element_attrs[:style]) : options[:style] = v; end
+      if (v = element_attrs[:tabindex]) : options[:tabindex] = v; end
+      if (v = element_attrs[:accesskey]) : options[:accesskey] = v; end
+      if (element_attrs[:disabled]) : options[:disabled] = true; end
+      if (element_attrs[:readonly]) : options[:readonly] = true; end
+
+      # these are not as common but take care of them anyway for convenience
+      if (v = element_attrs[:alt]) : options[:alt] = v; end
+      if (v = element_attrs[:width]) : options[:width] = v.to_i; end
+      if (v = element_attrs[:height]) : options[:height] = v.to_i; end
+      if (v = element_attrs[:rows]) : options[:rows] = v.to_i; end
+      if (v = element_attrs[:cols]) : options[:cols] = v.to_i; end
+      if (v = element_attrs[:size]) : options[:size] = v.to_i; end
+      if (v = element_attrs[:maxlength]) : options[:maxlength] = v.to_i; end
+      options
     end
 
-    #merge merge_hash into hashes stored in attribute_value string
-    #hash_index is the zero based index of the hash you want to add to
-    def merge_hash_attr_value!(hash_index, merge_hash)
-      self.attr_value = merge_into_embedded_hash(attr_value, hash_index, merge_hash)
+    # merge a hash into a string representation of a hash,
+    # this method basically appends the hash values to the end of the
+    # string taking into account whether the hash has brackets or is
+    # open. When ruby reads a hash it will keep the last value set
+    # so later values override previous values
+    def merge_hash_into_str(hash_to_merge, str_to_merge_into)
+      str_to_merge_into = '' if str_to_merge_into.nil?
+      sorted_hash_to_merge = hash_to_merge.sort { |a,b| a[0].to_s <=> b[0].to_s } #sort, remember the keys might be symbols so use to_s
+      str_to_merge = sorted_hash_to_merge.collect{ |h,v| "#{h.inspect} => #{v.inspect}" }.join(', ')
+      str = str_to_merge_into.strip
+      if(str[0,1] == '{') # has {} surrounding
+        str = str[1..-2].strip # get just contents stripping {}
+        str += ', ' unless str.empty? or str_to_merge.empty?
+        str += str_to_merge
+        str = '{'+str+'}'
+      else
+        str += ', ' unless str.empty? or str_to_merge.empty?
+        str += str_to_merge
+      end
+      str
     end
 
-    #calls non-evaling parse to split into string arguments
-    def parse_attr_value
-      parse(attr_value)
+    # find the first parent directive instance that matches the parentClass and if block is provided
+    # then evaluate the block as well allowing further filtering, if block is false then
+    # it won't be used as a match.
+    # This method is especially useful for providing a mechanism for children to locate
+    # parent directives and communicate with them potentially influencing their output.
+    # Once a parent directive instance is found, public methods on the parent directive
+    # can be called, so the child might add itself to some list, etc.
+    def find_parent_directive(parentClass, &block)
+      parent_dir = nil
+      tag = @directive_call_stack.context[:tag]
+      while( parent_dir.nil? )
+        tag = tag.parent
+        break if tag.nil?
+        parent_dir = tag.directives.directives.find { |d| d.is_a?(parentClass) and (block.nil? or block.call(d)) }
+      end
+      parent_dir
     end
 
-    # 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']
-      options[:accesskey] = attrs_lck['accesskey'] if attrs_lck['accesskey']
-      options[:disabled] = true if attrs_lck['disabled']
-      options[:readonly] = true if attrs_lck['readonly']
-      options
+    # convenience method to get to current renderer
+    def renderer
+      @directive_call_stack.context[:tag].renderer
     end
 
   end
-
 end
+