rtml 1.2.2 → 2.0.0.alpha.1

data/builtin/widgets/shorthand.rb

@@ -0,0 +1,49 @@
+class Rtml::Widgets::Shorthand < Rtml::Widget
+  affects :screen, :submit
+  entry_point :submit, :getvar
+
+  # Creates a TML +submit+ tag. Options include :target and :error.
+  #
+  #   screen :do_submit do
+  #     submit :target => url_for(:action => 'proc_submit'), :error => 'submit_err' do
+  #       getvar :name => 'amount'
+  #     end
+  #   end
+  #
+  # Note that the #submit method can only be called from a Screen element, even though #submit is a registered
+  # target.
+  def submit(*args)
+    validate_parent :screen
+    parent.build :submit, hash_for_args(args, :target, :error).rename(:target => :tgt, :error => :econn)
+  end
+
+  # Creates a TML +getvar+ tag for submission of data to the server.
+  #
+  #   screen :do_submit do
+  #     submit :target => url_for(:action => 'proc_submit'), :error => 'submit_err' do
+  #       getvar :name => 'amount'
+  #     end
+  #   end
+  #
+  # Note that the #getvar method can only be called from a Submit element, even though #screen is a registered
+  # target.
+  def getvar(*args)
+    validate_parent :submit
+    parent.build :getvar, hash_for_args(args, :name)
+  end
+
+  private
+  # First, calls Array#extract_options! to create a standard options hash.
+  # Then, iterates through *keys and maps values from args in the order they appear in keys. These
+  # can overwrite options found in extract_options!
+  #
+  # Example:
+  #   hash_for_args([1,2,3,{:a => 1}], :arg1, :arg2, :a)
+  #     => { :arg1 => 1, :arg2 => 2, :a => 3 }
+  #
+  def hash_for_args(args, *keys)
+    options = args.extract_options!
+    keys.each { |key| options[key] = args.shift unless args.empty? }
+    options
+  end
+end

data/builtin/widgets/static_content.rb

@@ -0,0 +1,51 @@
+# Generates some static (hard-coded) content to be inserted beneath the parent element.
+# This is generally ill-advised, since it produces content that cannot be processed as
+# part of the document object model (DOM). This Widget is used internally for +display+
+# and +print+, and should be avoided for pretty much all other uses.
+#
+# Instead of using StaticContent, first try to make use of another Widget, or failing
+# that, the Element Builder, to suit your needs. If all else fails, open a bug report!
+# You can go ahead and use StaticContent to work around an issue with RTML, but this
+# should be a temporary, not to mention last-resort, action that is backed out after
+# the bug in question has been resolved.
+#
+class Rtml::Widgets::StaticContent < Rtml::Widget
+  affects :document, :element # all elements
+  entry_point :static_content, :inner_content
+  disable_subprocessing!
+
+  def default_layout
+    if parent_type == :display || parent_type == :print
+      document.active_layout.path unless document.active_layout.nil?
+    else
+      nil
+    end
+  end
+
+  def static_content(options = { }, &block)
+    options = {:text => options} if options.kind_of?(String)
+    options = {:file => file_path(options)} if options.kind_of?(Symbol)
+
+    options[:layout] = default_layout unless options.key?(:layout)
+    #layout = (options.kind_of?(Hash) && options.key?(:layout) ? options.delete(:layout) : default_layout)
+    frontend_element = parent.build :frontend, :skip_validation => true
+    #frontend_element.property(:layout, layout) if layout
+    unless options.nil?
+      frontend_element.content_options = options
+      if block_given?
+        r = frontend_element.process(&block)
+        if r.kind_of?(String)
+          frontend_element.inner_content = r
+        end
+      end
+    end
+    frontend_element
+  end
+
+  alias_method :inner_content, :static_content
+
+  def file_path(filename)
+    controller ? filename.to_s : #"#{controller.action_name}/#{filename}" :
+            (document && document.name ? "#{document.name}/#{filename}" : filename.to_s)
+  end
+end

data/builtin/widgets/subroutine.rb

