Commit 6bb94d68 authored by Rafael Ostertag's avatar Rafael Ostertag
Browse files

Merge branch 'javascript_comments' into 'master'

First batch of comments



See merge request !16
parents 98a256c1 50c60c30
......@@ -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
......
......@@ -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 () {
......
......@@ -20,8 +20,8 @@ QfqNS.Element = QfqNS.Element || {};
(function (n) {
'use strict';
/**
* Checkbox (`<checkbox>`) Form Group.
*
* @param $element
* @constructor
......
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
......@@ -20,6 +20,7 @@ QfqNS.Element = QfqNS.Element || {};
/**
* Radio (`<radio>`) Form Group.
*
* @param $element
* @constructor
......
......@@ -21,6 +21,7 @@ QfqNS.Element = QfqNS.Element || {};
/**
* Select (`<select>`) Form Group.
*
* @param $element
* @constructor
......
......@@ -21,6 +21,7 @@ QfqNS.Element = QfqNS.Element || {};
/**
* Textarea (`<textarea>`) Form Group.
*
* @param $element
* @constructor
......
......@@ -20,7 +20,7 @@ QfqNS.Element = QfqNS.Element || {};
/**
* Textual <input> form groups.
* Textual `<input>` form groups.
*
* @param $element
* @constructor
......
......@@ -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 {{}}
......
......@@ -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
......
......@@ -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
......
......@@ -23,9 +23,13 @@ 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') {
......
......@@ -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
......
......@@ -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
*/
......
......@@ -22,9 +22,10 @@ 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') {
......@@ -69,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;
......
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment