domkey 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4e084e3b9ec1fd8d799b054c5c7621ff614cbe25
-  data.tar.gz: cc50953f3c169a28d21346e076681fb7e3dcc099
+  metadata.gz: 45e6ac05a48d93eede629f82f2a5b04b14037f62
+  data.tar.gz: 9c3b5d281b8b000852489e1933de6b855b2975e3
 SHA512:
-  metadata.gz: 708a161af1039a64b5beed49e5b8b3ea354387624ceae4fa810f9c52993aa21fb41b493778f6bd816a75a751a55ba060d2b86c4d743ff75fbdd58e4dece13aa8
-  data.tar.gz: 49e6a0ff0391b95355d136dcc44d9fae71acf7413829ea52cf3e0008d16a11de06d002a714071558b0f31a22bfe487a1f11289523e928f3f600c06238c70d095
+  metadata.gz: aa5af099b7354c11538d238e9c4a59eb91cf41a7f7845fe10bd92659af309e7e65ebf1630d722952e17a39ca1a0e9a790e955a00d91df35a074ea9de9b83d3d1
+  data.tar.gz: 2fe75c7ca69ba9f0656491cea2a358a048f815b5da77bc7d614425c4a4a5a353b653364b4f13b522e2a366de699744389e3244dcde80822a7ed9fd6ab727fe56

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "spec/watirspec"]
+	path = spec/watirspec
+	url = git://github.com/watir/watirspec.git

data/README.md

@@ -1,8 +1,6 @@
-# Domain Specifc PageObject for Selenium Watir-Webdriver
+# Domain Specific PageObject for Selenium Watir-Webdriver
 
-PageObject that models business domain first and browser code second.
-
-Watir-Webdriver is the Bee's Knees! Now with Domain Specific PageObject Factory!
+PageObject that models specific domain first and browser code second.
 
 Watir-Webdriver is the Bee's Knees! Now with Domain Specific PageObject Factory!
 

data/Rakefile

@@ -1,7 +1,10 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  # Do not include watirspec
+  spec.pattern = 'spec/*_spec.rb'
+end
 
 task :default => :spec
 

data/lib/domkey/version.rb

@@ -1,3 +1,3 @@
 module Domkey
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/domkey/view.rb

@@ -1,5 +1,9 @@
 require 'domkey/view/page_object'
 require 'domkey/view/page_object_collection'
+require 'domkey/view/radio_group'
+require 'domkey/view/checkbox_group'
+require 'domkey/view/cargo'
+
 module Domkey
 
   module View
@@ -7,18 +11,25 @@ module Domkey
     module ClassMethods
 
       # PageObjectCollection factory
-      def doms(key, &watirproc)
+      def doms(key, &package)
         send :define_method, key do
-          PageObjectCollection.new watirproc, Proc.new { browser }
+          PageObjectCollection.new package, Proc.new { browser }
         end
       end
 
       # PageObject factory
-      def dom(key, &watirproc)
+      def dom(key, &package)
         send :define_method, key do
-          PageObject.new watirproc, Proc.new { browser }
+          PageObject.new package, Proc.new { browser }
         end
       end
+
+      # build Cargo with model and view
+      # @return [Domkey::View::Cargo]
+      def cargo model, browser: nil
+        Cargo.new model: model, view: self.new(browser)
+      end
+
     end
 
     def self.included(klass)
@@ -27,13 +38,40 @@ module Domkey
 
     attr_accessor :browser
 
+    # @param [Watir::Browser] (false)
     def initialize browser=nil
       @browser = browser
     end
 
+    # browser for this view.
+    # if View was initialized without a browser then default Domkey.browser is provided
+    # @return [Watir::Browser]
     def browser
       @browser ||= Domkey.browser
     end
 
