Plato on Github

src/web/tag.js

Maintainability

77.75

Lines of code

391

Created with Raphaël 2.1.002550751002019-3-122018-12-32018-8-22018-5-92018-4-32018-2-282017-12-212017-11-12017-6-7

2019-10-30
Maintainability: 77.75

Created with Raphaël 2.1.001002003004002019-3-122018-12-32018-8-22018-5-92018-4-32018-2-282017-12-212017-11-12017-6-7

2019-10-30
Lines of Code: 391

Difficulty

24.89

Estimated Errors

1.15

Function weight

By Complexity

Created with Raphaël 2.1.0_gpfWebGetNamespace2

By SLOC

Created with Raphaël 2.1.0_gpfWebTagCreateFunction14
1
/**
2
 * @file Tag generation helper
3
 * @since 0.2.1
4
 */
5
/*#ifndef(UMD)*/
6
"use strict";
7
/*global _gpfArraySlice*/ // [].slice.call
8
/*global _gpfDefine*/ // Shortcut for gpf.define
9
/*global _gpfErrorDeclare*/ // Declare new gpf.Error names
10
/*global _gpfIsArray*/ // Return true if the parameter is an array
11
/*global _gpfIsLiteralObject*/ // Check if the parameter is a literal object
12
/*global _gpfObjectForEach*/ // Similar to [].forEach but for objects
13
/*global _gpfStringEscapeForHtml*/ // String escape for Html
14
/*global _gpfSyncReadSourceJSON*/ // Reads a source json file (only in source mode)
15
/*#endif*/
16
 
17
/**
18
 * Tag instance allocated by {@link gpf.typedef.tagFunc}
19
 *
20
 * @class gpf.typedef.Tag
21
 *
22
 * @see gpf.web.createTagFunction
23
 * @since 0.2.1
24
 */
25
 
26
/**
27
 * String conversion
28
 *
29
 * @method gpf.typedef.Tag.prototype.toString
30
 * @return {String} HTML result
31
 *
32
 * @see gpf.web.createTagFunction
33
 * @since 0.2.1
34
 */
35
 
36
/**
37
 * DOM insertion
38
 *
39
 * @method gpf.typedef.Tag.prototype.appendTo
40
 * @param {Object} node DOM parent to append the node to
41
 * @return {Object} Created DOM Node
42
 *
43
 * @see gpf.web.createTagFunction
44
 * @since 0.2.1
45
 */
46
 
47
/**
48
 * Tag generation function child specification.  When string, a text node is created.
49
 *
50
 * @typedef gpf.typedef.tagChild
51
 * @property {String|gpf.typedef.Tag}
52
 *
53
 * @see gpf.web.createTagFunction
54
 * @since 0.2.1
55
 */
56
 
57
/**
58
 * Tag generation function children specification
59
 *
60
 * @typedef gpf.typedef.tagChildren
61
 * @property {gpf.typedef.tagChild|gpf.typedef.tagChild[]}
62
 *
63
 * @see gpf.web.createTagFunction
64
 * @since 0.2.1
65
 */
66
 
67
/**
68
 * Tag generation function, it accepts up to two parameters:
69
 * - When no parameter is passed, an empty node is created
70
 * - If the first parameter is a literal object (see {@link gpf.isLiteralObject}), its properties are used to
71
 *   define the node attributes
72
 * - Otherwise, the second (or first if not a literal object) is used to define children that will be appended to this
73
 *   tag
74
 *
75
 * @callback gpf.typedef.tagFunc
76
 *
77
 * @param {Object|gpf.typedef.tagChildren} [attributes=undefined] When a literal object is passed, it is interpreted
78
 * as an attribute dictionary. The attribute name may contain the xlink namespace prefix.
79
 * @param {gpf.typedef.tagChildren} [children=undefined] List of children
80
 * @return {gpf.typedef.Tag} Tag object
81
 *
82
 * @see gpf.web.createTagFunction
83
 * @since 0.2.1
84
 */
85
 
86
_gpfErrorDeclare("web/tag", {
87
    /**
88
     * ### Summary
89
     *
90
     * Missing node name
91
     *
92
     * ### Description
93
     *
94
     * A tag can't be created if the node name is missing
95
     * @since 0.2.1
96
     */
97
    missingNodeName: "Missing node name",
98
 
99
    /**
100
     * ### Summary
101
     *
102
     * Unknown namespace prefix
103
     *
104
     * ### Description
105
     *
106
     * A prefix has been used prior to be associated with a namespace
107
     * @since 0.2.2
108
     */
109
    unknownNamespacePrefix: "Unknown namespace prefix",
110
 
111
    /**
112
     * ### Summary
113
     *
114
     * Unable to use namespace in string
115
     *
116
     * ### Description
117
     *
118
     * A prefix associated to a namespace has been used and can't be converted to string
119
     * @since 0.2.2
120
     */
121
    unableToUseNamespaceInString: "Unable to use namespace in string"
122
});
123
 