@@ -0,0 +1,54 @@
+# Subroutines allow you to build reusable blocks of TML code that return some result back to
+# your main TML source.
+#
+# If you are able to make use of Subroutines to fill a role that Widgets don't already fill,
+# let me know so that I have a reason to keep this code around, because I'm considering removing
+# this from RTML.
+#
+class Rtml::Widgets::Subroutine < Rtml::Widget
+  affects :document, :element
+  entry_point :subroutine, :call, :subroutine?
+  disable_subprocessing!
+  shared :subroutines => HashWithIndifferentAccess
+
+  def subroutine(name, options = { }, &block)
+    #return document.subroutine(name, options, &block) if document != parent
+
+    subroutines[name] = Rtml::HighLevel::Subroutine.new(name, parent, options, &block)
+  end
+
+  def subroutine?(name)
+    name = name.to_s if name.kind_of?(Symbol)
+    return true if subroutines.key?(name)
+    return true if parent != document && parent.parent.subroutine?(name)
+    false
+  end
+
+  def call(name, arguments = {})
+    raise Rtml::Errors::ProcessingError, "Can only call a subroutine from within a screen" unless parent.name == 'screen'
+    #return document.call(name, arguments) if document != parent
+    name = name.to_s if name.kind_of?(Symbol)
+    doc = document
+    p = parent
+    document.string :rtml_sub_return_val
+    while p == doc || p.respond_to?(:parent)
+      #unless p.subroutines
+      #  raise "No subroutines hash for #{p.inspect}"
+      #end
+      if p.subroutines && p.subroutines.key?(name)
+        return_value = p.subroutines[name].call(parent, arguments)
+        begin
+          parent.set :rtml_sub_return_val => return_value
+        rescue ArgumentError
+          parent.set :rtml_sub_return_val => ''
+        end
+        return parent.terminal_variables[:rtml_sub_return_val]
+      end
+      raise NoMethodError, "Subroutine does not exist: #{name}" if p == doc
+      raise Rtml::Errors::ProcessingError, "Parent of #{p.inspect} is nil" unless p.parent
+      p = p.parent
+    end
+
+    raise Rtml::Errors::ProcessingError, "Found a parent that is not a parent...? (this shouldn't happen)"
+  end
+end

data/generators/rtml_widget/USAGE

@@ -0,0 +1,19 @@
+Description:
+  Generates an RTML Widget. See the Rtml::Widget class documentation for more
+information.
+
+Example:
+  ./script/generate rtml_widget Thing [entry_point_1 entry_point_2]
+
+  This will create:
+    lib/rtml/widgets/thing.rb
+
+    And Test::Unit tests:
+      test/unit/rtml/widgets/thing_test.rb
+
+    -or-
+
+    RSpec and/or Cucumber tests:
+      spec/rtml/widgets/thing_spec.rb
+      features/rtml/widgets/thing.feature
+    