+    def set value
+      Cargo.new(model: value, view: self).set
+    end
+
+    # @param [Hash{Symbol => Object}] view data where Symbol is semantic descriptor for a pageobject in the view
+    # @param [Symbol] for one pageobject
+    # @param [Array<Symbol>] for array of pageobjects
+    #
+    # @return [Hash{Symbol => Object}] data from the view
+    def value value
+      # transform value into hash
+      value = case value
+              when Symbol
+                {value => nil}
+              when Array
+                #array of symbols
+                Hash[value.map { |v| [v, nil] }]
+              when Hash
+                value
+              end
+      Cargo.new(model: value, view: self).value
+    end
+
   end
 end

data/lib/domkey/view/cargo.rb

@@ -0,0 +1,92 @@
+module Domkey
+
+  module View
+
+    # Data shipping between Model and View
+    # Sends data to view. Grabs data from view
+    #
+    # For specialized transfer object a client would sublcass this Cargo,
+    # by default View.cargo factory method is provided for regular data transfer object
+    #
+    # @usage
+    #
+    #      class MyView
+    #        include Domkey::View
+    #
+    #        dom(:city) { text_field(id: 'city2') }
+    #
+    #        def fruit
+    #          RadioGroup.new -> { checkboxes(name: 'fruit') }
+    #        end
+    #      end
+    #
+    #      model      = {city: 'Austin', fruit: 'tomato'}
+    #      cargo = MyView.cargo model
+    #      cargo.set #=> sets view.city with model[:city] and view.fruit with model[:fruit]
+    #      cargo.value #=> returns {city: 'Austing', fruit: 'tomato'}
+    #
+    #      class MyCargo < Domkey::View::Cargo
+    #
+    #      end
+    #
+    #      model = {city: 'Mordor'}
+    #      view  = MyView.new
+    #      cargo = MyCargo.new view: view, model: model
+    #      cargo.set
+    #
+    class Cargo
+
+      attr_accessor :view, :model
+
+      def initialize model: nil, view: nil
+        @model = model
+        @view  = view
+      end
+
+      # set each pageobject in the view with the value from the model
+      def set
+        @model.each_pair do |key, value|
+          set_pageobject key, value
+        end
+        self
+      end
+
+      # extracts value for each pageobject identified by the model
+      # @returns [Model]
+      def value
+        extracted = {}
+        @model.each_pair do |key, value|
+          extracted[key] = value_for_pageobject(key, value)
+        end
+        extracted
+      end
+
+      private
+
+      def set_pageobject key, value
+        @view.send(key).set value
+      end
+
+      def value_for_pageobject key, value
+        object = @view.send(key)
+        # object is pageobject
+        if object.method(:value).parameters.empty?
+          object.value
+        else
+          # object is another view that has collection of pageobject
+          object.value value
+        end
+      end
+
+      ## submits view
+      #def submit
+      #
+      #end
+      #
+      ## is view ready?
+      #def ready?
+      #
+      #end
+    end
+  end
+end

data/lib/domkey/view/checkbox_group.rb

@@ -0,0 +1,75 @@
+require 'domkey/view/labeled_group'
+module Domkey
+
+  module View
+
+    # Acts like OptionSelectable object
+    # CheckboxGroup allows you to interact with PageObjectCollection of checkboxes as a single PageObject.
+    # Checkboxes collection is constrained by the same name attribute and acts like on object.
+    # It behaves like a Multi Select list.
+    # It can none, one or more options selected
+    class CheckboxGroup < PageObjectCollection
+
+      # clears all options and sets only the desired value(s)
+      # @param [String, Regexp] find value attribute or match value and set that checkbox
+      # @param [Array<String, Regexp>] find each value attribute and set each checkbox
+      # @param [False] uncheck any checked checkboxes
+      def set value
+        validate_scope
+        element.each { |e| e.clear }
+        return unless value
+        [*value].each do |v|
+          e = case v
+              when String
+                element.find { |e| e.value == v }
+              when Regexp
+                element.find { |e| e.value.match(v) }
+              end
+          e ? e.set : fail(Exception::Error, "Checkbox to be set not found by value: #{v.inspect}")
+        end
+      end
+
+      # @return [Array<String>] value attributes of each checked checkbox
+      def value
+        validate_scope
+        element.find_all { |e| e.set? }.map { |e| e.value }
+      end
+
+      def options
+        validate_scope
+        element.map { |e| e.value }
+      end
+
+      # convert to LabeledGroup settable by corresponding label text
+      def to_labeled
+        LabeledGroup.new(self)
+      end
+
+      # @yield [PageObject]
+      def each(&blk)
+        validate_scope
+        super(&blk)
+      end
+
+      # @return [Array<PageObject>]
+      def to_a
+        validate_scope
+        super
+      end
+
+      private
+
+      # precondition on acting on this collection
+      # @return [true] when all checkboxes in collection share the same name attribute
+      # @raise [Exception::Error] when where is more than one unique name attribute
+      # --
+      # returns true on subsequent unless magically more radios show up after initial validation
+      def validate_scope
+        return if @validated
+        groups = element.map { |e| e.name }.uniq
+        fail(Exception::Error, "CheckboxGroup definition scope too broad: Found #{groups.count} checkbox groups with names: #{groups}") unless (groups.size == 1)
+        @validated = true
+      end
+    end
+  end
+end

data/lib/domkey/view/label_mapper.rb

@@ -0,0 +1,18 @@
+module Domkey
+
+  module View
+
+    # return collection of PageObjects for label locators corresponding to id of each element in a collection
+    class LabelMapper
+      # @param [Array<PageObject>]
+      # @param [PageObjectCollection]
+      # @return [Array<PageObject>] where each PageObject is a locator for label for an id of a PageObject passed in parameters
+      def self.for collection
+        collection.map do |e|
+          PageObject.new -> { label(for: e.element.id) }, e.container
+        end
+      end
+    end
+  end
+end
+

data/lib/domkey/view/labeled_group.rb

@@ -0,0 +1,50 @@
+require 'delegate'
+require 'domkey/view/label_mapper'
+module Domkey
+
+  module View
+
+    # Interfact to CheckboxGroup and RadioGroup elements through corresponding label elements;
+    # radio and checkbox controls form a group by name attribute
+    # however they don't have visible text indicators to the user who is looking at the page.
+    # The common strategy is to provide a lable element such that
+    # its for: attribute value maps to id: attribute value of an individual control in a group.
+    # The labels become visual indicators for the user. Clicking corresponding lable activates the control.
+    class LabeledGroup < SimpleDelegator
+
+      def initialize group
+        __setobj__(group)
+      end
+
+      # @param value [String] a label text to set a corresponding element referenced
+      # @param value [Array<String>] one or more labels
+      def set value
+        __getobj__.set false
+        labels  = self.options
+        indices = [*value].map do |what|
+          i = case what
+              when String
+                labels.index(what)
+              when Regexp
+                labels.index(labels.find { |e| e.match(what) })
+              end
+          i ? i : fail(Exception::Error, "Label text to set not found for value: #{what.inspect}")
+        end
+        indices.each do |i|
+          __getobj__[i].element.set
+        end
+      end
+
+      # @return [Array<String>] label texts for selected elements
+      def value
+        selected_ones = __getobj__.find_all { |e| e.element.set? }
+        LabelMapper.for(selected_ones).map { |e| e.element.text }
+      end
+
+      # @return [Array<String>] label texts for all elements in a group
+      def options
+        LabelMapper.for(__getobj__).map { |e| e.element.text }
+      end
+    end
+  end
+end

data/lib/domkey/view/page_object.rb

@@ -1,120 +1,120 @@
+require 'domkey/view/widgetry_package'
+require 'domkey/view/watir_widget'
+
 module Domkey
 
   module View
 
