site_prism 1.1.1 → 1.2

data/README.md

@@ -917,20 +917,112 @@ end
 @results_page.wait_for_search_results(10) #=> waits for 10 seconds instead of the default capybara timeout
 ```
 
+## IFrames
+
+SitePrism allows you to interact with iframes. An iframe is declared as
+a `SitePrism::Page` class, and then referenced by the page or section it
+is embeded into. Like a section, it is possible to test for the
+existence of the iframe, wait for it to exist as well as interact with
+the page it contains.
+
+### Creating an iframe
+
+An iframe is declared in the same way as a Page:
+
+```ruby
+class MyIframe < SitePrism::Page
+  element :some_text_field, "input.username"
+end
+```
+
+To expose the iframe, reference it from another page or class using the `iframe`
+method. The `iframe` method takes 3 arguments; the name by which you
+would like to reference the iframe, the page class that represents the
+iframe, and an ID by which you can locate the iframe. For example:
+
+```ruby
+class PageContainingIframe < SitePrism::Page
+  iframe :my_iframe, MyIframe, "#my_iframe_id"
+end
+```
+
+NB: An iframe can only be referenced by its ID. This is a limitation
+imposed by Capybara. The third argument to the `iframe` method must
+contain a selector that will locate the iframe node, and the portion of
+the selector that locates the iframe node must use the iframe node's ID.
+
+### Testing for an iframe's existence
+
+Like an element or section, it is possible to test for an iframe's
+existence using the auto-generated `has_<iframe_name>?` method. Using
+the above example, here's how it's done:
+
+```ruby
+@page = PageContainingIframe.new
+# ...
+@page.has_my_iframe? #=> true
+@page.should have_my_iframe
+```
+
+### Waiting for an iframe
+
+Like an element or section, it is possible to wait for an iframe to
+exist by using the `wait_for_<iframe_name>` method. For example:
+
+```ruby
+@page = PageContainingIframe.new
+# ...
+@page.wait_for_my_iframe
+```
+
+### Interacting with an iframe's contents:
+
+Since an iframe contains a fully fledged SitePrism::Page, you are able
+to interact with the elements and sections defined within it. Due to
+capybara internals it is necessary to pass a block to the iframe instead
+of simply calling methods on it; the block argument is the
+SitePrism::Page that represents the iframe's contents. For example:
+
+```ruby
+# SitePrism::Page representing the iframe
+class Login < SitePrism::Page
+  element :username "input.username"
+  element :password "input.password"
+end
+
+# SitePrism::Page representing the page that contains the iframe
+class Home < SitePrism::Page
+  set_url "http://www.example.com"
+
+  iframe, :login_area, Login, "#login_and_registration"
+end
+
+# cucumber step that performs login
+When /^I log in$/ do
+  @home = Home.new
+  @home.load
+
+  @home.login_area do |frame|
+    #`frame` is an instance of the `Login` class
+    frame.username.set "admin"
+    frame.password.set "p4ssword"
+  end
+end
+```
 
 # Epilogue
 
 So, we've seen how to use SitePrism to put together page objects made up
-of pages, elements and sections. But how to organise this stuff? There
+of pages, elements, sections and iframes. But how to organise this stuff? There
 are a few ways of saving yourself having to create instances of pages
 all over the place. Here's an example of this common problem:
 
 ```ruby
-@home = Home.new
+@home = Home.new # <-- noise
 @home.load
 @home.search_field.set "Sausages"
 @home.search_field.search_button.click
