Merge remote-tracking branch 'origin/master'

javascript/src/BSTabs.js

@@ -21,7 +21,7 @@ var QfqNS = QfqNS || {};
     /**
      * Tab Constructor.
      *
-     * Programatically access Bootstrap nav-tabs.
+     * Programmatically access Bootstrap nav-tabs.
      *
      * @param {string} tabId HTML id of the element having `nav` and `nav-tabs` classes
      * @constructor

javascript/src/CharacterCount.js

@@ -12,6 +12,31 @@ var QfqNS = QfqNS || {};
 
     n.CharacterCount = {};
 
+    /**
+     * Initialize character count.
+     *
+     * Character count keeps track of characters in `<input>` and `<textarea>` elements (tracked elements). By default,
+     * all elements having the `qfq-character-count` class are initialized. When non-`<input>/<textarea>` elements are
+     * encountered during initialization, the behavior is undefined.
+     *
+     * Each element eligible for character count must provide a `data-character-count-id` attribute holding the element
+     * id of the element receiving the character count. The receiving element's text is replaced by the current number
+     * of characters of the tracked element. The number of characters in a tracked element is updated in the receiving
+     * element upon a `change` or `keyup` event.
+     *
+     * If the `maxlength` attribute is present on the tracked element, the receiving element will display
+     *
+     *     N/<maxlength>
+     *
+     * where `N` is the current number of characters of the tracked element. If `maxlength` is not present, the
+     * receiving element will display
+     *
+     *     N/∞
+     *
+     * where `N` is the current number of characters of the tracked element.
+     *
+     * @param selector {string} optional selector. Defaults to `.qfq-character-count`.
+     */
     n.CharacterCount.initialize = function (selector) {
         selector = selector || ".qfq-character-count";
         $(selector).each(function () {

javascript/src/Element/Checkbox.js

@@ -20,8 +20,8 @@ QfqNS.Element = QfqNS.Element || {};
 (function (n) {
     'use strict';
 
-
     /**
+     * Checkbox (`<checkbox>`) Form Group.
      *
      * @param $element
      * @constructor

javascript/src/Element/README.md

+Element
+===
+
+On a QfqForm, an Element is comprised of several HTML elements enclosed in a Bootstrap `form-group`, for instance
+
+    <div class="form-group">
+        <div class="col-md-2">
+           <label for="personHompage" class="control-label">Hompage</label>
+        </div>
+        <div class="col-md-6">
+           <input id="personHompage" type="text" class="form-control">
+        </div>
+
+        <div class=" col-md-4">
+           <p class="help-block">
+             Alternative zur default 'Persoenlichen Homepage'. Falls kein Link auf
+             eine Homepage gesetzt werden soll: <b>no_homepage</b>
+           </p>
+        </div>
+    </div>
+    
+FormGroup is an abstraction which allows to perform common operations on a QfqForm Element. It hides the intricacies of 
+the underlying HTML Form Elements and the Element.
+
+The user should not instantiate FormGroup directly, but use the factory method `QfqNS.Element.getElement()` (defined 
+in `NameSpaceFunctions.js`).
\ No newline at end of file

javascript/src/Element/Radio.js

@@ -20,6 +20,7 @@ QfqNS.Element = QfqNS.Element || {};
 
 
     /**
+     * Radio (`<radio>`) Form Group.
      *
      * @param $element
      * @constructor

javascript/src/Element/Select.js

@@ -21,6 +21,7 @@ QfqNS.Element = QfqNS.Element || {};
 
 
     /**
+     * Select (`<select>`) Form Group.
      *
      * @param $element
      * @constructor

javascript/src/Element/TextArea.js

@@ -21,6 +21,7 @@ QfqNS.Element = QfqNS.Element || {};
 
 
     /**
+     * Textarea (`<textarea>`) Form Group.
      *
      * @param $element
      * @constructor

javascript/src/Element/Textual.js

@@ -20,7 +20,7 @@ QfqNS.Element = QfqNS.Element || {};
 
 
     /**
-     * Textual <input> form groups.
+     * Textual `<input>` form groups.
      *
      * @param $element
      * @constructor

javascript/src/ElementUpdate.js

@@ -13,7 +13,7 @@ var QfqNS = QfqNS || {};
     'use strict';
 
     /**
-     * Update HTML elements by a given id. Supports adding, setting, and removing attributes as well setting the
+     * Update HTML elements by a given id. Supports adding, setting, and removing attributes as well as setting the
      * text enclosed by the element.
      *
      * @type {{}}

javascript/src/FileDelete.js

@@ -17,9 +17,13 @@ var QfqNS = QfqNS || {};
     'use strict';
 
     /**
+     * Handle file deletion.
      *
-     * @param formSelector
-     * @param targetUrl
+     * Upon instantiation, it attaches to all `<button>` elements having the class `delete-file`, within the elements
+     * selected by the `formSelector`.
+     *
+     * @param formSelector jQuery selector of the `<form>` this instance is responsible for.
+     * @param targetUrl endpoint URL to send delete requests to.
      * @constructor
      *
      * @name QfqNS.FileDelete

javascript/src/Form.js

@@ -17,6 +17,7 @@ var QfqNS = QfqNS || {};
     'use strict';
 
     /**
+     * Abstraction of `<form>`.
      *
      * @param formId
      * @param formChanged
@@ -26,8 +27,8 @@ var QfqNS = QfqNS || {};
     n.Form = function (formId, formChanged) {
         this.formId = formId;
         this.eventEmitter = new EventEmitter();
-        // In order to immediately emit events, we bind event handlers on `<form/>` `change` and `input` and `paste` on
-        // `<input/> and `<textarea/>`s. Without precaution, this will lead to emitting `form.changed` twice upon
+        // In order to immediately emit events, we bind event handlers on `<form>` `change` and `input` and `paste` on
+        // `<input> and `<textarea>`s. Without precaution, this will lead to emitting `form.changed` twice upon
         // `input` and `paste` events, since they eventually will raise a form `change` event.  We perform bookkeeping
         // using this flag, to avoid emitting `form.changed` twice when bubbling.
         //
@@ -125,6 +126,7 @@ var QfqNS = QfqNS || {};
         return this.$form.serialize();
     };
 
+
     /**
      * @private
      * @param url base url

javascript/src/Helper/codemirror.js

@@ -23,12 +23,17 @@ QfqNS.Helper = QfqNS.Helper || {};
     'use strict';
 
     /**
-
+     * Initializes codemirror. Only `<textarea/>` elements having the class `qfq-codemirror` are initialized.
+     *
+     * The codemirror configuration has to be provided in the `data-config` attribute as JSON. E.g.
+     *
+     *      <textarea class="qfq-codemirror" data-config='{ "mode": "text/x-sql", "lineNumbers": true }'></textarea>
+     *
      * @function
-     * @name QfqNS.Helper.jqxEditor
      */
     var codemirror = function () {
         if (typeof CodeMirror === 'undefined') {
+            QfqNS.log.error("CodeMirror not loaded, cannot initialize Qfq CodeMirror.");
             return;
         }
 

javascript/src/Helper/jqxComboBox.js

@@ -22,6 +22,24 @@ QfqNS.Helper = QfqNS.Helper || {};
     'use strict';
 
     /**
+     * Initialize a jqxComboBox.
+     *
+     * Only `<div>` elements having a `jqw-combobox` class are taken into account during initialization.
+     *
+     * Data for the jqxComboBox has to be provided in a `<script>` element. In order for the widget to find the script
+     * tag, the `<div>` element requries a `data-control-name` attribute. The id of the corresponding `<script>` tag is
+     * derived by appending `_source` to the value of `data-control-name`.
+     *
+     * The content of the data `<script>` element has to be a valid JSON array of objects, e.g.
+     *
+     *     [
+     *       {"text": "A", "value": "1"},
+     *       {"text": "B", "value": "2"},
+     *       ...
+     *     ]
+     *
+     * The `text` and `value` attributes are required. `text` will be displayed to the enduser, and `value` is
+     * submitted to the backend.
      *
      * @function
      * @name QfqNS.Helper.jqxComboBox

javascript/src/Helper/jqxEditor.js

@@ -21,7 +21,7 @@ QfqNS.Helper = QfqNS.Helper || {};
     'use strict';
 
     /**
-
+     * Initialize a jqxEditor widget on all `<textarea>` elements having the class `jqw-editor`.
      * @function
      * @name QfqNS.Helper.jqxEditor
      */

javascript/src/Helper/tinyMCE.js

@@ -22,12 +22,14 @@ QfqNS.Helper = QfqNS.Helper || {};
     'use strict';
 
     /**
-
+     * Initialize tinyMce. All HTML elements having the `qfq-tinymce` class will be initialized. TinyMce configuration
+     * is provided in the `data-config` attribute. Each element further requires the `id` attribute to be present.
+     *
      * @function
-     * @name QfqNS.Helper.jqxEditor
      */
     var tinyMce = function () {
         if (typeof tinymce === 'undefined') {
+            QfqNS.log.error("tinymce not loaded, cannot initialize Qfq tinymce.");
             return;
         }
 
@@ -68,6 +70,9 @@ QfqNS.Helper = QfqNS.Helper || {};
         );
     };
 
+    /**
+     * Force update of the shadowed `<textarea>`. Usually called before a form submit.
+     */
     tinyMce.prepareSave = function () {
         if (typeof tinymce === 'undefined') {
             return;

javascript/src/TypeAhead.js

@@ -18,6 +18,7 @@ var QfqNS = QfqNS || {};
 
 
     /**
+     * Coerce corejs-typeahead into our use-case.
      *
      * @param typeahead_endpoint the endpoint to be called
      * @constructor
@@ -96,7 +97,7 @@ var QfqNS = QfqNS || {};
                 })(suggestions));
                 // The pedantic handler will test if the shadow element has a value set (the KEY). If not, the
                 // typeahead element is cleared. Thus we have to guarantee that no value exists in the shadow
-                // element, the instant the user starts typing since we don't know the outcome of the search.
+                // element the instant the user starts typing since we don't know the outcome of the search.
                 //
                 // If we don't clear the shadow element the instant the user starts typing, and simply let the
                 // `typeahead:select` or `typeahead:autocomplete` handler set the selected value, the