rtml 1.2.2

data/app_generators/rtml/templates/rtml/lib/rtml/validation/dom_tag.rb

@@ -0,0 +1,52 @@
+class Rtml::Validation::DomTag
+  attr_accessor :name
+  attr_accessor :children
+  attr_accessor :child_order
+  attr_writer :root
+  
+  def root?; @root end
+    
+  def initialize(name)
+    @name = name.to_s
+    @children = []
+    @child_order = []
+  end
+  
+  def validate(validator, ruleset, xml)
+    # note that validate does NOT validate *this* element -- only children!
+    tml_elements = xml/"/#{self.name}"
+    tml_elements.each do |element|
+      #validate that children specified are present
+      children.each do |set|
+        for chele in set[0]
+          chele = ruleset.tags.find_by_name(chele) if chele.kind_of? Symbol or chele.kind_of? String
+          options = set[1].reverse_merge(:minimum => 0)
+          found = chele.validate(validator, ruleset, element).length
+
+          validator.test_case.assert_operator found, ">=", options[:minimum],
+            "Found #{found} occurrances of #{chele.name}; expected to find at least #{options[:minimum]}"
+          
+          if options[:maximum]
+            validator.test_case.assert_operator found, "<=", options[:maximum],
+              "Found #{found} occurrances of #{chele.name}; expected to find at most #{options[:maximum]}"
+          end
+        end
+      end
+
+      # validate that children not specified are not present
+      acceptable = children.collect { |c| c[0] }.flatten.collect do |c|
+        ((c.kind_of? Symbol or c.kind_of? String) ? ruleset.tags.find_by_name(c) : c)
+      end
+      forbidden = ruleset.tags - acceptable
+      forbidden.each do |tag|
+        count = (element/"/#{tag.name}").length
+        validator.test_case.assert_equal count, 0,
+          "Element #{tag.name} is not allowed to appear within parent #{element.name}"
+      end
+    end
+  end
+  
+  def to_s
+    name
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/validation/predefined_variable_rule_parser.rb

@@ -0,0 +1,97 @@
+class Rtml::Validation::PredefinedVariableRuleParser
+  class VariableNamespace
+    VAR_INHERITABLE_OPTIONS = [ :type, :default, :values, :perms ]
+    attr_reader :children, :name
+    attr_accessor :filename, :fail_if_file_missing, :base_path, :parent_path
+    attr_writer *VAR_INHERITABLE_OPTIONS
+    attr_writer :desc
+    delegate :to_s, :to => :name
+    
+    def initialize(name, options = {}, &block)
+      @name = name
+      @children = HashWithIndifferentAccess.new
+      @variables = []
+      @base_path = File.join(File.dirname(__FILE__), "../../../rules")
+      @parent_path = ""
+      @search_path = ""
+      
+      options.each { |k,v| self.send("#{k}=", v) }
+      self.filename ||= @name
+      #self.search_path = File.join(search_path.to_s, filename.to_s)
+      process(options, &block)
+    end
+    
+    def _vardcl(name, options = {})
+      options.reverse_merge!({:type => type, :default => default, :values => values, :perms => perms})
+      options[:name] = name
+      @variables << options
+      options
+    end
+    
+    def to_a
+      (@variables + @children.collect { |i| i[1].to_a }).flatten.collect do |i|
+        r = i.dup
+        unless self.name.blank?
+          r[:name] = "#{self.name}.#{r[:name]}"
+        else
+          r[:name] = "#{r[:name]}"
+        end
+        r
+      end
+    end
+    
+    def respond_to?(*a); super; end
+    def method_missing(name, *args, &block)
+      options = args.extract_options!
+      if args.length == 1
+        options[:desc] = args[0]
+      elsif args.length == 0
+        options[:desc] = name.to_s.titleize
+      else
+        raise "Invalid number of arguments: Expected 0 or 1"
+      end
+      _vardcl(name, options)
+    end
+    
+    (VAR_INHERITABLE_OPTIONS + [:desc, :search_path]).each do |t|
+      attr_writer t
+      eval "def #{t}(a = nil); @#{t} = a if a; @#{t}; end", binding, __FILE__, __LINE__
+    end
+
+    def namespace(name, options = {}, &block)
+      name = name.to_s
+      o = { :base_path => base_path, :parent_path => File.join(parent_path, search_path, self.name.to_s) }
+      VAR_INHERITABLE_OPTIONS.each { |i| o[i] = self.send(i) }
+      if children[name]
+        children[name].process(options.merge(o), &block)
+      else
+        children[name] = VariableNamespace.new(name, options.merge(o), &block)
+      end
+    end
+    
+    private
+    def process(options = {}, &block)
+      if filename
+        fn = File.join("", parent_path.to_s, search_path, "#{filename}.rb")
+        print "Searching for namespace: #{fn}... " if $DEBUG
+        if File.exist?(File.join(base_path, fn))
+          puts "Found!" if $DEBUG
+          eval File.read(File.join(base_path, fn)), binding, fn, 1
+        else
+          puts "not found." if $DEBUG
+          raise "File not found: #{fn}" if fail_if_file_missing
+        end
+      end
+      
+      instance_eval &block if block_given?
+    end
+  end
+  
+  def initialize(filename, &block)
+    @root_namespace = VariableNamespace.new(nil, :fail_if_file_missing => true, :filename => filename, &block)
+  end
+  
+  def to_a
+    @root_namespace.to_a
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/validation/tml_validator.rb

