rtml 1.2.2 → 2.0.0.alpha.1

data/builtin/models/rtml/state.rb

@@ -0,0 +1,20 @@
+class Rtml::State < ActiveRecord::Base
+  serialize :other_data, HashWithIndifferentAccess
+  set_table_name 'rtml_states'
+  validates_presence_of :model
+  validates_uniqueness_of :itid
+
+  def after_initialize
+    self.other_data ||= {}.with_indifferent_access
+  end
+
+  def [](key)
+    return self.send(key) if attributes.keys.include?(key)
+    other_data[key]
+  end
+  
+  def []=(key, value)
+    return self.send("#{key}=", value) if attributes.keys.include?(key)
+    other_data[key] = value
+  end
+end

data/builtin/models/rtml/state/variable_mapping.rb

@@ -0,0 +1,13 @@
+class Rtml::State::VariableMapping < HashWithIndifferentAccess
+  def initialize(*args)
+    super
+    setup_default_mapping
+  end
+
+  # Sets up the variable mapping. Override this method if you intend to add custom variables to the mapping.
+  def setup_default_mapping
+    %w(datetime datetime_start itid model os part_number serial_number).each do |var|
+      self["terminal.#{var}"] = var
+    end
+  end
+end

data/builtin/models/rtml/view.rb

@@ -0,0 +1,5 @@
+class Rtml::View < ActiveRecord::Base
+  set_table_name "rtml_views"
+  validates_presence_of :name
+  validates_uniqueness_of :name
+end

data/builtin/rtml_helpers/rtml/get_state.rb

@@ -0,0 +1,23 @@
+Rtml::actions_for :rtml do
+  def get_state
+    cache false
+    expires_at { Time.at(0) }
+    on :cancel => embedded_app
+
+    screen :gather_data, :submit_err do
+      build :submit, :tgt => url_for(params), :econn => "#submit_err", :cache => "deny" do
+        [:datetime, :datetime_start, :itid, :model, :os, :part_number, :serial_number].each do |field|
+          build :getvar, :name => "terminal.#{field}"
+        end
+      end
+    end
+
+    screen :submit_err do
+      display <<-end_tml
+        <br/><br/>
+        Error initializing session state data. See logs for more details.<br/>
+        <getvar name='err.baddata_reason' />
+      end_tml
+    end
+  end
+end

data/builtin/rtml_helpers/rtml/rescue_action.rb

@@ -0,0 +1,25 @@
+Rtml::actions_for :rtml do
+  def rescue_action_locally
+    #on :cancel => embedded_app
+    #cache false
+    #expires_at { Time.at(0) }
+
+    screen :rescue, :next => "/index.tml" do
+      clean_params = request.parameters.clone
+      clean_params.delete "action"
+      clean_params.delete "controller"
+      @request_dump = clean_params.empty? ? "None" : clean_params.inspect.gsub(',', ",\n")
+
+      display :file => "rtml/rescue_action_locally"
+    end
+  end
+
+  def rescue_action_in_public
+    #cache false
+    #expires_at { Time.at(0) }
+
+    screen :rescue, :next => '/index.tml' do
+      display :file => "rtml/rescue_action_in_public"
+    end
+  end
+end

data/builtin/views/rtml/rescue_action_in_public.rtml.erb

@@ -0,0 +1 @@
+<p>Could not complete transaction. Please try again.</p>

data/builtin/views/rtml/rescue_action_locally.rtml.erb

@@ -0,0 +1,29 @@
+<h1>
+  <%=h @exception.class%> in
+  <%=h request.parameters["controller"].capitalize if request.parameters["controller"]%>#<%=h request.parameters["action"]%>
+</h1>
+<br/>
+
+<h2>Message: <%=h(@exception ? @exception.message : "")%></h2>
+<br/>
+
+<%=link_to "Retry Request", params%> |
+<%=link_to "Restart Application", "/index.tml"%> |
+<%=link_to "Configuration", embedded_app%>
+<br/><br/>
+
+<pre>RAILS_ROOT: <%=defined?(RAILS_ROOT) ? RAILS_ROOT : "unset"%></pre>
+<br/>
+
+<div id="traces">
+  <%=@exception ?
+      @exception.application_backtrace.select { |i| not(i =~ /lib\/ruby\/gems/) }.collect { |i| h(i) }.join("<br/>\n") :
+      ""%>
+</div>
+
+<h2>Request</h2>
+Parameters: <pre><%=h @request_dump%></pre>
+<br/>
+
+<h2>Response</h2>
+Headers: <pre><%=h(response ? response.headers.inspect.gsub(',', ",\n") : "None")%></pre>

