1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Atoms for frame handling.
20
 *
21
 */
22

23

24
goog.provide('bot.frame');
25

26
goog.require('bot');
27
goog.require('bot.Error');
28
goog.require('bot.ErrorCode');
29
goog.require('bot.dom');
30
goog.require('bot.locators');
31
goog.require('goog.dom');
32
goog.require('goog.dom.TagName');
33

34

35
/**
36
 * @return {!Window} The top window.
37
 */
38
bot.frame.defaultContent = function () {
39
  return bot.getWindow().top;
40
};
41

42

43
/**
44
 * @return {!Element} The currently active element.
45
 */
46
bot.frame.activeElement = function () {
47
  return document.activeElement || document.body;
48
};
49

50

51
/**
52
 * Gets the parent frame of the specified frame.
53
 *
54
 * @param {!Window=} opt_root The window get the parent of.
55
 *     Defaults to `bot.getWindow()`.
56
 * @return {!Window} The frame if found, self otherwise.
57
 */
58
bot.frame.parentFrame = function (opt_root) {
59
  var domWindow = opt_root || bot.getWindow();
60
  return domWindow.parent;
61
};
62

63

64
/**
65
 * Returns a reference to the window object corresponding to the given element.
66
 * Note that the element must be a frame or an iframe.
67
 *
68
 * @param {!(HTMLIFrameElement|HTMLFrameElement)} element The iframe or frame
69
 *     element.
70
 * @return {Window} The window reference for the given iframe or frame element.
71
 */
72
bot.frame.getFrameWindow = function (element) {
73
  if (bot.frame.isFrame_(element)) {
74
    var frame = /** @type {HTMLFrameElement|HTMLIFrameElement} */ (element);
75
    return goog.dom.getFrameContentWindow(frame);
76
  }
77
  throw new bot.Error(bot.ErrorCode.NO_SUCH_FRAME,
78
    "The given element isn't a frame or an iframe.");
79
};
80

81

82
/**
83
 * Returns whether an element is a frame (or iframe).
84
 *
85
 * @param {!Element} element The element to check.
86
 * @return {boolean} Whether the element is a frame (or iframe).
87
 * @private
88
 */
89
bot.frame.isFrame_ = function (element) {
90
  return bot.dom.isElement(element, goog.dom.TagName.FRAME) ||
91
    bot.dom.isElement(element, goog.dom.TagName.IFRAME);
92
};
93

94

95
/**
96
 * Looks for a frame by its name or id (preferring name over id)
97
 * under the given root. If no frame was found, we look for an
98
 * iframe by name or id.
99
 *
100
 * @param {(string|number)} nameOrId The frame's name, the frame's id, or the
101
 *     index of the frame in the containing window.
102
 * @param {!Window=} opt_root The window to perform the search under.
103
 *     Defaults to `bot.getWindow()`.
104
 * @return {Window} The window if found, null otherwise.
105
 */
106
bot.frame.findFrameByNameOrId = function (nameOrId, opt_root) {
107
  var domWindow = opt_root || bot.getWindow();
108

109
  // Lookup frame by name
110
  var numFrames = domWindow.frames.length;
111
  for (var i = 0; i < numFrames; i++) {
112
    var frame = domWindow.frames[i];
113
    var frameElement = frame.frameElement || frame;
114
    if (frameElement.name == nameOrId) {
115
      // This is needed because Safari 4 returns
116
      // an HTMLFrameElement instead of a Window object.
117
      if (frame.document) {
118
        return frame;
119
      } else {
120
        return goog.dom.getFrameContentWindow(frame);
121
      }
122
    }
123
  }
124

125
  // Lookup frame by id
126
  var elements = bot.locators.findElements({ id: nameOrId }, domWindow.document);
127
  for (var i = 0; i < elements.length; i++) {
128
    var frameElement = elements[i];
129
    if (frameElement && bot.frame.isFrame_(frameElement)) {
130
      return goog.dom.getFrameContentWindow(frameElement);
131
    }
132
  }
133
  return null;
134
};
135

136

137
/**
138
 * Looks for a frame by its index under the given root.
139
 *
140
 * @param {number} index The frame's index.
141
 * @param {!Window=} opt_root The window to perform
142
 *     the search under. Defaults to `bot.getWindow()`.
143
 * @return {Window} The frame if found, null otherwise.
144
 */
145
bot.frame.findFrameByIndex = function (index, opt_root) {
146
  var domWindow = opt_root || bot.getWindow();
147
  return domWindow.frames[index] || null;
148
};
149

150

151
/**
152
 * Gets the index of a frame in the given window. Note that the element must
153
 * be a frame or an iframe.
154
 *
155
 * @param {!(HTMLIFrameElement|HTMLFrameElement)} element The iframe or frame
156
 *     element.
157
 * @param {!Window=} opt_root The window to perform the search under. Defaults
158
 *     to `bot.getWindow()`.
159
 * @return {?number} The index of the frame if found, null otherwise.
160
 */
161
bot.frame.getFrameIndex = function (element, opt_root) {
162
  try {
163
    var elementWindow = element.contentWindow;
164
  } catch (e) {
165
    // Happens in IE{7,8} if a frame doesn't have an enclosing frameset.
166
    return null;
167
  }
168

169
  if (!bot.frame.isFrame_(element)) {
170
    return null;
171
  }
172

173
  var domWindow = opt_root || bot.getWindow();
174
  for (var i = 0; i < domWindow.frames.length; i++) {
175
    if (elementWindow == domWindow.frames[i]) {
176
      return i;
177
    }
178
  }
179
  return null;
180
};
181

182