Commit 1daf8de1 authored by jhodgdon's avatar jhodgdon

Issue #2493677 by nod_, dawehner, Wim Leers: JSDoc for misc/ files

parent 9ae64742
...@@ -18,6 +18,8 @@ ...@@ -18,6 +18,8 @@
* *
* Does not discriminate based on element type, so allows you to set the * Does not discriminate based on element type, so allows you to set the
* is-active class on any element: a, li… * is-active class on any element: a, li…
*
* @type {Drupal~behavior}
*/ */
Drupal.behaviors.activeLinks = { Drupal.behaviors.activeLinks = {
attach: function (context) { attach: function (context) {
...@@ -28,7 +30,8 @@ ...@@ -28,7 +30,8 @@
var originalSelectors = ['[data-drupal-link-system-path="' + path.currentPath + '"]']; var originalSelectors = ['[data-drupal-link-system-path="' + path.currentPath + '"]'];
var selectors; var selectors;
// If this is the front page, we have to check for the <front> path as well. // If this is the front page, we have to check for the <front> path as
// well.
if (path.isFront) { if (path.isFront) {
originalSelectors.push('[data-drupal-link-system-path="<front>"]'); originalSelectors.push('[data-drupal-link-system-path="<front>"]');
} }
......
This diff is collapsed.
/** /**
* @file
* Adds an HTML element and method to trigger audio UAs to read system messages. * Adds an HTML element and method to trigger audio UAs to read system messages.
* *
* Use Drupal.announce() to indicate to screen reader users that an element on * Use {@link Drupal.announce} to indicate to screen reader users that an
* the page has changed state. For instance, if clicking a link loads 10 more * element on the page has changed state. For instance, if clicking a link
* items into a list, one might announce the change like this. * loads 10 more items into a list, one might announce the change like this.
*
* @example
* $('#search-list') * $('#search-list')
* .on('itemInsert', function (event, data) { * .on('itemInsert', function (event, data) {
* // Insert the new items. * // Insert the new items.
...@@ -14,6 +17,7 @@ ...@@ -14,6 +17,7 @@
* )); * ));
* }); * });
*/ */
(function (Drupal, debounce) { (function (Drupal, debounce) {
"use strict"; "use strict";
...@@ -22,8 +26,9 @@ ...@@ -22,8 +26,9 @@
var announcements = []; var announcements = [];
/** /**
* Builds a div element with the aria-live attribute and attaches it * Builds a div element with the aria-live attribute and add it to the DOM.
* to the DOM. *
* @type {Drupal~behavior}
*/ */
Drupal.behaviors.drupalAnnounce = { Drupal.behaviors.drupalAnnounce = {
attach: function (context) { attach: function (context) {
...@@ -80,17 +85,19 @@ ...@@ -80,17 +85,19 @@
* *
* The aria-live region will only read the text that currently populates its * The aria-live region will only read the text that currently populates its
* text node. Replacing text quickly in rapid calls to announce results in * text node. Replacing text quickly in rapid calls to announce results in
* only the text from the most recent call to Drupal.announce() being read. * only the text from the most recent call to {@link Drupal.announce} being
* By wrapping the call to announce in a debounce function, we allow for * read. By wrapping the call to announce in a debounce function, we allow for
* time for multiple calls to Drupal.announce() to queue up their messages. * time for multiple calls to {@link Drupal.announce} to queue up their
* These messages are then joined and append to the aria-live region as one * messages. These messages are then joined and append to the aria-live region
* text node. * as one text node.
* *
* @param String text * @param {string} text
* A string to be read by the UA. * A string to be read by the UA.
* @param String priority * @param {string} [priority='polite']
* A string to indicate the priority of the message. Can be either * A string to indicate the priority of the message. Can be either
* 'polite' or 'assertive'. Polite is the default. * 'polite' or 'assertive'.
*
* @return {function}
* *
* @see http://www.w3.org/WAI/PF/aria-practices/#liveprops * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
*/ */
......
/**
* @file
* Autocomplete based on jQuery UI.
*/
(function ($, Drupal) { (function ($, Drupal) {
"use strict"; "use strict";
...@@ -7,7 +12,9 @@ ...@@ -7,7 +12,9 @@
/** /**
* Helper splitting terms from the autocomplete value. * Helper splitting terms from the autocomplete value.
* *
* @param {String} value * @function Drupal.autocomplete.splitValues
*
* @param {string} value
* *
* @return {Array} * @return {Array}
*/ */
...@@ -43,9 +50,11 @@ ...@@ -43,9 +50,11 @@
/** /**
* Returns the last value of an multi-value textfield. * Returns the last value of an multi-value textfield.
* *
* @param {String} terms * @function Drupal.autocomplete.extractLastTerm
*
* @param {string} terms
* *
* @return {String} * @return {string}
*/ */
function extractLastTerm(terms) { function extractLastTerm(terms) {
return autocomplete.splitValues(terms).pop(); return autocomplete.splitValues(terms).pop();
...@@ -54,9 +63,11 @@ ...@@ -54,9 +63,11 @@
/** /**
* The search handler is called before a search is performed. * The search handler is called before a search is performed.
* *
* @param {Object} event * @function Drupal.autocomplete.options.search
* *
* @return {Boolean} * @param {object} event
*
* @return {bool}
*/ */
function searchHandler(event) { function searchHandler(event) {
var options = autocomplete.options; var options = autocomplete.options;
...@@ -70,10 +81,10 @@ ...@@ -70,10 +81,10 @@
} }
/** /**
* jQuery UI autocomplete source callback. * JQuery UI autocomplete source callback.
* *
* @param {Object} request * @param {object} request
* @param {Function} response * @param {function} response
*/ */
function sourceData(request, response) { function sourceData(request, response) {
var elementId = this.element.attr('id'); var elementId = this.element.attr('id');
...@@ -86,7 +97,7 @@ ...@@ -86,7 +97,7 @@
* Filter through the suggestions removing all terms already tagged and * Filter through the suggestions removing all terms already tagged and
* display the available terms to the user. * display the available terms to the user.
* *
* @param {Object} suggestions * @param {object} suggestions
*/ */
function showSuggestions(suggestions) { function showSuggestions(suggestions) {
var tagged = autocomplete.splitValues(request.term); var tagged = autocomplete.splitValues(request.term);
...@@ -103,7 +114,7 @@ ...@@ -103,7 +114,7 @@
/** /**
* Transforms the data object into an array and update autocomplete results. * Transforms the data object into an array and update autocomplete results.
* *
* @param {Object} data * @param {object} data
*/ */
function sourceCallbackHandler(data) { function sourceCallbackHandler(data) {
autocomplete.cache[elementId][term] = data; autocomplete.cache[elementId][term] = data;
...@@ -128,7 +139,7 @@ ...@@ -128,7 +139,7 @@
/** /**
* Handles an autocompletefocus event. * Handles an autocompletefocus event.
* *
* @return {Boolean} * @return {bool}
*/ */
function focusHandler() { function focusHandler() {
return false; return false;
...@@ -137,10 +148,10 @@ ...@@ -137,10 +148,10 @@
/** /**
* Handles an autocompleteselect event. * Handles an autocompleteselect event.
* *
* @param {Object} event * @param {jQuery.Event} event
* @param {Object} ui * @param {object} ui
* *
* @return {Boolean} * @return {bool}
*/ */
function selectHandler(event, ui) { function selectHandler(event, ui) {
var terms = autocomplete.splitValues(event.target.value); var terms = autocomplete.splitValues(event.target.value);
...@@ -161,10 +172,10 @@ ...@@ -161,10 +172,10 @@
/** /**
* Override jQuery UI _renderItem function to output HTML by default. * Override jQuery UI _renderItem function to output HTML by default.
* *
* @param {Object} ul * @param {object} ul
* @param {Object} item * @param {object} item
* *
* @return {Object} * @return {object}
*/ */
function renderItem(ul, item) { function renderItem(ul, item) {
return $("<li>") return $("<li>")
...@@ -174,6 +185,8 @@ ...@@ -174,6 +185,8 @@
/** /**
* Attaches the autocomplete behavior to all required fields. * Attaches the autocomplete behavior to all required fields.
*
* @type {Drupal~behavior}
*/ */
Drupal.behaviors.autocomplete = { Drupal.behaviors.autocomplete = {
attach: function (context) { attach: function (context) {
...@@ -202,6 +215,8 @@ ...@@ -202,6 +215,8 @@
/** /**
* Autocomplete object implementation. * Autocomplete object implementation.
*
* @namespace Drupal.autocomplete
*/ */
autocomplete = { autocomplete = {
cache: {}, cache: {},
...@@ -209,6 +224,12 @@ ...@@ -209,6 +224,12 @@
splitValues: autocompleteSplitValues, splitValues: autocompleteSplitValues,
extractLastTerm: extractLastTerm, extractLastTerm: extractLastTerm,
// jQuery UI autocomplete options. // jQuery UI autocomplete options.
/**
* JQuery UI option object.
*
* @name Drupal.autocomplete.options
*/
options: { options: {
source: sourceData, source: sourceData,
focus: focusHandler, focus: focusHandler,
......
/** /**
* @file
* Drupal's batch API. * Drupal's batch API.
*/ */
(function ($, Drupal) { (function ($, Drupal) {
"use strict"; "use strict";
/** /**
* Attaches the batch behavior to progress bars. * Attaches the batch behavior to progress bars.
*
* @type {Drupal~behavior}
*/ */
Drupal.behaviors.batch = { Drupal.behaviors.batch = {
attach: function (context, settings) { attach: function (context, settings) {
......
/**
* @file
* Polyfill for HTML5 details elements.
*/
(function ($, Modernizr, Drupal) { (function ($, Modernizr, Drupal) {
"use strict"; "use strict";
/** /**
* The collapsible details object represents a single collapsible details element. * The collapsible details object represents a single details element.
*
* @constructor Drupal.CollapsibleDetails
*
* @param {HTMLElement} node
*/ */
function CollapsibleDetails(node) { function CollapsibleDetails(node) {
this.$node = $(node); this.$node = $(node);
...@@ -20,22 +29,24 @@ ...@@ -20,22 +29,24 @@
this.setupLegend(); this.setupLegend();
} }
/** $.extend(CollapsibleDetails, /** @lends Drupal.CollapsibleDetails */{
* Extend CollapsibleDetails function.
*/
$.extend(CollapsibleDetails, {
/** /**
* Holds references to instantiated CollapsibleDetails objects. * Holds references to instantiated CollapsibleDetails objects.
*
* @type {Array.<Drupal.CollapsibleDetails>}
*/ */
instances: [] instances: []
}); });
/** $.extend(CollapsibleDetails.prototype, /** @lends Drupal.CollapsibleDetails# */{
* Extend CollapsibleDetails prototype.
*/
$.extend(CollapsibleDetails.prototype, {
/** /**
* Initialize and setup summary events and markup. * Initialize and setup summary events and markup.
*
* @fires event:summaryUpdated
*
* @listens event:summaryUpdated
*/ */
setupSummary: function () { setupSummary: function () {
this.$summary = $('<span class="summary"></span>'); this.$summary = $('<span class="summary"></span>');
...@@ -43,6 +54,7 @@ ...@@ -43,6 +54,7 @@
.on('summaryUpdated', $.proxy(this.onSummaryUpdated, this)) .on('summaryUpdated', $.proxy(this.onSummaryUpdated, this))
.trigger('summaryUpdated'); .trigger('summaryUpdated');
}, },
/** /**
* Initialize and setup legend markup. * Initialize and setup legend markup.
*/ */
...@@ -65,20 +77,25 @@ ...@@ -65,20 +77,25 @@
.append(this.$summary) .append(this.$summary)
.on('click', $.proxy(this.onLegendClick, this)); .on('click', $.proxy(this.onLegendClick, this));
}, },
/** /**
* Handle legend clicks * Handle legend clicks.
*
* @param {jQuery.Event} e
*/ */
onLegendClick: function (e) { onLegendClick: function (e) {
this.toggle(); this.toggle();
e.preventDefault(); e.preventDefault();
}, },
/** /**
* Update summary * Update summary.
*/ */
onSummaryUpdated: function () { onSummaryUpdated: function () {
var text = $.trim(this.$node.drupalGetSummary()); var text = $.trim(this.$node.drupalGetSummary());
this.$summary.html(text ? ' (' + text + ')' : ''); this.$summary.html(text ? ' (' + text + ')' : '');
}, },
/** /**
* Toggle the visibility of a details element using smooth animations. * Toggle the visibility of a details element using smooth animations.
*/ */
...@@ -99,6 +116,11 @@ ...@@ -99,6 +116,11 @@
} }
}); });
/**
* Polyfill HTML5 details element.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.collapse = { Drupal.behaviors.collapse = {
attach: function (context) { attach: function (context) {
if (Modernizr.details) { if (Modernizr.details) {
......
/** /**
* Limits the invocations of a function in a given time frame. * @file
*
* Adapted from underscore.js with the addition Drupal namespace. * Adapted from underscore.js with the addition Drupal namespace.
*/
/**
* Limits the invocations of a function in a given time frame.
* *
* The debounce function wrapper should be used sparingly. One clear use case * The debounce function wrapper should be used sparingly. One clear use case
* is limiting the invocation of a callback attached to the window resize event. * is limiting the invocation of a callback attached to the window resize event.
...@@ -11,13 +14,17 @@ ...@@ -11,13 +14,17 @@
* function can be written in such a way that it is only invoked under specific * function can be written in such a way that it is only invoked under specific
* conditions. * conditions.
* *
* @param {Function} callback * @param {function} func
* The function to be invoked. * The function to be invoked.
* * @param {number} wait
* @param {Number} wait
* The time period within which the callback function should only be * The time period within which the callback function should only be
* invoked once. For example if the wait period is 250ms, then the callback * invoked once. For example if the wait period is 250ms, then the callback
* will only be called at most 4 times per second. * will only be called at most 4 times per second.
* @param {bool} immediate
* Whether we wait at the beginning or end to execute the function.
*
* @return {function}
* The debounced function.
*/ */
Drupal.debounce = function (func, wait, immediate) { Drupal.debounce = function (func, wait, immediate) {
......
...@@ -7,6 +7,11 @@ ...@@ -7,6 +7,11 @@
"use strict"; "use strict";
/**
* Handles `aria-expanded` and `aria-pressed` attributes on details elements.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.detailsAria = { Drupal.behaviors.detailsAria = {
attach: function () { attach: function () {
$('body').once('detailsAria').on('click.detailsAria', 'summary', function (event) { $('body').once('detailsAria').on('click.detailsAria', 'summary', function (event) {
......
...@@ -7,6 +7,11 @@ ...@@ -7,6 +7,11 @@
"use strict"; "use strict";
/**
* Initialize dialogs for Ajax purposes.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.dialog = { Drupal.behaviors.dialog = {
attach: function (context, settings) { attach: function (context, settings) {
var $context = $(context); var $context = $(context);
...@@ -46,9 +51,10 @@ ...@@ -46,9 +51,10 @@
/** /**
* Scan a dialog for any primary buttons and move them to the button area. * Scan a dialog for any primary buttons and move them to the button area.
* *
* @param $dialog * @param {jQuery} $dialog
* An jQuery object containing the element that is the dialog target. * An jQuery object containing the element that is the dialog target.
* @return *
* @return {Array}
* An array of buttons that need to be added to the button area. * An array of buttons that need to be added to the button area.
*/ */
prepareDialogButtons: function ($dialog) { prepareDialogButtons: function ($dialog) {
...@@ -81,6 +87,12 @@ ...@@ -81,6 +87,12 @@
/** /**
* Command to open a dialog. * Command to open a dialog.
*
* @param {Drupal.Ajax} ajax
* @param {object} response
* @param {number} [status]
*
* @return {bool|undefined}
*/ */
Drupal.AjaxCommands.prototype.openDialog = function (ajax, response, status) { Drupal.AjaxCommands.prototype.openDialog = function (ajax, response, status) {
if (!response.selector) { if (!response.selector) {
...@@ -107,7 +119,7 @@ ...@@ -107,7 +119,7 @@
response.dialogOptions.buttons = Drupal.behaviors.dialog.prepareDialogButtons($dialog); response.dialogOptions.buttons = Drupal.behaviors.dialog.prepareDialogButtons($dialog);
} }
// Bind dialogButtonsChange // Bind dialogButtonsChange.
$dialog.on('dialogButtonsChange', function () { $dialog.on('dialogButtonsChange', function () {
var buttons = Drupal.behaviors.dialog.prepareDialogButtons($dialog); var buttons = Drupal.behaviors.dialog.prepareDialogButtons($dialog);
$dialog.dialog('option', 'buttons', buttons); $dialog.dialog('option', 'buttons', buttons);
...@@ -131,6 +143,12 @@ ...@@ -131,6 +143,12 @@
* Command to close a dialog. * Command to close a dialog.
* *
* If no selector is given, it defaults to trying to close the modal. * If no selector is given, it defaults to trying to close the modal.
*
* @param {Drupal.Ajax} [ajax]
* @param {object} response
* @param {string} response.selector
* @param {bool} response.persist
* @param {number} [status]
*/ */
Drupal.AjaxCommands.prototype.closeDialog = function (ajax, response, status) { Drupal.AjaxCommands.prototype.closeDialog = function (ajax, response, status) {
var $dialog = $(response.selector); var $dialog = $(response.selector);
...@@ -141,14 +159,21 @@ ...@@ -141,14 +159,21 @@
} }
} }
// Unbind dialogButtonsChange // Unbind dialogButtonsChange.
$dialog.off('dialogButtonsChange'); $dialog.off('dialogButtonsChange');
}; };
/** /**
* Command to set a dialog property. * Command to set a dialog property.
* *
* jQuery UI specific way of setting dialog options. * JQuery UI specific way of setting dialog options.
*
* @param {Drupal.Ajax} [ajax]
* @param {object} response
* @param {string} response.selector
* @param {string} response.optionsName
* @param {string} response.optionValue
* @param {number} [status]
*/ */
Drupal.AjaxCommands.prototype.setDialogOption = function (ajax, response, status) {