+    # PageObject represents an semantically essential area in a View
+    # It is an object that responds to set and value as the main way of sending data to it.
+    # it is composed of one or more watir elements.
+    # PageObject encapuslates the widgetry of DOM elements to provide semantic interfact to the user of the widgetry
+    #
+    # Compose PageObject with package and container
+    #
+    # What is a container? it's a proc, a callable object that plays a role of a container for package widgetry
+    # container can be one of:
+    # - browser (default)
+    # - a pageobject
+    #
+    # What is package? it's a proc of DOM elements widgetry that can be found inside the container
+    # package can be one of the following:
+    #   - definition of single watir element i.e. `-> { text_field(:id, 'foo')}`
+    #   - a pageobject i.e. previously instantiated definition
+    #   - hash where key defines subelement and value a definition or pageobject
+    #
+    # Usage:
+    # Clients would not usually instantate this class.
+    # A client class which acts as a View would use a :dom factory method to create PageObjects
+    # Example:
+    #
+    #        class MyView
+    #          include Domkey::View
+    #
+    #          dom(:headline) { text_field(id:, 'some_desc_text') }
+    #
+    #          def property
+    #            PropertyPanel.new browser.div(id: 'container')
+    #          end
+    #        end
+    #
+    #        class PropertyPanel
+    #          include Domkey::View
+    #          dom(:headline) { text_field(class: 'headline_for_house') }
+    #        end
+    #
+    #        view = MyView.new
+    #        view.headline.set 'HomeAway Rules!'
+    #        view.value #=> returns 'HomeAway Rules!'
+    #        view.property.headline.set 'Awesome Vactaion Home'
+    #        view.property.headline.value #=> returns 'Awesome Vaction Home'
+    #
     class PageObject
 
-      attr_accessor :watirproc, :container
-
-      # PageObject represents an semantically essential area in a View
-      # It is an object that responds to set and value as the main way of sending data to it.
-      # it is composed of one or more watir elements.
-      # PageObject encapuslates the widgetry of DOM elements to provide semantic interfact to the user of the widgetry
-      #
-      # Compose PageObject with watirproc and container
-      #
-      # What is a container? it's a proc, a callable object that plays a role of a container for watirproc widgetry
-      # container can be one of:
-      # - browser (default)
-      # - a pageobject
-      #
-      # What is watirproc? it's a proc of DOM elements widgetry that can be found inside the container
-      # watirproc can be one of the following:
-      #   - definition of single watir element i.e. `-> { text_field(:id, 'foo')}`
-      #   - a pageobject i.e. previously instantiated definition
-      #   - hash where key defines subelement and value a definition or pageobject
-      #
-      # Usage:
-      # Clients would not usually instantate this class.
-      # A client class which acts as a View would use a :dom factory method to create PageObjects
-      # Example:
-      #
-      #        class MyView
-      #          include Domkey::View
-      #
-      #          dom(:headline) { text_field(id:, 'some_desc_text') }
-      #
-      #          def property
-      #            PropertyPanel.new browser.div(id: 'container')
-      #          end
-      #        end
-      #
-      #        class PropertyPanel
-      #          include Domkey::View
-      #          dom(:headline) { text_field(class: 'headline_for_house') }
-      #        end
-      #
-      #        view = MyView.new
-      #        view.headline.set 'HomeAway Rules!'
-      #        view.value #=> returns 'HomeAway Rules!'
-      #        view.property.headline.set 'Awesome Vactaion Home'
-      #        view.property.headline.value #=> returns 'Awesome Vaction Home'
-      #
-      def initialize watirproc, container=lambda { Domkey.browser }
-        @container = container
-        @watirproc = initialize_this watirproc
-      end
+      # @api private
+      include WidgetryPackage
 
+      # Each Semantic PageObject defines what value means for itself
+      # @param [SemanticValue] Delegated to WebdriverElement and we expect it to respond to set
+      # @parma [Hash{Symbol => SemanticValue}]
       def set value
