rtml 1.2.2

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

@@ -0,0 +1,18 @@
+module Rtml::Features
+  def self.included(base)
+    base.send :include, Rtml::Features::ControllerInstanceMethods
+    base.send :extend, Rtml::Features::ControllerClassMethods
+    # Views are shared across all Features because Features must be designed to coexist.
+    base.append_view_path_for_action nil, File.join(PLUGIN_BASE, "components", "rtml", "features", "views")
+  end
+  
+  def self.all
+    features = (Rtml::Features.constants - %W(ControllerClassMethods  ControllerInstanceMethods
+                                              ArrayOfFeatureInstances))
+    features.collect do |k|
+      Rtml::Features.const_get(k)
+    end
+  end
+  
+  def self.each(*a, &b) self.all.each(*a, &b) end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/features/array_of_feature_instances.rb

@@ -0,0 +1,17 @@
+module Rtml
+  module Features
+    class ArrayOfFeatureInstances < Array
+      def init(rtml_document, after_init)
+        prev_ft = rtml_document.screen :feature_init
+        self.flatten.each_with_index do |feature, index|
+          next unless feature.respond_to? :init
+          cur_ft = rtml_document.screen "ft_init_#{index}" do |scr| feature.init(scr) end
+          prev_ft.next_screen cur_ft.id
+          prev_ft = cur_ft
+        end
+        prev_ft.next_screen after_init
+        :feature_init
+      end
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/features/controller_class_methods.rb

@@ -0,0 +1,30 @@
+module Rtml::Features::ControllerClassMethods
+  def configuration_blocks
+    return superclass.configuration_blocks if superclass.respond_to? :configuration_blocks
+    @configuration_blocks ||= []
+  end
+  
+  def configure_features(&block)
+    raise "Block expected" unless block_given?
+    configuration_blocks << block
+  end
+  
+  def self.extended(base)
+  end
+
+  def self.feature_files
+    ret = []
+    [
+      File.join(RAILS_ROOT, "lib", "rtml", "features"),
+      File.join(RAILS_ROOT, "vendor", "plugins", "rtml", "components", "rtml", "features")
+    ].each do |features_dir|
+      extract = /^#{Regexp.quote(features_dir)}\/?(.*)\.rb$/
+      ret.concat Dir["#{features_dir}/**/*.rb"].map { |file| file.sub extract, 'rtml/features/\1' }
+    end
+    ret
+  end
+
+  feature_files.each do |file_name|
+    require_dependency(file_name)
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/features/controller_instance_methods.rb

@@ -0,0 +1,35 @@
+module Rtml::Features::ControllerInstanceMethods
+  def self.included(base)
+    base.send :before_filter, :setup_features
+    base.send :hide_action, :configure_features, :setup_features, :feature_instances, :feature_config,
+              :add_features
+  end
+
+  def configure_features(config = self.feature_config)
+    yield config if block_given?
+  end
+  
+  def setup_features
+    yield feature_config if block_given?
+    self.class.configuration_blocks.each { |config_block| configure_features(feature_config, &config_block) }
+  end
+  
+  def feature_instances
+    return @feature_instances if @feature_instances
+    @feature_instances = feature_config.to_instances
+    @feature_instances
+  end
+  
+  def features; feature_instances; end
+  
+  def feature_config
+    @feature_config ||= Rtml::FeatureConfig.new
+  end
+  
+  def add_features(*feature_classes)
+    tml_document.action_view.instance_variable_set("@config", feature_config)
+    feature_instances.flatten.each do |instance|
+      instance.add_to tml_document if feature_classes.empty? or feature_classes.include? instance.feature_class
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Rtml
+  # Helper methods for RTML Widgets.
+  module Helpers
+    # Applies the current layout to the given target object
+    # If a block is supplied, that block will be called with the target object
+    # as an argument, and the result of that block will have the layout applied to it.
+    # If there is no layout for this object, the above happens but a layout is not applied.
+    def do_layout(target = nil, &block)
+      if target.respond_to? :layout=
+        target.layout = layout
+        yield target if block_given?
+        target.to_tml
+      else
+        c = ((block_given?) ? block.call(target) :
+              ((target.respond_to? :to_tml) ? target.to_tml : target.to_s)
+            )
+        ((layout) ? (layout.to_tml { c.to_s.indent }) : c.to_s)
+      end
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/helpers/controller_helpers.rb

