Introduced more suitable function names. Deprecated old function names....

Introduced more suitable function names. Deprecated old function names. Documented public functions.

javascript/src/FieldTemplate.js

@@ -11,7 +11,32 @@ var QfqNS = QfqNS || {};
 (function (n) {
     'use strict';
 
+    /**
+     * @name addFields
+     * @function
+     * @global
+     * @deprecated use appendTemplate().
+     *
+     */
     n.addFields = function (templateSelector, targetSelector, maxLines) {
+        n.appendTemplate(templateSelector, targetSelector, maxLines);
+    };
+
+    /**
+     * Append a child created from a template to a target. All occurrences of `%d` in attribute values will be replaced
+     * by the number of children of target.
+     *
+     * @name appendTemplate
+     * @public
+     * @global
+     * @function
+     *
+     * @param {string} templateSelector jQuery selector uniquely identifying the template.
+     * @param {string} targetSelector jQuery selector uniquely identifying the target container.
+     * @param {number} maxChildren do not allow more than `maxChildren` of children in target.
+     *
+     */
+    n.appendTemplate = function (templateSelector, targetSelector, maxChildren) {
         var escapedTemplateSelector = n.escapeJqueryIdSelector(templateSelector);
         var escapedTargetSelector = n.escapeJqueryIdSelector(targetSelector);
 
@@ -21,7 +46,7 @@ var QfqNS = QfqNS || {};
 
         var lines = n.countLines(escapedTargetSelector);
 
-        if (lines >= maxLines) {
+        if (lines >= maxChildren) {
             return;
         }
 
@@ -31,7 +56,30 @@ var QfqNS = QfqNS || {};
         $target.append(deserializedTemplate);
     };
 
+    /**
+     * @name initializeFields
+     * @global
+     * @function
+     * @deprecated use initializeTemplateTarget()
+     */
     n.initializeFields = function (element, templateSelectorData) {
+        n.initializeTemplateTarget(element, templateSelectorData);
+    };
+
+    /**
+     * When the template target contains no children, it initializes the target element by appending the first child
+     * created from the template.
+     *
+     * @name initializeTemplateTarget
+     * @global
+     * @function
+     *
+     * @param {HTMLElement} element the target HTMLElement to be initialized
+     * @param {string} [templateSelectorData=qfq-line-template] name of the `data-` attribute containing the jQuery
+     * selector
+     * selecting the template
+     */
+    n.initializeTemplateTarget = function (element, templateSelectorData) {
         var $element = $(element);
         var templateSelector, escapedTemplateSelector, $template, deserializedTemplate;
 
@@ -52,8 +100,27 @@ var QfqNS = QfqNS || {};
         $element.append(deserializedTemplate);
     };
 
+    /**
+     * @name removeFields
+     * @global
+     * @function
+     * @deprecated use removeThisChild()
+     */
     n.removeFields = function (target) {
-        var $line = $(target).closest('.qfq-line');
+        n.removeThisChild(target);
+    };
+
+    /**
+     * Remove the element having a class `qfq-line`. Uses `eventTarget` as start point for determining the closest
+     * element.
+     *
+     * @name removeFields
+     * @global
+     * @function
+     * @param {HTMLElement} eventTarget start point for determining the closest `.qfq-line`.
+     */
+    n.removeThisChild = function (eventTarget) {
+        var $line = $(eventTarget).closest('.qfq-line');
         var $container = $line.parent();
         $line.remove();
 
@@ -61,8 +128,11 @@ var QfqNS = QfqNS || {};
     };
 
     /**
+     * Takes a template as string and deserializes it into DOM. Any attributes having a value containing `%d` will be
+     *
      * @private
      * @param template
+     *
      */
     n.deserializeTemplateAndRetainPlaceholders = function (template) {
         var $deserializedTemplate = $(template);