-@results_page = SearchResults.new
+@results_page = SearchResults.new # <-- noise
 @results_page.should have_search_result_items
 ```
 

data/lib/site_prism/element_container.rb

@@ -2,9 +2,7 @@ module SitePrism::ElementContainer
 
   def element element_name, element_locator = nil
     if element_locator.nil?
-      define_method element_name.to_s do
-        raise SitePrism::NoLocatorForElement.new("#{self.class.name} => :#{element_name} needs a locator")
-      end
+      create_no_locator element_name
     else
       add_element_name element_name.to_s
       define_method element_name.to_s do
@@ -17,9 +15,7 @@ module SitePrism::ElementContainer
 
   def elements collection_name, collection_locator = nil
     if collection_locator.nil?
-      define_method collection_name.to_s do
-        raise SitePrism::NoLocatorForElement.new("#{self.class.name} => :#{element_name} needs a locator")
-      end
+      create_no_locator collection_name
     else
       add_element_name collection_name
       define_method collection_name.to_s do
@@ -51,6 +47,17 @@ module SitePrism::ElementContainer
     end
   end
 
+  def iframe iframe_name, iframe_page_class, iframe_id
+    add_element_name iframe_name
+    create_existence_checker iframe_name, iframe_id
+    create_waiter iframe_name, iframe_id
+    define_method iframe_name do |&block|
+      within_frame iframe_id.split("#").last do
+        block.call iframe_page_class.new
+      end
+    end
+  end
+
   def add_element_name element_name
     @element_names ||= []
     @element_names << element_name
@@ -65,9 +72,7 @@ module SitePrism::ElementContainer
   def create_existence_checker element_name, element_locator
     method_name = "has_#{element_name.to_s}?"
     if element_locator.nil?
-      define_method method_name do
-        raise SitePrism::NoLocatorForElement.new("#{self.class.name} => :#{element_name} needs a locator")
-      end
+      create_no_locator element_name, method_name
     else
       define_method method_name do
         Capybara.using_wait_time 0 do
@@ -80,11 +85,9 @@ module SitePrism::ElementContainer
   def create_waiter element_name, element_locator
     method_name = "wait_for_#{element_name.to_s}"
     if element_locator.nil?
-      define_method method_name do
-        raise SitePrism::NoLocatorForElement.new("#{self.class.name} => :#{element_name} needs a locator")
-      end
+      create_no_locator element_name, method_name
     else
-      define_method method_name do |*args|
+      define_method method_name do |*args| #used to use block args, but they don't work under ruby 1.8 :(
         timeout = args.shift || Capybara.default_wait_time
         Capybara.using_wait_time timeout do
           element_waiter element_locator
@@ -92,5 +95,12 @@ module SitePrism::ElementContainer
       end
     end
   end
+
+  def create_no_locator element_name, method_name = nil
+    no_locator_method_name = method_name.nil? ? element_name : method_name
+    define_method no_locator_method_name do
+      raise SitePrism::NoLocatorForElement.new("#{self.class.name} => :#{element_name} needs a locator")
+    end
+  end
 end
 

data/lib/site_prism/version.rb

@@ -1,4 +1,4 @@
 module SitePrism
-  VERSION = "1.1.1"
+  VERSION = "1.2"
 end
 

metadata

@@ -1,8 +1,11 @@
 --- !ruby/object:Gem::Specification 
 name: site_prism
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 1.1.1
+  prerelease: false
+  segments: 
+  - 1
+  - 2
+  version: "1.2"
 platform: ruby
 authors: 
 - Nat Ritmeyer
@@ -10,16 +13,20 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-06-17 00:00:00 Z
+date: 2012-07-02 00:00:00 +01:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: capybara
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        - 1
         version: 1.1.1
   type: :runtime
   version_requirements: *id001
@@ -27,10 +34,13 @@ dependencies:
   name: rspec
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 0
         version: 2.0.0
   type: :runtime
   version_requirements: *id002
@@ -53,6 +63,7 @@ files:
 - lib/site_prism.rb
 - LICENSE
 - README.md
+has_rdoc: true
 homepage: http://github.com/natritmeyer/site_prism
 licenses: []
 
@@ -62,24 +73,25 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: A Page Object Model DSL for Capybara
 test_files: []
 
-has_rdoc: