diff --git a/core/modules/block/js/block.admin.js b/core/modules/block/js/block.admin.js index d301ade..b399dd0 100644 --- a/core/modules/block/js/block.admin.js +++ b/core/modules/block/js/block.admin.js @@ -1,3 +1,8 @@ +/** + * @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
element for a category if it has no visible blocks. + * Hides the `
` 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) { diff --git a/core/modules/block/js/block.js b/core/modules/block/js/block.js index c3a4d0d..e5c0907 100644 --- a/core/modules/block/js/block.js +++ b/core/modules/block/js/block.js @@ -1,9 +1,16 @@ +/** + * @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); diff --git a/core/modules/block_content/js/block_content.js b/core/modules/block_content/js/block_content.js index de36d4b..1c9cea2 100644 --- a/core/modules/block_content/js/block_content.js +++ b/core/modules/block_content/js/block_content.js @@ -7,6 +7,9 @@ "use strict"; + /** + * @type {Drupal~behavior} + */ Drupal.behaviors.blockContentDetailsSummaries = { attach: function (context) { var $context = $(context); diff --git a/core/modules/book/book.js b/core/modules/book/book.js index df57547..e67c6a2 100644 --- a/core/modules/book/book.js +++ b/core/modules/book/book.js @@ -7,6 +7,9 @@ "use strict"; + /** + * @type {Drupal~behavior} + */ Drupal.behaviors.bookDetailsSummaries = { attach: function (context) { $(context).find('.book-outline-form').drupalSetSummary(function (context) { diff --git a/core/modules/color/color.js b/core/modules/color/color.js index c177c4c..1a9d8a5 100644 --- a/core/modules/color/color.js +++ b/core/modules/color/color.js @@ -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('
'); } @@ -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. diff --git a/core/modules/color/preview.js b/core/modules/color/preview.js index f121ade..956b53e 100644 --- a/core/modules/color/preview.js +++ b/core/modules/color/preview.js @@ -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()); diff --git a/core/modules/comment/comment-entity-form.js b/core/modules/comment/comment-entity-form.js index b41ab84..9e90979 100644 --- a/core/modules/comment/comment-entity-form.js +++ b/core/modules/comment/comment-entity-form.js @@ -7,6 +7,10 @@ "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.commentFieldsetSummaries = { attach: function (context) { var $context = $(context); diff --git a/core/modules/comment/js/comment-by-viewer.js b/core/modules/comment/js/comment-by-viewer.js index 0abea0d..4f597e0 100644 --- a/core/modules/comment/js/comment-by-viewer.js +++ b/core/modules/comment/js/comment-by-viewer.js @@ -1,12 +1,16 @@ /** + * @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) { diff --git a/core/modules/comment/js/comment-new-indicator.js b/core/modules/comment/js/comment-new-indicator.js index b15e67c..8a2bf07 100644 --- a/core/modules/comment/js/comment-new-indicator.js +++ b/core/modules/comment/js/comment-new-indicator.js @@ -1,15 +1,19 @@ /** + * @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) { diff --git a/core/modules/comment/js/node-new-comments-link.js b/core/modules/comment/js/node-new-comments-link.js index 97c7871..fce15aa 100644 --- a/core/modules/comment/js/node-new-comments-link.js +++ b/core/modules/comment/js/node-new-comments-link.js @@ -1,15 +1,19 @@ /** + * @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) { diff --git a/core/modules/content_translation/content_translation.admin.js b/core/modules/content_translation/content_translation.admin.js index 857cbd7..0071b6e 100644 --- a/core/modules/content_translation/content_translation.admin.js +++ b/core/modules/content_translation/content_translation.admin.js @@ -1,9 +1,16 @@ +/** + * @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) { diff --git a/core/modules/contextual/js/contextual.js b/core/modules/contextual/js/contextual.js index eccb54b..3694f45 100644 --- a/core/modules/contextual/js/contextual.js +++ b/core/modules/contextual/js/contextual.js @@ -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,38 @@ } }; + /** + * @namespace + */ Drupal.contextual = { - // The Drupal.contextual.View instances associated with each list element of - // contextual links. + /** + * The 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 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 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 () { diff --git a/core/modules/contextual/js/contextual.toolbar.js b/core/modules/contextual/js/contextual.toolbar.js index 4641890..c6b752c 100644 --- a/core/modules/contextual/js/contextual.toolbar.js +++ b/core/modules/contextual/js/contextual.toolbar.js @@ -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,15 @@ } }; + /** + * @namespace + */ Drupal.contextualToolbar = { - // The Drupal.contextualToolbar.Model instance. + /** + * The Drupal.contextualToolbar.Model instance. + * + * @type {?Drupal.contextualToolbar.StateModel} + */ model: null }; diff --git a/core/modules/contextual/js/models/StateModel.js b/core/modules/contextual/js/models/StateModel.js index 24907b0..0396835 100644 --- a/core/modules/contextual/js/models/StateModel.js +++ b/core/modules/contextual/js/models/StateModel.js @@ -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')) { diff --git a/core/modules/contextual/js/toolbar/models/StateModel.js b/core/modules/contextual/js/toolbar/models/StateModel.js index 360b9fb..0c261c5 100644 --- a/core/modules/contextual/js/toolbar/models/StateModel.js +++ b/core/modules/contextual/js/toolbar/models/StateModel.js @@ -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) { diff --git a/core/modules/contextual/js/toolbar/views/AuralView.js b/core/modules/contextual/js/toolbar/views/AuralView.js index 38f7363..1344df8 100644 --- a/core/modules/contextual/js/toolbar/views/AuralView.js +++ b/core/modules/contextual/js/toolbar/views/AuralView.js @@ -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 yet. + * + * @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 diff --git a/core/modules/contextual/js/toolbar/views/VisualView.js b/core/modules/contextual/js/toolbar/views/VisualView.js index 41b095f..0aa71dd 100644 --- a/core/modules/contextual/js/toolbar/views/VisualView.js +++ b/core/modules/contextual/js/toolbar/views/VisualView.js @@ -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. + * + * Handles edit mode toggle interactions. + * + * @constructs + * + * @augments Backbone.View */ initialize: function () { this.listenTo(this.model, 'change', this.render); @@ -38,7 +42,9 @@ }, /** - * {@inheritdoc} + * @inheritdoc + * + * @return {Drupal.contextualToolbar.VisualView} */ render: function () { // Render the visibility. @@ -52,12 +58,12 @@ /** * Model change handler; persists the isViewing value to localStorage. * - * isViewing === true is the default, so only stores in localStorage when + * `isViewing === true` is the default, so only stores in localStorage when * it's not the default value (i.e. false). * - * @param Drupal.contextualToolbar.StateModel model - * A Drupal.contextualToolbar.StateModel model. - * @param bool isViewing + * @param {Drupal.contextualToolbar.StateModel} model + * A {@link Drupal.contextualToolbar.StateModel} model. + * @param {bool} isViewing * The value of the isViewing attribute in the model. */ persist: function (model, isViewing) { diff --git a/core/modules/contextual/js/views/AuralView.js b/core/modules/contextual/js/views/AuralView.js index 40aff22..407f151 100644 --- a/core/modules/contextual/js/views/AuralView.js +++ b/core/modules/contextual/js/views/AuralView.js @@ -7,13 +7,16 @@ "use strict"; - /** - * Renders the aural view of a contextual link (i.e. screen reader support). - */ - Drupal.contextual.AuralView = Backbone.View.extend({ + Drupal.contextual.AuralView = Backbone.View.extend(/** @lends Drupal.contextual.AuralView# */{ /** - * {@inheritdoc} + * Renders the aural view of a contextual link (i.e. screen reader support). + * + * @constructs + * + * @augments Backbone.View + * + * @param {object} options */ initialize: function (options) { this.options = options; @@ -28,7 +31,7 @@ }, /** - * {@inheritdoc} + * @inheritdoc */ render: function () { var isOpen = this.model.get('isOpen'); diff --git a/core/modules/contextual/js/views/KeyboardView.js b/core/modules/contextual/js/views/KeyboardView.js index d6ebcec..4cf54ad 100644 --- a/core/modules/contextual/js/views/KeyboardView.js +++ b/core/modules/contextual/js/views/KeyboardView.js @@ -7,10 +7,11 @@ "use strict"; - /** - * Provides keyboard interaction for a contextual link. - */ - Drupal.contextual.KeyboardView = Backbone.View.extend({ + Drupal.contextual.KeyboardView = Backbone.View.extend(/** @lends Drupal.contextual.KeyboardView# */{ + + /** + * @type {object} + */ events: { 'focus .trigger': 'focus', 'focus .contextual-links a': 'focus', @@ -26,14 +27,22 @@ }, /** - * {@inheritdoc} + * Provides keyboard interaction for a contextual link. + * + * @constructs + * + * @augments Backbone.View */ initialize: function () { - // The timer is used to create a delay before dismissing the contextual - // links on blur. This is only necessary when keyboard users tab into - // contextual links without edit mode (i.e. without TabbingManager). - // That means that if we decide to disable tabbing of contextual links - // without edit mode, all this timer logic can go away. + /** + * The timer is used to create a delay before dismissing the contextual + * links on blur. This is only necessary when keyboard users tab into + * contextual links without edit mode (i.e. without TabbingManager). + * That means that if we decide to disable tabbing of contextual links + * without edit mode, all this timer logic can go away. + * + * @type {NaN|number} + */ this.timer = NaN; }, diff --git a/core/modules/contextual/js/views/RegionView.js b/core/modules/contextual/js/views/RegionView.js index 10c5c51..b64ee45 100644 --- a/core/modules/contextual/js/views/RegionView.js +++ b/core/modules/contextual/js/views/RegionView.js @@ -7,11 +7,11 @@ "use strict"; - /** - * Renders the visual view of a contextual region element. - */ - Drupal.contextual.RegionView = Backbone.View.extend({ + Drupal.contextual.RegionView = Backbone.View.extend(/** @lends Drupal.contextual.RegionView# */{ + /** + * @return {object} + */ events: function () { var mapping = { mouseenter: function () { this.model.set('regionIsHovered', true); }, @@ -27,14 +27,20 @@ }, /** - * {@inheritdoc} + * Renders the visual view of a contextual region element. + * + * @constructs + * + * @augments Backbone.View */ initialize: function () { this.listenTo(this.model, 'change:hasFocus', this.render); }, /** - * {@inheritdoc} + * @inheritdoc + * + * @return {Drupal.contextual.RegionView} */ render: function () { this.$el.toggleClass('focus', this.model.get('hasFocus')); diff --git a/core/modules/contextual/js/views/VisualView.js b/core/modules/contextual/js/views/VisualView.js index c40b30a..8da3c19 100644 --- a/core/modules/contextual/js/views/VisualView.js +++ b/core/modules/contextual/js/views/VisualView.js @@ -7,11 +7,11 @@ "use strict"; - /** - * Renders the visual view of a contextual link. Listens to mouse & touch. - */ - Drupal.contextual.VisualView = Backbone.View.extend({ + Drupal.contextual.VisualView = Backbone.View.extend(/** @lends Drupal.contextual.VisualView# */{ + /** + * @return {object} + */ events: function () { // Prevents delay and simulated mouse events. var touchEndToClick = function (event) { @@ -32,14 +32,20 @@ }, /** - * {@inheritdoc} + * Renders the visual view of a contextual link. Listens to mouse & touch. + * + * @constructs + * + * @augments Backbone.View */ initialize: function () { this.listenTo(this.model, 'change', this.render); }, /** - * {@inheritdoc} + * @inheritdoc + * + * @return {Drupal.contextual.VisualView} */ render: function () { var isOpen = this.model.get('isOpen'); diff --git a/core/modules/field_ui/field_ui.js b/core/modules/field_ui/field_ui.js index 9bdbe50..fceb94e 100644 --- a/core/modules/field_ui/field_ui.js +++ b/core/modules/field_ui/field_ui.js @@ -7,14 +7,17 @@ "use strict"; + /** + * @type {Drupal~behavior} + */ Drupal.behaviors.fieldUIFieldStorageAddForm = { attach: function (context) { var $form = $(context).find('#field-ui-field-storage-add-form').once('field_ui_add'); if ($form.length) { - // Add a few 'form-required' css classes here. We can not use the Form API - // '#required' property because both label elements for "add new" and - // "re-use existing" can never be filled and submitted at the same time. - // The actual validation will happen server-side. + // Add a few 'form-required' css classes here. We can not use the Form + // API '#required' property because both label elements for "add new" + // and "re-use existing" can never be filled and submitted at the same + // time. The actual validation will happen server-side. $form.find( '.form-item-label label,' + '.form-item-field-name label,' + @@ -52,6 +55,10 @@ } }; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.fieldUIDisplayOverview = { attach: function (context, settings) { $(context).find('table#field-display-overview').once('field-display-overview').each(function () { @@ -60,9 +67,17 @@ } }; + /** + * @namespace + */ Drupal.fieldUIOverview = { + /** * Attaches the fieldUIOverview behavior. + * + * @param {HTMLTableElement} table + * @param {object} rowsData + * @param {object} rowHandlers */ attach: function (table, rowsData, rowHandlers) { var tableDrag = Drupal.tableDrag[table.id]; @@ -79,7 +94,8 @@ var data = rowsData[row.id]; data.tableDrag = tableDrag; - // Create the row handler, make it accessible from the DOM row element. + // Create the row handler, make it accessible from the DOM row + // element. var rowHandler = new rowHandlers[data.rowHandler](row, data); $(row).data('fieldUIRowHandler', rowHandler); } @@ -140,9 +156,7 @@ * * Copied from block.js. * - * @param table - * The table DOM element. - * @param rowObject + * @param {HTMLElement} draggedRow * The tableDrag rowObject for the row being dragged. */ onSwap: function (draggedRow) { @@ -152,7 +166,8 @@ // If the dragged row is in this region, but above the message row, swap // it down one space. if ($this.prev('tr').get(0) === rowObject.group[rowObject.group.length - 1]) { - // Prevent a recursion problem when using the keyboard to move rows up. + // Prevent a recursion problem when using the keyboard to move rows + // up. if ((rowObject.method !== 'keyboard' || rowObject.direction === 'down')) { rowObject.swap('after', this); } @@ -175,7 +190,7 @@ * The #ajax behavior is therefore not attached directly to the selects, but * triggered manually through a hidden #ajax 'Refresh' button. * - * @param rows + * @param {object} rows * A hash object, whose keys are the names of the rows to refresh (they * will receive the 'ajax-new-content' effect on the server side), and * whose values are the DOM element in the row that should get an Ajax @@ -210,6 +225,8 @@ /** * Row handlers for the 'Manage display' screen. + * + * @namespace */ Drupal.fieldUIDisplayOverview = {}; @@ -218,10 +235,14 @@ * * This handler is used for both fields and 'extra fields' rows. * - * @param row + * @constructor + * + * @param {HTMLTableRowElement} row * The row DOM element. - * @param data + * @param {object} data * Additional data to be populated in the constructed object. + * + * @return {Drupal.fieldUIDisplayOverview.field} */ Drupal.fieldUIDisplayOverview.field = function (row, data) { this.row = row; @@ -237,8 +258,11 @@ }; Drupal.fieldUIDisplayOverview.field.prototype = { + /** * Returns the region corresponding to the current form values of the row. + * + * @return {string} */ getRegion: function () { return (this.$pluginSelect.val() === 'hidden') ? 'hidden' : 'content'; @@ -247,16 +271,18 @@ /** * Reacts to a row being changed regions. * - * This function is called when the row is moved to a different region, as a + * This function is called when the row is moved to a different region, as + * a * result of either : - * - a drag-and-drop action (the row's form elements then probably need to be - * updated accordingly) + * - a drag-and-drop action (the row's form elements then probably need to + * be updated accordingly) * - user input in one of the form elements watched by the * Drupal.fieldUIOverview.onChange change listener. * - * @param region + * @param {string} region * The name of the new region for the row. - * @return + * + * @return {object} * A hash object indicating which rows should be Ajax-updated as a result * of the change, in the format expected by * Drupal.displayOverview.AJAXRefreshRows(). @@ -271,8 +297,9 @@ // if (region !== 'hidden') { if (region === 'content') { if (currentValue === 'hidden') { - // Restore the formatter back to the default formatter. Pseudo-fields do - // not have default formatters, we just return to 'visible' for those. + // Restore the formatter back to the default formatter. Pseudo-fields + // do not have default formatters, we just return to 'visible' for + // those. value = (typeof this.defaultPlugin !== 'undefined') ? this.defaultPlugin : this.$pluginSelect.find('option').val(); } } diff --git a/core/modules/file/file.js b/core/modules/file/file.js index 8f0c9db..73487e2 100644 --- a/core/modules/file/file.js +++ b/core/modules/file/file.js @@ -13,6 +13,8 @@ /** * Attach behaviors to managed file element upload fields. + * + * @type {Drupal~behavior} */ Drupal.behaviors.fileValidateAutoAttach = { attach: function (context, settings) { @@ -49,6 +51,8 @@ /** * Attach behaviors to managed file element upload fields. + * + * @type {Drupal~behavior} */ Drupal.behaviors.fileAutoUpload = { attach: function (context) { @@ -63,6 +67,8 @@ /** * Attach behaviors to the file upload and remove buttons. + * + * @type {Drupal~behavior} */ Drupal.behaviors.fileButtons = { attach: function (context) { @@ -79,6 +85,8 @@ /** * Attach behaviors to links within managed file elements. + * + * @type {Drupal~behavior} */ Drupal.behaviors.filePreviewLinks = { attach: function (context) { @@ -91,10 +99,17 @@ /** * File upload utility functions. + * + * @namespace */ Drupal.file = Drupal.file || { + /** * Client-side file input validation of file extensions. + * + * @name Drupal.file.validateExtension + * + * @param {jQuery.Event} event */ validateExtension: function (event) { event.preventDefault(); @@ -124,14 +139,24 @@ } } }, + /** * Trigger the upload_button mouse event to auto-upload as a managed file. + * + * @name Drupal.file.triggetUploadButton + * + * @param {jQuery.Event} event */ triggerUploadButton: function (event) { $(event.target).closest('.form-managed-file').find('.js-form-submit').trigger('mousedown'); }, + /** * Prevent file uploads when using buttons not intended to upload. + * + * @name Drupal.file.disableFields + * + * @param {jQuery.Event} event */ disableFields: function (event) { var $clickedButton = $(this).findOnce('ajax'); @@ -149,20 +174,26 @@ // Temporarily disable upload fields other than the one we're currently // working with. Filter out fields that are already disabled so that they - // do not get enabled when we re-enable these fields at the end of behavior - // processing. Re-enable in a setTimeout set to a relatively short amount - // of time (1 second). All the other mousedown handlers (like Drupal's Ajax - // behaviors) are executed before any timeout functions are called, so we - // don't have to worry about the fields being re-enabled too soon. - // @todo If the previous sentence is true, why not set the timeout to 0? + // do not get enabled when we re-enable these fields at the end of + // behavior processing. Re-enable in a setTimeout set to a relatively + // short amount of time (1 second). All the other mousedown handlers + // (like Drupal's Ajax behaviors) are executed before any timeout + // functions are called, so we don't have to worry about the fields being + // re-enabled too soon. @todo If the previous sentence is true, why not + // set the timeout to 0? var $fieldsToTemporarilyDisable = $('div.form-managed-file input.form-file').not($enabledFields).not(':disabled'); $fieldsToTemporarilyDisable.prop('disabled', true); setTimeout(function () { $fieldsToTemporarilyDisable.prop('disabled', false); }, 1000); }, + /** * Add progress bar support if possible. + * + * @name Drupal.file.progressBar + * + * @param {jQuery.Event} event */ progressBar: function (event) { var $clickedButton = $(this); @@ -183,8 +214,13 @@ $clickedButton.closest('div.form-managed-file').find('div.ajax-progress-bar').slideDown(); }, 500); }, + /** * Open links to files within forms in a new window. + * + * @name Drupal.file.openInNewWindow + * + * @param {jQuery.Event} event */ openInNewWindow: function (event) { event.preventDefault(); diff --git a/core/modules/filter/filter.admin.js b/core/modules/filter/filter.admin.js index ba650c8..e14634c 100644 --- a/core/modules/filter/filter.admin.js +++ b/core/modules/filter/filter.admin.js @@ -7,6 +7,10 @@ "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.filterStatus = { attach: function (context, settings) { var $context = $(context); diff --git a/core/modules/filter/filter.filter_html.admin.js b/core/modules/filter/filter.filter_html.admin.js index d8e36c4..0854cf8 100644 --- a/core/modules/filter/filter.filter_html.admin.js +++ b/core/modules/filter/filter.filter_html.admin.js @@ -7,12 +7,19 @@ "use strict"; - /** - * Implement a live setting parser to prevent text editors from automatically - * enabling buttons that are not allowed by this filter's configuration. - */ if (Drupal.filterConfiguration) { + + /** + * Implement a live setting parser to prevent text editors from automatically + * enabling buttons that are not allowed by this filter's configuration. + * + * @namespace + */ Drupal.filterConfiguration.liveSettingParsers.filter_html = { + + /** + * @return {Array} + */ getRules: function () { var currentValue = $('#edit-filters-filter-html-settings-allowed-html').val(); var rules = []; @@ -37,6 +44,12 @@ }; } + /** + * + * @type {Drupal~behavior} + * + * @todo Remove everything but 'attach' and 'detach' and make a proper object. + */ Drupal.behaviors.filterFilterHtmlUpdating = { // The form item contains the "Allowed HTML tags" setting. @@ -114,12 +127,12 @@ * The filter_html filter is only concerned with the required tags, not with * any properties, nor with each feature's "allowed" tags. * - * @param Array userAllowedTags + * @param {Array} userAllowedTags * The list of user-defined allowed tags. - * @param Object newFeatures + * @param {object} newFeatures * A list of Drupal.EditorFeature objects' rules, keyed by their name. * - * @return Array + * @return {Array} * A list of new allowed tags. */ _calculateAutoAllowedTags: function (userAllowedTags, newFeatures) { @@ -141,10 +154,10 @@ /** * Parses the value of this.$allowedHTMLFormItem. * - * @param String setting + * @param {string} setting * The string representation of the setting. e.g. "


" * - * @return Array + * @return {Array} * The array representation of the setting. e.g. ['p', 'br', 'a'] */ _parseSetting: function (setting) { @@ -154,10 +167,10 @@ /** * Generates the value of this.$allowedHTMLFormItem. * - * @param Array setting + * @param {Array} tags * The array representation of the setting. e.g. ['p', 'br', 'a'] * - * @return Array + * @return {Array} * The string representation of the setting. e.g. "


" */ _generateSetting: function (tags) { @@ -169,9 +182,10 @@ /** * Theme function for the filter_html update message. * - * @param Array tags + * @param {Array} tags * An array of the new tags that are to be allowed. - * @return + * + * @return {string} * The corresponding HTML. */ Drupal.theme.filterFilterHTMLUpdateMessage = function (tags) { diff --git a/core/modules/filter/filter.js b/core/modules/filter/filter.js index 38797e5..58b595f 100644 --- a/core/modules/filter/filter.js +++ b/core/modules/filter/filter.js @@ -9,6 +9,8 @@ /** * Displays the guidelines of the selected text format automatically. + * + * @type {Drupal~behavior} */ Drupal.behaviors.filterGuidelines = { attach: function (context) { diff --git a/core/modules/history/js/history.js b/core/modules/history/js/history.js index 5030790..cba7787 100644 --- a/core/modules/history/js/history.js +++ b/core/modules/history/js/history.js @@ -1,8 +1,10 @@ /** + * @file * JavaScript API for the History module, with client-side caching. * * May only be loaded for authenticated users, with the History module enabled. */ + (function ($, Drupal, drupalSettings, storage) { "use strict"; @@ -19,14 +21,17 @@ embeddedLastReadTimestamps = drupalSettings.history.lastReadTimestamps; } + /** + * @namespace + */ Drupal.history = { /** * Fetch "last read" timestamps for the given nodes. * - * @param Array nodeIDs + * @param {Array} nodeIDs * An array of node IDs. - * @param Function callback + * @param {function} callback * A callback that is called after the requested timestamps were fetched. */ fetchTimestamps: function (nodeIDs, callback) { @@ -55,10 +60,10 @@ /** * Get the last read timestamp for the given node. * - * @param Number|String nodeID + * @param {number|string} nodeID * A node ID. * - * @return Number + * @return {number} * A UNIX timestamp. */ getLastRead: function (nodeID) { @@ -72,7 +77,7 @@ /** * Marks a node as read, store the last read timestamp in client-side storage. * - * @param Number|String nodeID + * @param {number|string} nodeID * A node ID. */ markAsRead: function (nodeID) { @@ -98,12 +103,12 @@ * Any content that was published before the oldest known reading also never * gets a "new" or "updated" indicator, because it must've been read already. * - * @param Number|String nodeID + * @param {number|string} nodeID * A node ID. - * @param Number contentTimestamp + * @param {number} contentTimestamp * The time at which some content (e.g. a comment) was published. * - * @return Boolean + * @return {bool} * Whether a server check is necessary for the given node and its timestamp. */ needsServerCheck: function (nodeID, contentTimestamp) { diff --git a/core/modules/history/js/mark-as-read.js b/core/modules/history/js/mark-as-read.js index b2ba518..848d351 100644 --- a/core/modules/history/js/mark-as-read.js +++ b/core/modules/history/js/mark-as-read.js @@ -1,8 +1,12 @@ /** + * @file * Marks the nodes listed in drupalSettings.history.nodesToMarkAsRead as read. * * Uses the History module JavaScript API. + * + * @see Drupal.history */ + (function (window, Drupal, drupalSettings) { "use strict"; diff --git a/core/modules/language/language.admin.js b/core/modules/language/language.admin.js index cea77c6..7f59a86 100644 --- a/core/modules/language/language.admin.js +++ b/core/modules/language/language.admin.js @@ -1,9 +1,16 @@ +/** + * @file + * Language admin behavior. + */ + (function ($, Drupal) { "use strict"; /** * Makes language negotiation inherit user interface negotiation. + * + * @type {Drupal~behavior} */ Drupal.behaviors.negotiationLanguage = { attach: function () { diff --git a/core/modules/locale/locale.admin.js b/core/modules/locale/locale.admin.js index 9c32c5e..c7bac21 100644 --- a/core/modules/locale/locale.admin.js +++ b/core/modules/locale/locale.admin.js @@ -1,9 +1,16 @@ +/** + * @file + * Locale admin behavior. + */ + (function ($, Drupal) { "use strict"; /** - * Marks changes of translations + * Marks changes of translations. + * + * @type {Drupal~behavior} */ Drupal.behaviors.localeTranslateDirty = { attach: function () { @@ -41,6 +48,8 @@ /** * Show/hide the description details on Available translation updates page. + * + * @type {Drupal~behavior} */ Drupal.behaviors.hideUpdateInformation = { attach: function (context, settings) { @@ -73,10 +82,20 @@ } }; - $.extend(Drupal.theme, { + $.extend(Drupal.theme, /** @lends Drupal.theme */{ + + /** + * + * @return {string} + */ localeTranslateChangedMarker: function () { return '*'; }, + + /** + * + * @return {string} + */ localeTranslateChangedWarning: function () { return '

' + Drupal.theme('localeTranslateChangedMarker') + ' ' + Drupal.t('Changes made in this table will not be saved until the form is submitted.') + '
'; } diff --git a/core/modules/locale/locale.bulk.js b/core/modules/locale/locale.bulk.js index 80952d0..7ddafd0 100644 --- a/core/modules/locale/locale.bulk.js +++ b/core/modules/locale/locale.bulk.js @@ -1,3 +1,8 @@ +/** + * @file + * Locale behavior. + */ + (function ($, Drupal) { "use strict"; @@ -6,6 +11,8 @@ * Select the language code of an imported file based on its filename. * * This only works if the file name ends with "LANGCODE.po". + * + * @type {Drupal~behavior} */ Drupal.behaviors.importLanguageCodeSelector = { attach: function (context, settings) { diff --git a/core/modules/locale/locale.datepicker.js b/core/modules/locale/locale.datepicker.js index 4628eda..197fc42 100644 --- a/core/modules/locale/locale.datepicker.js +++ b/core/modules/locale/locale.datepicker.js @@ -9,6 +9,8 @@ /** * Attaches language support to the jQuery UI datepicker component. + * + * @type {Drupal~behavior} */ Drupal.behaviors.localeDatepicker = { attach: function (context, settings) { diff --git a/core/modules/locale/tests/locale_test.js b/core/modules/locale/tests/locale_test.js index 336d979..ba62b75 100644 --- a/core/modules/locale/tests/locale_test.js +++ b/core/modules/locale/tests/locale_test.js @@ -1,6 +1,8 @@ /** * @file * JavaScript for locale_test.module. + * + * @ignore */ Drupal.t("Standard Call t"); diff --git a/core/modules/menu_ui/menu_ui.admin.js b/core/modules/menu_ui/menu_ui.admin.js index 8c037c5..5120d6e 100644 --- a/core/modules/menu_ui/menu_ui.admin.js +++ b/core/modules/menu_ui/menu_ui.admin.js @@ -1,7 +1,16 @@ +/** + * @file + * Menu UI admin behaviors. + */ + (function ($) { "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.menuUiChangeParentItems = { attach: function (context, settings) { var $menu = $('#edit-menu').once('menu-parent'); diff --git a/core/modules/menu_ui/menu_ui.js b/core/modules/menu_ui/menu_ui.js index 3859b7a..2103952 100644 --- a/core/modules/menu_ui/menu_ui.js +++ b/core/modules/menu_ui/menu_ui.js @@ -1,7 +1,16 @@ +/** + * @file + * Menu UI behaviors. + */ + (function ($) { "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.menuUiDetailsSummaries = { attach: function (context) { $(context).find('.menu-link-form').drupalSetSummary(function (context) { @@ -18,6 +27,8 @@ /** * Automatically fill in a menu link title, if possible. + * + * @type {Drupal~behavior} */ Drupal.behaviors.menuUiLinkAutomaticTitle = { attach: function (context) { diff --git a/core/modules/node/content_types.js b/core/modules/node/content_types.js index c77a2c3..77ab168 100644 --- a/core/modules/node/content_types.js +++ b/core/modules/node/content_types.js @@ -7,6 +7,10 @@ "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.contentTypes = { attach: function (context) { var $context = $(context); diff --git a/core/modules/node/node.js b/core/modules/node/node.js index cf0f979..af2ed46 100644 --- a/core/modules/node/node.js +++ b/core/modules/node/node.js @@ -7,6 +7,10 @@ "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.nodeDetailsSummaries = { attach: function (context) { var $context = $(context); diff --git a/core/modules/node/node.preview.js b/core/modules/node/node.preview.js index 09ce7a0..d69cf3b 100644 --- a/core/modules/node/node.preview.js +++ b/core/modules/node/node.preview.js @@ -1,3 +1,8 @@ +/** + * @file + * Preview behaviors. + */ + (function ($, Drupal) { "use strict"; @@ -5,6 +10,8 @@ /** * Disabling all links (except local fragment identifiers such as href="#frag") * in node previews to prevent users from leaving the page. + * + * @type {Drupal~behavior} */ Drupal.behaviors.nodePreviewDestroyLinks = { attach: function (context) { @@ -52,6 +59,8 @@ /** * Switch view mode. + * + * @type {Drupal~behavior} */ Drupal.behaviors.nodePreviewSwitchViewMode = { attach: function (context) { @@ -64,6 +73,10 @@ } }; + /** + * + * @return {string} + */ Drupal.theme.nodePreviewModal = function () { return '

' + Drupal.t('Leaving the preview will cause unsaved changes to be lost. Are you sure you want to leave the preview?') + diff --git a/core/modules/path/path.js b/core/modules/path/path.js index aa91bb2..474cf87 100644 --- a/core/modules/path/path.js +++ b/core/modules/path/path.js @@ -6,6 +6,10 @@ "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.pathDetailsSummaries = { attach: function (context) { $(context).find('.path-form').drupalSetSummary(function (context) { diff --git a/core/modules/simpletest/simpletest.js b/core/modules/simpletest/simpletest.js index b1c63de..6630cc4 100644 --- a/core/modules/simpletest/simpletest.js +++ b/core/modules/simpletest/simpletest.js @@ -1,9 +1,16 @@ +/** + * @file + * Simpletest behaviors. + */ + (function ($) { "use strict"; /** * Collapses table rows followed by group rows on the test listing page. + * + * @type {Drupal~behavior} */ Drupal.behaviors.simpleTestGroupCollapse = { attach: function (context) { @@ -25,6 +32,8 @@ /** * Toggles test checkboxes to match the group checkbox. + * + * @type {Drupal~behavior} */ Drupal.behaviors.simpleTestSelectAll = { attach: function (context) { @@ -64,6 +73,8 @@ * Text search input: input.table-filter-text * Target table: input.table-filter-text[data-table] * Source text: .table-filter-text-source + * + * @type {Drupal~behavior} */ Drupal.behaviors.simpletestTableFilterByText = { attach: function (context) { diff --git a/core/modules/statistics/statistics.js b/core/modules/statistics/statistics.js index 35bba66..f892dd4 100644 --- a/core/modules/statistics/statistics.js +++ b/core/modules/statistics/statistics.js @@ -1,3 +1,8 @@ +/** + * @file + * Statistics functionality. + */ + (function ($, Drupal, drupalSettings) { "use strict"; diff --git a/core/modules/system/system.js b/core/modules/system/system.js index 31096f9..e052c3f 100644 --- a/core/modules/system/system.js +++ b/core/modules/system/system.js @@ -1,3 +1,8 @@ +/** + * @file + * System behaviors. + */ + (function ($, Drupal, drupalSettings) { "use strict"; @@ -9,6 +14,8 @@ * When a field is filled out, apply its value to other fields that will likely * use the same value. In the installer this is used to populate the * administrator email address with the same value as the site email address. + * + * @type {Drupal~behavior} */ Drupal.behaviors.copyFieldValue = { attach: function (context) { @@ -34,12 +41,13 @@ $('#' + ids.join(', #')).removeOnce('copy-field-values').off('blur'); } }, + /** * Event handler that fill the target element with the specified value. * - * @param e + * @param {jQuery.Event} e * Event object. - * @param value + * @param {string} value * Custom value from jQuery trigger. */ valueTargetCopyHandler: function (e, value) { @@ -48,10 +56,13 @@ $target.val(value); } }, + /** * Handler for a Blur event on a source field. * * This event handler will trigger a 'value:copy' event on all dependent fields. + * + * @param {jQuery.Event} e */ valueSourceBlurHandler: function (e) { var value = $(e.target).val(); diff --git a/core/modules/system/system.modules.js b/core/modules/system/system.modules.js index 45ddf3b..49a9879 100644 --- a/core/modules/system/system.modules.js +++ b/core/modules/system/system.modules.js @@ -1,3 +1,8 @@ +/** + * @file + * Module page behaviors. + */ + (function ($, Drupal) { "use strict"; @@ -11,6 +16,8 @@ * Text search input: input.table-filter-text * Target table: input.table-filter-text[data-table] * Source text: .table-filter-text-source + * + * @type {Drupal~behavior} */ Drupal.behaviors.tableFilterByText = { attach: function (context, settings) { diff --git a/core/modules/system/tests/modules/twig_theme_test/twig_theme_test.js b/core/modules/system/tests/modules/twig_theme_test/twig_theme_test.js index 28364a2..39bf0bb 100644 --- a/core/modules/system/tests/modules/twig_theme_test/twig_theme_test.js +++ b/core/modules/system/tests/modules/twig_theme_test/twig_theme_test.js @@ -1,2 +1,6 @@ - -/* This file is for testing asset file inclusion, no contents are necessary. */ +/** + * @file + * This file is for testing asset file inclusion, no contents are necessary. + * + * @ignore + */ diff --git a/core/modules/taxonomy/taxonomy.js b/core/modules/taxonomy/taxonomy.js index 8ffe502..fb4c0ce 100644 --- a/core/modules/taxonomy/taxonomy.js +++ b/core/modules/taxonomy/taxonomy.js @@ -1,3 +1,8 @@ +/** + * @file + * Taxonomy behaviors. + */ + (function ($) { "use strict"; @@ -7,12 +12,15 @@ * * 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.termDrag = { attach: function (context, settings) { var backStep = settings.taxonomy.backStep; var forwardStep = settings.taxonomy.forwardStep; - var tableDrag = Drupal.tableDrag.taxonomy; // Get the blocks tableDrag object. + // Get the blocks tableDrag object. + var tableDrag = Drupal.tableDrag.taxonomy; var $table = $('#taxonomy'); var rows = $table.find('tr').length; diff --git a/core/modules/text/text.js b/core/modules/text/text.js index 7360e44..82fdf2a 100644 --- a/core/modules/text/text.js +++ b/core/modules/text/text.js @@ -1,9 +1,16 @@ +/** + * @file + * Text behaviors. + */ + (function ($) { "use strict"; /** * Auto-hide summary textarea if empty and show hide and unhide links. + * + * @type {Drupal~behavior} */ Drupal.behaviors.textSummary = { attach: function (context, settings) { diff --git a/core/modules/tour/js/tour.js b/core/modules/tour/js/tour.js index 08e5688..d4f8bca 100644 --- a/core/modules/tour/js/tour.js +++ b/core/modules/tour/js/tour.js @@ -14,12 +14,14 @@ * * It uses the query string for: * - tour: When ?tour=1 is present, the tour will start automatically - * after the page has loaded. + * after the page has loaded. * - tips: Pass ?tips=class in the url to filter the available tips to - * the subset which match the given class. + * the subset which match the given class. * - * Example: - * http://example.com/foo?tour=1&tips=bar + * @example + * http://example.com/foo?tour=1&tips=bar + * + * @type {Drupal~behavior} */ Drupal.behaviors.tour = { attach: function (context) { @@ -35,7 +37,8 @@ .on('change:isActive', function (model, isActive) { $(document).trigger((isActive) ? 'drupalTourStarted' : 'drupalTourStopped'); }) - // Initialization: check whether a tour is available on the current page. + // Initialization: check whether a tour is available on the current + // page. .set('tour', $(context).find('ol#tour')); // Start the tour immediately if toggled via query string. @@ -46,31 +49,72 @@ } }; - Drupal.tour = Drupal.tour || {models: {}, views: {}}; + /** + * @namespace + */ + Drupal.tour = Drupal.tour || { + + /** + * @namespace Drupal.tour.models + */ + models: {}, + + /** + * @namespace Drupal.tour.views + */ + views: {} + }; /** * Backbone Model for tours. + * + * @constructor + * + * @augments Backbone.Model */ - Drupal.tour.models.StateModel = Backbone.Model.extend({ - defaults: { - // Indicates whether the Drupal root window has a tour. + Drupal.tour.models.StateModel = Backbone.Model.extend(/** @lends Drupal.tour.models.StateModel# */{ + + /** + * @type {object} + */ + defaults: /** @lends Drupal.tour.models.StateModel# */{ + + /** + * Indicates whether the Drupal root window has a tour. + * + * @type {Array} + */ tour: [], - // Indicates whether the tour is currently running. + + /** + * Indicates whether the tour is currently running. + * + * @type {bool} + */ isActive: false, - // Indicates which tour is the active one (necessary to cleanly stop). + + /** + * Indicates which tour is the active one (necessary to cleanly stop). + * + * @type {Array} + */ activeTour: [] } }); - /** - * Handles edit mode toggle interactions. - */ - Drupal.tour.views.ToggleTourView = Backbone.View.extend({ + Drupal.tour.views.ToggleTourView = Backbone.View.extend(/** @lends Drupal.tour.views.ToggleTourView# */{ + /** + * @type {object} + */ events: {'click': 'onClick'}, /** - * Implements Backbone Views' initialize(). + * Handles edit mode toggle interactions. + * + * @constructs + * + * @augments Backbone.View */ initialize: function () { this.listenTo(this.model, 'change:tour change:isActive', this.render); @@ -78,7 +122,9 @@ }, /** - * Implements Backbone Views' render(). + * @inheritdoc + * + * @return {Drupal.tour.views.ToggleTourView} */ render: function () { // Render the visibility. @@ -103,7 +149,8 @@ $tour.joyride({ autoStart: true, postRideCallback: function () { that.model.set('isActive', false); }, - template: { // HTML segments for tip layout + // HTML segments for tip layout. + template: { link: '×', button: '' } @@ -119,6 +166,8 @@ /** * Toolbar tab click event handler; toggles isActive. + * + * @param {jQuery.Event} event */ onClick: function (event) { this.model.set('isActive', !this.model.get('isActive')); @@ -129,8 +178,8 @@ /** * Gets the tour. * - * @return jQuery - * A jQuery element pointing to a

    containing tour items. + * @return {jQuery} + * A jQuery element pointing to a `
      ` containing tour items. */ _getTour: function () { return this.model.get('tour'); @@ -139,7 +188,7 @@ /** * Gets the relevant document as a jQuery element. * - * @return jQuery + * @return {jQuery} * A jQuery element pointing to the document within which a tour would be * started given the current state. */ @@ -148,22 +197,21 @@ }, /** - * Removes tour items for elements that don't have matching page elements or - * are explicitly filtered out via the 'tips' query string. + * Removes tour items for elements that don't have matching page elements. * - * Example: - * http://example.com/foo?tips=bar + * Or that are explicitly filtered out via the 'tips' query string. * - * The above will filter out tips that do not have a matching page element or - * don't have the "bar" class. + * @example This will filter out tips that do not have a matching + * page element or don't have the "bar" class. + * http://example.com/foo?tips=bar * - * @param jQuery $tour - * A jQuery element pointing to a
        containing tour items. - * @param jQuery $document + * @param {jQuery} $tour + * A jQuery element pointing to a `
          ` containing tour items. + * @param {jQuery} $document * A jQuery element pointing to the document within which the elements * should be sought. * - * @see _getDocument() + * @see Drupal.tour.views.ToggleTourView#_getDocument() */ _removeIrrelevantTourItems: function ($tour, $document) { var removals = false; diff --git a/core/modules/user/user.js b/core/modules/user/user.js index 615689c..e988f74 100644 --- a/core/modules/user/user.js +++ b/core/modules/user/user.js @@ -1,10 +1,17 @@ +/** + * @file + * User behaviors. + */ + (function ($, Drupal, drupalSettings) { "use strict"; /** - * Attach handlers to evaluate the strength of any password fields and to check - * that its confirmation is correct. + * Attach handlers to evaluate the strength of any password fields and to + * check that its confirmation is correct. + * + * @type {Drupal~behavior} */ Drupal.behaviors.password = { attach: function (context, settings) { @@ -60,7 +67,8 @@ $passwordSuggestions.html(result.message); } - // Only show the description box if a weakness exists in the password. + // Only show the description box if a weakness exists in the + // password. $passwordSuggestions.toggle(result.strength !== 100); // Adjust the length of the strength indicator. @@ -94,6 +102,11 @@ * Evaluate the strength of a user's password. * * Returns the estimated strength and the relevant output message. + * + * @param {string} password + * @param {object} translate + * + * @return {object} */ Drupal.evaluatePasswordStrength = function (password, translate) { var indicatorText; @@ -107,8 +120,8 @@ var hasNumbers = /[0-9]/.test(password); var hasPunctuation = /[^a-zA-Z0-9]/.test(password); - // If there is a username edit box on the page, compare password to that, otherwise - // use value from the database. + // If there is a username edit box on the page, compare password to that, + // otherwise use value from the database. var $usernameBox = $('input.username'); var username = ($usernameBox.length > 0) ? $usernameBox.val() : translate.username; @@ -162,7 +175,8 @@ strength = 5; } - // Based on the strength, work out what text should be shown by the password strength meter. + // Based on the strength, work out what text should be shown by the + // password strength meter. if (strength < 60) { indicatorText = translate.weak; indicatorClass = 'is-weak'; diff --git a/core/modules/user/user.permissions.js b/core/modules/user/user.permissions.js index 6e473fa..4db8454 100644 --- a/core/modules/user/user.permissions.js +++ b/core/modules/user/user.permissions.js @@ -1,9 +1,16 @@ +/** + * @file + * User permission page behaviors. + */ + (function ($) { "use strict"; /** * Shows checked and disabled checkboxes for inherited permissions. + * + * @type {Drupal~behavior} */ Drupal.behaviors.permissions = { attach: function (context) { diff --git a/core/modules/views/js/ajax_view.js b/core/modules/views/js/ajax_view.js index 65017ff..1b9f118 100644 --- a/core/modules/views/js/ajax_view.js +++ b/core/modules/views/js/ajax_view.js @@ -2,12 +2,16 @@ * @file * Handles AJAX fetching of views, including filter submission and response. */ + (function ($, Drupal, drupalSettings) { "use strict"; /** - * Attaches the AJAX behavior to Views exposed filter forms and key View links. + * Attaches the AJAX behavior to Views exposed filter forms and key View + * links. + * + * @type {Drupal~behavior} */ Drupal.behaviors.ViewsAjaxView = {}; Drupal.behaviors.ViewsAjaxView.attach = function () { @@ -21,11 +25,23 @@ } }; + /** + * @namespace + */ Drupal.views = {}; + + /** + * @type {object.} + */ Drupal.views.instances = {}; /** * Javascript object for a certain view. + * + * @constructor + * + * @param {object} settings + * @param {string} settings.view_dom_id */ Drupal.views.ajaxView = function (settings) { var selector = '.js-view-dom-id-' + settings.view_dom_id; @@ -34,7 +50,8 @@ // Retrieve the path to use for views' ajax. var ajax_path = drupalSettings.views.ajax_path; - // If there are multiple views this might've ended up showing up multiple times. + // If there are multiple views this might've ended up showing up multiple + // times. if (ajax_path.constructor.toString().indexOf("Array") !== -1) { ajax_path = ajax_path[0]; } @@ -45,7 +62,8 @@ // Remove the question mark and Drupal path component if any. queryString = queryString.slice(1).replace(/q=[^&]+&?|&?render=[^&]+/, ''); if (queryString !== '') { - // If there is a '?' in ajax_path, clean url are on and & should be used to add parameters. + // If there is a '?' in ajax_path, clean url are on and & should be + // used to add parameters. queryString = ((/\?/.test(ajax_path)) ? '&' : '?') + queryString; } } @@ -86,6 +104,9 @@ this.refreshViewAjax = Drupal.ajax(self_settings); }; + /** + * @method + */ Drupal.views.ajaxView.prototype.attachExposedFormAjax = function () { var button = $('input[type=submit], input[type=image]', this.$exposed_form); button = button[0]; @@ -97,6 +118,12 @@ this.exposedFormAjax = Drupal.ajax(self_settings); }; + /** + * @return {bool} + * If there is at least one parent with a view class return false. + * + * @todo remove .size() replace with .length. + */ Drupal.views.ajaxView.prototype.filterNestedViews = function () { // If there is at least one parent with a view class, this view // is nested (e.g., an attachment). Bail. @@ -113,6 +140,9 @@ /** * Attach the ajax behavior to a singe link. + * + * @param {string} id + * @param {HTMLElement} link */ Drupal.views.ajaxView.prototype.attachPagerLinkAjax = function (id, link) { var $link = $(link); @@ -136,6 +166,12 @@ this.pagerAjax = Drupal.ajax(self_settings); }; + /** + * + * @param {Drupal.Ajax} [ajax] + * @param {object} response + * @param {string} response.selector + */ Drupal.AjaxCommands.prototype.viewsScrollTop = function (ajax, response) { // Scroll to the top of the view. This will allow users // to browse newly loaded content after e.g. clicking a pager @@ -149,7 +185,7 @@ while ($(scrollTarget).scrollTop() === 0 && $(scrollTarget).parent()) { scrollTarget = $(scrollTarget).parent(); } - // Only scroll upward + // Only scroll upward. if (offset.top - 10 < $(scrollTarget).scrollTop()) { $(scrollTarget).animate({scrollTop: (offset.top - 10)}, 500); } diff --git a/core/modules/views/js/base.js b/core/modules/views/js/base.js index d28b21d..d428229 100644 --- a/core/modules/views/js/base.js +++ b/core/modules/views/js/base.js @@ -2,14 +2,22 @@ * @file * Some basic behaviors and utility functions for Views. */ + (function ($, Drupal, drupalSettings) { "use strict"; + /** + * @namespace + */ Drupal.Views = {}; /** * Helper function to parse a querystring. + * + * @param {string} query + * + * @return {object} */ Drupal.Views.parseQueryString = function (query) { var args = {}; @@ -31,6 +39,11 @@ /** * Helper function to return a view's arguments based on a path. + * + * @param {string} href + * @param {string} viewPath + * + * @return {object} */ Drupal.Views.parseViewArgs = function (href, viewPath) { var returnObj = {}; @@ -46,12 +59,16 @@ /** * Strip off the protocol plus domain from an href. + * + * @param {string} href + * + * @return {string} */ Drupal.Views.pathPortion = function (href) { // Remove e.g. http://example.com if present. var protocol = window.location.protocol; if (href.substring(0, protocol.length) === protocol) { - // 2 is the length of the '//' that normally follows the protocol + // 2 is the length of the '//' that normally follows the protocol. href = href.substring(href.indexOf('/', protocol.length + 2)); } return href; @@ -59,6 +76,10 @@ /** * Return the Drupal path portion of an href. + * + * @param {string} href + * + * @return {string} */ Drupal.Views.getPath = function (href) { href = Drupal.Views.pathPortion(href); diff --git a/core/modules/views/js/views-contextual.js b/core/modules/views/js/views-contextual.js index e5eb14b..e0fe169 100644 --- a/core/modules/views/js/views-contextual.js +++ b/core/modules/views/js/views-contextual.js @@ -2,10 +2,15 @@ * @file * Javascript related to contextual links. */ + (function ($) { "use strict"; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsContextualLinks = { attach: function (context) { var id = $('body').attr('data-views-page-contextual-id'); diff --git a/core/modules/views/tests/modules/views_test_data/views_cache.test.js b/core/modules/views/tests/modules/views_test_data/views_cache.test.js index 8dd17c1..4089267 100644 --- a/core/modules/views/tests/modules/views_test_data/views_cache.test.js +++ b/core/modules/views/tests/modules/views_test_data/views_cache.test.js @@ -1,5 +1,8 @@ /** * @file * Just a placeholder file for the test. + * * @see ViewsCacheTest::testHeaderStorage + * + * @ignore */ diff --git a/core/modules/views_ui/js/ajax.js b/core/modules/views_ui/js/ajax.js index 492b63e..3079bad 100644 --- a/core/modules/views_ui/js/ajax.js +++ b/core/modules/views_ui/js/ajax.js @@ -2,15 +2,30 @@ * @file * Handles AJAX submission and response in Views UI. */ + (function ($, Drupal, drupalSettings) { "use strict"; + /** + * + * @param {Drupal.Ajax} [ajax] + * @param {object} response + * @param {string} response.selector + * @param {number} [status] + */ Drupal.AjaxCommands.prototype.viewsHighlight = function (ajax, response, status) { $('.hilited').removeClass('hilited'); $(response.selector).addClass('hilited'); }; + /** + * + * @param {Drupal.Ajax} [ajax] + * @param {object} response + * @param {bool} response.changed + * @param {number} [status] + */ Drupal.AjaxCommands.prototype.viewsShowButtons = function (ajax, response, status) { $('div.views-edit-view div.form-actions').removeClass('js-hide'); if (response.changed) { @@ -18,12 +33,26 @@ } }; + /** + * + * @param {Drupal.Ajax} [ajax] + * @param {object} [response] + * @param {number} [status] + */ Drupal.AjaxCommands.prototype.viewsTriggerPreview = function (ajax, response, status) { if ($('input#edit-displays-live-preview').is(':checked')) { $('#preview-submit').trigger('click'); } }; + /** + * + * @param {Drupal.Ajax} [ajax] + * @param {object} response + * @param {string} response.siteName + * @param {string} response.title + * @param {number} [status] + */ Drupal.AjaxCommands.prototype.viewsReplaceTitle = function (ajax, response, status) { var doc = document; // For the element, make a best-effort attempt to replace the page @@ -40,7 +69,9 @@ }; /** - * Get rid of irritating tabledrag messages + * Get rid of irritating tabledrag messages. + * + * @return {Array} */ Drupal.theme.tableDragChangedWarning = function () { return []; @@ -48,6 +79,8 @@ /** * Trigger preview when the "live preview" checkbox is checked. + * + * @type {Drupal~behavior} */ Drupal.behaviors.livePreview = { attach: function (context) { @@ -61,6 +94,8 @@ /** * Sync preview display. + * + * @type {Drupal~behavior} */ Drupal.behaviors.syncPreviewDisplay = { attach: function (context) { @@ -74,6 +109,10 @@ } }; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsAjax = { collapseReplaced: false, attach: function (context, settings) { diff --git a/core/modules/views_ui/js/dialog.views.js b/core/modules/views_ui/js/dialog.views.js index bdfd185..6f22e7f 100644 --- a/core/modules/views_ui/js/dialog.views.js +++ b/core/modules/views_ui/js/dialog.views.js @@ -1,3 +1,8 @@ +/** + * @file + * Views dialog behaviors. + */ + (function ($, Drupal, drupalSettings) { "use strict"; @@ -25,6 +30,10 @@ } } + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsModalContent = { attach: function (context) { $('body').once('viewsDialog').on('dialogContentResize.viewsDialog', '.ui-dialog-content', handleDialogResize); diff --git a/core/modules/views_ui/js/views-admin.js b/core/modules/views_ui/js/views-admin.js index 16df3bc..03407ee 100644 --- a/core/modules/views_ui/js/views-admin.js +++ b/core/modules/views_ui/js/views-admin.js @@ -2,14 +2,20 @@ * @file * Some basic behaviors and utility functions for Views UI. */ + (function ($, Drupal, drupalSettings) { "use strict"; + /** + * @namespace + */ Drupal.viewsUi = {}; /** * Improve the user experience of the views edit interface. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsUiEditView = { attach: function () { @@ -22,8 +28,10 @@ }; /** - * In the add view wizard, use the view name to prepopulate form fields such as - * page title and menu link. + * In the add view wizard, use the view name to prepopulate form fields such + * as page title and menu link. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsUiAddView = { attach: function (context) { @@ -33,8 +41,8 @@ var replace = '-'; var suffix; - // The page title, block title, and menu link fields can all be prepopulated - // with the view name - no regular expression needed. + // The page title, block title, and menu link fields can all be + // prepopulated with the view name - no regular expression needed. var $fields = $context.find('[id^="edit-page-title"], [id^="edit-block-title"], [id^="edit-page-link-properties-title"]'); if ($fields.length) { if (!this.fieldsFiller) { @@ -42,10 +50,11 @@ } else { // After an AJAX response, this.fieldsFiller will still have event - // handlers bound to the old version of the form fields (which don't exist - // anymore). The event handlers need to be unbound and then rebound to the - // new markup. Note that jQuery.live is difficult to make work in this - // case because the IDs of the form fields change on every AJAX response. + // handlers bound to the old version of the form fields (which don't + // exist anymore). The event handlers need to be unbound and then + // rebound to the new markup. Note that jQuery.live is difficult to + // make work in this case because the IDs of the form fields change + // on every AJAX response. this.fieldsFiller.rebind($fields); } } @@ -61,8 +70,8 @@ } } - // Populate the RSS feed field with a URLified version of the view name, and - // an .xml suffix (to make it unique). + // Populate the RSS feed field with a URLified version of the view name, + // and an .xml suffix (to make it unique). var $feedField = $context.find('[id^="edit-page-feed-properties-path"]'); if ($feedField.length) { if (!this.feedFiller) { @@ -81,38 +90,75 @@ * * Prepopulates a form field based on the view name. * - * @param $target + * @constructor + * + * @param {jQuery} $target * A jQuery object representing the form field or fields to prepopulate. - * @param exclude - * (optional) A regular expression representing characters to exclude from + * @param {bool} [exclude=false] + * A regular expression representing characters to exclude from * the target field. - * @param replace - * (optional) A string to use as the replacement value for disallowed - * characters. - * @param suffix - * (optional) A suffix to append at the end of the target field content. + * @param {string} [replace=''] + * A string to use as the replacement value for disallowed characters. + * @param {string} [suffix=''] + * A suffix to append at the end of the target field content. */ Drupal.viewsUi.FormFieldFiller = function ($target, exclude, replace, suffix) { + + /** + * + * @type {jQuery} + */ this.source = $('#edit-label'); + + /** + * + * @type {jQuery} + */ this.target = $target; + + /** + * + * @type {bool} + */ this.exclude = exclude || false; + + /** + * + * @type {string} + */ this.replace = replace || ''; + + /** + * + * @type {string} + */ this.suffix = suffix || ''; // Create bound versions of this instance's object methods to use as event - // handlers. This will let us easily unbind those specific handlers later on. - // NOTE: jQuery.proxy will not work for this because it assumes we want only - // one bound version of an object method, whereas we need one version per - // object instance. + // handlers. This will let us easily unbind those specific handlers later + // on. NOTE: jQuery.proxy will not work for this because it assumes we want + // only one bound version of an object method, whereas we need one version + // per object instance. var self = this; + + /** + * + * @return {*} + */ this.populate = function () { return self._populate.call(self); }; + + /** + * + * @return {*} + */ this.unbind = function () { return self._unbind.call(self); }; this.bind(); // Object constructor; no return value. }; - $.extend(Drupal.viewsUi.FormFieldFiller.prototype, { + $.extend(Drupal.viewsUi.FormFieldFiller.prototype, /** @lends Drupal.viewsUi.FormFieldFiller# */{ + /** * Bind the form-filling behavior. */ @@ -126,6 +172,8 @@ /** * Get the source form field value as altered by the passed-in parameters. + * + * @return {string} */ getTransliterated: function () { var from = this.source.val(); @@ -157,7 +205,9 @@ }, /** - * Bind event handlers to the new form fields, after they're replaced via AJAX. + * Bind event handlers to new form fields, after they're replaced via Ajax. + * + * @param {jQuery} $fields */ rebind: function ($fields) { this.target = $fields; @@ -165,6 +215,10 @@ } }); + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.addItemForm = { attach: function (context) { var $context = $(context); @@ -174,21 +228,45 @@ $form = $context.find('form[id^="views-ui-add-handler-form"]'); } if ($form.once('views-ui-add-handler-form').length) { - // If we we have an unprocessed views-ui-add-handler-form, let's instantiate. + // If we we have an unprocessed views-ui-add-handler-form, let's + // instantiate. new Drupal.viewsUi.AddItemForm($form); } } }; + /** + * + * @constructor + * + * @param {jQuery} $form + */ Drupal.viewsUi.AddItemForm = function ($form) { + + /** + * + * @type {jQuery} + */ this.$form = $form; this.$form.find('.views-filterable-options :checkbox').on('click', $.proxy(this.handleCheck, this)); - // Find the wrapper of the displayed text. + + /** + * Find the wrapper of the displayed text. + */ this.$selected_div = this.$form.find('.views-selected-options').parent(); this.$selected_div.hide(); + + /** + * + * @type {Array} + */ this.checkedItems = []; }; + /** + * + * @param {jQuery.Event} event + */ Drupal.viewsUi.AddItemForm.prototype.handleCheck = function (event) { var $target = $(event.target); var label = $.trim($target.next().text()); @@ -199,7 +277,8 @@ } else { var position = $.inArray(label, this.checkedItems); - // Delete the item from the list and make sure that the list doesn't have undefined items left. + // Delete the item from the list and make sure that the list doesn't have + // undefined items left. for (var i = 0; i < this.checkedItems.length; i++) { if (i === position) { this.checkedItems.splice(i, 1); @@ -226,9 +305,12 @@ }; /** - * The input field items that add displays must be rendered as <input> elements. - * The following behavior detaches the <input> elements from the DOM, wraps them - * in an unordered list, then appends them to the list of tabs. + * The input field items that add displays must be rendered as `<input>` + * elements. The following behavior detaches the `<input>` elements from the + * DOM, wraps them in an unordered list, then appends them to the list of + * tabs. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsUiRenderAddViewButton = { attach: function (context) { @@ -242,10 +324,9 @@ var $displayButtons = $menu.nextAll('input.add-display').detach(); $displayButtons.appendTo($addDisplayDropdown.find('.action-list')).wrap('<li>') .parent().eq(0).addClass('first').end().eq(-1).addClass('last'); - // Remove the 'Add ' prefix from the button labels since they're being placed - // in an 'Add' dropdown. - // @todo This assumes English, but so does $addDisplayDropdown above. Add - // support for translation. + // Remove the 'Add ' prefix from the button labels since they're being + // placed in an 'Add' dropdown. @todo This assumes English, but so does + // $addDisplayDropdown above. Add support for translation. $displayButtons.each(function () { var label = $(this).val(); if (label.substr(0, 4) === 'Add ') { @@ -254,7 +335,7 @@ }); $addDisplayDropdown.appendTo($menu); - // Add the click handler for the add display button + // Add the click handler for the add display button. $menu.find('li.add > a').on('click', function (event) { event.preventDefault(); var $trigger = $(this); @@ -278,14 +359,22 @@ }; /** - * @note [@jessebeach] I feel like the following should be a more generic function and - * not written specifically for this UI, but I'm not sure where to put it. + * @param {jQuery} $trigger + * + * + * @note [@jessebeach] I feel like the following should be a more generic + * function and not written specifically for this UI, but I'm not sure + * where to put it. */ Drupal.behaviors.viewsUiRenderAddViewButton.toggleMenu = function ($trigger) { $trigger.parent().toggleClass('open'); $trigger.next().slideToggle('fast'); }; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsUiSearchOptions = { attach: function (context) { var $context = $(context); @@ -305,17 +394,33 @@ * Constructor for the viewsUi.OptionsSearch object. * * The OptionsSearch object filters the available options on a form according - * to the user's search term. Typing in "taxonomy" will show only those options - * containing "taxonomy" in their label. + * to the user's search term. Typing in "taxonomy" will show only those + * options containing "taxonomy" in their label. + * + * @constructor + * + * @param {jQuery} $form */ Drupal.viewsUi.OptionsSearch = function ($form) { + + /** + * + * @type {jQuery} + */ this.$form = $form; - // Add a keyup handler to the search box. + + /** + * Add a keyup handler to the search box. + */ this.$searchBox = this.$form.find('#edit-override-controls-options-search'); this.$searchBox.on('keyup', $.proxy(this.handleKeyup, this)); - // Get a list of option labels and their corresponding divs and maintain it - // in memory, so we have as little overhead as possible at keyup time. + + /** + * Get a list of option labels and their corresponding divs and maintain it + * in memory, so we have as little overhead as possible at keyup time. + */ this.options = this.getOptions(this.$form.find('.filterable-option')); + // Restripe on initial loading. this.handleKeyup(); // Trap the ENTER key in the search box so that it doesn't submit the form. @@ -326,13 +431,16 @@ }); }; - $.extend(Drupal.viewsUi.OptionsSearch.prototype, { + $.extend(Drupal.viewsUi.OptionsSearch.prototype, /** @lends Drupal.viewsUi.OptionsSearch# */{ + /** * Assemble a list of all the filterable options on the form. * - * @param $allOptions - * A $ object representing the rows of filterable options to be + * @param {jQuery} $allOptions + * A jQuery object representing the rows of filterable options to be * shown and hidden depending on the user's search terms. + * + * @return {Array} */ getOptions: function ($allOptions) { var $label; @@ -357,15 +465,18 @@ }, /** - * Keyup handler for the search box that hides or shows the relevant options. + * Keyup handler for the search box that hides or shows the relevant + * options. + * + * @param {jQuery.Event} event */ handleKeyup: function (event) { var found; var option; var zebraClass; - // Determine the user's search query. The search text has been converted to - // lowercase. + // Determine the user's search query. The search text has been converted + // to lowercase. var search = this.$searchBox.val().toLowerCase(); var words = search.split(' '); var wordsLength = words.length; @@ -402,6 +513,10 @@ } }); + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsUiPreview = { attach: function (context) { // Only act on the edit view form. @@ -410,9 +525,10 @@ return; } - // If the display has no contextual filters, hide the form where you enter - // the contextual filters for the live preview. If it has contextual filters, - // show the form. + // If the display has no contextual filters, hide the form where you + // enter + // the contextual filters for the live preview. If it has contextual + // filters, show the form. var $contextualFilters = $contextualFiltersBucket.find('.views-display-setting a'); if ($contextualFilters.length) { $('#preview-args').parent().show(); @@ -428,6 +544,10 @@ } }; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsUiRearrangeFilter = { attach: function (context) { // Only act on the rearrange filter form. @@ -445,19 +565,49 @@ /** * Improve the UI of the rearrange filters dialog box. + * + * @constructor + * + * @param {jQuery} $table + * @param {jQuery} $operator */ Drupal.viewsUi.RearrangeFilterHandler = function ($table, $operator) { - // Keep a reference to the <table> being altered and to the div containing - // the filter groups operator dropdown (if it exists). + + /** + * Keep a reference to the `<table>` being altered and to the div containing + * the filter groups operator dropdown (if it exists). + */ this.table = $table; + + /** + * + * @type {jQuery} + */ this.operator = $operator; + + /** + * + * @type {bool} + */ this.hasGroupOperator = this.operator.length > 0; - // Keep a reference to all draggable rows within the table. + /** + * Keep a reference to all draggable rows within the table. + * + * @type {jQuery} + */ this.draggableRows = $table.find('.draggable'); - // Keep a reference to the buttons for adding and removing filter groups. + /** + * Keep a reference to the buttons for adding and removing filter groups. + * + * @type {jQuery} + */ this.addGroupButton = $('input#views-add-group'); + + /** + * @type {jQuery} + */ this.removeGroupButtons = $table.find('input.views-remove-group'); // Add links that duplicate the functionality of the (hidden) add and remove @@ -467,14 +617,17 @@ // When there is a filter groups operator dropdown on the page, create // duplicates of the dropdown between each pair of filter groups. if (this.hasGroupOperator) { + /** + * @type {jQuery} + */ this.dropdowns = this.duplicateGroupsOperator(); this.syncGroupsOperators(); } - // Add methods to the tableDrag instance to account for operator cells (which - // span multiple rows), the operator labels next to each filter (e.g., "And" - // or "Or"), the filter groups, and other special aspects of this tableDrag - // instance. + // Add methods to the tableDrag instance to account for operator cells + // (which span multiple rows), the operator labels next to each filter + // (e.g., "And" or "Or"), the filter groups, and other special aspects of + // this tableDrag instance. this.modifyTableDrag(); // Initialize the operator labels (e.g., "And" or "Or") that are displayed @@ -486,36 +639,37 @@ .on('change.views-rearrange-filter-handler', $.proxy(this, 'redrawOperatorLabels')); // Bind handlers so that when a "Remove" link is clicked, we: - // - Update the rowspans of cells containing an operator dropdown (since they - // need to change to reflect the number of rows in each group). + // - Update the rowspans of cells containing an operator dropdown (since + // they need to change to reflect the number of rows in each group). // - Redraw the operator labels next to the filters in the group (since the - // filter that is currently displayed last in each group is not supposed to - // have a label display next to it). + // filter that is currently displayed last in each group is not supposed + // to have a label display next to it). $table.find('a.views-groups-remove-link') .once('views-rearrange-filter-handler') .on('click.views-rearrange-filter-handler', $.proxy(this, 'updateRowspans')) .on('click.views-rearrange-filter-handler', $.proxy(this, 'redrawOperatorLabels')); }; - $.extend(Drupal.viewsUi.RearrangeFilterHandler.prototype, { + $.extend(Drupal.viewsUi.RearrangeFilterHandler.prototype, /** @lends Drupal.viewsUi.RearrangeFilterHandler# */{ + /** * Insert links that allow filter groups to be added and removed. */ insertAddRemoveFilterGroupLinks: function () { - // Insert a link for adding a new group at the top of the page, and make it - // match the action link styling used in a typical page.html.twig. Since - // Drupal does not provide a theme function for this markup this is the best - // we can do. + // Insert a link for adding a new group at the top of the page, and make + // it match the action link styling used in a typical page.html.twig. + // Since Drupal does not provide a theme function for this markup this is + // the best we can do. $('<ul class="action-links"><li><a id="views-add-group-link" href="#">' + this.addGroupButton.val() + '</a></li></ul>') .prependTo(this.table.parent()) - // When the link is clicked, dynamically click the hidden form button for - // adding a new filter group. + // When the link is clicked, dynamically click the hidden form button + // for adding a new filter group. .once('views-rearrange-filter-handler') .on('click.views-rearrange-filter-handler', $.proxy(this, 'clickAddGroupButton')); - // Find each (visually hidden) button for removing a filter group and insert - // a link next to it. + // Find each (visually hidden) button for removing a filter group and + // insert a link next to it. var length = this.removeGroupButtons.length; var i; for (i = 0; i < length; i++) { @@ -532,11 +686,13 @@ /** * Dynamically click the button that adds a new filter group. + * + * @param {jQuery.Event} event */ clickAddGroupButton: function (event) { // Due to conflicts between Drupal core's AJAX system and the Views AJAX - // system, the only way to get this to work seems to be to trigger both the - // mousedown and submit events. + // system, the only way to get this to work seems to be to trigger both + // the mousedown and submit events. this.addGroupButton .trigger('mousedown') .trigger('submit'); @@ -546,7 +702,7 @@ /** * Dynamically click a button for removing a filter group. * - * @param event + * @param {jQuery.Event} event * Event being triggered, with event.data.buttonId set to the ID of the * form button that should be clicked. */ @@ -558,6 +714,8 @@ /** * Move the groups operator so that it's between the first two groups, and * duplicate it between any subsequent groups. + * + * @return {jQuery} */ duplicateGroupsOperator: function () { var dropdowns; @@ -575,7 +733,8 @@ this.operator.find('label').add('div.description').addClass('visually-hidden'); this.operator.find('select').addClass('form-select'); - // Keep a list of the operator dropdowns, so we can sync their behavior later. + // Keep a list of the operator dropdowns, so we can sync their behavior + // later. dropdowns = this.operator; // Move the operator to a new row just above the second group. @@ -605,7 +764,8 @@ */ syncGroupsOperators: function () { if (this.dropdowns.length < 2) { - // We only have one dropdown (or none at all), so there's nothing to sync. + // We only have one dropdown (or none at all), so there's nothing to + // sync. return; } @@ -616,6 +776,8 @@ * Click handler for the operators that appear between filter groups. * * Forces all operator dropdowns to have the same value. + * + * @param {jQuery.Event} event */ operatorChangeHandler: function (event) { var $target = $(event.target); @@ -625,6 +787,9 @@ operators.val($target.val()); }, + /** + * @method + */ modifyTableDrag: function () { var tableDrag = Drupal.tableDrag['views-rearrange-filters']; var filterHandler = this; @@ -632,19 +797,22 @@ /** * Override the row.onSwap method from tabledrag.js. * - * When a row is dragged to another place in the table, several things need - * to occur. - * - The row needs to be moved so that it's within one of the filter groups. - * - The operator cells that span multiple rows need their rowspan attributes - * updated to reflect the number of rows in each group. - * - The operator labels that are displayed next to each filter need to be + * When a row is dragged to another place in the table, several things + * need to occur. + * - The row needs to be moved so that it's within one of the filter + * groups. + * - The operator cells that span multiple rows need their rowspan + * attributes updated to reflect the number of rows in each group. + * - The operator labels that are displayed next to each filter need to + * be * redrawn, to account for the row's new location. */ tableDrag.row.prototype.onSwap = function () { if (filterHandler.hasGroupOperator) { - // Make sure the row that just got moved (this.group) is inside one of - // the filter groups (i.e. below an empty marker row or a draggable). If - // it isn't, move it down one. + // Make sure the row that just got moved (this.group) is inside one + // of + // the filter groups (i.e. below an empty marker row or a draggable). + // If it isn't, move it down one. var thisRow = $(this.group); var previousRow = thisRow.prev('tr'); if (previousRow.length && !previousRow.hasClass('group-message') && !previousRow.hasClass('draggable')) { @@ -665,22 +833,22 @@ * Override the onDrop method from tabledrag.js. */ tableDrag.onDrop = function () { - // If the tabledrag change marker (i.e., the "*") has been inserted inside - // a row after the operator label (i.e., "And" or "Or") rearrange the items - // so the operator label continues to appear last. + // If the tabledrag change marker (i.e., the "*") has been inserted + // inside a row after the operator label (i.e., "And" or "Or") + // rearrange the items so the operator label continues to appear last. var changeMarker = $(this.oldRowElement).find('.tabledrag-changed'); if (changeMarker.length) { - // Search for occurrences of the operator label before the change marker, - // and reverse them. + // Search for occurrences of the operator label before the change + // marker, and reverse them. var operatorLabel = changeMarker.prevAll('.views-operator-label'); if (operatorLabel.length) { operatorLabel.insertAfter(changeMarker); } } - // Make sure the "group" dropdown is properly updated when rows are dragged - // into an empty filter group. This is borrowed heavily from the block.js - // implementation of tableDrag.onDrop(). + // Make sure the "group" dropdown is properly updated when rows are + // dragged into an empty filter group. This is borrowed heavily from + // the block.js implementation of tableDrag.onDrop(). var groupRow = $(this.rowObject.element).prevAll('tr.group-message').get(0); var groupName = groupRow.className.replace(/([^ ]+[ ]+)*group-([^ ]+)-message([ ]+[^ ]+)*/, '$2'); var groupField = $('select.views-group-select', this.rowObject.element); @@ -697,29 +865,31 @@ */ redrawOperatorLabels: function () { for (var i = 0; i < this.draggableRows.length; i++) { - // Within the row, the operator labels are displayed inside the first table - // cell (next to the filter name). + // Within the row, the operator labels are displayed inside the first + // table cell (next to the filter name). var $draggableRow = $(this.draggableRows[i]); var $firstCell = $draggableRow.find('td').eq(0); if ($firstCell.length) { // The value of the operator label ("And" or "Or") is taken from the - // first operator dropdown we encounter, going backwards from the current - // row. This dropdown is the one associated with the current row's filter - // group. + // first operator dropdown we encounter, going backwards from the + // current row. This dropdown is the one associated with the current + // row's filter group. var operatorValue = $draggableRow.prevAll('.views-group-title').find('option:selected').html(); var operatorLabel = '<span class="views-operator-label">' + operatorValue + '</span>'; // If the next visible row after this one is a draggable filter row, // display the operator label next to the current row. (Checking for - // visibility is necessary here since the "Remove" links hide the removed - // row but don't actually remove it from the document). + // visibility is necessary here since the "Remove" links hide the + // removed row but don't actually remove it from the document). var $nextRow = $draggableRow.nextAll(':visible').eq(0); var $existingOperatorLabel = $firstCell.find('.views-operator-label'); if ($nextRow.hasClass('draggable')) { - // If an operator label was already there, replace it with the new one. + // If an operator label was already there, replace it with the new + // one. if ($existingOperatorLabel.length) { $existingOperatorLabel.replaceWith(operatorLabel); } - // Otherwise, append the operator label to the end of the table cell. + // Otherwise, append the operator label to the end of the table + // cell. else { $firstCell.append(operatorLabel); } @@ -737,7 +907,8 @@ }, /** - * Update the rowspan attribute of each cell containing an operator dropdown. + * Update the rowspan attribute of each cell containing an operator + * dropdown. */ updateRowspans: function () { var $row; @@ -761,7 +932,8 @@ $operatorCell.attr('rowspan', 2); } else if ($row.hasClass('draggable') && $row.is(':visible')) { - // We've found a visible filter row, so we now know the group isn't empty. + // We've found a visible filter row, so we now know the group isn't + // empty. draggableCount++; $currentEmptyRow.removeClass('group-empty').addClass('group-populated'); // The operator cell should span all draggable rows, plus the title. @@ -773,6 +945,8 @@ /** * Add a select all checkbox, which checks each checkbox at once. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsFilterConfigSelectAll = { attach: function (context) { @@ -800,6 +974,8 @@ /** * Remove icon class from elements that are themed as buttons or dropbuttons. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsRemoveIconClass = { attach: function (context) { @@ -809,6 +985,8 @@ /** * Change "Expose filter" buttons into checkboxes. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsUiCheckboxify = { attach: function (context, settings) { @@ -824,6 +1002,8 @@ /** * Change the default widget to select the default group according to the * selected widget for the exposed group. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsUiChangeDefaultWidget = { attach: function () { @@ -849,9 +1029,11 @@ }; /** - * Attaches an expose filter button to a checkbox that triggers its click event. + * Attaches expose filter button to a checkbox that triggers its click event. + * + * @constructor * - * @param button + * @param {HTMLElement} button * The DOM object representing the button to be checkboxified. */ Drupal.viewsUi.Checkboxifier = function (button) { @@ -868,6 +1050,8 @@ /** * When the checkbox is checked or unchecked, simulate a button press. + * + * @param {jQuery.Event} e */ Drupal.viewsUi.Checkboxifier.prototype.clickHandler = function (e) { this.$button @@ -877,6 +1061,8 @@ /** * Change the Apply button text based upon the override select state. + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewsUiOverrideSelect = { attach: function (context) { @@ -912,11 +1098,15 @@ } }; + /** + * + * @type {Drupal~behavior} + */ Drupal.behaviors.viewsUiHandlerRemoveLink = { attach: function (context) { var $context = $(context); - // Handle handler deletion by looking for the hidden checkbox and hiding the - // row. + // Handle handler deletion by looking for the hidden checkbox and hiding + // the row. $context.find('a.views-remove-link').once('views').on('click', function (event) { var id = $(this).attr('id').replace('views-remove-link-', ''); $context.find('#views-row-' + id).hide(); @@ -924,8 +1114,8 @@ event.preventDefault(); }); - // Handle display deletion by looking for the hidden checkbox and hiding the - // row. + // Handle display deletion by looking for the hidden checkbox and hiding + // the row. $context.find('a.display-remove-link').once('display').on('click', function (event) { var id = $(this).attr('id').replace('display-remove-link-', ''); $context.find('#display-row-' + id).hide(); diff --git a/core/modules/views_ui/js/views_ui.listing.js b/core/modules/views_ui/js/views_ui.listing.js index 0374891..4c13d79 100644 --- a/core/modules/views_ui/js/views_ui.listing.js +++ b/core/modules/views_ui/js/views_ui.listing.js @@ -1,3 +1,8 @@ +/** + * @file + * Views listing behaviors. + */ + (function ($, Drupal) { "use strict"; @@ -8,6 +13,8 @@ * Text search input: input.views-filter-text * Target table: input.views-filter-text[data-table] * Source text: .views-table-filter-text-source + * + * @type {Drupal~behavior} */ Drupal.behaviors.viewTableFilterByText = { attach: function (context, settings) {