celerity 0.0.4 → 0.0.6

data/lib/celerity/elements/select_list.rb

@@ -1,70 +1,106 @@
 module Celerity
-  #
-  # Input: Select
-  #
-  # This class is the way in which select boxes are manipulated
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#select_list method
   class SelectList < InputElement
     TAGS = [ Identifier.new('select') ]
     DEFAULT_HOW = :name
-  
-    # Returns an array strings representing the text value of the select list's options.
-    def get_all_contents
+
+    #
+    # @return [Array<String>] An array of strings representing the text value of the select list's options.
+    #
+    
+    def options
       assert_exists
       @object.getOptions.map { |e| e.asText }
     end
-
-    # Returns an array strings representing the text value of the currently selected options.  
-    def get_selected_items
+    
+    #
+    # @return [Array<String>] An array of strings representing the text value of the currently selected options.
+    #
+    
+    def selected_options
       assert_exists
       @object.getSelectedOptions.map { |e| e.asText }
     end
-  
+    
+    #
     # Clear all selected options
-    # FIXME: should update page for each option changed?
-    def clear_selection
+    #
+    
+    def clear
       # assert_exists called by SelectList#type here
+      # TODO: should update page for each option changed?
       @object.getSelectedOptions.each { |e| e.setSelected(false) } unless type() == 'select-one'
     end
-  
+
+    #
     # Select the option(s) matching the given value.
-    # value can be a String or Regexp.
-    # 
     # If several options match the value given, all will be selected.
+    #
+    # @param [String, Regexp] value A value.
+    # @raise [Celerity::Exception::NoValueFoundException] if the value does not exist.
+    # @return [String, nil] The option selected. If multiple options match, returns the first match
+    # 
+    #
+    
     def select(value)
       assert_exists
-      raise NoValueFoundException, "unknown option with value #{value.inspect}" unless include?(value)
+      raise NoValueFoundException, "unknown option with value #{value.inspect} for select_list #{@conditions.inspect}" unless include?(value)
+      
+      selected = nil
       @object.getOptions.select { |e| matches?(e.asText, value) }.each do |option|
-        @container.update_page(option.click)
+        selected ||= option.asText
+        @container.update_page option.click
       end
+      
+      selected
     end
     alias_method :set, :select
-  
+
+    #
     # Returns true if the select list has one or more options matching the given value.
-    # value can be a String or Regexp.
+    #
+    # @param [String, Regexp] value A value.
+    # @return [true, false]
+    #
+    
     def include?(value)
       assert_exists
       !!@object.getOptions.find { |e| matches?(e.asText, value) }
     end
-  
+
+    #
     # Returns true if any of the selected options match the given value.
-    # value can be a String or Regexp.
+    #
+    # @param [String, Regexp] value A value.
+    # @raise [Celerity::Exception::UnknownObjectException] if the value does not exist.
+    # @return [true, false]
+    #
+    
     def selected?(value)
       assert_exists
-      raise UnknownObjectException, "unknown option with value #{value.inspect}" unless include?(value)
+      raise UnknownObjectException, "unknown option with value #{value.inspect} for select_list #{@conditions.inspect}" unless include?(value)
       !!@object.getOptions.find { |e| matches?(e.asText, value) && e.isSelected }
     end
 
-    # Returns 'select-multiple' if the select list has the 'multiple' attribute defined.
-    # Retunrs 'select-one' otherwise.
+    #
+    # Returns 'select-multiple' if the select list has the 'multiple' attribute,
+    # defined, otherwise 'select-one'.
+    #
+    # @return [String]
     # TODO: Move to watir_compatibility or delete it 2008-05-23 Alexander
+    #
+    
     def type
       assert_exists
       'select-' + (@object.isAttributeDefined('multiple') ? 'multiple' : 'one')
     end
-  
+
+    #
     # Returns the value of the first selected option in the select list.
     # Returns nil if no option is selected.
+    #
+    # @return [String, nil]
+    #
+
     def value
       assert_exists
       if (optn = @object.getSelectedOptions.to_a.first)
@@ -72,5 +108,5 @@ module Celerity
       end
     end
 
-  end
-end
+  end # SelectList
+end # Celerity

data/lib/celerity/elements/table.rb