data/builtin/widgets/default_document.rb

@@ -0,0 +1,25 @@
+class Rtml::Widgets::DefaultDocument < Rtml::Widget
+  affects :document
+  entry_point :setup_default_document
+
+  # Runs the initial setup for an instance of Rtml::Document. This is triggered by
+  # the #initialize method of that class. It should be safe to call this method
+  # multiple times if you need to, but the only effect after the first will be a call to
+  # Rtml::Document#apply_document_options. See that method for information about what
+  # options are available.
+  def setup_default_document(options = {})
+    apply_document_options(options)
+    if parent.root.blank?
+      parent.build :tml, :xmlns => "http://www.ingenico.co.uk/tml", :cache => "allow" do
+        head
+      end
+
+      document.during_finalization do
+        screen :assert do
+          display "<h1>Assertion Error!</h1>On screen: <getvar name='oebr.prev_screen' />"
+        end
+      end
+    end
+  end
+  
+end

data/builtin/widgets/document_variable_processing.rb

@@ -0,0 +1,133 @@
+class Rtml::Widgets::DocumentVariableProcessing < Rtml::Widget
+  VALID_OPTIONS = %w(type name format perms value)
+  VALID_TYPES = %w(integer string opaque datetime)
+
+  affects :document
+  entry_point :declare_variable, :define_variable, :variable?, :variable_declared?, :variable_defined?
+  entry_point :string, :integer, :opaque, :datetime, :binary, :boolean
+  entry_point :strings, :integers, :opaques, :datetimes, :binaries, :booleans
+  entry_point :string?, :integer?, :opaque?, :datetime?, :binary?, :boolean?
+  entry_point :defined_variables, :variable_definitions
+  entry_point :declared_variables, :variable_declarations
+  entry_point :variable
+
+  # Declares a TML variable to be used within this document. Valid options include:
+  #   :name       the name of the variable
+  #   :type       string, integer, opaque, date
+  #   :volatile   yes, no
+  #   :perms      "rw---", "rwxrw", etc
+  def declare_variable(name, options = { })
+    unless variable?(name)
+      define_variable name, options
+      document.root.build :vardcl, options.merge(:name => name.to_s)
+    end
+  end
+
+  # Defines a TML variable to be used within this document, without explicitly declaring it.
+  # This is useful for adding built-in TML variables, or those set at the Incendo gateway level,
+  # to RTML's scope.
+  def define_variable(name, options = {})
+    options_with_name = options.merge(:name => name.to_s)
+    validate_options(options_with_name)
+    vd = variable_definitions(options[:type])
+    vd << options_with_name.with_indifferent_access
+    vd
+  end
+
+  def validate_options(options)
+    options.each do |key, value|
+      unless VALID_OPTIONS.include?(key.to_s)
+        raise Rtml::Errors::InvalidOptionError, "Option '#{key}' is not allowed; expected one of #{VALID_OPTIONS.inspect}"
+      end
+      case key.to_s
+        when 'type'
+          unless VALID_TYPES.include?(value.to_s)
+            raise Rtml::Errors::InvalidOptionError, "Type must be one of #{VALID_TYPES.inspect}; found #{value}"
+          end
+      end
+    end
+  end
+
+  # Returns all known variable definitions of the specified type, which can be one of
+  # :all, :string, :datetime, :opaque, :binary, :integer, :boolean
+  def variable_definitions(type = :all)
+    vdn = '@variable_definitions'
+    type = "opaque" if type.to_s == "binary"
+    vd = document.instance_variable_get(vdn) || document.instance_variable_set(vdn, {}.with_indifferent_access)
+    if type == :all
+      vd.collect { |i, j| j }.flatten
+    else
+      vd[type] = [] unless vd[type]
+      document.instance_variable_set(vdn, vd)
+      vd[type]
+    end
+  end
+  alias defined_variables variable_definitions
+
+  # Returns all explicit variable declarations of the specified type, which can be one of
+  # :all, :string, :datetime, :opaque, :binary, :integer, :boolean
+  def variable_declarations(type = :all)
+    r = []
+    type = "opaque" if type.to_s == "binary"
+    type = "integer" if type.to_s == "boolean"
+    vardecs = (document / 'vardcl') || []
+    vardecs = [vardecs] unless vardecs.kind_of? Array
+    vardecs.each do |vardec|
+      if type == :all || vardec.property('type') == type
+        r << vardec
+      end
+    end
+    r
+  end
+
+  alias declared_variables variable_declarations
+
+  %w(string integer opaque datetime).each do |type|
+    line = __LINE__ + 2
+    code = <<-end_code
+    def #{type}(*names)
+      options = names.extract_options!
+      names.each do |name|
+        declare_variable(name, (options || {}).merge(:type => #{type.inspect}))
+      end
+    end
+
+    def #{type.pluralize}(*names)
+      if names.empty?
+        variable_declarations(#{type.inspect})
+      else #{type}(*names)
+      end
+    end
+
+    def #{type}?(name)
+      name = name.to_s
+      !variable_definitions(#{type.inspect}).collect { |var| var[:name] == name }.empty?
+    end
+    end_code
+    eval code, binding, __FILE__, line
+  end
+
+  def variable_defined?(name)
+    name = name.to_s
+    !variable_definitions(:all).select { |var| var[:name] == name }.empty?
+  end
+
+  def variable_declared?(name)
+    name = name.to_s
+    !variable_declarations(:all).select { |var| var.property(:name) == name }.empty?
+  end
+
+  alias variable? variable_defined?
+
+  alias binary opaque
+  alias binaries opaques
+  alias binary? opaque?
+
+  alias boolean integer
+  alias booleans integers
+  alias boolean? integer?
+
+  def document
+    parent
+  end
+end

data/builtin/widgets/element_builder.rb

@@ -0,0 +1,148 @@
+# The ElementBuilder Widget is the heart of RTML document generation. All other Widgets are built on top of this one,
+# and use it to formulate a valid document object model (DOM) representing the TML to be sent downstream.
+#
+# ElementBuilder can be invoked from any document or element via its entry point, #build. Any options are converted
+# into element properties.
+#
+# ElementBuilder will create an instance of Rtml::Dom::Element whose parent is whichever element you invoked the
+# ElementBuilder from and whose name is set accordingly. An error will be raised if the element does not match any
+# of the parent's valid children.
+#
+# A block can be passed to the ElementBuilder invocation in order to create children of the initially-built element.
+# In this case, a set of methods are predefined to match the names of valid children. Calling one of those methods
+# is exactly the same as calling #build with the first argument being the name of the element.
+#
+# Examples:
+#   document = Rtml::Document.new
+#   document.build(:tml) do
+#     head
+#     screen :id => 'gather_data' do
+#       submit :target => url_for(params), :error => '#submit_err', :cache => "deny" do
+#         getvar :name => 'terminal.datetime'
+#       end
+#     end
+#   end
+#
+# It should be noted that generating a document using solely the ElementBuilder would be little different than writing
+# it in raw TML. This is discouraged. ElementBuilder is meant to serve as an interface upon which other Widgets can be
+# constructed. There's certainly no reason you can't use it to accomplish something the other Widgets do not, but you
+# might consider writing a brand-new Widget to accomplish the same task instead, so that others (and perhaps yourself
+# in the future) may benefit from your contribution of missing functionality.
+#
+# In the event that the method name that would be used to generate a child element is also the name of a Widget entry
+# point, that entry point takes priority over the generated method.
+#
+class Rtml::Widgets::ElementBuilder < Rtml::Widget
+  affects :document, :element # all elements
+  entry_point :build
+  attr_reader :name
+  disable_subprocessing!
+
+  def rules_apply?
+    parent.respond_to?(:document) && parent.document ? parent.document.rules :
+            (parent.respond_to?(:rules) && parent.rules)
+  end
+
+  def build(name, properties = {}, &block)
+    @name = name.to_s
+    raise ArgumentError, "Expected properties to be a Hash", caller unless properties.kind_of?(Hash)
+    skip_validation = properties.delete(:skip_validation) || false
+    valid_tag_names = (rules_apply? ? case parent
+      when Rtml::Document
+        validate_tag_is_the_only_root unless skip_validation
+        [ rules.root ]
+      else
+        validate_tag_is_in_order unless skip_validation
+        rules.tag(parent.name).children
+    end : [])
+    validate_name_is_one_of(valid_tag_names) if rules_apply? and not skip_validation
+
+    # validation passed, so create the element
+    @element = parent.build_element(name, properties)
+    if @element.respond_to?(:parent=)
+      if @element.changed? || @element.new_record?
+        @element.parent = parent
+      else
+        @element.update_attribute(:parent, parent)
+      end
+    end
+
+    rebuild_invalid_elements
+    add_method_proxies
+    begin
+      @element.process &block
+    rescue
+      # if the subprocessing failed, then remove the element from parent.
+      if parent.respond_to?(:elements)
+        parent.elements.delete @element
+      elsif parent.respond_to?(:root) && parent.root == @element
+        parent.root = nil
+      end
+      raise
+    end if block_given?
+    @element
+  end
+
+  private
+  # Removes elements in the @out_of_order array from the parent element, and then rebuilds them. This ensures
+  # that they come *after* the current element, because #validate_tag_is_in_order has already verified that that
+  # is where they belong.
+  def rebuild_invalid_elements
+    @out_of_order.each do |o|
+      ele = o
+      parent.elements.delete o
+      parent.elements << o
+    end if @out_of_order
+  end
+
+  # Aliases #build in the newly-created element for each valid child of that element.
+  def add_method_proxies
+    if rules_apply?
+      code = ""
+      tag = rules.tag(name)
+      proxy = Module.new
+      entry_points = @element.widget_entry_points
+
+      tag.children.each do |method_name|
+        # we can't abort if respond_to? is true because that would prevent things like "display" or "p" from working
+        # as expected. So we get a list of known entry points, and ignore them because anything we define here will
+        # likely override them. (Since ElementBuilder is considerably low-level, that is probably the opposite of what
+        # the user writing the Widget in question would expect.) Then we continue, even if the method already exists,
+        # as long as it's not a Widget entry point.
+        next if entry_points.include? method_name
+        #puts "#{@element.name} - #{method_name}"
+        code.concat "def #{method_name}(*a, &b); build('#{method_name}', *a, &b); end\n"
+      end if tag && !tag.kind_of?(Array)
+      proxy.class_eval code, __FILE__, __LINE__ unless code.blank?
+      (class << @element; self; end).send(:include, proxy)
+    end
+  end
+
+  # Raises RulesViolationError if #name is out of the accepted order.
+  def validate_tag_is_in_order
+    order = rules.order(parent.name)
+    first = order.index(name)
+    after = order.select { |i| order.index(i) > first }
+    out_of_order = parent.elements.select { |c| after.include?(c.name) }
+
+    # out_of_order is supposed to come after first, but is already in the list so is placed before it.
+    # (first hasn't been created yet.)
+    @out_of_order = out_of_order
+  end
+
+  # Raises RulesViolationError if #name is not a root tag or if there is already a root tag.
+  def validate_tag_is_the_only_root
+    unless name == rules.root
+      raise Rtml::Errors::RulesViolationError, "Tag must be a root tag (#{rules.root.inspect}); was #{name.inspect}"
+    end
+    if (first = parent.root)
+      raise Rtml::Errors::RulesViolationError, "Already have a root tag (#{first.name.inspect})"
+    end
+  end
+
+  # Raises RulesViolationError if #name is not in the specified array.
+  def validate_name_is_one_of(valid_tag_names)
+    return if valid_tag_names.include? name
+    raise Rtml::Errors::RulesViolationError, "Tag name should be one of #{valid_tag_names.inspect}; was #{name.inspect}"
+  end
+end

data/builtin/widgets/event_listener.rb

@@ -0,0 +1,41 @@
+class Rtml::Widgets::EventListener < Rtml::Widget
+  affects :document, :screen
+  entry_point :on
+  disable_subprocessing!
+
+  def on(events)
+    events.each do |key, destination|
+      make_sure_key_is_valid(key)
+      register_event(key, destination)
+    end
+  end
+
+  def valid_keys
+    case source_type
+      when :document then %w(menu cancel)
+      when :screen then %w(0 1 2 3 4 5 6 7 8 9 00 f1 f2 f3 f4 f5 f6 f7 f8 f9 down up menu stop cancel enter)
+    end
+  end
+
+  # Returns the +defaults+ TML tag beneath the document's +head+ TML tag, or creates it.
+  def defaults_tag
+    head = (document / "head").first
+    (head / "defaults").first || head.build(:defaults)
+  end
+
+  private
+  def make_sure_key_is_valid(key)
+    if !valid_keys.include?(key.to_s)
+      raise Rtml::Errors::RulesViolationError,
+            "Expected key to be one of #{valid_keys.to_sentence(:locale => :en)}; found #{key.inspect}"
+    end
+  end
+
+  def register_event(key, destination)
+    if source_type == :document
+      defaults_tag.property(key, destination, :id_ref => true)
+    else
+      parent.goto destination, :key => key
+    end
+  end
+end