@@ -0,0 +1,16 @@
+class Rtml::Validation::TmlValidator
+  attr_reader :test_case  
+  
+  def initialize(tc, tml)
+    tc = tc.test_case if tc.respond_to? :test_case
+    @test_case = tc
+    @tml = tml
+    @parser = Rtml::Validation::DomRuleParser.new
+    @parser.parse! File.join(File.dirname(__FILE__), "../../../rules", "tml_document_structure.rb")
+    validate
+  end
+  
+  def validate(root = nil)
+    @parser.validate(self, @tml, root)
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/version.rb

@@ -0,0 +1,11 @@
+require 'rtml/beryl/version'
+
+module Rtml
+  module VERSION
+    MAJOR = 1
+    MINOR = 2
+    TINY  = 2
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/widgets/property.rb

@@ -0,0 +1,11 @@
+module Rtml::Widgets
+  # Defines a Property for a Widget. You should not have to instantiate this directly.
+  class Property
+    attr_accessor :value
+    attr_reader :name
+    
+    def initialize(name)
+      @name = name
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/widgets/property_accessors.rb

@@ -0,0 +1,59 @@
+module Rtml::Widgets::PropertyAccessors
+  # Ensures that all properties currently contain valid values.
+  # If a property has been declared to REQUIRE a value, and its
+  # current value is nil, an exception will be raised.
+  #
+  def validate_properties
+    properties.each do |name, prop|
+      raise "Value for property #{name.inspect} in Widget #{self.class.name} was not set" if prop.value == :required
+    end
+    1
+  end
+  
+  # Sets or gets the value of the specified property. If no arguments are specified, the
+  # current value is returned. Otherwise, the arguments are assigned and the new value is
+  # returned. If a block is given, it is passed into the callbacks for the property.
+  def access_property(prop_name, *args, &block)
+    if args.length == 0 and not block_given? then get_property_value prop_name
+    else set_property_value prop_name, args[0], &block
+    end
+  end
+  
+  # Returns the current value for the specified property
+  def get_property_value(prop_name)
+    get_property(prop_name).value
+  end
+  
+  # Sets the specified property to the given value. Block is passed into the callbacks, if any.
+  def set_property_value(prop_name, value, &block)
+    self.class.callbacks_for(prop_name).each { |c| value = self.send(c, value, &block) }
+    get_property(prop_name).value = value
+  end
+  
+  # Returns the Property object with the given property name. This is the actual
+  # RTML Property object, not the value of the specified property.
+  def get_property(prop_name)
+    properties[prop_name] ||= Rtml::Widgets::Property.new(prop_name)
+  end
+  
+  # An optional callback to be called immediately after initialization. Should be used
+  # to set up default values for properties.
+  #
+  # If a property is given the value :required, then an exception will be raised if no
+  # overriding value is set before to_tml is called.
+  #
+  # Example:
+  #   property :first_name, :password
+  #   
+  #   def init_properties
+  #     first_name "Joe"
+  #     password :required
+  #   end
+  #
+  def init_properties; end
+  
+  # Returns the hash of properties for this Widget.
+  def properties
+    @properties ||= HashWithIndifferentAccess.new
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/widgets/widget.rb

