rtml 1.2.2 → 2.0.0.alpha.1

data/lib/rtml/widget_core/gui_configuration.rb

@@ -0,0 +1,94 @@
+# This class is yielded to +Rtml::Widget#gui+ in order to set up the Widget in question for use within the RTML
+# Application Builder (the GUI).
+class Rtml::WidgetCore::GuiConfiguration
+  attr_accessor :icon, :title, :tooltip_message
+  attr_reader :widget_class
+
+  # A hash whose keys represent options to be passed to this Widget when it is instantiated. The value for each key
+  # is either a Symbol or an Array containing a String and a Symbol:
+  #
+  # Examples:
+  #   # This is what the Screens Widget looks like:
+  #
+  #   gui do |config|
+  #     . . .
+  #     config.fields[:next] = { :caption => "Next Screen", :type => :screen_ref }
+  #     config.fields[:name] = :string
+  #   end
+  #
+  attr_reader :fields
+
+  def initialize(widget_class)
+    @widget_class = widget_class
+    @title = nil#widget_class.name.gsub(/Rtml(\:\:|\/)Widgets(\:\:|\/)/, '').titleize
+    @fields = ActiveSupport::OrderedHash.new
+    @entry_points = :all
+    initializer_arguments { |fields| [fields] }
+  end
+
+  # Constructs a complete options hash for each field, and then returns an array containing those hashes.
+  # A complete options hash includes :name, :caption and :type. If not found, :type defaults to :string and
+  # :caption defaults to options[:name].titleize.
+  def fields_with_inferences
+    field_array = []
+    fields.each do |name, setup|
+      field_options = {:name => name, :caption => name.to_s.titleize, :type => setup || :string}
+      if setup.kind_of?(Array)
+        field_options[:caption] = setup[0]
+        field_options[:type] = setup[1] || :string
+        if setup[1].nil? && field_options[:caption].is_a?(Symbol)
+          field_options[:type] = field_options[:caption]
+          field_options[:caption] = name.to_s.titleize
+        end
+        if field_options[:caption].is_a?(Symbol) && field_options[:type].is_a?(String)
+          field_options[:caption], field_options[:type] = field_options[:type], field_options[:caption]
+        end
+      elsif setup.kind_of?(Hash)
+        field_options.merge! setup
+      end
+      field_array << field_options
+    end
+    field_array
+  end
+
+  # Returns all entry points found in #widget_class that can be associated with the GUI.
+  # By default, this returns all entry points.
+  # See also #entry_points=
+  def entry_points
+    return widget_class.entry_points if @entry_points == :all
+    return @entry_points if @entry_points.kind_of?(Array)
+    return [@entry_points]
+  end
+
+  # Defines the specific entry points which can be used with this GUI. If this is set to :all, then
+  # all entry points in the #widget_class will be used.
+  #
+  # This can be a symbol, string or an array of symbols/strings.
+  def entry_points=(entry_point_or_points)
+    @entry_points = entry_point_or_points
+  end
+
+  def id(addl = nil)
+    "#{title}_#{addl}".parameterize('_').to_s
+  end
+
+  # Give this method a block which returns an Array. That array will be converted to arguments to initialize an instance
+  # of this Widget.
+  #
+  # Example:
+  #   # This is the default implementation:
+  #   gui do |config|
+  #     . . .
+  #     config.initializer_arguments do |fields|
+  #       [ fields ] # since fields is a hash, this will look like [ :name => '...', :next => '...', :etc => '...' ]
+  #     end
+  #   end
+  def initializer_arguments(&block)
+    @initializer_arguments = block
+  end
+
+  # Takes a hash of fields and produces an array of arguments.
+  def construct_arguments(fields)
+    @initializer_arguments.call(fields)
+  end
+end

data/lib/rtml/widget_core/widget_accessor_class_methods.rb

@@ -0,0 +1,12 @@
+module Rtml::WidgetCore::WidgetAccessorClassMethods
+  def class_widget_proxies
+    included_modules.select { |k| k.kind_of?(Rtml::WidgetCore::WidgetProxy) }
+  end
+
+  def class_widget_entry_points
+    (class_widgets || []).collect { |k| k.entry_points }.flatten.uniq
+    #class_widget_proxies.collect { |k| k.instance_methods }.flatten.uniq
+  end
+
+  alias class_widget_methods class_widget_entry_points
+end