124
/**
125
 * Mapping of attribute name aliases
126
 * @type {Object}
127
 * @since 0.2.1
128
 */
129
var _gpfWebTagAttributeAliases = _gpfSyncReadSourceJSON("web/attributes.json");
130
 
131
/**
132
 * Mapping of prefixes for namespaces
133
 * @type {Object}
134
 * @since 0.2.2
135
 */
136
var _gpfWebNamespacePrefix = _gpfSyncReadSourceJSON("web/namespaces.json");
137
 
138
/**
139
 * Retrieves namespace associated to the prefix or fail
140
 *
141
 * @param {String} prefix Namespace prefix
142
 * @return {String} Namespace URI
143
 * @throws {gpf.Error.UnknownNamespacePrefix}
144
 * @since 0.2.2
145
 */
146
function _gpfWebGetNamespace (prefix) {
147
    var namespace = _gpfWebNamespacePrefix[prefix];
148
    if (undefined === namespace) {
149
        gpf.Error.unknownNamespacePrefix();
150
    }
151
    return namespace;
152
}
153
 
154
/**
155
 * Resolves prefixed name to namespace and name
156
 *
157
 * @param {String} name Attribute or node name
158
 * @return {{namespace, name}|undefined} Namespace and name in a structure if prefixed, undefined otherwise
159
 * @since 0.2.2
160
 */
161
function _gpfWebGetNamespaceAndName (name) {
162
    var EXPECTED_PARTS_COUNT = 2,
163
        NAMESPACE_PREFIX = 0,
164
        NAME = 1,
165
        parts = name.split(":");
166
    if (parts.length === EXPECTED_PARTS_COUNT) {
167
        return {
168
            namespace: _gpfWebGetNamespace(parts[NAMESPACE_PREFIX]),
169
            name: parts[NAME]
170
        };
171
    }
172
}
173
 
174
/**
175
 * Fails if the name includes namespace prefix
176
 *
177
 * @param {String} name Attribute or node name
178
 * @throws {gpf.Error.UnableToUseNamespaceInString}
179
 * @since 0.2.2
180
 */
181
function _gpfWebCheckNamespaceSafe (name) {
182
    if (name.includes(":")) {
183
        gpf.Error.unableToUseNamespaceInString();
184
    }
185
}
186
 
187
/**
188
 * Resolve attribute name
189
 *
190
 * @param {String} name Attribute name used in the tag function
191
 * @return {String} Attribute to set on the node ele,ment
192
 * @since 0.2.1
193
 */
194
function _gpfWebTagAttributeAlias (name) {
195
    return _gpfWebTagAttributeAliases[name] || name;
196
}
197
 
198
/**
199
 * Apply the callback to each array item,
200
 * process recursively if the array item is an array
201
 *
202
 * @param {Array} array array of items
203
 * @param {Function} callback Function to apply on each array item
204
 * @since 0.2.1
205
 */
206
function _gpfWebTagFlattenChildren (array, callback) {
207
    array.forEach(function (item) {
208
        if (_gpfIsArray(item)) {
209
            _gpfWebTagFlattenChildren(item, callback);
210
        } else {
211
            callback(item);
212
        }
213
    });
214
}
215
 
