Commit c3cb3031 authored by jhodgdon's avatar jhodgdon

Issue #2493691 by nod_, eiriksm, dawehner: Add JSDoc for core modules JS

parent 4fb37aa1
/**
* @file
* Block admin behaviors.
*/
(function ($, Drupal) {
"use strict";
......@@ -8,6 +13,8 @@
* Text search input: input.block-filter-text
* Target element: input.block-filter-text[data-element]
* Source text: .block-filter-text-source
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.blockFilterByText = {
attach: function (context, settings) {
......@@ -17,7 +24,10 @@
var $details;
/**
* Hides the <details> element for a category if it has no visible blocks.
* Hides the `<details>` element for a category if it has no visible blocks.
*
* @param {number} index
* @param {HTMLElement} element
*/
function hideCategoryDetails(index, element) {
var $catDetails = $(element);
......@@ -26,12 +36,17 @@
/**
* Filters the block list.
*
* @param {jQuery.Event} e
*/
function filterBlockList(e) {
var query = $(e.target).val().toLowerCase();
/**
* Shows or hides the block entry based on the query.
*
* @param {number} index
* @param {HTMLElement} block
*/
function showBlockEntry(index, block) {
var $block = $(block);
......@@ -71,6 +86,8 @@
/**
* Highlights the block that was just placed into the block listing.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.blockHighlightPlacement = {
attach: function (context, settings) {
......
/**
* @file
* Block behaviors.
*/
(function ($, window) {
"use strict";
/**
* Provide the summary information for the block settings vertical tabs.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.blockSettingsSummary = {
attach: function () {
......@@ -46,6 +53,8 @@
*
* This behavior is dependent on the tableDrag behavior, since it uses the
* objects initialized in that behavior to update the row.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.blockDrag = {
attach: function (context, settings) {
......@@ -55,8 +64,8 @@
}
var table = $('#blocks');
var tableDrag = Drupal.tableDrag.blocks; // Get the blocks tableDrag object.
// Get the blocks tableDrag object.
var tableDrag = Drupal.tableDrag.blocks;
// Add a handler for when a row is swapped, update empty regions.
tableDrag.row.prototype.onSwap = function (swappedRow) {
checkEmptyRegions(table, this);
......
......@@ -7,6 +7,9 @@
"use strict";
/**
* @type {Drupal~behavior}
*/
Drupal.behaviors.blockContentDetailsSummaries = {
attach: function (context) {
var $context = $(context);
......
......@@ -7,6 +7,9 @@
"use strict";
/**
* @type {Drupal~behavior}
*/
Drupal.behaviors.bookDetailsSummaries = {
attach: function (context) {
$(context).find('.book-outline-form').drupalSetSummary(function (context) {
......
......@@ -7,6 +7,9 @@
"use strict";
/**
* @type {Drupal~behavior}
*/
Drupal.behaviors.color = {
attach: function (context, settings) {
var i;
......@@ -49,7 +52,8 @@
width.push(parseInt(gradient.css('width'), 10) / 10);
// Add rows (or columns for horizontal gradients).
// Each gradient line should have a height (or width for horizontal
// gradients) of 10px (because we divided the height/width by 10 above).
// gradients) of 10px (because we divided the height/width by 10
// above).
for (j = 0; j < (settings.gradients[i].direction === 'vertical' ? height[i] : width[i]); ++j) {
gradient.append('<div class="gradient-line"></div>');
}
......@@ -82,11 +86,19 @@
/**
* Shifts a given color, using a reference pair (ref in HSL).
*
* This algorithm ensures relative ordering on the saturation and luminance
* axes is preserved, and performs a simple hue shift.
* This algorithm ensures relative ordering on the saturation and
* luminance axes is preserved, and performs a simple hue shift.
*
* It is also symmetrical. If: shift_color(c, a, b) === d, then
* shift_color(d, b, a) === c.
*
* @function Drupal.color~shift_color
*
* @param {string} given
* @param {Array} ref1
* @param {Array} ref2
*
* @return {string}
*/
function shift_color(given, ref1, ref2) {
var d;
......@@ -129,6 +141,11 @@
/**
* Callback for Farbtastic when a new color is chosen.
*
* @param {HTMLElement} input
* @param {string} color
* @param {bool} propagate
* @param {bool} colorScheme
*/
function callback(input, color, propagate, colorScheme) {
var matched;
......@@ -182,6 +199,8 @@
/**
* Focuses Farbtastic on a particular field.
*
* @param {jQuery.Event} e
*/
function focus(e) {
var input = e.target;
......@@ -203,7 +222,7 @@
// Initialize color fields.
form.find('.js-color-palette input.form-text')
.each(function () {
// Extract palette field name
// Extract palette field name.
this.key = this.id.substring(13);
// Link to color picker temporarily to initialize.
......
......@@ -7,14 +7,26 @@
"use strict";
/**
* @namespace
*/
Drupal.color = {
/**
* @param {Element} context
* @param {object} settings
* @param {HTMLFormElement} form
* @param {object} farb
* @param {number} height
* @param {number} width
*/
callback: function (context, settings, form, farb, height, width) {
var accum;
var delta;
// Solid background.
form.find('.color-preview').css('backgroundColor', form.find('.color-palette input[name="palette[base]"]').val());
// Text preview
// Text preview.
form.find('#text').css('color', form.find('.color-palette input[name="palette[text]"]').val());
form.find('#text a, #text h2').css('color', form.find('.color-palette input[name="palette[link]"]').val());
......
......@@ -7,6 +7,10 @@
"use strict";
/**
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.commentFieldsetSummaries = {
attach: function (context) {
var $context = $(context);
......
/**
* @file
* Attaches behaviors for the Comment module's "by-viewer" class.
*/
(function ($, Drupal, drupalSettings) {
"use strict";
/**
* Add 'by-viewer' class to comments written by the current user.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.commentByViewer = {
attach: function (context) {
......
/**
* @file
* Attaches behaviors for the Comment module's "new" indicator.
*
* May only be loaded for authenticated users, with the History module
* installed.
*/
(function ($, Drupal, window) {
"use strict";
/**
* Render "new" comment indicators wherever necessary.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.commentNewIndicator = {
attach: function (context) {
......
/**
* @file
* Attaches behaviors for the Comment module's "X new comments" link.
*
* May only be loaded for authenticated users, with the History module
* installed.
*/
(function ($, Drupal) {
"use strict";
/**
* Render "X new comments" links wherever necessary.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.nodeNewCommentsLink = {
attach: function (context) {
......
/**
* @file
* Content Translation admin behaviors.
*/
(function ($, Drupal, drupalSettings) {
"use strict";
/**
* Forces applicable options to be checked as translatable.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.contentTranslationDependentOptions = {
attach: function (context) {
......@@ -66,6 +73,8 @@
/**
* Makes field translatability inherit bundle translatability.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.contentTranslation = {
attach: function (context) {
......
......@@ -33,12 +33,12 @@
}
/**
* Initializes a contextual link: updates its DOM, sets up model and views
* Initializes a contextual link: updates its DOM, sets up model and views.
*
* @param jQuery $contextual
* @param {jQuery} $contextual
* A contextual links placeholder DOM element, containing the actual
* contextual links as rendered by the server.
* @param string html
* @param {string} html
* The server-side rendered HTML for this contextual link.
*/
function initContextual($contextual, html) {
......@@ -97,7 +97,7 @@
*
* This only deals with two levels of nesting; deeper levels are not touched.
*
* @param jQuery $contextual
* @param {jQuery} $contextual
* A contextual links placeholder DOM element, containing the actual
* contextual links as rendered by the server.
*/
......@@ -138,6 +138,8 @@
* Events
* Contextual triggers an event that can be used by other scripts.
* - drupalContextualLinkAdded: Triggered when a contextual link is added.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.contextual = {
attach: function (context) {
......@@ -206,23 +208,39 @@
}
};
/**
* @namespace
*/
Drupal.contextual = {
// The Drupal.contextual.View instances associated with each list element of
// contextual links.
/**
* The {@link Drupal.contextual.View} instances associated with each list
* element of contextual links.
*
* @type {Array}
*/
views: [],
// The Drupal.contextual.RegionView instances associated with each contextual
// region element.
/**
* The {@link Drupal.contextual.RegionView} instances associated with each contextual
* region element.
*
* @type {Array}
*/
regionViews: []
};
// A Backbone.Collection of Drupal.contextual.StateModel instances.
/**
* A Backbone.Collection of {@link Drupal.contextual.StateModel} instances.
*
* @type {Backbone.Collection}
*/
Drupal.contextual.collection = new Backbone.Collection([], {model: Drupal.contextual.StateModel});
/**
* A trigger is an interactive element often bound to a click handler.
*
* @return String
* @return {string}
* A string representing a DOM fragment.
*/
Drupal.theme.contextualTrigger = function () {
......
......@@ -14,9 +14,9 @@
};
/**
* Initializes a contextual link: updates its DOM, sets up model and views
* Initializes a contextual link: updates its DOM, sets up model and views.
*
* @param DOM links
* @param {HTMLElement} context
* A contextual links DOM element as rendered by the server.
*/
function initContextualToolbar(context) {
......@@ -45,6 +45,8 @@
/**
* Attaches contextual's edit toolbar tab behavior.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.contextualToolbar = {
attach: function (context) {
......@@ -54,8 +56,16 @@
}
};
/**
* @namespace
*/
Drupal.contextualToolbar = {
// The Drupal.contextualToolbar.Model instance.
/**
* The {@link Drupal.contextualToolbar.StateModel} instance.
*
* @type {?Drupal.contextualToolbar.StateModel}
*/
model: null
};
......
......@@ -9,20 +9,58 @@
/**
* Models the state of a contextual link's trigger, list & region.
*
* @constructor
*
* @augments Backbone.Model
*/
Drupal.contextual.StateModel = Backbone.Model.extend({
Drupal.contextual.StateModel = Backbone.Model.extend(/** @lends Drupal.contextual.StateModel# */{
defaults: {
// The title of the entity to which these contextual links apply.
/**
* @type {object}
*
* @prop {string} title
* @prop {bool} regionIsHovered
* @prop {bool} hasFocus
* @prop {bool} isOpen
* @prop {bool} isLocked
*/
defaults: /** @lends Drupal.contextual.StateModel# */{
/**
* The title of the entity to which these contextual links apply.
*
* @type {string}
*/
title: '',
// Represents if the contextual region is being hovered.
/**
* Represents if the contextual region is being hovered.
*
* @type {bool}
*/
regionIsHovered: false,
// Represents if the contextual trigger or options have focus.
/**
* Represents if the contextual trigger or options have focus.
*
* @type {bool}
*/
hasFocus: false,
// Represents if the contextual options for an entity are available to
// be selected (i.e. whether the list of options is visible).
/**
* Represents if the contextual options for an entity are available to
* be selected (i.e. whether the list of options is visible).
*
* @type {bool}
*/
isOpen: false,
// When the model is locked, the trigger remains active.
/**
* When the model is locked, the trigger remains active.
*
* @type {bool}
*/
isLocked: false
},
......@@ -30,6 +68,8 @@
* Opens or closes the contextual link.
*
* If it is opened, then also give focus.
*
* @return {Drupal.contextual.StateModel}
*/
toggleOpen: function () {
var newIsOpen = !this.get('isOpen');
......@@ -45,6 +85,8 @@
*
* Does not call blur() because we want to allow a contextual link to have
* focus, yet be closed for example when hovering.
*
* @return {Drupal.contextual.StateModel}
*/
close: function () {
this.set('isOpen', false);
......@@ -55,6 +97,8 @@
* Gives focus to this contextual link.
*
* Also closes + removes focus from every other contextual link.
*
* @return {Drupal.contextual.StateModel}
*/
focus: function () {
this.set('hasFocus', true);
......@@ -69,6 +113,8 @@
/**
* Removes focus from this contextual link, unless it is open.
*
* @return {Drupal.contextual.StateModel}
*/
blur: function () {
if (!this.get('isOpen')) {
......
......@@ -7,33 +7,62 @@
"use strict";
/**
* Models the state of the edit mode toggle.
*/
Drupal.contextualToolbar.StateModel = Backbone.Model.extend({
Drupal.contextualToolbar.StateModel = Backbone.Model.extend(/** @lends Drupal.contextualToolbar.StateModel# */{
defaults: {
// Indicates whether the toggle is currently in "view" or "edit" mode.
/**
* @type {object}
*
* @prop {bool} isViewing
* @prop {bool} isVisible
* @prop {number} contextualCount
* @prop {Drupal~TabbingContext} tabbingContext
*/
defaults: /** @lends Drupal.contextualToolbar.StateModel# */{
/**
* Indicates whether the toggle is currently in "view" or "edit" mode.
*
* @type {bool}
*/
isViewing: true,
// Indicates whether the toggle should be visible or hidden. Automatically
// calculated, depends on contextualCount.
/**
* Indicates whether the toggle should be visible or hidden. Automatically
* calculated, depends on contextualCount.
*
* @type {bool}
*/
isVisible: false,
// Tracks how many contextual links exist on the page.
/**
* Tracks how many contextual links exist on the page.
*
* @type {number}
*/
contextualCount: 0,
// A TabbingContext object as returned by Drupal.TabbingManager: the set
// of tabbable elements when edit mode is enabled.
/**
* A TabbingContext object as returned by {@link Drupal~TabbingManager}:
* the set of tabbable elements when edit mode is enabled.
*
* @type {?Drupal~TabbingContext}
*/
tabbingContext: null
},
/**
* {@inheritdoc}
* Models the state of the edit mode toggle.
*
* @constructs
*
* @augments Backbone.Model
*
* @param Object attrs
* @param Object options
* @param {object} attrs
* @param {object} options
* An object with the following option:
* - Backbone.collection contextualCollection: the collection of
* Drupal.contextual.StateModel models that represent the contextual
* links on the page.
* @param {Backbone.collection} options.contextualCollection
* The collection of {@link Drupal.contextual.StateModel} models that
* represent the contextual links on the page.
*/
initialize: function (attrs, options) {
// Respond to new/removed contextual links.
......@@ -57,9 +86,9 @@
/**
* Tracks the number of contextual link models in the collection.
*
* @param Drupal.contextual.StateModel contextualModel
* @param {Drupal.contextual.StateModel} contextualModel
* The contextual links model that was added or removed.
* @param Backbone.Collection contextualCollection
* @param {Backbone.Collection} contextualCollection
* The collection of contextual link models.
*/
countContextualLinks: function (contextualModel, contextualCollection) {
......@@ -69,9 +98,9 @@
/**
* Lock newly added contextual links if edit mode is enabled.
*
* @param Drupal.contextual.StateModel contextualModel
* @param {Drupal.contextual.StateModel} contextualModel
* The contextual links model that was added.
* @param Backbone.Collection contextualCollection
* @param {Backbone.Collection} [contextualCollection]
* The collection of contextual link models.
*/
lockNewContextualLinks: function (contextualModel, contextualCollection) {
......
......@@ -7,16 +7,23 @@
"use strict";
/**
* Renders the aural view of the edit mode toggle (i.e.screen reader support).
*/
Drupal.contextualToolbar.AuralView = Backbone.View.extend({
Drupal.contextualToolbar.AuralView = Backbone.View.extend(/** @lends Drupal.contextualToolbar.AuralView# */{
// Tracks whether the tabbing constraint announcement has been read once yet.
/**
* Tracks whether the tabbing constraint announcement has been read once.
*
* @type {bool}
*/
announcedOnce: false,
/*
* {@inheritdoc}
/**
* Renders the aural view of the edit mode toggle (screen reader support).
*
* @constructs
*
* @augments Backbone.View
*
* @param {object} options
*/
initialize: function (options) {
this.options = options;
......@@ -28,7 +35,9 @@
},
/**
* {@inheritdoc}
* @inheritdoc
*
* @return {Drupal.contextualToolbar.AuralView}
*/
render: function () {
// Render the state.
......@@ -39,11 +48,6 @@
/**
* Limits tabbing to the contextual links and edit mode toolbar tab.
*
* @param Drupal.contextualToolbar.StateModel model
* A Drupal.contextualToolbar.StateModel model.
* @param bool isViewing
* The value of the isViewing attribute in the model.
*/
manageTabbing: function () {
var tabbingContext = this.model.get('tabbingContext');
......@@ -75,7 +79,7 @@
/**
* Responds to esc and tab key press events.
*
* @param jQuery.Event event
* @param {jQuery.Event} event
*/
onKeypress: function (event) {
// The first tab key press is tracked so that an annoucement about tabbing
......
......@@ -7,13 +7,11 @@
"use strict";
/**
* Renders the visual view of the edit mode toggle. Listens to mouse & touch.
*
* Handles edit mode toggle interactions.
*/
Drupal.contextualToolbar.VisualView = Backbone.View.extend({
Drupal.contextualToolbar.VisualView = Backbone.View.extend(/** @lends Drupal.contextualToolbar.VisualView# */{
/**
* @return {object}
*/
events: function () {
// Prevents delay and simulated mouse events.
var touchEndToClick = function (event) {
......@@ -30,7 +28,13 @@
},
/**
* {@inheritdoc}
* Renders the visual view of the edit mode toggle.
*
* Listens to mouse & touch and handles edit mode toggle interactions.
*
* @constructs
*
* @augments Backbone.View
*/
initialize: function () {
this.listenTo(this.model, 'change', this.render);
......@@ -38,7 +42,9 @@
},