Class: Parfait::Region

Inherits:
ParfaitArtifact show all
Defined in:
lib/parfait/region.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from ParfaitArtifact

#add_check, #add_generic_present, #add_present, #check, #is_present_defined?, #present, #verify_presence

Constructor Details

#initialize(opts = {}) ⇒ Region

Create a new region object

Regions use filters to reduce the scope of HTML that their child elements (Controls or other Regions) need to consider. This allows for easier management of repeated controls on a page.

For instance, assume the Region’s parent is a Page and that page contains a list of users, each with an “Edit” link next to them.

Defining a Region would allow any child controls to look specifically at a single user, by userid, perhaps. Then a child control can be created to select “Edit” for the chosen userid.

Options

name

the name used to identify this region

aliases

specifies an array of aliases for the region

parent

specifies the parent object (Region or Page) of this control

Example

# Define the application
mybrowser = Watir::Browser.new()
myapp = Parfait::Application.new(
  :name => "Blog",
  :browser => mybrowser
)

# Define the page
mypage = Parfait::Page.new(
  :name => "User List"
)
myapp.add_page(mypage)

# Define the region
myregion = Parfait::Region.new(
  :name => "User",
  :parent => mypage
)



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/parfait/region.rb', line 47

def initialize(opts = {})
  o = {
    :name => nil,
    :aliases => [],
    :parent => nil
  }.merge(opts)
  @name = o[:name]
  @aliases = o[:aliases]
  @parent = o[:parent]

  @controls = Hash.new
  @regions = Hash.new
  @pages = Hash.new

  if @name
    unless @name.is_a?(String)
      raise "Name must be a String when adding a region"
    end
  else
    raise "Name must be specified when adding a region"
  end
  if @aliases
    unless @aliases.is_a?(Array)
      raise "Parfait::Region requires aliases to be an array"
    end
    @aliases.each do |my_alias|
      raise "Parfait::Region requires each alias in the array to be a string" unless my_alias.is_a?(String)
    end
  end

  if @parent
    if @parent.is_a? Parfait::Page
      add_to_page(@parent)
    else
      if @parent.is_a? Parfait::Region
        add_to_region(@parent)
      else
        raise "Parent specified for Region \"#{@name}\", but parent object type unrecognized."
      end
    end
  end

  super
end

Instance Attribute Details

#aliases ⇒ Object (readonly)

Returns the value of attribute aliases.



5
6
7
 
# File 'lib/parfait/region.rb', line 5

def aliases
  @aliases
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



5
6
7
 
# File 'lib/parfait/region.rb', line 5

def name
  @name
end

Instance Method Details

#add_control(control) ⇒ Object

Add a Control to the current Region

Options

control

specifies the Control object to be added

Example

region = Parfait::Region.new(
  :name => "Prescription List" 
)
control = Parfait::Control.new(
  :name => "Edit Prescription"
)
region.add_control(control)



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/parfait/region.rb', line 301

def add_control(control)

  if control
    if control.is_a?(Parfait::Control)
      @controls[control.name] = control
      if control.aliases
        control.aliases.each do |my_alias|
          @controls[my_alias] = control
        end
      end
    else
      raise "Control must be a Parfait::Control when being adding to a Region"
    end
  else
    raise "Control must be specified when adding a Control to an Region"
  end
  self
end

#add_filter(&block) ⇒ Object

Set the filter for this Region to use.

When a child of this Region is invoked, the Region will use this filter to zoom in on a subset of the parent element’s HTML in order to reduce the scope of HTML that the child needs to consider.

The defined filter should alter the Thread.current[:parfait_region] value.

Options

block

specifies the block of code that will reduce the scope of HTML by updating Thread.current[:parfait_region]. The block should take a single parameter indicating data unique to the filtered region. For example, in a list of users, the block parameter could be a user ID.

Example

# Define the application
mybrowser = Watir::Browser.new()
myapp = Parfait::Application.new(
  :name => "Blog",
  :browser => mybrowser
)

# Define the page
mypage = Parfait::Page.new(
  :name => "User List"
)
mybrowser.add_page(mypage)

