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
goog.provide('bot.locators.className');
19

20
goog.require('bot.Error');
21
goog.require('bot.ErrorCode');
22
goog.require('goog.dom');
23
goog.require('goog.string');
24

25

26
/**
27
 * Tests whether the standardized W3C Selectors API are available on an
28
 * element.
29
 * @param {!(Document|Element)} root The document or element to test for CSS
30
 *     selector support.
31
 * @return {boolean} Whether or not the root supports query selector APIs.
32
 * @see http://www.w3.org/TR/selectors-api/
33
 * @private
34
 */
35
bot.locators.className.canUseQuerySelector_ = function (root) {
36
  return !!(root.querySelectorAll && root.querySelector);
37
};
38

39

40
/**
41
 * Find an element by its class name.
42
 * @param {string} target The class name to search for.
43
 * @param {!(Document|Element)} root The document or element to perform the
44
 *     search under.
45
 * @return {Element} The first matching element found in the DOM, or null if no
46
 *     such element could be found.
47
 */
48
bot.locators.className.single = function (target, root) {
49
  if (!target) {
50
    throw new bot.Error(bot.ErrorCode.INVALID_SELECTOR_ERROR,
51
      'No class name specified');
52
  }
53

54
  target = goog.string.trim(target);
55
  if (target.indexOf(' ') !== -1) {
56
    throw new bot.Error(bot.ErrorCode.INVALID_SELECTOR_ERROR,
57
      'Compound class names not permitted');
58
  }
59

60
  // Closure will not properly escape class names that contain a '.' when using
61
  // the native selectors API, so we have to handle this ourselves.
62
  if (bot.locators.className.canUseQuerySelector_(root)) {
63
    try {
64
      return root.querySelector('.' + target.replace(/\./g, '\\.')) || null;
65
    } catch (e) {
66
      throw new bot.Error(bot.ErrorCode.INVALID_SELECTOR_ERROR,
67
        'An invalid or illegal class name was specified');
68
    }
69
  }
70
  var elements = goog.dom.getDomHelper(root).getElementsByTagNameAndClass(
71
      /*tagName=*/'*', /*className=*/target, root);
72
  return elements.length ? elements[0] : null;
73
};
74

75

76
/**
77
 * Find an element by its class name.
78
 * @param {string} target The class name to search for.
79
 * @param {!(Document|Element)} root The document or element to perform the
80
 *     search under.
81
 * @return {!IArrayLike} All matching elements, or an empty list.
82
 */
83
bot.locators.className.many = function (target, root) {
84
  if (!target) {
85
    throw new bot.Error(bot.ErrorCode.INVALID_SELECTOR_ERROR,
86
      'No class name specified');
87
  }
88

89
  target = goog.string.trim(target);
90
  if (target.indexOf(' ') !== -1) {
91
    throw new bot.Error(bot.ErrorCode.INVALID_SELECTOR_ERROR,
92
      'Compound class names not permitted');
93
  }
94

95
  // Closure will not properly escape class names that contain a '.' when using
96
  // the native selectors API, so we have to handle this ourselves.
97
  if (bot.locators.className.canUseQuerySelector_(root)) {
98
    try {
99
      return root.querySelectorAll('.' + target.replace(/\./g, '\\.'));
100
    } catch (e) {
101
      throw new bot.Error(bot.ErrorCode.INVALID_SELECTOR_ERROR,
102
        'An invalid or illegal class name was specified');
103
    }
104
  }
105
  return goog.dom.getDomHelper(root).getElementsByTagNameAndClass(
106
      /*tagName=*/'*', /*className=*/target, root);
107
};
108

109