data/lib/rtml/widget_core/widget_accessor_instance_methods.rb

@@ -0,0 +1,19 @@
+module Rtml::WidgetCore::WidgetAccessorInstanceMethods
+  def widget_instances
+    @widget_instances ||= []
+  end
+
+  delegate :class_widget_proxies, :class_widget_entry_points, :to => 'self.class'
+
+  def singleton_widgets; (class << self; self; end).class_widgets end
+  def singleton_widget_proxies; (class << self; self; end).class_widget_proxies end
+  def singleton_widget_entry_points; (class << self; self; end).class_widget_entry_points end
+
+  def widgets; singleton_widgets + class_widgets end
+  def widget_proxies; singleton_widget_proxies + class_widget_proxies end
+  def widget_entry_points; singleton_widget_entry_points + class_widget_entry_points end
+
+  alias class_widget_methods     class_widget_entry_points
+  alias singleton_widget_methods singleton_widget_entry_points
+  alias widget_methods           widget_entry_points
+end

data/lib/rtml/widget_core/widget_proxy.rb

@@ -0,0 +1,70 @@
+class Rtml::WidgetCore::WidgetProxy < Module
+  attr_reader :proxied_widgets
+
+  # An explanation:
+  # What we have set up looks a little like this:
+  #   Class includes Module1
+  #
+  #   Module1 includes Module2
+  #
+  #   Class is now expected to include methods from Module2 -- BUT it doesn't because its references haven't been
+  #   updated.
+  #
+  # Class must explicitly reinclude Module1 in order to include methods from Module2. Unfortunately, by this time,
+  # we have already forgotten what class included Module1 to begin with. So, include_proxy will hunt down that class
+  # for us, and reinclude "self" (this WidgetProxy instance).
+  #
+  # The name of the method "imbue" is a nod to where I learned that "ObjectSpace" exists (and a working code example, of
+  # course):
+  # http://stackoverflow.com/questions/1655623/ruby-class-c-includes-module-m-including-module-n-in-m-does-not-affect-c-what
+  #
+  # If anybody's curious, the reason I didn't include his code directly is because I want to keep RTML dependencies to
+  # a minimum.
+  #
+  def imbue(proxy)
+    include proxy
+    ObjectSpace.each_object(Class) do |k|
+      k.send :include, self if k.include? self
+    end
+  end
+
+  def initialize(*a, &b)
+    @proxied_widgets = []
+    super(*a, &b)
+  end
+
+  def included(base)
+    base.class_widgets ||= []
+    base.class_widgets.concat self.proxied_widgets
+  end
+
+  
+#  def included(base)
+#    line = __LINE__ + 1
+#    code = "def initialize_with_shared_variables(*a, &b)\n"
+#    (@proxies || []).each do |proxy|
+#      owner = proxy.instance_variable_get("@owner")
+#      next unless owner
+#      code += <<-end_code
+#        initialize_without_shared_variables(*a, &b)
+#        #{owner.name}.shared_variables.each do |sv|
+#          unless instance_variable_get("@\#{sv[:name]}")
+#            if sv[:default_value]
+#              if sv[:default_value].kind_of?(Class)
+#                instance_variable_set("@\#{sv[:name]}", sv[:default_value].new)
+#              else
+#                instance_variable_set("@\#{sv[:name]}", sv[:default_value].dup)
+#              end
+#            end
+#            #{owner.name}.send(:attr_accessor, sv[:name])
+#          end
+#        end
+#      end_code
+#    end
+#    code += "end\n"
+#
+#    base.class_eval code, __FILE__, line
+#    base.send(:alias_method_chain, :initialize, :shared_variables)
+#    #base.send(:attr_accessor, sv[:name])
+#  end
+end

data/lib/rtml/widgets.rb