@@ -1,94 +1,141 @@
-module Celerity
-
-  class Table < Element
-    include Enumerable # specs for this?
-    include Container
-    
-    TAGS = [ Identifier.new('table') ]
-    ATTRIBUTES = BASE_ATTRIBUTES | [:summary, :width, :border, :frame, :rules, 
-                                    :cellspacing, :cellpadding, :align, :bgcolor]
-    DEFAULT_HOW = :id
-    
-    def locate
-      super
-      if @object # cant call assert_exists here, as an exists? method call will fail
-        @rows = @object.getRows
-        @cells = []
-        @rows.each do |row| 
-          row.getCells.each do |c|
-            @cells << c
-          end 
-        end
-      end
-    end
-    
-    # Returns a TableRows object.
-    def rows
-      assert_exists
-      TableRows.new(self, :object, @rows)
-    end
-    
-    # Returns a TableCells object.
-    def cells
-      assert_exists
-      TableCells.new(self, :object, @cells)
-    end
-    
-    # Iterates through each row in the table, passing TableRow objects to the given block.
-    def each
-      assert_exists
-      @rows.each { |row| yield TableRow.new(self, :object, row)  }
-    end
-    
-    # Returns the TableRow at the given index (1-indexed).
-    #
-    #   browser.table(:foo, 'bar')[1] # => #<TableRow...>
-    #   browser.table(:foo, 'bar').child_row[1] # => #<TableRow...>
-    def child_row(index)
-      assert_exists
-      raise UnknownRowException, "Unable to locate a row at index #{index}" if @cells.length < index
-      TableRow.new(self, :object, @rows[index-1])
-    end
-    alias_method :[], :child_row
-    
-    # Returns the TableCell at the given index (1-indexed).
-    #
-    # In a 10-column row, table.child_cell[11] will return the first cell on the second row.
-    def child_cell(index)
-      assert_exists
-      raise UnknownCellException, "Unable to locate a cell at index #{index}" if @cells.length < index
-      TableCell.new(self, :object, @cells[index-1])
-    end
-    
-    # The number of rows in the table
-    def row_count
-      assert_exists
-      @object.getRowCount
-    end
-    
-    # Returns the number of columns on the row at the given index. (1-indexed)
-    # Default is the number of columns on the first row
-    def column_count(index = 1)
-      assert_exists
-      @object.getRow(index-1).getCells.length
-    end
-    
-    # Returns the text of each cell in the the table as a two-dimensional array.
-    def to_a
-      assert_exists
-      @object.getRows.map do |table_row|
-        table_row.getCells.map { |td| td.asText }
-      end
-    end
-    
-    def column_values(column_number)
-      (1..row_count).map { |index| self[index][column_number].text }
-    end
-    
-    def row_values(row_number)
-      (1..column_count(row_number)).map { |index| self[row_number][index].text }
-    end
-
-  end
-  
-end
+module Celerity
+
+  class Table < Element
+    include ClickableElement
+    include Enumerable
+    include Container
+
+    TAGS = [ Identifier.new('table') ]
+    ATTRIBUTES = BASE_ATTRIBUTES | [:summary, :width, :border, :frame, :rules,
+                                    :cellspacing, :cellpadding, :align, :bgcolor]
+    DEFAULT_HOW = :id
+
+    def locate
+      super
+      if @object # cant call assert_exists here, as an exists? method call will fail
+        @rows = @object.getRows
+        @cells = []
+        @rows.each do |row|
+          row.getCells.each do |c|
+            @cells << c
+          end
+        end
+      end
+    end
+    
+    #
+    # @return [Celerity::TableRows]
+    #
+    
+    def rows
+      assert_exists
+      TableRows.new(self, :object, @rows)
+    end
+    
+    #
+    # @return [Celerity::TableCells]
+    #
+    
+    def cells
+      assert_exists
+      TableCells.new(self, :object, @cells)
+    end
+    
+    #
+    # Iterates through each row in the table.
+    # @yieldparam [Celerity::TableRow] row A row.
+    #
+    
+    def each
+      assert_exists
+      @rows.each { |row| yield TableRow.new(self, :object, row)  }
+    end
+
+    #
+    # Returns the TableRow at the given index (1-indexed).
+    #
+    #   browser.table(:foo, 'bar')[1] # => #<TableRow...>
+    #   browser.table(:foo, 'bar').child_row[1] # => #<TableRow...>
+    #
+    # @param [Fixnum] index The index of the wanted row, 1-indexed.
+    # @raise [Celerity::Exception::UnknownRowException]
+    # @return [Celerity::TableRow]
+    #
+    
+    def child_row(index)
+      assert_exists
+
+      if (index - INDEX_OFFSET) >= @rows.length
+        raise UnknownRowException, "Unable to locate a row at index #{index}"
+      end
+
+      TableRow.new(self, :object, @rows[index - INDEX_OFFSET])
+    end
+    alias_method :[], :child_row
+
+    #
+    # Returns the TableCell at the given index (1-indexed).
+    #
+    # In a 10-column row, table.child_cell[11] will return the first cell on the second row.
+    #
+    # @param [Fixnum] index The index of the wanted cell, 1-indexed.
+    # @raise [Celerity::Exception::UnknownCellException]
+    # @return [Celerity::TableCell]
+    #
+    
+    def child_cell(index)
+      assert_exists
+
+      if (index - INDEX_OFFSET) >= @cells.length
+        raise UnknownCellException, "Unable to locate a cell at index #{index}"
+      end
+      TableCell.new(self, :object, @cells[index - INDEX_OFFSET])
+    end
+
+    #
+    # The number of rows in the table
+    # @return [Fixnum]
+    #
+    
+    def row_count
+      assert_exists
+      @object.getRowCount
+    end
+    
+    #
+    # Returns the number of columns on the row at the given index. (1-indexed)
+    # Default is the number of columns on the first row
+    # @param [Fixnum] index An index, 1-indexed (optional).
+    # @return [Fixnum]
+    #
+    
+    def column_count(index = INDEX_OFFSET)
+      assert_exists
+      @object.getRow(index - INDEX_OFFSET).getCells.length
+    end
+
+    #
+    # Returns the text of each cell in the the table as a two-dimensional array.
+    # @return [Array<Array<String>>]
+    #
+    
+    def to_a
+      assert_exists
+      # @object.getRows.map do |table_row|
+      #   table_row.getCells.map { |td| td.asText.strip }
+      # end
+      rows.map do |table_row|
+        table_row.map { |td| td.text }
+      end
+    end
+
+    def column_values(column_number)
+      (1..row_count).map { |index| self[index][column_number].text }
+    end
+
+    def row_values(row_number)
+      (1..column_count(row_number)).map { |index| self[row_number][index].text }
+    end
+
+  end # Table
+end # Celerity

