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 @@
*
* Does not discriminate based on element type, so allows you to set the
* is-active class on any element: a, li…
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.activeLinks = {
attach: function (context) {
......@@ -28,7 +30,8 @@
var originalSelectors = ['[data-drupal-link-system-path="' + path.currentPath + '"]'];
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) {
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.
*
* Use Drupal.announce() to indicate to screen reader users that an element on
* the page has changed state. For instance, if clicking a link loads 10 more
* items into a list, one might announce the change like this.
* Use {@link Drupal.announce} to indicate to screen reader users that an
* element on the page has changed state. For instance, if clicking a link
* loads 10 more items into a list, one might announce the change like this.
*
* @example
* $('#search-list')
* .on('itemInsert', function (event, data) {
* // Insert the new items.
......@@ -14,6 +17,7 @@
* ));
* });
*/
(function (Drupal, debounce) {
"use strict";
......@@ -22,8 +26,9 @@
var announcements = [];
/**
* Builds a div element with the aria-live attribute and attaches it
* to the DOM.
* Builds a div element with the aria-live attribute and add it to the DOM.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.drupalAnnounce = {
attach: function (context) {
......@@ -80,17 +85,19 @@
*
* 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
* only the text from the most recent call to Drupal.announce() being 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.
* These messages are then joined and append to the aria-live region as one
* text node.
* only the text from the most recent call to {@link Drupal.announce} being
* read. By wrapping the call to announce in a debounce function, we allow for
* time for multiple calls to {@link Drupal.announce} to queue up their
* messages. These messages are then joined and append to the aria-live region
* as one text node.
*
* @param String text
* @param {string} text
* 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
* 'polite' or 'assertive'. Polite is the default.
* 'polite' or 'assertive'.
*
* @return {function}
*
* @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
*/
......
/**
* @file
* Autocomplete based on jQuery UI.
*/
(function ($, Drupal) {
"use strict";
......@@ -7,7 +12,9 @@
/**
* Helper splitting terms from the autocomplete value.
*
* @param {String} value
* @function Drupal.autocomplete.splitValues
*
* @param {string} value
*
* @return {Array}
*/
......@@ -43,9 +50,11 @@
/**
* 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) {
return autocomplete.splitValues(terms).pop();
......@@ -54,9 +63,11 @@
/**
* 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) {
var options = autocomplete.options;
......@@ -70,10 +81,10 @@
}
/**
* jQuery UI autocomplete source callback.
* JQuery UI autocomplete source callback.
*
* @param {Object} request
* @param {Function} response
* @param {object} request
* @param {function} response
*/
function sourceData(request, response) {
var elementId = this.element.attr('id');
......@@ -86,7 +97,7 @@
* Filter through the suggestions removing all terms already tagged and
* display the available terms to the user.
*
* @param {Object} suggestions
* @param {object} suggestions
*/
function showSuggestions(suggestions) {
var tagged = autocomplete.splitValues(request.term);
......@@ -103,7 +114,7 @@
/**
* Transforms the data object into an array and update autocomplete results.
*
* @param {Object} data
* @param {object} data
*/
function sourceCallbackHandler(data) {
autocomplete.cache[elementId][term] = data;
......@@ -128,7 +139,7 @@
/**
* Handles an autocompletefocus event.
*
* @return {Boolean}
* @return {bool}
*/
function focusHandler() {
return false;
......@@ -137,10 +148,10 @@
/**
* Handles an autocompleteselect event.
*
* @param {Object} event
* @param {Object} ui
* @param {jQuery.Event} event
* @param {object} ui
*
* @return {Boolean}
* @return {bool}
*/
function selectHandler(event, ui) {
var terms = autocomplete.splitValues(event.target.value);
......@@ -161,10 +172,10 @@
/**
* Override jQuery UI _renderItem function to output HTML by default.
*
* @param {Object} ul
* @param {Object} item
* @param {object} ul
* @param {object} item
*
* @return {Object}
* @return {object}
*/
function renderItem(ul, item) {
return $("<li>")
......@@ -174,6 +185,8 @@
/**
* Attaches the autocomplete behavior to all required fields.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.autocomplete = {
attach: function (context) {
......@@ -202,6 +215,8 @@
/**
* Autocomplete object implementation.
*
* @namespace Drupal.autocomplete
*/
autocomplete = {
cache: {},
......@@ -209,6 +224,12 @@
splitValues: autocompleteSplitValues,
extractLastTerm: extractLastTerm,
// jQuery UI autocomplete options.
/**
* JQuery UI option object.
*
* @name Drupal.autocomplete.options
*/
options: {
source: sourceData,
focus: focusHandler,
......
/**
* @file
* Drupal's batch API.
*/
(function ($, Drupal) {
"use strict";
/**
* Attaches the batch behavior to progress bars.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.batch = {
attach: function (context, settings) {
......
/**
* @file
* Polyfill for HTML5 details elements.
*/
(function ($, Modernizr, Drupal) {
"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) {
this.$node = $(node);
......@@ -20,22 +29,24 @@
this.setupLegend();
}
/**
* Extend CollapsibleDetails function.
*/
$.extend(CollapsibleDetails, {
$.extend(CollapsibleDetails, /** @lends Drupal.CollapsibleDetails */{
/**
* Holds references to instantiated CollapsibleDetails objects.
*
* @type {Array.<Drupal.CollapsibleDetails>}
*/
instances: []
});
/**
* Extend CollapsibleDetails prototype.
*/
$.extend(CollapsibleDetails.prototype, {
$.extend(CollapsibleDetails.prototype, /** @lends Drupal.CollapsibleDetails# */{
/**
* Initialize and setup summary events and markup.
*
* @fires event:summaryUpdated
*
* @listens event:summaryUpdated
*/
setupSummary: function () {
this.$summary = $('<span class="summary"></span>');
......@@ -43,6 +54,7 @@
.on('summaryUpdated', $.proxy(this.onSummaryUpdated, this))
.trigger('summaryUpdated');
},
/**
* Initialize and setup legend markup.
*/
......@@ -65,20 +77,25 @@
.append(this.$summary)
.on('click', $.proxy(this.onLegendClick, this));
},
/**
* Handle legend clicks
* Handle legend clicks.
*
* @param {jQuery.Event} e
*/
onLegendClick: function (e) {
this.toggle();
e.preventDefault();
},
/**
* Update summary
* Update summary.
*/
onSummaryUpdated: function () {
var text = $.trim(this.$node.drupalGetSummary());
this.$summary.html(text ? ' (' + text + ')' : '');
},
/**
* Toggle the visibility of a details element using smooth animations.
*/
......@@ -99,6 +116,11 @@
}
});
/**
* Polyfill HTML5 details element.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.collapse = {
attach: function (context) {
if (Modernizr.details) {
......
/**
* Limits the invocations of a function in a given time frame.
*
* @file
* 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
* is limiting the invocation of a callback attached to the window resize event.
......@@ -11,13 +14,17 @@
* function can be written in such a way that it is only invoked under specific
* conditions.
*
* @param {Function} callback
* @param {function} func
* The function to be invoked.
*
* @param {Number} wait
* @param {number} wait
* The time period within which the callback function should only be
* invoked once. For example if the wait period is 250ms, then the callback
* 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) {
......
......@@ -7,6 +7,11 @@
"use strict";
/**
* Handles `aria-expanded` and `aria-pressed` attributes on details elements.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.detailsAria = {
attach: function () {
$('body').once('detailsAria').on('click.detailsAria', 'summary', function (event) {
......
......@@ -7,6 +7,11 @@
"use strict";
/**
* Initialize dialogs for Ajax purposes.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.dialog = {
attach: function (context, settings) {
var $context = $(context);
......@@ -46,9 +51,10 @@
/**
* 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.
* @return
*
* @return {Array}
* An array of buttons that need to be added to the button area.
*/
prepareDialogButtons: function ($dialog) {
......@@ -81,6 +87,12 @@
/**
* 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) {
if (!response.selector) {
......@@ -107,7 +119,7 @@
response.dialogOptions.buttons = Drupal.behaviors.dialog.prepareDialogButtons($dialog);
}
// Bind dialogButtonsChange
// Bind dialogButtonsChange.
$dialog.on('dialogButtonsChange', function () {
var buttons = Drupal.behaviors.dialog.prepareDialogButtons($dialog);
$dialog.dialog('option', 'buttons', buttons);
......@@ -131,6 +143,12 @@
* Command to close a dialog.
*
* 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) {
var $dialog = $(response.selector);
......@@ -141,14 +159,21 @@
}
}
// Unbind dialogButtonsChange
// Unbind dialogButtonsChange.
$dialog.off('dialogButtonsChange');
};
/**
* 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) {
var $dialog = $(response.selector);
......@@ -159,6 +184,11 @@
/**
* Binds a listener on dialog creation to handle the cancel link.
*
* @param {jQuery.Event} e
* @param {Drupal.dialog~dialogDefinition} dialog
* @param {jQuery} $element
* @param {object} settings
*/
$(window).on('dialog:aftercreate', function (e, dialog, $element, settings) {
$element.on('click.dialog', '.dialog-cancel', function (e) {
......@@ -170,6 +200,10 @@
/**
* Removes all 'dialog' listeners.
*
* @param {jQuery.Event} e
* @param {Drupal.dialog~dialogDefinition} dialog
* @param {jQuery} $element
*/
$(window).on('dialog:beforeclose', function (e, dialog, $element) {
$element.off('.dialog');
......
......@@ -2,6 +2,7 @@
* @file
* Adds default classes to buttons for styling purposes.
*/
(function ($) {
"use strict";
......
/**
* @file
* Dialog API inspired by HTML5 dialog element.
*
* Dialog API inspired by HTML5 dialog element:
* http://www.whatwg.org/specs/web-apps/current-work/multipage/commands.html#the-dialog-element
* @see http://www.whatwg.org/specs/web-apps/current-work/multipage/commands.html#the-dialog-element
*/
(function ($, Drupal, drupalSettings) {
"use strict";
/**
* Default dialog options.
*
* @type {object}
*
* @prop {bool} [autoOpen=true]
* @prop {string} [dialogClass='']
* @prop {string} [buttonClass='button']
* @prop {string} [buttonPrimaryClass='button--primary']
* @prop {function} close
*/
drupalSettings.dialog = {
autoOpen: true,
dialogClass: '',
// Drupal-specific extensions: see dialog.jquery-ui.js.
buttonClass: 'button',
buttonPrimaryClass: 'button--primary',
// When using this API directly (when generating dialogs on the client side),
// you may want to override this method and do
// @code
// jQuery(event.target).remove()
// @endcode
// as well, to remove the dialog on closing.
// When using this API directly (when generating dialogs on the client
// side), you may want to override this method and do
// `jQuery(event.target).remove()` as well, to remove the dialog on
// closing.
close: function (event) {
Drupal.detachBehaviors(event.target, null, 'unload');
}
};
/**
* @typedef {object} Drupal.dialog~dialogDefinition
*
* @prop {boolean} open
* Is the dialog open or not.
* @prop {*} returnValue
* Return value of the dialog.
* @prop {function} show
* Method to display the dialog on the page.
* @prop {function} showModal
* Method to display the dialog as a modal on the page.
* @prop {function} close
* Method to hide the dialog from the page.
*/
/**
* Polyfill HTML5 dialog element with jQueryUI.
*
* @param {HTMLElement} element
* @param {object} options
* jQuery UI options to be passed to the dialog.
*
* @return {Drupal.dialog~dialogDefinition}
*/
Drupal.dialog = function (element, options) {
function openDialog(settings) {
......
/**
* @file
* Positioning extensions for dialogs.
*/
/**
* Triggers when content inside a dialog changes.
*
* @event dialogContentResize
*/
(function ($, Drupal, drupalSettings, debounce, displace) {
"use strict";
......@@ -11,7 +22,13 @@
* This is used as a window resize and scroll callback to reposition the
* jQuery UI dialog. Although not a built-in jQuery UI option, this can
* be disabled by setting autoResize: false in the options array when creating
* a new Drupal.dialog().
* a new {@link Drupal.dialog}.
*
* @function Drupal.dialog~resetSize
*
* @param {jQuery.Event} event
*
* @fires event:dialogContentResize
*/
function resetSize(event) {
var positionOptions = ['width', 'height', 'minWidth', 'minHeight', 'maxHeight', 'maxWidth', 'position'];
......@@ -46,6 +63,12 @@
/**
* Position the dialog's center at the center of displace.offsets boundaries.
*
* @function Drupal.dialog~resetPosition
*
* @param {object} options
*
* @return {object}
*/
function resetPosition(options) {
var offsets = displace.offsets;
......
/**
* @file
* Manages elements that can offset the size of the viewport.
*
* Measures and reports viewport offset dimensions from elements like the
* toolbar that can potentially displace the positioning of other elements.
*/
/**
* @typedef {object} Drupal~displaceOffset
*
* @prop {number} top
* @prop {number} left
* @prop {number} right
* @prop {number} bottom
*/
/**
* Triggers when layout of the page changes.
*
* This is used to position fixed element on the page during page resize and
* Toolbar toggling.
*
* @event drupalViewportOffsetChange
*/
(function ($, Drupal, debounce) {
"use strict";
/**
* @name Drupal.displace.offsets
*
* @type {Drupal~displaceOffset}
*/
var offsets = {
top: 0,
right: 0,
......@@ -17,6 +42,8 @@
/**
* Registers a resize handler on the window.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.drupalDisplace = {
attach: function () {
......@@ -33,14 +60,20 @@
/**
* Informs listeners of the current offset dimensions.
*
* @param {boolean} broadcast