@@ -0,0 +1,112 @@
+# This module makes sure that all Widgets that can be found in Rtml.configuration.widget_paths have been loaded, and
+# then registers Widget functionality with whatever class included Rtml::Widgets. Note that while merely including this
+# module does allow your class to _support_ Widgets, the Widget itself must declare that it is meant to affect your
+# object.
+#
+# You can interface with existing Widgets (assuming they support your class at a more fundamental level) by defining
+# a self.name method which returns the name of one of the elements the Widget in question affects. This definition must
+# appear _before_ the inclusion of Rtml::Widgets.
+#
+
+module Rtml::Widgets
+  class << self
+    # The Widget mapping is a hash whose keys are symbols and whose values are instances of Module. The symbols
+    # represent either RTML models or TML tag names, while the Modules represent the proxy from the representation's
+    # class into the Widget itself. This way, the Module can be mixed-in with the target, and Widgets added after
+    # the fact can simply add methods to the mixed-in Module. These methods are automatically added to the target
+    # class by Ruby. It's a really fancy version of doing something like this:
+    #   mixin = Module.new
+    #   mixin.send(:define_method, :say_hi) { puts 'hello' }
+    #   class Target; end
+    #   Target.send(:include, mixin)
+    #   mixin.send(:define_method, :say_bye) { puts 'goodbye' } # notice this happens AFTER it's mixed in!
+    #
+    #   target_instance = Target.new
+    #   target_instance.say_hi        # => hello
+    #   target_instance.say_bye       # => goodbye
+    def mapping(key)
+      @widget_mapping ||= {}
+      @widget_mapping[key.to_s] ||= Rtml::WidgetCore::WidgetProxy.new
+    end
+
+    # Returns all Widgets which affect the specified target.
+    def affecting(target)
+      mapping(target).proxied_widgets
+    end
+
+
+    def included(base)
+      @bases ||= []
+      @bases << base
+
+      create_widgets_array(base)
+      base.send(:include, Rtml::WidgetCore::WidgetAccessorInstanceMethods)
+      base.send(:extend,  Rtml::WidgetCore::WidgetAccessorClassMethods)
+      load_widgets
+      add_proxies_to_base(base)
+    end
+
+    # Mixes the various proxy methods into the specified base.
+    def add_proxies_to_base(base)
+      target_name = base.respond_to?(:name) ? base.name.underscore.sub(/^.*\//, '') : nil
+      (@widget_mapping ||= {}).each do |key, mixin|
+        klass = base
+        if base.kind_of? ActiveRecord::Base
+          klass = class << base; self; end
+        end
+
+        if klass.respond_to?(:name) && key == target_name
+          klass.send(:include, mixin)
+        end
+      end
+    end
+
+    def load_widgets(load_path = nil)
+      if load_path.nil?
+        load_widgets(File.join(Rtml.root, 'builtin/widgets'))
+
+        Rtml.configuration.widget_paths.each do |lp|
+          if defined?(Rails) && defined?(Rails.root)
+            lp = File.join(Rails.root, lp) unless lp =~ /^#{Regexp::escape Rails.root}/ || lp =~ /^C\:/ || lp =~ /\//
+            load_widgets(lp)
+          else
+            load_widgets(lp)
+          end
+        end
+      else
+        if File.file?(load_path)
+          load_widget!(load_path)
+        else
+          if Rtml.configuration.widget_logging_enabled
+            Rails.logger.debug "Searching for Widgets in '#{load_path}/**/*.rb'..."
+          end
+          Dir.glob(File.join(load_path, "**/*.rb")).each do |fi|
+            next if fi =~ /\.svn/ or File.directory?(fi)
+            load_widget!(fi)
+          end
+        end
+      end
+    end
+
+    def load_widget!(file)
+      if Rtml.configuration.widget_logging_enabled
+        begin
+          result = require_dependency(file)
+          Rails.logger.debug "Loading Widget: #{file} (#{result})"
+        rescue
+          Rails.logger.debug "Loading Widget: #{file} (#{$!.message})"
+          raise $!
+        end
+      else
+        require_dependency file
+      end
+    end
+
+    def create_widgets_array(base)
+      base.instance_eval do
+        class_inheritable_array :class_widgets
+        read_inheritable_attribute(:class_widgets) || write_inheritable_attribute(:class_widgets, [])
+      end
+    end
+  end
+end

data/lib/rtml_routes.rb

@@ -0,0 +1,3 @@
+ActionController::Routing::Routes.draw do |map|
+  map.connect_rtml :controller => 'rtml'
+end

data/rails/init.rb

@@ -0,0 +1,6 @@
+path = File.expand_path File.join(File.dirname(__FILE__), '../lib')
+$:.unshift(path) unless $:.include?(path) || $:.include?(File.expand_path(path))
+
+require File.join(path, 'rtml')
+require File.join(path, 'rtml/dependencies')
+require File.join(path, 'rtml/environment')

data/rails_generators/rtml/USAGE

@@ -0,0 +1,19 @@
+
+Usage (from your Rails application root):
+  ruby script/generate rtml
+
+This generator is run for a new RTML application, and should be rerun after
+every RTML update. It is responsible for generating the base set of RTML
+support files:
+
+  * db/migrate/*.rb
+    - Database migrations for RTML models
+
+  * config/tml_dom_ruleset.rb
+    - The TML ruleset which governs RTML's document generation rules
+
+  * lib/tasks/rtml.rake
+    - RTML-specific rake tasks
+
+  * doc/io_tml-application-development-guidelines.pdf
+    - The Incendo Online TML documentation (Never leave home without it!)

data/rails_generators/rtml/rtml_generator.rb

@@ -0,0 +1,64 @@
+# This generator is run for a new RTML application, and should be rerun after
+# every RTML update. It is responsible for generating the base set of RTML
+# support files:
+#
+#   * db/migrate/*.rb
+#     - Database migrations for RTML models
+#
+#   * config/tml_dom_ruleset.rb
+#     - The TML ruleset which governs RTML's document generation rules
+#
+#   * lib/tasks/rtml.rake
+#     - RTML-specific rake tasks
+#
+#   * doc/io_tml-application-development-guidelines.pdf
+#     - The Incendo Online TML documentation (Never leave home without it!)
+#
+class RtmlGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.directory 'db/migrate'
+      m.directory 'config/initializers'
+      m.directory 'lib/tasks'
+      m.directory 'doc'
+
+      m.file 'config/tml_dom_ruleset.rb', 'config/tml_dom_ruleset.rb'
+      m.file 'config/initializers/rtml.rb', 'config/initializers/rtml.rb'
+      m.file 'lib/tasks/rtml.rake', 'lib/tasks/rtml.rake'
+      m.file 'doc/io_tml-application-development-guidelines.pdf',
+             'doc/io_tml-application-development-guidelines.pdf'
+
+      MIGRATIONS.each do |migration|
+        name = File.join("db/migrate", migration)
+        m.file name, name
+      end
+    end
+  end
+
+  protected
+    def banner
+      <<-EOS
+
+
+      This command is used to apply an RTML configuration to your Rails project.
+      It can safely be run multiple times, and you should consider doing so
+      every time you update your 'rtml' gem in order to make sure your project
+      contains the latest database migrations, TML rules, and so on.
+
+      USAGE: #{$0} #{spec.name}
+      EOS
+    end
+
+    MIGRATIONS = %w(
+      20100113131401_add_options_to_properties.rb
+      20100110071920_add_parent_id_to_rtml_instructions.rb
+      20100110060124_create_rtml_instructions.rb
+      20100108165127_create_rtml_documents.rb
+      20100108163827_create_rtml_dom_properties.rb
+      20100108163703_create_rtml_dom_elements.rb
+      20100127173146_add_parent_type_to_rtml_dom_elements.rb
+      20100208114234_create_rtml_states.rb
+      20100303021609_add_x_and_y_to_rtml_instructions.rb
+    )
+
+end

data/rails_generators/rtml/templates/config/initializers/rtml.rb

@@ -0,0 +1,13 @@
+Rtml.configure do |config|
+  # RTML will search these paths for Widgets.
+  config.widget_paths << 'lib/rtml/widgets'
+
+  # RTML will search these paths for RTML Actions.
+  config.rtml_helper_paths << ['app/rtml_actions', 'app/rtml_helpers', 'app/helpers/rtml_helpers']
+
+  # If true, RTML will dump all generated TML content to the Rails log before sending it downstream.
+  config.log_tml = false
+
+  # If true, RTML will log the loading of all discovered Widgets and their locations.
+  config.widget_logging_enabled = false
+end

data/rails_generators/rtml/templates/config/tml_dom_ruleset.rb

@@ -0,0 +1,81 @@
+# This file quite literally tells RTML the "rules" governing the TML document structure. You could modify this file
+# if you are directly inventing a TML-ish language of your own, but otherwise it's probably best to leave this file
+# as it is, or else you are at risk of generating invalid TML.
+#
+# Was going to store all of this in the DB, but decided it's probably better for everyone to just static load it.
+# Might revisit this someday, but for now, whatever.
+
+tags %W{
+  a baddata base br call_func card col colgroup dd defaults display div dl dt econn error form getvar h1 h2 h3 h4 h5
+  h6 head hr img input layout li link log logdcl logrec next ol p pinentry postvar pre print prompt screen setvar span
+  strtemplate submit submit_log table tbody td textarea tfoot tform th thead tml tmlpost tr ul vardcl variant
+}
+
+root :tml
+order do
+  head :base, :link, :defaults, :error
+  logdcl :vardcl, :layout
+  screen :setvar, :strtemplate, :logrec, :next, :error, :call_func, :display, :print, :submit, :tform
+  submit :econn, :getvar, :submit_log
+  table :col, :colgroup, :thead, :tfoot, :tbody, :tr
+  tform :baddata, :card, :prompt, :pinentry
+  tml :head, :vardcl, :logdcl, :screen
+end
+children :layout, all_tag_names - [:form]
+children :print, %W{div dl h1 h2 h3 h4 h5 h6 hr img log ol p pre table ul form}
+children :display, %W{a br div dl form getvar h1 h2 h3 h4 h5 h6 hr img input log ol p pre span table textarea ul}
+children :p, %W{a br getvar input span textarea}
+children do
+  a :img
+  baddata %W{a br div dl h1 h2 h3 h4 h5 h6 hr img getvar ol p pre span table ul}
+  colgroup :col
+  dd %W{a br span getvar input textarea div dl h1 h2 h3 h4 h5 h6 hr img ol p pre table ul form}
+  div %W{a br div dl form getvar h1 h2 h3 h4 h5 h6 hr img input ol p pre span table textarea ul}
+  dl %W{dt dd}, :minimum => 1 #dt+ dd+
+  dt %W{a br div dl form getvar h1 h2 h3 h4 h5 h6 hr img input ol p pre span table textarea ul}
+  econn :variant #variant*
+  error :variant #variant*
+  form %W{div dl h1 h2 h3 h4 h5 h6 hr img ol p pre table ul input textarea}
+  h1 %W{a br getvar input span textarea}
+  h2 %W{a br getvar input span textarea}
+  h3 %W{a br getvar input span textarea}
+  h4 %W{a br getvar input span textarea}
+  h5 %W{a br getvar input span textarea}
+  h6 %W{a br getvar input span textarea}
+  head %W{base defaults error}, :minimum => 0, :maximum => 1 #base?, defaults?, error?
+  head :link # link*
+  input :baddata, :minimum => 0, :maximum => 1
+  li %W{a br span getvar input textarea div dl h1 h2 h3 h4 h5 h6 hr img ol p pre table ul form}
+  log %W{vardcl layout}
+  send :next, %W{variant}
+  ol :li
+  pre %W{a br getvar input span textarea}
+  prompt %W{div dl h1 h2 h3 h4 h5 h6 hr img ol p pre table ul}
+  screen %W{setvar strtemplate logrec}
+  screen %W{next error call_func display print submit tform}, :maximum => 1
+  span %W{a br span getvar input textarea}
+  strtemplate :getvar, :minimum => 0, :maximum => 9
+  submit :econn, :maximum => 1
+  submit %W{getvar submit_log}
+  table %W{col colgroup tbody tr}
+  table %W{thead tfoot}, :maximum => 1
+  tbody :tr
+  td %W{a br span getvar input textarea div dl h1 h2 h3 h4 h5 h6 hr img ol p pre table ul form dd display li print td
+        th}
+  textarea :baddata, :maximum => 1
+  tfoot :tr
+  tform %W{baddata prompt}, :maximum => 1
+  tform :card
+  tform :pinentry, :maximum => 1
+  th %W{a br span getvar input textarea div dl h1 h2 h3 h4 h5 h6 hr img ol p pre table ul form dd display li print td
+        th}
+  thead :tr
+  tml :head, :maximum => 1
+  tml %W{vardcl logdcl screen}
+  tmlpost :postvar
+  tr :th, :td
+  ul :li
+  variant :li
+end
+
+freeze # prevent further modification of the rules