Debian Codegraph @

closure-library/closure/goog/dom/dataset.js

raw
1 // Copyright 2009 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Utilities for adding, removing and setting values in
17 * an Element's dataset.
18 * See {@link http://www.w3.org/TR/html5/Overview.html#dom-dataset}.
19 *
20 * @author [email protected] (Alex Nicksay)
21 */
22
23 goog.provide('goog.dom.dataset');
24
25 goog.require('goog.labs.userAgent.browser');
26 goog.require('goog.string');
27 goog.require('goog.userAgent.product');
28
29
30 /**
31 * Whether using the dataset property is allowed.
32 *
33 * In IE (up to and including IE 11), setting element.dataset in JS does not
34 * propagate values to CSS, breaking expressions such as
35 * `content: attr(data-content)` that would otherwise work.
36 * See {@link https://github.com/google/closure-library/issues/396}.
37 *
38 * In Safari >= 9, reading from element.dataset sometimes returns
39 * undefined, even though the corresponding data- attribute has a value.
40 * See {@link https://bugs.webkit.org/show_bug.cgi?id=161454}.
41 * @const
42 * @private
43 */
44 goog.dom.dataset.ALLOWED_ =
45 !goog.userAgent.product.IE && !goog.labs.userAgent.browser.isSafari();
46
47
48 /**
49 * The DOM attribute name prefix that must be present for it to be considered
50 * for a dataset.
51 * @type {string}
52 * @const
53 * @private
54 */
55 goog.dom.dataset.PREFIX_ = 'data-';
56
57
58 /**
59 * Returns whether a string is a valid dataset property name.
60 * @param {string} key Property name for the custom data attribute.
61 * @return {boolean} Whether the string is a valid dataset property name.
62 * @private
63 */
64 goog.dom.dataset.isValidProperty_ = function(key) {
65 return !/-[a-z]/.test(key);
66 };
67
68
69 /**
70 * Sets a custom data attribute on an element. The key should be
71 * in camelCase format (e.g "keyName" for the "data-key-name" attribute).
72 * @param {Element} element DOM node to set the custom data attribute on.
73 * @param {string} key Key for the custom data attribute.
74 * @param {string} value Value for the custom data attribute.
75 */
76 goog.dom.dataset.set = function(element, key, value) {
77 if (goog.dom.dataset.ALLOWED_ && element.dataset) {
78 element.dataset[key] = value;
79 } else if (!goog.dom.dataset.isValidProperty_(key)) {
80 throw new Error(
81 goog.DEBUG ? '"' + key + '" is not a valid dataset property name.' :
82 '');
83 } else {
84 element.setAttribute(
85 goog.dom.dataset.PREFIX_ + goog.string.toSelectorCase(key), value);
86 }
87 };
88
89
90 /**
91 * Gets a custom data attribute from an element. The key should be
92 * in camelCase format (e.g "keyName" for the "data-key-name" attribute).
93 * @param {Element} element DOM node to get the custom data attribute from.
94 * @param {string} key Key for the custom data attribute.
95 * @return {?string} The attribute value, if it exists.
96 */
97 goog.dom.dataset.get = function(element, key) {
98 // Edge, unlike other browsers, will do camel-case conversion when retrieving
99 // "dash-case" properties.
100 if (!goog.dom.dataset.isValidProperty_(key)) {
101 return null;
102 }
103 if (goog.dom.dataset.ALLOWED_ && element.dataset) {
104 // Android browser (non-chrome) returns the empty string for
105 // element.dataset['doesNotExist'].
106 if (goog.labs.userAgent.browser.isAndroidBrowser() &&
107 !(key in element.dataset)) {
108 return null;
109 }
110 var value = element.dataset[key];
111 return value === undefined ? null : value;
112 } else {
113 return element.getAttribute(
114 goog.dom.dataset.PREFIX_ + goog.string.toSelectorCase(key));
115 }
116 };
117
118
119 /**
120 * Removes a custom data attribute from an element. The key should be
121 * in camelCase format (e.g "keyName" for the "data-key-name" attribute).
122 * @param {Element} element DOM node to get the custom data attribute from.
123 * @param {string} key Key for the custom data attribute.
124 */
125 goog.dom.dataset.remove = function(element, key) {
126 // Edge, unlike other browsers, will do camel-case conversion when removing
127 // "dash-case" properties.
128 if (!goog.dom.dataset.isValidProperty_(key)) {
129 return;
130 }
131 if (goog.dom.dataset.ALLOWED_ && element.dataset) {
132 // In strict mode Safari will trigger an error when trying to delete a
133 // property which does not exist.
134 if (goog.dom.dataset.has(element, key)) {
135 delete element.dataset[key];
136 }
137 } else {
138 element.removeAttribute(
139 goog.dom.dataset.PREFIX_ + goog.string.toSelectorCase(key));
140 }
141 };
142
143
144 /**
145 * Checks whether custom data attribute exists on an element. The key should be
146 * in camelCase format (e.g "keyName" for the "data-key-name" attribute).
147 *
148 * @param {Element} element DOM node to get the custom data attribute from.
149 * @param {string} key Key for the custom data attribute.
150 * @return {boolean} Whether the attribute exists.
151 */
152 goog.dom.dataset.has = function(element, key) {
153 // Edge, unlike other browsers, will do camel-case conversion when retrieving
154 // "dash-case" properties.
155 if (!goog.dom.dataset.isValidProperty_(key)) {
156 return false;
157 }
158 if (goog.dom.dataset.ALLOWED_ && element.dataset) {
159 return key in element.dataset;
160 } else if (element.hasAttribute) {
161 return element.hasAttribute(
162 goog.dom.dataset.PREFIX_ + goog.string.toSelectorCase(key));
163 } else {
164 return !!(
165 element.getAttribute(
166 goog.dom.dataset.PREFIX_ + goog.string.toSelectorCase(key)));
167 }
168 };
169
170
171 /**
172 * Gets all custom data attributes as a string map. The attribute names will be
173 * camel cased (e.g., data-foo-bar -> dataset['fooBar']). This operation is not
174 * safe for attributes having camel-cased names clashing with already existing
175 * properties (e.g., data-to-string -> dataset['toString']).
176 * @param {!Element} element DOM node to get the data attributes from.
177 * @return {!Object} The string map containing data attributes and their
178 * respective values.
179 */
180 goog.dom.dataset.getAll = function(element) {
181 if (goog.dom.dataset.ALLOWED_ && element.dataset) {
182 return element.dataset;
183 } else {
184 var dataset = {};
185 var attributes = element.attributes;
186 for (var i = 0; i < attributes.length; ++i) {
187 var attribute = attributes[i];
188 if (goog.string.startsWith(attribute.name, goog.dom.dataset.PREFIX_)) {
189 // We use substr(5), since it's faster than replacing 'data-' with ''.
190 var key = goog.string.toCamelCase(attribute.name.substr(5));
191 dataset[key] = attribute.value;
192 }
193 }
194 return dataset;
195 }
196 };