-        return instantiator.set(value) unless value.respond_to?(:each_pair)
-        value.each_pair { |k, v| watirproc.fetch(k).set(v) }
+        return watir_widget.set value unless value.respond_to?(:each_pair)
+        value.each_pair { |k, v| package.fetch(k).set(v) }
       end
 
+      alias_method :value=, :set
+
+      # Each Semantic PageObject defines what value means for itself
+      # @return [SemanticValue] delegated to WebdriverElement and we expect it to respond to value message
+      # @return [Hash{Symbol => SemanticValue}]
       def value
-        return instantiator.value unless watirproc.respond_to?(:each_pair)
-        Hash[watirproc.map { |key, pageobject| [key, pageobject.value] }]
+        return watir_widget.value unless package.respond_to?(:each_pair)
+        Hash[package.map { |key, pageobject| [key, pageobject.value] }]
       end
 
-      # access widgetry of watir elements composing this page object
-      def element(key=false)
-        return instantiator unless watirproc.respond_to?(:each_pair)
-        return watirproc.fetch(key).element if key
-        Hash[watirproc.map { |key, watirproc| [key, watirproc.element] }]
+      def options
+        return watir_widget.options unless package.respond_to?(:each_pair)
+        Hash[package.map { |key, pageobject| [key, pageobject.options] }]
       end
 
       private
 
-      # recursive
-      def initialize_this watirproc
-        if watirproc.respond_to?(:each_pair) #hash
-          Hash[watirproc.map { |key, watirproc| [key, PageObject.new(watirproc, container)] }]
+      # wrap instantiator with strategy for setting and getting value for watir object
+      # expects that element to respond to set and value
+      # @returns [WatirWidget]
+      def watir_widget
+        WatirWidget.new(instantiator)
+      end
+
+      # @api private
+      # Recursive. Examines each packages and turns each Proc into PageObject
+      def initialize_this package
+        if package.respond_to?(:each_pair) #hash
+          Hash[package.map { |key, package| [key, PageObject.new(package, container)] }]
         else
-          if watirproc.respond_to?(:call) #proc
+          if package.respond_to?(:call) #proc
             begin
               # peek inside suitcase that is proc. XXX ouch, ugly
-              peeked_inside = watirproc.call
+              peeked_inside = package.call
             rescue NoMethodError
-              return watirproc #suitecase exploded, proc returned
+              return package #suitecase exploded, proc returned
             end
             if peeked_inside.respond_to?(:each_pair) # hash
               return initialize_this peeked_inside
             elsif peeked_inside.respond_to?(:wd) # watir element
               return lambda { peeked_inside }
-            elsif peeked_inside.respond_to?(:watirproc) #pageobject
-              return peeked_inside.watirproc
+            elsif peeked_inside.respond_to?(:package) #pageobject
+              return peeked_inside.package
             else
-              fail Exception::Error, "watirproc must be kind of hash, watirelement or pageobject but I got this: #{watirproc}"
+              fail Exception::Error, "package must be kind of hash, watirelement or pageobject but I got this: #{package}"
             end
-          elsif watirproc.respond_to?(:watirproc) #pageobject
-            return watirproc.watirproc
+          elsif package.respond_to?(:package) #pageobject
+            return package.package
           else
-            fail Exception::Error, "watirproc must be kind of hash, watirelement or pageobject but I got this: #{watirproc}"
+            fail Exception::Error, "package must be kind of hash, watirelement or pageobject but I got this: #{package}"
           end
         end
       end
-
-      # talk to the browser executor.
-      # returns runtime element in a specified container
-      # expects that element to respond to set and value
-      def instantiator
-        container_instantiator.instance_exec(&watirproc)
-      end
-
-      # talk to the browser
-      # returns runtime container element in a browser/driver
-      def container_instantiator
-        container.respond_to?(:call) ? container.call : container.send(:instantiator)
-      end
     end
   end
 end