@@ -0,0 +1,59 @@
+module Rtml::Helpers::ControllerHelpers
+  # The RTML Helper is the core of your RTML application. This is where you tell your controller
+  # which helpers to load. Most common usage is:
+  #
+  #   tml_helper :all
+  #
+  # Note to myself (you probably shouldn't care): To load internal TML helpers, use this syntax:
+  #
+  #   tml_helper :all, :plugin_path => true
+  #  
+  def tml_helper(*args)
+    options = args.extract_options!
+    
+    args.flatten.each do |arg|
+      case arg
+        when Module
+
+        when :all
+          tml_helper(all_tml_helpers(options[:plugin_path]), :plugin_path => options[:plugin_path])
+        when String, Symbol
+          file_name  = arg.to_s.underscore
+          class_name = file_name.camelize
+          view_path = File.join("app/views", controller_path)
+          view_path = File.join("vendor", "plugins", "rtml", view_path) if options[:plugin_path]
+          view_path = File.join(view_path, file_name)
+          file_name = File.join("#{controller_path}_tml_helpers/#{file_name}") unless File.exist?("#{file_name}.rb")
+          
+          begin
+            logger.debug "Adding TML Helper: #{file_name}" if ENV['RAILS_ENV'] == 'development'
+            require_dependency(file_name)
+            append_view_path_for_action(class_name.underscore, view_path)
+          rescue LoadError => load_error
+            requiree = / -- (.*?)(\.rb)?$/.match(load_error.message).to_a[1]
+            if requiree == file_name
+              msg = "Missing TML helper file helpers/#{file_name}.rb"
+              raise LoadError.new(msg).copy_blame!(load_error)
+            else
+              raise
+            end
+          end
+        else
+          raise ArgumentError, "tml_helper expects String or Symbol argument (was: #{args.inspect})"
+      end
+    end
+  end
+  
+  private
+    def all_tml_helpers(plugin_path = false)
+      ret = []
+      f = ""
+      f = File.join("vendor", "plugins", "rtml") if plugin_path
+      
+      [File.join(RAILS_ROOT, f, "app", "helpers", "#{controller_path}_tml_helpers")].each do |helpers_dir|
+        extract = /^#{Regexp.quote(helpers_dir)}\/?(.*)\.rb$/
+        ret.concat Dir["#{helpers_dir}/*.rb"].map { |file| file.sub extract, '\1' }
+      end
+      ret
+    end  
+end

data/app_generators/rtml/templates/rtml/lib/rtml/helpers/controller_helpers/menu_helpers.rb