# Define the region
myregion = Parfait::Region.new(
  :name => "User"
)

# Set the filter for this region to look specifically at user ID
myregion.add_filter { |userid|
  Thread.current[:parfait_region] =  Thread.current[:parfait_region].div(:id => "userlist").div(:text => /#{userid}/)
}
mypage.add_region(myregion)

# Use the Region to focus on the entry for User "jrotter"
myapp.page("User List").region("User" => "jrotter")



197
198
199
 
# File 'lib/parfait/region.rb', line 197

def add_filter(&block)
  @filter_method = block
end

#add_region(region) ⇒ Object

Add a Region to the current Region

Options

region

specifies the Region object to be added

Example

region1 = Parfait::Region.new(
  :name => "User List"
)
page.add_region(region1)
region2 = Parfait::Region.new(
  :name => "User Roles"
)
region1.add_region(region2)



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/parfait/region.rb', line 234

def add_region(region)

  if region
    if region.is_a?(Parfait::Region)
      @regions[region.name] = region
      if region.aliases
        region.aliases.each do |my_alias|
          @regions[my_alias] = region
        end
      end
    else
      raise "Region must be a Parfait::Region when being added to another Region"
    end
  else
    raise "Region must be specified when adding a Region to another Region"
  end
  self
end

#add_to_page(page) ⇒ Object

Add this Region to a Page

Options

page

specifies a Parfait::Page object to add this Region to

Example

mypage = Parfait::Page.new(
  :name => "Edit User",
  :aliases => ["User Edit"]
)
region.add_to_page(mypage)



107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/parfait/region.rb', line 107

def add_to_page(page)

  if page
    case
    when page.is_a?(Parfait::Page)
      page.add_region(self)
    else
      raise "Input value must be a Page object when adding this Region to a Page"
    end
  else
    raise "Input value cannot be nil when adding this Region to a Page"
  end
  self
end

#add_to_region(region) ⇒ Object

Add this Region to a Region

Options

region

specifies a Parfait::Region object to add this Region to

Example

existing_region = Parfait::Region.new(
  :name => "User"
)
new_region = Parfait::Region.new(
  :name => "Roles"
)
new_region.add_to_region(existing_region)



139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/parfait/region.rb', line 139

def add_to_region(region)

  if region
    case
    when region.is_a?(Parfait::Region)
      region.add_region(self)
    else
      raise "Input value must be a Region object when adding this Region to another Region"
    end
  else
    raise "Input value cannot be nil when adding this Region to another Region"
  end
  self
end

#control(requested_name) ⇒ Object

Retrieve a Control object by name or alias.

Under the covers, if there is an existence directive defined for this control, it will be run on the current browser to confirm that it is indeed present.

Options

name

specifies the name or alias of the control

Example

myregion.control("User ID")



335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/parfait/region.rb', line 335

def control(requested_name)
  control = @controls[requested_name] 
  if control
    # Confirm that we are in the expected region
    verify_presence "Cannot navigate to control \"#{requested_name}\" because region presence check failed"


    return control
  else
    raise "Invalid control name requested: \"#{requested_name}\""
  end
end

#filter(param) ⇒ Object

Call the filter for this region

Options

param

specifies the parameter to use when applying the filter for this region

Example

region.filter("patches.ohoulihan")



212
213
214
 
# File 'lib/parfait/region.rb', line 212

def filter(param)
   @filter_method.call(param)
end

#region(opts = {}) ⇒ Object

Retrieve a Region object by name or alias.

Under the covers, if there is an existence directive defined for this region, it will be run on the current browser to confirm that it is indeed present.

Options

name

specifies the name or alias of the region

Example

myregion.region("User List" => username)



268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/parfait/region.rb', line 268

def region(opts = {})
  region = @regions[opts.first[0]] 
  if region

    # Confirm that we are in the expected region
    verify_presence "Cannot navigate to region \"#{opts.first[0]}\" because region presence check failed"

    # Apply the filter method
    region.filter(opts.first[1])

    return region
  else
    raise "Invalid region name requested: \"#{opts.first[0]}\""
  end
end