@@ -0,0 +1,251 @@
+require 'find'
+
+module Rtml::Widgets
+  # All RTML Widgets should extend this class.
+  #
+  # The simplest definition of an RTML \Widget is "an object which generates raw TML code".
+  # Widgets are responsible for the vast majority of the heavy lifting in RTML, and are
+  # indispensable.
+  #  
+  # It is important to realize that "core" RTML – that is, RTML without Widgets -- is entirely
+  # unable to accommodate an acceptable TML application. This is because "core" RTML consists
+  # of the TMLDocument object, which is responsible for creating the highest level only of the
+  # document object model, and the Screen object, which is responsible for creating the
+  # individual screens within that document. All other content -- such as displays, views,
+  # credit card parsers, and so forth -- is brought to you by Widgets.
+  #
+  # By default, you can create new Widgets in your lib/rtml/widgets directory. If you
+  # need to change this load path or add more directories to it, you can do so by modifying
+  # the Widget.load_paths array via your environment.rb file:
+  #
+  #   Rtml::Widgets::Widget.load_paths << "lib/rtml/third_party/widgets"
+  #
+  # The simplest way to create a Widget is to use the command line generator:
+  #
+  #   script/generate rtml_widget my_test
+  #
+  # This will create a Widget called MyTestWidget in the lib/rtml/widgets directory.
+  # By default, there will be lots of comments in this file to help you get started. If
+  # you wish to generate a Widget without the comments, disable them:
+  #
+  #   script/generate rtml_widget my_test --no-help
+  #
+  # There are required components to your Widget. First, it <strong>must</code> list at least
+  # one Accessor. An Accessor is the class name of an object that is going to be allowed to
+  # make use of this Widget. For instance, if you want a user to be able to use your Widget
+  # from the TMLDocument object itself, you would say:
+  #
+  #   accessor TMLDocument
+  #
+  # The usage of the MyTestWidget with a TML helper, then, would look like:
+  #
+  #   Rtml::actions_for MyTestController do
+  #     def index
+  #       my_test { . . . }
+  #     end
+  #   end
+  #
+  # To make this Widget accessible to a Screen, you would specify Screen as the accessor.
+  # Then, usage would look like:
+  #
+  #   Rtml::actions_for MyTestController do
+  #     def index
+  #       screen :index, :next => :next_scr do
+  #         my_test { . . . }
+  #       end
+  #     end
+  #   end
+  #
+  # You can also specify other Widgets as accessors directly. For instance, you could specify
+  # the Display Widget as an accessor to make this Widget available from within the Display
+  # builder. Likewise, you can specify the Widget class itself as an accessor, which would make
+  # your Widget accessible to <strong>all</code> other Widgets. This wouldn't include TMLDocument
+  # or Screen, however, because they are not Widgets. You can also specify multiple accessors:
+  #
+  #   accessor Widget
+  #   accessor TMLDocument, Screen
+  #
+  # This would, in effect, make this Widget accessible from any context whatsoever.
+  #
+  #
+  # The other required component of a Widget is a #to_tml method. This method most often returns
+  # a String, and if it does not, the value it does return will be converted to one. It can, for
+  # instance, return a reference to another Widget. Its #to_tml method would be called automatically,
+  # and then the String value of that would be substituted for the Widget itself. The #to_tml
+  # method is in charge of actually building the TML content of a document. Without this method,
+  # there is no content.
+  #
+  # See the rest of this page for information on the non-required elements of a Widget, or the
+  # RTML Wiki ( at http://wiki.rubytml.com ) for complete tutorials.
+  #
+  # Many of the methods available to a Widget are defined in WidgetSupport, so be sure to take a
+  # look at that class as well.
+  # 
+  class Widget < Rtml::Element
+    include Rtml::Core
+    include Rtml::Helpers
+    
+    include Rtml::Widgets::PropertyAccessors
+    extend Rtml::Widgets::WidgetClassMethods
+    
+    # Provides access to the RTML object which this Widget was added to.
+    attr_reader :parent
+    attr_writer :layout
+
+    # The return value of the block given during initialization, or nil if no
+    # block was supplied.
+    attr_reader :block_value
+    
+    # Provides access to the RTML Layout in use, if any. This will be assigned
+    # prior to render, but may not necessarily be assigned during initialization.
+    # If a screen Layout is applied to the entire document, it will be applied to this
+    # Widget.
+    #
+    # However, if this Widget resides within a Screen object and an explicit Layout
+    # is applied to that Screen, then this will override the TMLDocument Layout
+    # and be applied to this Widget instead. This sequence is behind-the-scenes
+    # and is not something the author of the Widget should ever have to think about.
+    #
+    # Regardless, it is up to the author of the Widget whether or not to take
+    # advantage of the supplied Layout.
+    #
+    # Note that any Widgets underneath this one will also inherit its Layout, so
+    # even if this particular Widget does not make use of a Layout, yielding to
+    # child Widgets may result in a Layout being rendered anyways. If this Widget
+    # is going to disallow layouts, it should also iterate through its children
+    # and clear their Layouts as well.
+    def layout
+      return @layout if @layout
+      return parent.layout if parent
+      return nil
+    end
+    
+    # A Widget is initialized with a reference to its parent object (for instance, Screen)
+    # and a Hash of options. It is optionally constructed with a block which can also set these
+    # options. The constructor assigns the values specified in the options Hash and yields to
+    # the block (if given).
+    def initialize(parent, *arguments, &block)
+      super(nil, nil, nil, parent)
+      @arguments = arguments.dup
+      @options = arguments.extract_options!
+      @parent = parent
+      protect_all_instance_variables!
+      protected_instance_variables << "@block_value"
+      wrap_view(parent.action_view) if parent
+      if self.methods.include? 'init_properties'
+        if self.method(:init_properties).arity == 0 then self.init_properties
+        else self.init_properties(options.first)
+        end
+      end
+      
+      if self.class.assign_properties?
+        (arguments + [@options]).each do |o|
+          if o.kind_of? Hash
+            o.each { |n,v| self.send("#{n}=", v) if self.respond_to? "#{n}=" }
+          end
+        end
+      end
+
+      self.send :after_initialize if self.respond_to? :after_initialize
+
+      @block_value = yield_with_optional_param self, &block if block_given?
+    end
+          
+    # Returns the array of load paths to look for Widget definitions in.
+    # You can modify this array directly This is probably best done
+    # from config/environment.rb.
+    def Widget.load_paths
+      @@load_paths ||= [ File.join(RAILS_ROOT, "lib", "rtml", "widgets"),
+                         File.join(PLUGIN_BASE, "components", "rtml", "widgets")]
+    end
+
+    def Widget.load_widgets(unused = __FILE__)#:nodoc:
+      default_widget_constants = Rtml::Widgets.constants
+      Widget.load_paths.each do |dir|
+        Dir.glob(File.join(dir, "**", "*.rb")) do |file|
+          require_dependency(file) unless file =~ /[\\\/]\.svn[\\\/]/
+        end
+      end
+      (Rtml::Widgets.constants - default_widget_constants).each do |konst|
+        klass = Rtml::Widgets.const_get(konst)
+        # When it's done, do this...
+        if klass.accessor_list.empty? and klass != self
+          raise "Error: Widget #{klass.name} is not accessible"
+        end
+      end
+      true
+    end
+    
+    # Returns the ID for the current screen, or raises an error if it can't be found.
+    def current_screen_id
+      current_screen.id
+    end
+    
+    def current_screen
+      ancestors.each { |p| return p if p.kind_of? Rtml::Core::Screen }
+      raise "Can't find any screen in parent hierarchy"
+    end
+    
+    # Renders this Widget. This method should always be called instead
+    # of to_tml when dealing with Widgets, because it takes care of
+    # :before_render validation and ensures that a layout, if available,
+    # has been assigned. This method is also in charge of constructing
+    # the block which is passed to #to_tml.
+    #
+    # For content generation, this method takes 3 steps:
+    #  1. The current Widget's to_tml method is called with a block
+    #     which, when yielded to, will call #render_widget_tml.
+    #  2. The return value of to_tml is tested for 3 conditions:
+    #       a. If the returned object contains a #render_tml method,
+    #         that method is called and this second return value will be
+    #         returned as a String.
+    #       b. If the #render_tml method does not exist but the #to_tml
+    #         method does exist, it is called with no block and returned
+    #         as a String.
+    #       c. If neither of these two methods exist, the current value
+    #         is returned as a String.
+    #
+    # In normal RTML generation, you should never have to directly reference
+    # this method; it is called internally, but is made available to you in
+    # case you need to circumvent the built-in functionality for some reason.
+    #
+    def render_tml
+      validate_properties
+      to_tml { render_widget_tml }.to_s.strip
+    end
+    
+    # This method can be called in any way that Rtml::Helpers::WidgetSupport#content_of_view
+    # can be called. You should see that method for usage examples, because there are a lot
+    # of them. Arguments include a String, nil or no arguments, a Block, a Hash or another
+    # RTML argument.
+    #
+    # The #display method will call Rtml::Helpers::WidgetSupport#content_of_view on the
+    # input arguments and then call Widget#do_layout on the return value. The result
+    # is a set of content that has had the current layout, if any, applied to it.
+    # That content is then concatenated to the current element using the #concat
+    # method, which adds the content to the output buffer of this Widget. Finally,
+    # nil is returned. This is useful because there are some cases where a Widget's
+    # return value is concatenated to the element being generated. By returning nil,
+    # this method ensures that its content will not be added twice.
+    #
+    def display(*a, &b)
+      c = content_of_view(*a, &b).to_s
+      r = ((layout.nil? or layout == false) ? c : (layout.to_tml { c.indent })).to_s.indent
+      concat r
+      nil
+    end
+    
+    # This method is in charge of producing the TML which will be sent to your Widget's parent
+    # object. Obviously, this return value must be a String. An exception will be raised if
+    # to_tml is referenced and is not overridden in your Widget.
+    def to_tml
+      raise "Implement method to_tml to return a String or Widget to be rendered in the TML document"
+    end
+
+    protected
+    # Returns the list of arguments this Widget was constructed with.
+    attr_reader :arguments
+    # Returns the options hash this Widget was constructed with.
+    attr_reader :options
+  end
+end