data/generators/rtml_widget/rtml_widget_generator.rb

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'active_support/core_ext'
+
+# Description:
+#   Generates an RTML Widget. See the Rtml::Widget class documentation for more
+# information.
+#
+# Example:
+#   ./script/generate rtml_widget Thing [entry_point_1 entry_point_2]
+#
+#   This will create:
+#     lib/rtml/widgets/thing.rb
+#
+#     And Test::Unit tests:
+#       test/unit/rtml/widgets/thing_test.rb
+#
+#     -or-
+#
+#     RSpec and/or Cucumber tests:
+#       spec/rtml/widgets/thing_spec.rb
+#       features/rtml/widgets/thing.feature
+#
+class RtmlWidgetGenerator < RubiGen::Base
+  attr_reader :name
+  attr_reader :entry_points, :human_name, :class_name, :file_name
+
+  def initialize(runtime_args, runtime_options = {})
+    super
+    usage if args.empty?
+    @name = args.shift
+    @class_name = @name.camelize
+    @entry_points = args.dup
+    @entry_points << class_name.underscore.sub(/^.*\//, '') if @entry_points.empty?
+    @file_name = class_name.underscore
+    @human_name = file_name.humanize
+  end
+
+  def manifest
+    record do |m|
+      m.directory "lib/rtml/widgets"
+      m.template 'default_widget.erb', "lib/rtml/widgets/#{file_name}.rb"
+
+      if File.directory?(File.join("spec")) || File.directory?(File.join("features"))
+        if File.directory?(File.join("spec"))
+          m.directory "spec/rtml/widgets"
+          m.template "default_widget_spec.erb", "spec/rtml/widgets/#{file_name}_spec.rb"
+        end
+
+        if File.directory?(File.join("features"))
+          m.directory "features/rtml/widgets"
+          m.template "default_widget.feature.erb", "features/rtml/widgets/#{file_name}.feature"
+        end
+      else # we only need unit tests neither cucumber nor rspec is available.
+        m.directory "test/unit/rtml/widgets"
+        m.template 'default_widget_test.erb', "test/unit/rtml/widgets/#{file_name}_test.rb"
+      end
+    end
+  end
+end

data/generators/rtml_widget/templates/default_widget.erb

@@ -0,0 +1,10 @@
+class Rtml::Widgets::<%=class_name%> < Rtml::Widget
+  affects :document, :element # all elements
+  entry_point <%=entry_points.collect { |ep| ":#{ep.underscore.gsub(/\//, '_')}" }.join(", ")%>
+
+<%entry_points.each do |entry_point| -%>
+  def <%=entry_point.underscore.gsub(/\//, '_')%>(name, options = { })
+
+  end
+<%end -%>
+end

data/generators/rtml_widget/templates/default_widget.feature.erb

@@ -0,0 +1,11 @@
+Feature: <%=human_name.titleize%> Widget
+  In order to [business value]
+  As an RTML developer
+  I want to [action]
+
+  Scenario:
+    Given I have a new RTML document
+    When I follow these instructions:
+      | screen :init, :main          |
+      | screen :main                 |
+    Then the TML should resemble { :tml => :screen }

data/generators/rtml_widget/templates/default_widget_spec.erb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+require 'rtml/test/spec'
+
+describe Rtml::Widgets::<%=class_name%> do
+  before :each do
+    @doc = Rtml::Document.new
+  end
+
+  # add your own tests here
+  it "should be able to handle the truth" do
+    true.should == true
+  end
+end

data/generators/rtml_widget/templates/default_widget_test.erb

@@ -0,0 +1,13 @@
+require 'test_helper'
+
+class Rtml::Widgets::<%=class_name%>Test < ActiveSupport::TestCase
+  def setup
+    @doc = Rtml::Document.new
+    @doc.setup_default_document
+  end
+
+  # add your own tests here
+  test "should be able to handle the truth" do
+    assert true
+  end
+end

data/lib/extensions/action_controller/response.rb

@@ -0,0 +1,30 @@
+module ActionController
+  class Response
+    # Returns true if this response is well-formed XML, follows the TML syntactic rules, and has a format :rtml_helpers or :tml.
+    # Raises an error if any of these are false.
+    def valid_tml?
+      unless template.template_format == :rtml || template.template_format == :tml
+        raise "Expected format to be :rtml or :tml, found #{template.template_format.inspect}"
+      end
+      body.valid_tml?
+    end
+
+    # Verifies that the produced TML resembles the given structure. See +Rtml::Rules::DomValidation#validate_tml_dom+
+    # for more information.
+    def tml_should_resemble(structure)
+      body.validate_tml_structure(structure)
+    end
+
+    # Verifies that the produced TML does NOT resemble the given structure.
+    # See +Rtml::Rules::DomValidation#validate_tml_dom+ for more information.
+    def tml_should_not_resemble(structure)
+      inspected = structure.inspect
+      begin
+        body.validate_tml_structure(structure)
+      rescue
+        return true
+      end
+      raise Rtml::Errors::ProcessingError, "TML was expected not to resemble #{inspected}, but it did!", caller
+    end
+  end
+end

data/lib/extensions/action_controller/routing/route_set.rb

@@ -0,0 +1,42 @@
+module ActionController
+  module Routing
+    class RouteSet
+      class Mapper
+        # Modifies your route set to produce TML-compatible routes. Also connects the default
+        # TML request (/index.tml) to the options you provide, if any.
+        #
+        # Unlike the rest of Rails routing, if you call #connect_rtml multiple times with different
+        # options, the /index.tml path will be updated to reflect the new options.
+        #
+        # To use, just add the following to your /config/routes.rb file:
+        # map.connect_rtml :controller => "start_page"
+        #
+        def connect_rtml(options = {})
+          make_rtml_connection('/:controller/:action.:format', '/rtml/index.rtml')
+          make_rtml_connection('/:controller/:action.:id.:format', '/rtml/index.1.rtml')
+          make_rtml_connection('/:controller/:action/:id', '/rtml/index/1')
+
+          connect_options = !options.empty?
+          ActionController::Routing::Routes.routes.each do |route|
+            segs = route.segments.to_s[0...-1]
+            if segs =~ /^\/index.tml(\/|)$/ && connect_options
+              route.requirements.merge! options.reverse_merge(:format => 'rtml')
+              connect_options = false
+            end
+          end
+
+          if connect_options
+            connect '/index.tml', options.reverse_merge(:format => 'rtml') unless options.empty?
+          end
+        end
+
+        private
+        def make_rtml_connection(connection, example)
+          ActionController::Routing::Routes.recognize_path(example)
+        rescue ActionController::RoutingError
+          connect connection
+        end
+      end
+    end
+  end
+end

data/lib/extensions/active_support/test_case.rb

@@ -0,0 +1,3 @@
+require 'active_support/test_case'
+
+ActiveSupport::TestCase.send(:include, Rtml::Rules::DomValidation)

data/lib/extensions/hpricot/doc.rb

@@ -0,0 +1,5 @@
+module Hpricot
+  class Doc
+    include Rtml::ReverseEngineering::Simulator::Casting
+  end
+end

data/lib/extensions/hpricot/elem.rb

@@ -0,0 +1,5 @@
+module Hpricot
+  class Elem
+    include Rtml::ReverseEngineering::Simulator::Casting
+  end
+end

data/lib/extensions/string.rb

@@ -0,0 +1,35 @@
+class String
+  include Rtml::Rules::DomValidation
+  include Rtml::ReverseEngineering::Simulator::Casting
+
+  def to_controller
+    camel = self.camelize
+    "#{camel}Controller".constantize
+  rescue NameError
+    camel.constantize
+  end
+
+  def valid_tml?
+    validate_tml(self)
+    true
+  end
+
+  def validate_tml_structure(structure)
+    validate_tml_dom(self, structure)
+    true
+  end
+
+  # Verifies that the produced TML does NOT resemble the given structure.
+  # See +Rtml::Rules::DomValidation#validate_tml_dom+ for more information.
+  def tml_should_not_resemble(structure)
+    inspected = structure.inspect
+    begin
+      validate_tml_dom(self, structure)
+    rescue
+      return true
+    end
+    raise Rtml::ProcessingError, "TML was expected not to resemble #{inspected}, but it did!", caller
+  end
+
+  alias tml_should_resemble validate_tml_structure
+end

data/lib/rtml.rb

@@ -1,4 +1,90 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+path = File.expand_path File.join(File.dirname(__FILE__), 'lib')
+$:.unshift(path) unless $:.include?(path) || $:.include?(File.expand_path(path))
+
+RTML_ROOT = File.expand_path(File.join(File.dirname(__FILE__), "..")) unless defined?(RTML_ROOT)
+require 'rtml/version'
+
 module Rtml
+  class << self
+    def root
+      RTML_ROOT
+    end
+
+    def configuration
+      @configuration ||= Rtml::Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    # Defines a single RTML action.
+    # 
+    # Examples:
+    #    Rtml.action :index, :controller => :rtml do
+    #      def index
+    #        # . . .
+    #      end
+    #    end
+    #
+    def action(name, controller, &block)
+      case controller
+        when Array then controllers = controller
+        when String, Symbol, ActionController::Base then controllers = [ controller ]
+        when Hash then controllers = [ controller.delete(:controller) ] || controller.delete(:controllers)
+        else raise ArgumentError, "Expected an Array, String, Symbol or Hash listing affected controllers"
+      end
+
+      actions_for controllers do
+        define_method name do
+          self.instance_eval &block
+        end
+      end
+    end
+
+
+    # Defines a block containing a set of RTML actions for the specified controllers.
+    #
+    # Examples:
+    #    Rtml::actions_for :controller_name do
+    #      def index
+    #        # . . .
+    #      end
+    #    end
+    #
+    def actions_for(*controllers, &block)
+      raise ArgumentError, "actions_for: block containing RTML actions is expected", caller unless block_given?
+      (controllers.flatten.collect do |controller|
+        case controller
+          when String, Symbol then "#{controller.to_s.camelize}Controller".constantize
+          else controller
+        end
+      end).each do |controller|
+        helpers = controller.rtml_helpers
+        old_methods = helpers.instance_methods
+        helpers.class_eval &block
+        new_methods = helpers.instance_methods - old_methods
+        controller.rtml_actions.concat new_methods
+
+        new_methods.each do |method_name|
+          unless helpers.hidden_action?(method_name)
+            helpers.class_eval(<<-end_code, __FILE__, __LINE__+1)
+              def #{method_name}_with_ivars
+                copy_ivars_from(controller)
+                # Give rtml actions access to the controller's view helpers
+                (class << self; self; end).send(:include, controller.response.template.helpers)
+                #{method_name}_without_ivars
+              end
+            end_code
+
+            helpers.send(:alias_method_chain, method_name, :ivars)
+          end
+          unless helpers.hidden_action?(method_name) || controller.instance_methods.include?(method_name)
+            controller.add_rtml_proxy_action(method_name)
+          end
+        end
+      end
+    end
+  end
 end