data/lib/celerity/elements/table_cell.rb

@@ -1,16 +1,17 @@
 module Celerity
-  
+
   class TableCell < Element
     include Celerity::Exception
+    include ClickableElement
     include Container
 
     TAGS = [ Identifier.new('td') ]
-    ATTRIBUTES = BASE_ATTRIBUTES | CELLHALIGN_ATTRIBUTES | CELLVALIGN_ATTRIBUTES |
-                         [:abbr, :axis, :headers, :scope, :rowspan, :colspan] 
-                                
+    ATTRIBUTES = BASE_ATTRIBUTES | CELLHALIGN_ATTRIBUTES |
+                 CELLVALIGN_ATTRIBUTES | [:abbr, :axis, :headers, :scope, :rowspan, :colspan]
+
     DEFAULT_HOW = :id
-    
-    alias_method :to_s, :text
+
+    alias_method :to_s, :text # why?
 
     def colspan
       assert_exists
@@ -19,4 +20,10 @@ module Celerity
     end
 
   end
+
+  #-- needs code review regarding attributes/correctness of this
+  class Th < TableCell
+    TAGS = [ Identifier.new('th')]
+  end
+
 end

data/lib/celerity/elements/{table_body.rb → table_elements.rb}

@@ -1,30 +1,42 @@
 module Celerity
-  class TableBody < Element
-    include Enumerable # specs for this? 
-    
-    TAGS = [ Identifier.new('tbody') ]
+  class TableElement < Element
+    include Enumerable
+    include ClickableElement
+
     ATTRIBUTES = BASE_ATTRIBUTES | CELLHALIGN_ATTRIBUTES | CELLVALIGN_ATTRIBUTES
     DEFAULT_HOW = :id
 
     def locate
       super
-      @rows = @object.getRows if @object 
+      @rows = @object.getRows if @object
     end
 
     def [](index)
       assert_exists
-      TableRow.new(self, :object, @rows[index-1])
+      TableRow.new(self, :object, @rows[index - INDEX_OFFSET])
     end
 
     def length
       assert_exists
       @object.getRows.length
     end
-    
+
     def each
       assert_exists
       @rows.each { |row| yield TableRow.new(self, :object, row) }
     end
+  end
+
+  class TableBody < TableElement
+    TAGS = [ Identifier.new('tbody') ]
+  end
 
+  class TableFooter < TableElement
+    TAGS = [ Identifier.new('tfoot') ]
   end
-end
+
+  class TableHeader < TableElement
+    TAGS = [ Identifier.new('thead') ]
+  end
+
+end