module Symbiont
  module Enclosers
    
    # Used to identify a web object as existing within an enclosing object
    # like a frame or an iframe. It is possible to nest by passing in parent
    # enclosers as the second parameter.
    #
    # @param [String] locator how an encloser will be referenced; the
    # only valid locators here are :id, :index, and :name
    # @param encloser a parent encloser that is passed from a previous call
    # @param [optional] block that contains calls to web objects within the
    # encloser
    #
    # @example
    #   within_frame(id: "loginSection") do |encloser|
    #     text_field :username, id: "userName", frame: encloser
    #     button :login, id: "btnSubmit", frame: encloser
    #   end
    def within_frame(locator, encloser=nil, &block)
      encloser = [] if encloser.nil?
      encloser << locator
      block.call(encloser)
    end
    
  end # module: Enclosers
end # module: Symbiont