@@ -0,0 +1,193 @@
+module Rtml::Helpers::ControllerHelpers::MenuHelpers
+  # Constructs a new Menu Item to be rendered at the main menu of an application.
+  #
+  #
+  # Option definitions:
+  #   [option]     => [default value] [description]
+  #   :label       =>  -              the text label to render
+  #   :image       => nil             the URL to the image to render
+  #   :partial     => nil             the Partial to render (negates :image, :label, :render_mode)
+  #   :escape      => true            whether to HTML-escape the label or block result
+  #   :display     => true            whether to display this menu item at all
+  #   :position    => num_menu_items  a number between 0 and the number of menu items representing
+  #                                   where in the list this item should be placed
+  #   :render_mode => :normal         The render_mode option determines how to render the data
+  #                                   if a display is less capable of rendering graphics.
+  #
+  #   Available render modes:
+  #       :always       => Always render both label and image
+  #       :normal       => Render label and image in graphical displays, and just label otherwise.
+  #       :image        => Render only image for graphical displays, and fall back to label otherwise.
+  #       :always_image => Always render only the image and never the label.
+  #
+  #   Note that the render mode is ignored if a partial is supplied.
+  #
+  # Examples:
+  #  menu_item :sale
+  #  menu_item :sale, :label       => "Sale", :image => "rtml/sale.gif"
+  #  menu_item :sale, :next        => :sale_screen
+  #  menu_item :sale, :next_screen => :sale_screen
+  #  menu_item :sale, :image       => "rtml/sale.gif", :label => nil
+  #  menu_item :sale, :partial     => 'menu_sale'
+  #  menu_item :sale, :display     => false  ## disables this menu item
+  #  menu_item :sale, :position    => 0     ## inserts this menu item at index 0
+  #  menu_item :sale, :render_mode => :always
+  #
+  # If a block is included, it will be called and the return value will be
+  # rendered:
+  #
+  #  menu_item :sale, :next => :sale_screen do |info|
+  #    info[:escape] = false
+  #    "CLICK TO BEGIN SALE"
+  #  end
+  #
+  # The argument passed into the block is the Hash containing the details of
+  # this menu item. It can be modified here, if you wish to alter information.
+  # After the block ends, its return value will be converted to a link pointing
+  # to the <code>info[:next_screen]</code> screen. If <code>info[:escape]</code> is set
+  # to <code>true</code> (this is the default), it will be HTML-escaped before
+  # the link is created.
+  def menu_item(*args, &block)
+    defaults = { :label => args[0].to_s.titleize, :image => nil, :partial => nil, :escape => true,
+                 :display => true, :position => menu_items.values.length, :render_mode => :normal }
+    defaults[:block] = block if block_given?
+    item = nil
+    case args.length
+      when 0
+        raise "Expected at least one argument (Symbol or Hash)"
+      when 1
+        if args[0].kind_of? Hash
+          item = menu_items[args[0][:name]] || { :name => args[0][:name] }.merge(defaults)
+          old_name = item[:name]
+          item.merge! args[0]
+        elsif args[0].kind_of? Symbol
+          item = menu_items[args[0]] || { :name => args[0], :next_screen => args[0] }.merge(defaults)
+          old_name = item[:name]
+        else
+          raise "Expected argument to be a Symbol or Hash"
+        end
+      when 2
+        unless args[0].kind_of? Symbol
+          raise "Expected first argument to be a Symbol if second argument is given"
+        end
+        raise "Expected second argument to be a Hash" unless args[1].kind_of? Hash
+        item = menu_items[args[0]] || { :name => args[0], :next_screen => args[0] }.merge(defaults)
+        old_name = item[:name]
+        item.merge! args[1]
+      else
+        raise "Expected no more than 2 arguments (Symbol and a Hash)"
+    end
+    item[:next_screen] = item.delete :next if item.keys.include? :next
+
+    raise "No :next_screen specified" unless item[:next_screen]
+    
+    if item[:name] != old_name
+      menu_items.delete item[:name]
+    end
+  
+    menu_items[item[:name]] = item
+    menu_items.reorder!
+  end
+  
+  # Renders the menu to a string. If a block is given, it will be executed for each item and
+  # its value will be assigned in place of the defaults.
+  #
+  # The arguments given to the optional block are the item itself, and the return value of 
+  # calling that item's block (or nil, if no block was given).
+  def render_menu_items(*items, &block)
+    r = ""
+    if items.empty? then items = menu_items.ordered_values
+    else items = menu_items.ordered_values(*items)
+    end
+    
+    items.each do |item|
+      if item[:display]
+        block_response = (item[:block] ? item[:block].call(item) : nil)
+        if block_given?
+          r.concat yield(item, render_menu_items(item[:name]))
+        else
+          if item[:partial]
+            rx = render(:partial => item[:partial], :locals => item)
+            r.concat rx
+          elsif block_response
+            x = CGI::escapeHTML block_response if item[:escape]
+            x = rtml_interface.action_view.link_to x, item[:next_screen].to_screen_ref
+            r.concat x
+          else
+            label = item[:label]
+            label = CGI::escapeHTML label if item[:escape]
+            x = ""
+            case item[:render_mode]
+              when :always
+                raise "No image to display" unless item[:image]
+                x = "<img src='#{item[:image]}' alt='' /> #{label}"
+              when :normal
+                if color_display? and item[:image]
+                  x = "<img src='#{item[:image]}' alt='' /> #{label}".strip
+                else x = label
+                end
+              when :image
+                if color_display? and item[:image]
+                  x = "<img src='#{item[:image]}' alt='' />"
+                else
+                  x = label
+                end
+              when :always_image
+                raise "No image to display" unless item[:image]
+                x = "<img src='#{item[:image]}' alt='' />"
+              else raise "Invalid render_mode: #{item[:render_mode]}"
+            end
+            r.concat rtml_interface.action_view.link_to(x, item[:next_screen].to_screen_ref)
+          end
+        end
+      end
+    end
+    r
+  end
+  
+  def self.included(base)
+    if base.ancestors.include? ActionController::Base
+      base.class_eval do
+        hide_action :menu_items, :render_menu_items, :menu_item, :controller
+        
+        def menu_items
+          unless @menu_items
+            @menu_items = {}.with_indifferent_access
+            def @menu_items.ordered_values(*only)
+              if only.empty? then self.values
+              else only.collect { |key| key.nil? ? nil : self[key.to_s] } - [nil]
+              end.sort { |a,b| a[:position] <=> b[:position] }
+            end
+            
+            # keeps :position equal to a predictable value
+            # this is not important for a first-level app (ie btmlpa), but
+            # becomes important as that application is extended. If a user
+            # sets :position equal to 2.5 to emphasize that it belongs *between*
+            # item 2 and item 3, we need to somehow normalize that so that the
+            # user doesn't have to remember that there's a 2.5 in there.
+            # reorder! accomplishes this by replacing 2, 2.5 and 3 with
+            # 2, 3, 4 respectively.
+            def @menu_items.reorder!
+              #self.ordered_values.each_with_index do |item,index|
+              #  item[:position] = index
+              #end
+              self
+            end
+          end
+          
+          @menu_items
+        end
+        
+        def controller
+          self
+        end
+      end
+    else
+      base.class_eval do
+        def menu_items
+          controller.menu_items
+        end
+      end
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/helpers/core_helpers/action_view_wrapper.rb