216
var _GpfWebTag = _gpfDefine({
217
    $class: "gpf.web.Tag",
218
 
219
    /**
220
     * Tag object
221
     *
222
     * @param {String} nodeName Node name
223
     * @param {Object} [attributes] Dictionary of attributes to set
224
     * @param {Array} [children] Children
225
     *
226
     * @constructor gpf.web.Tag
227
     * @private
228
     * @since 0.2.1
229
     */
230
    constructor: function (nodeName, attributes, children) {
231
        this._nodeName = nodeName;
232
        this._attributes = attributes || {};
233
        this._children = children;
234
    },
235
 
236
    /**
237
     * Node name
238
     * @since 0.2.1
239
     */
240
    _nodeName: "",
241
 
242
    /**
243
     * Node attributes
244
     * @since 0.2.1
245
     */
246
    _attributes: {},
247
 
248
    /**
249
     * Node children
250
     * @since 0.2.1
251
     */
252
    _children: [],
253
 
254
    //region toString implementation
255
 
256
    _getAttributesAsString: function () {
257
        return Object.keys(this._attributes).map(function (name) {
258
            _gpfWebCheckNamespaceSafe(name);
259
            return " " + _gpfWebTagAttributeAlias(name)
260
                + "=\"" + _gpfStringEscapeForHtml(this._attributes[name]) + "\"";
261
        }, this).join("");
262
    },
263
 
264
    _getChildrenAsString: function () {
265
        var result = [];
266
        _gpfWebTagFlattenChildren(this._children, function (child) {
267
            result.push(child.toString());
268
        });
269
        return result.join("");
270
    },
271
 
272
    _getClosingString: function () {
273
        if (this._children.length) {
274
            return ">" + this._getChildrenAsString() + "</" + this._nodeName + ">";
275
        }
276
        return "/>";
277
    },
278
 
279
    /**
280
     * Convert the current tag into HTML
281
     *
282
     * @return {String} HTML representation of the tag
283
     * @since 0.2.1
284
     */
285
    toString: function () {
286
        _gpfWebCheckNamespaceSafe(this._nodeName);
287
        return "<" + this._nodeName + this._getAttributesAsString() + this._getClosingString();
288
    },
289
 
290
    //endregion
291
 
292
    //region appendTo implementation
293
 
294
    _createElement: function (node) {
295
        var ownerDocument = node.ownerDocument,
296
            qualified = _gpfWebGetNamespaceAndName(this._nodeName);
297
        if (qualified) {
298
            return ownerDocument.createElementNS(qualified.namespace, qualified.name);
299
        }
300
        return ownerDocument.createElement(this._nodeName);
301
    },
302
 
303
    _setAttributesTo: function (node) {
304
        _gpfObjectForEach(this._attributes, function (value, name) {
305
            var qualified = _gpfWebGetNamespaceAndName(name);
306
            if (qualified) {
307
                node.setAttributeNS(qualified.namespace, _gpfWebTagAttributeAlias(qualified.name), value);
308
            } else {
309
                node.setAttribute(_gpfWebTagAttributeAlias(name), value);
310
            }
311
        });
312
    },
313
 
314
    _appendChildrenTo: function (node) {
315
        var ownerDocument = node.ownerDocument;
316
        _gpfWebTagFlattenChildren(this._children, function (child) {
317
            if (child instanceof _GpfWebTag) {
318
                child.appendTo(node);
319
            } else {
320
                node.appendChild(ownerDocument.createTextNode(child.toString()));
321
            }
322
        });
323
    },
324
 
325
    /**
326
     * Appends the tag to the provided node
327
     *
328
     * @param {Object} node Expected to be a DOM node
329
     * @return {Object} Created node
330
     * @since 0.2.1
331
     */
332
    appendTo: function (node) {
333
        var element = this._createElement(node);
334
        this._setAttributesTo(element);
335
        this._appendChildrenTo(element);
336
        return node.appendChild(element);
337
    }
338
 
339
    //endregion
340
 
341
});
342
 
343
/**
344
 * Create a tag generation function
345
 *
346
 * @param {String} nodeName tag name.
347
 * May include the namespace prefix svg for [SVG elements](https://developer.mozilla.org/en-US/docs/Web/SVG)
348
 * @return {gpf.typedef.tagFunc} The tag generation function
349
 * @gpf:closure
350
 * @since 0.2.1
351
 */
352
function _gpfWebTagCreateFunction (nodeName) {
353
    if (!nodeName) {
354
        gpf.Error.missingNodeName();
355
    }
356
    return function (firstParam) {
357
        var sliceFrom = 0,
358
            attributes;
359
        if (_gpfIsLiteralObject(firstParam)) {
360
            attributes = firstParam;
361
            ++sliceFrom;
362
        }
363
        return new _GpfWebTag(nodeName, attributes, _gpfArraySlice(arguments, sliceFrom));
364
    };
365
}
366
 
367
/**
368
 * @gpf:sameas _gpfWebTagCreateFunction
369
 * @since 0.2.1
370
 *
371
 * @example <caption>Tree building to string</caption>
372
 * var div = gpf.web.createTagFunction("div"),
373
 *     span = gpf.web.createTagFunction("span"),
374
 * tree = div({className: "test1"}, "Hello ", span({className: "test2"}, "World!"));
375
 * // tree.toString() gives <div class="test1">Hello <span class="test2">World!</span></div>
376
 *
377
 * @example <caption>Tree building to DOM</caption>
378
 * var mockNode = mockDocument.createElement("any"),
379
 *     div = gpf.web.createTagFunction("div"),
380
 *     span = gpf.web.createTagFunction("span"),
381
 *     tree = div({className: "test"}, "Hello ", span("World!")),
382
 *     result = tree.appendTo(mockNode);
383
 *
384
 * @example <caption>SVG building</caption>
385
 * var mockNode = mockDocument.createElement("any"),
386
 *     svgImage = gpf.web.createTagFunction("svg:image"),
387
 *     tree = svgImage({x: 0, y: 0, "xlink:href": "test.png"}),
388
 *     result = tree.appendTo(mockNode);
389
 *
390
 */
391
gpf.web.createTagFunction = _gpfWebTagCreateFunction;