@@ -0,0 +1,23 @@
+module Rtml::Helpers::CoreHelpers
+  # Wraps an instance of ActionView::Base such that any method that is called on this
+  # object that doesn't exist will be proxied through to the ActionView object instead.
+  module ActionViewWrapper
+    def action_view
+      return root_element.action_view unless parent.nil?
+      @action_view
+    end
+    
+    alias view action_view
+  
+    # Wraps the specified view. This should only be called for a single instance of ActionView::Base.
+    def wrap_view(view)
+      @action_view = view if parent.nil?
+      return unless action_view
+      if controller
+        copy_instance_variables_from controller
+        copy_instance_variables_from controller.rtml_interface
+      end
+      copy_instance_variables_from parent if parent
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/helpers/core_helpers/event_helpers.rb

@@ -0,0 +1,28 @@
+module Rtml::Helpers::CoreHelpers
+  # Helper methods to deal with terminal event handling.
+  module EventHelpers
+    # Takes an event designation and an action. The event can be anything, but should
+    # be a valid TML event designation such as :menu, :cancel, :f1, :f2, etc.
+    #
+    # If the event is :error, then the action will be taken if an error occurs.
+    # If the event is any of :menu, :cancel, :stop, :enter, :up, :down, :00, [:f1 - :f9], [0 - 9]
+    # then the action will be triggered when the corresponding button has been pressed.
+    #
+    # The action should be either a String or Symbol pointing to the screen to go
+    # to in the event of the button press.
+    #
+    # Examples:
+    #  on :cancel => :cancel_pressed
+    #  on :menu => :menu_pressed, :error => :err_screen
+    def on(event_list)
+      event_list.each do |event,action|
+        if action.nil?
+          event_handler.unregister(event)
+        else
+          target = (action.kind_of? Hash) ? url_for(action) : action.to_screen_ref
+          event_handler.register(event, target)
+        end
+      end
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/helpers/core_helpers/layout_helpers.rb

@@ -0,0 +1,47 @@
+module Rtml::Helpers::CoreHelpers::LayoutHelpers
+  # Defines, undefines or retrieves a layout for this Element. If no arguments
+  # are given, the current layout is returned, or the parent's layout is returned
+  # if this Element has no layout (but has a parent Element).
+  #
+  # If a value of nil or false is given, the current layout will be removed, and
+  # if a layout has been inherited from the parent Element, it will not be used.
+  # If a Rtml::Core::Layout object is specified, it will be used.
+  # If any other value is specified, a new Layout will be constructed using the View
+  # associated with this screen. A second argument may optionally contain a Hash
+  # to be used as local variables within the Layout.
+  #
+  # Examples:
+  #   layout document.screens[0].layout # Will use the layout and locals used by document.screens[0]
+  #   layout 'layout', { :a => 5 }      # Will use a new layout, with a local variable a == 5
+  #   layout nil                        # Will use no layout for this screen
+  def layout(*args)
+    if args.empty?
+      # So basically, if @layout is nil, then it's never been explicitly set, and it should "inherit"
+      # from parent. @layout can still be false, which would mean that the user has explicitly said
+      # that this layout should not be used.
+      @layout = ((parent.nil?) ? nil : parent.layout) if @layout.nil?
+      @layout
+    else
+      case args[0].class.name
+        when 'Rtml::Core::Layout' then
+          @layout = Rtml::Core::Layout.new(action_view, args[0].name, locals_for_layout(args[0].locals))
+        when 'NilClass', 'FalseClass' then @layout = false
+        else @layout = Rtml::Core::Layout.new(action_view, args[0], locals_for_layout(args[1]))
+      end
+      @layout
+    end
+  end
+  
+  # Returns the Hash of local variables that will be used for the layout for this Element.
+  # These variables will also be passed into any View Templates for use with this Element, and
+  # are inherited from parent Elements. If an argument is given, it is expected to be a Hash
+  # to be merged with the other local variables.
+  def locals_for_layout(merge_with = nil)
+    if @locals_for_layout.nil?
+      @locals_for_layout ||= HashWithIndifferentAccess.new
+      @locals_for_layout.merge! parent.locals_for_layout if parent
+    end
+    @locals_for_layout.merge! merge_with unless merge_with.nil?
+    @locals_for_layout
+  end
+end