Skip to content

GitLab

D
drupal
Commit 38833e0f authored by jhodgdon's avatar jhodgdon
Browse files
Options

Issue #2493683 by nod_, dawehner, eiriksm, Wim Leers: JSDoc for JS using Backbone

parent 08344875
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1962 additions and 903 deletions
core/modules/ckeditor/js/ckeditor.admin.js
View file @ 38833e0f
......@@ -2,12 +2,16 @@
* @file
* CKEditor button and group configuration user interface.
*/
(function ($, Drupal, _, CKEDITOR) {
"use strict";
Drupal.ckeditor = Drupal.ckeditor || {};
/**
* @type {Drupal~behavior}
*/
Drupal.behaviors.ckeditorAdmin = {
attach: function (context) {
// Process the CKEditor configuration fragment once.
......@@ -69,13 +73,23 @@
/**
* CKEditor configuration UI methods of Backbone objects.
*
* @namespace
*/
Drupal.ckeditor = {
// A hash of View instances.
/**
* A hash of View instances.
*
* @type {object}
*/
views: {},
// A hash of Model instances.
/**
* A hash of Model instances.
*
* @type {object}
*/
models: {},
/**
......@@ -86,11 +100,11 @@
* placeholder, then a process is launched to name that group before the button
* move is translated into configuration.
*
* @param Backbone.View view
* @param {Backbone.View} view
* The Backbone View that invoked this function.
* @param jQuery $button
* @param {jQuery} $button
* A jQuery set that contains an li element that wraps a button element.
* @param function callback
* @param {function} callback
* A callback to invoke after the button group naming modal dialog has been
* closed.
*/
......@@ -118,9 +132,9 @@
* Each row has a placeholder group at the end of the row. A user may not move
* an existing button group past the placeholder group at the end of a row.
*
* @param Backbone.View view
* @param {Backbone.View} view
* The Backbone View that invoked this function.
* @param jQuery $group
* @param {jQuery} $group
* A jQuery set that contains an li element that wraps a group of buttons.
*/
registerGroupMove: function (view, $group) {
......@@ -143,11 +157,11 @@
/**
* Opens a Drupal dialog with a form for changing the title of a button group.
*
* @param Backbone.View view
* @param {Backbone.View} view
* The Backbone View that invoked this function.
* @param jQuery $group
* @param {jQuery} $group
* A jQuery set that contains an li element that wraps a group of buttons.
* @param function callback
* @param {function} callback
* A callback to invoke after the button group naming modal dialog has been
* closed.
*/
......@@ -157,10 +171,11 @@
/**
* Validates the string provided as a button group title.
*
* @param DOM form
* @param {HTMLElement} form
* The form DOM element that contains the input with the new button group
* title string.
* @return Boolean
*
* @return {bool}
* Returns true when an error exists, otherwise returns false.
*/
function validateForm(form) {
......@@ -182,9 +197,9 @@
/**
* Attempts to close the dialog; Validates user input.
*
* @param String action
* @param {string} action
* The dialog action chosen by the user: 'apply' or 'cancel'.
* @param DOM form
* @param {HTMLElement} form
* The form DOM element that contains the input with the new button group
* title string.
*/
......@@ -203,9 +218,9 @@
/**
* Applies a string as the name of a CKEditor button group.
*
* @param jQuery $group
* @param {jQuery} $group
* A jQuery set that contains an li element that wraps a group of buttons.
* @param String name
* @param {string} name
* The new name of the CKEditor button group.
*/
function namePlaceholderGroup($group, name) {
......@@ -336,9 +351,10 @@
};
/**
* Automatically shows/hides settings of buttons-only CKEditor plugins.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.ckeditorAdminButtonPluginSettings = {
attach: function (context) {
......@@ -411,7 +427,7 @@
/**
* Themes a blank CKEditor row.
*
* @return String
* @return {string}
*/
Drupal.theme.ckeditorRow = function () {
return '<li class="ckeditor-row placeholder" role="group"><ul class="ckeditor-toolbar-groups clearfix"></ul></li>';
......@@ -420,7 +436,7 @@
/**
* Themes a blank CKEditor button group.
*
* @return String
* @return {string}
*/
Drupal.theme.ckeditorToolbarGroup = function () {
var group = '';
......@@ -434,7 +450,7 @@
/**
* Themes a form for changing the title of a CKEditor button group.
*
* @return String
* @return {string}
*/
Drupal.theme.ckeditorButtonGroupNameForm = function () {
return '<form><input name="group-name" required="required"></form>';
......@@ -443,7 +459,7 @@
/**
* Themes a button that will toggle the button group names in active config.
*
* @return String
* @return {string}
*/
Drupal.theme.ckeditorButtonGroupNamesToggle = function () {
return '<a class="ckeditor-groupnames-toggle" role="button" aria-pressed="false"></a>';
......@@ -452,7 +468,7 @@
/**
* Themes a button that will prompt the user to name a new button group.
*
* @return String
* @return {string}
*/
Drupal.theme.ckeditorNewButtonGroup = function () {
return '<li class="ckeditor-add-new-group"><button role="button" aria-label="' + Drupal.t('Add a CKEditor button group to the end of this row.') + '">' + Drupal.t('Add group') + '</button></li>';
......
core/modules/ckeditor/js/ckeditor.drupalimage.admin.js
View file @ 38833e0f
/**
* @file
* CKEditor 'drupalimage' plugin admin behavior.
*/
(function ($, Drupal, drupalSettings) {
"use strict";
/**
* Provides the summary for the "drupalimage" plugin settings vertical tab.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.ckeditorDrupalImageSettingsSummary = {
attach: function () {
......
core/modules/ckeditor/js/ckeditor.js
View file @ 38833e0f
/**
* @file
* CKEditor implementation of {@link Drupal.editors} API.
*/
(function (Drupal, debounce, CKEDITOR, $) {
"use strict";
/**
* @namespace
*/
Drupal.editors.ckeditor = {
/**
* Editor attach callback.
*
* @param {HTMLElement} element
* @param {string} format
*
* @return {bool}
*/
attach: function (element, format) {
this._loadExternalPlugins(format);
// Also pass settings that are Drupal-specific.
......@@ -26,6 +42,15 @@
return !!CKEDITOR.replace(element, format.editorSettings);
},
/**
* Editor detach callback.
*
* @param {HTMLElement} element
* @param {string} format
* @param {string} trigger
*
* @return {bool}
*/
detach: function (element, format, trigger) {
var editor = CKEDITOR.dom.element.get(element).getEditor();
if (editor) {
......@@ -40,6 +65,13 @@
return !!editor;
},
/**
*
* @param {HTMLElement} element
* @param {function} callback
*
* @return {bool}
*/
onChange: function (element, callback) {
var editor = CKEDITOR.dom.element.get(element).getEditor();
if (editor) {
......@@ -50,6 +82,15 @@
return !!editor;
},
/**
*
* @param {HTMLElement} element
* @param {object} format
* @param {string} mainToolbarId
* @param {string} floatedToolbarId
*
* @return {bool}
*/
attachInlineEditor: function (element, format, mainToolbarId, floatedToolbarId) {
this._loadExternalPlugins(format);
// Also pass settings that are Drupal-specific.
......@@ -101,6 +142,9 @@
return !!CKEDITOR.inline(element, settings);
},
/**
* @param {object} format
*/
_loadExternalPlugins: function (format) {
var externalPlugins = format.editorSettings.drupalExternalPlugins;
// Register and load additional CKEditor plugins as necessary.
......@@ -117,8 +161,11 @@
};
Drupal.ckeditor = {
/**
* Variable storing the current dialog's save callback.
*
* @type {?function}
*/
saveCallback: null,
......@@ -128,16 +175,16 @@
* This dynamically loads jQuery UI (if necessary) using the Drupal AJAX
* framework, then opens a dialog at the specified Drupal path.
*
* @param editor
* @param {CKEditor} editor
* The CKEditor instance that is opening the dialog.
* @param string url
* @param {string} url
* The URL that contains the contents of the dialog.
* @param Object existingValues
* @param {object} existingValues
* Existing values that will be sent via POST to the url for the dialog
* contents.
* @param Function saveCallback
* @param {function} saveCallback
* A function to be called upon saving the dialog.
* @param Object dialogSettings
* @param {object} dialogSettings
* An object containing settings to be passed to the jQuery UI.
*/
openDialog: function (editor, url, existingValues, saveCallback, dialogSettings) {
......@@ -156,8 +203,8 @@
dialogSettings.dialogClass = classes.join(' ');
dialogSettings.autoResize = Drupal.checkWidthBreakpoint(600);
// Add a "Loading…" message, hide it underneath the CKEditor toolbar, create
// a Drupal.ajax instance to load the dialog and trigger it.
// Add a "Loading…" message, hide it underneath the CKEditor toolbar,
// create a Drupal.Ajax instance to load the dialog and trigger it.
var $content = $('<div class="ckeditor-dialog-loading"><span style="top: -40px;" class="ckeditor-dialog-loading-link">' + Drupal.t('Loading...') + '</span></div>');
$content.appendTo($target);
......
core/modules/ckeditor/js/ckeditor.stylescombo.admin.js
View file @ 38833e0f
/**
* @file
* CKEditor SylesCombo admin behavior.
*/
(function ($, Drupal, drupalSettings) {
"use strict";
......@@ -9,6 +14,8 @@
* plugin settings change, to ensure that the corresponding feature metadata is
* immediately updated — i.e. ensure that HTML tags and classes entered here are
* known to be "required", which may affect filter settings.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.ckeditorStylesComboSettings = {
attach: function (context) {
......@@ -46,10 +53,10 @@
* parsing works identically, but instead of failing on invalid styles, we
* just ignore those.
*
* @param String styles
* @param {string} styles
* The "styles" setting.
*
* @return array
* @return {Array}
* An array containing the "stylesSet" configuration.
*/
_generateStylesSetSetting: function (styles) {
......@@ -93,6 +100,8 @@
/**
* Provides the summary for the "stylescombo" plugin settings vertical tab.
*
* @type {Drupal~behavior}
*/
Drupal.behaviors.ckeditorStylesComboSettingsSummary = {
attach: function () {
......
core/modules/ckeditor/js/models/Model.js
View file @ 38833e0f
......@@ -9,26 +9,58 @@
/**
* Backbone model for the CKEditor toolbar configuration state.
*
* @constructor
*
* @augments Backbone.Model
*/
Drupal.ckeditor.Model = Backbone.Model.extend({
defaults: {
// The CKEditor configuration that is being manipulated through the UI.
Drupal.ckeditor.Model = Backbone.Model.extend(/** @lends Drupal.ckeditor.Model# */{
/**
* Default values.
*
* @type {object}
*/
defaults: /** @lends Drupal.ckeditor.Model# */{
/**
* The CKEditor configuration that is being manipulated through the UI.
*/
activeEditorConfig: null,
// The textarea that contains the serialized representation of the active
// CKEditor configuration.
/**
* The textarea that contains the serialized representation of the active
* CKEditor configuration.
*/
$textarea: null,
// Tracks whether the active toolbar DOM structure has been changed. When
// true, activeEditorConfig needs to be updated, and when that is updated,
// $textarea will also be updated.
/**
* Tracks whether the active toolbar DOM structure has been changed. When
* true, activeEditorConfig needs to be updated, and when that is updated,
* $textarea will also be updated.
*/
isDirty: false,
// The configuration for the hidden CKEditor instance that is used to build
// the features metadata.
/**
* The configuration for the hidden CKEditor instance that is used to
* build the features metadata.
*/
hiddenEditorConfig: null,
// A hash, keyed by a feature name, that details CKEditor plugin features.
/**
* A hash, keyed by a feature name, that details CKEditor plugin features.
*/
featuresMetadata: null,
// Whether the button group names are currently visible.
/**
* Whether the button group names are currently visible.
*/
groupNamesVisible: false
},
/**
* @method
*/
sync: function () {
// Push the settings into the textarea.
this.get('$textarea').val(JSON.stringify(this.get('activeEditorConfig')));
......
core/modules/ckeditor/js/plugins/drupalimage/plugin.js
View file @ 38833e0f
......@@ -7,8 +7,12 @@
* uses to track where images are being used)
* - use a Drupal-native dialog (that is in fact just an alterable Drupal form
* like any other) instead of CKEditor's own dialogs.
* @see \Drupal\editor\Form\EditorImageDialog
*
* @see \Drupal\editor\Form\EditorImageDialog
*
* @ignore
*/
(function ($, Drupal, CKEDITOR) {
"use strict";
......
core/modules/ckeditor/js/plugins/drupalimagecaption/plugin.js
View file @ 38833e0f
......@@ -5,8 +5,11 @@
* This alters the existing CKEditor image2 widget plugin, which is already
* altered by the Drupal Image plugin, to:
* - allow for the data-caption and data-align attributes to be set
* - mimic the upcasting behavior of the caption_filter filter
* - mimic the upcasting behavior of the caption_filter filter.
*
* @ignore
*/
(function (CKEDITOR) {
"use strict";
......@@ -220,9 +223,10 @@
* Function will check first the passed element itself and then all its
* children in DFS order.
*
* @param CKEDITOR.htmlParser.element element
* @param String name
* @return CKEDITOR.htmlParser.element
* @param {CKEDITOR.htmlParser.element} element
* @param {string} name
*
* @return {CKEDITOR.htmlParser.element}
*/
function findElementByName(element, name) {
if (element.name === name) {
......@@ -233,7 +237,8 @@
element.forEach(function (el) {
if (el.name === name) {
found = el;
return false; // Stop here.
// Stop here.
return false;
}
}, CKEDITOR.NODE_ELEMENT);
return found;
......
core/modules/ckeditor/js/plugins/drupallink/plugin.js
View file @ 38833e0f
/**
* @file
* Drupal Link plugin.
*
* @ignore
*/
(function ($, Drupal, drupalSettings, CKEDITOR) {
......@@ -199,6 +201,7 @@
*
* The following selection will all return the link element.
*
* @example
* <a href="#">li^nk</a>
* <a href="#">[link]</a>
* text[<a href="#">link]</a>
......@@ -207,6 +210,8 @@
* [<a href="#"><b>li]nk</b></a>
*
* @param {CKEDITOR.editor} editor
*
* @return {?bool}
*/
function getSelectedLink(editor) {
var selection = editor.getSelection();
......
core/modules/ckeditor/js/views/AuralView.js
View file @ 38833e0f
......@@ -7,11 +7,11 @@
"use strict";
/**
* Backbone View for CKEditor toolbar configuration; aural UX (output only).
*/
Drupal.ckeditor.AuralView = Backbone.View.extend({
Drupal.ckeditor.AuralView = Backbone.View.extend(/** @lends Drupal.ckeditor.AuralView# */{
/**
* @type {object}
*/
events: {
'click .ckeditor-buttons a': 'announceButtonHelp',
'click .ckeditor-multiple-buttons a': 'announceSeparatorHelp',
......@@ -21,7 +21,11 @@
},
/**
* {@inheritdoc}
* Backbone View for CKEditor toolbar configuration; aural UX (output only).
*
* @constructs
*
* @augments Backbone.View
*/
initialize: function () {
// Announce the button and group positions when the model is no longer
......@@ -32,8 +36,8 @@
/**
* Calls announce on buttons and groups when their position is changed.
*
* @param Drupal.ckeditor.ConfigurationModel model
* @param Boolean isDirty
* @param {Drupal.ckeditor.ConfigurationModel} model
* @param {bool} isDirty
* A model attribute that indicates if the changed toolbar configuration
* has been stored or not.
*/
......@@ -57,7 +61,7 @@
/**
* Handles the focus event of elements in the active and available toolbars.
*
* @param jQuery.Event event
* @param {jQuery.Event} event
*/
onFocus: function (event) {
event.stopPropagation();
......@@ -76,7 +80,7 @@
/**
* Announces the current position of a button group.
*
* @param jQuery $group
* @param {jQuery} $group
* A jQuery set that contains an li element that wraps a group of buttons.
*/
announceButtonGroupPosition: function ($group) {
......@@ -106,7 +110,7 @@
/**
* Announces current button position.
*
* @param jQuery $button
* @param {jQuery} $button
* A jQuery set that contains an li element that wraps a button.
*/
announceButtonPosition: function ($button) {
......@@ -166,7 +170,7 @@
/**
* Provides help information when a button is clicked.
*
* @param jQuery.Event event
* @param {jQuery.Event} event
*/
announceButtonHelp: function (event) {
var $link = $(event.currentTarget);
......@@ -194,7 +198,7 @@
/**
* Provides help information when a separator is clicked.
*
* @param jQuery.Event event
* @param {jQuery.Event} event
*/
announceSeparatorHelp: function (event) {
var $link = $(event.currentTarget);
......
core/modules/ckeditor/js/views/ControllerView.js
View file @ 38833e0f
......@@ -7,15 +7,19 @@
"use strict";
/**
* Backbone View acting as a controller for CKEditor toolbar configuration.
*/
Drupal.ckeditor.ControllerView = Backbone.View.extend({
Drupal.ckeditor.ControllerView = Backbone.View.extend(/** @lends Drupal.ckeditor.ControllerView# */{
/**
* @type {object}
*/
events: {},
/**
* {@inheritdoc}
* Backbone View acting as a controller for CKEditor toolbar configuration.
*
* @constructs
*
* @augments Backbone.View
*/
initialize: function () {
this.getCKEditorFeatures(this.model.get('hiddenEditorConfig'), this.disableFeaturesDisallowedByFilters.bind(this));
......@@ -28,16 +32,18 @@
/**
* Converts the active toolbar DOM structure to an object representation.
*
* @param Drupal.ckeditor.ConfigurationModel model
* @param {Drupal.ckeditor.ConfigurationModel} model
* The state model for the CKEditor configuration.
* @param Boolean isDirty
* @param {bool} isDirty
* Tracks whether the active toolbar DOM structure has been changed.
* isDirty is toggled back to false in this method.
* @param Object options
* @param {object} options
* An object that includes:
* - Boolean broadcast: (optional) A flag that controls whether a
* CKEditorToolbarChanged event should be fired for configuration
* changes.
* @param {bool} [options.broadcast]
* A flag that controls whether a CKEditorToolbarChanged event should be
* fired for configuration changes.
*
* @fires event:CKEditorToolbarChanged
*/
parseEditorDOM: function (model, isDirty, options) {
if (isDirty) {
......@@ -97,13 +103,13 @@
* In order to get a list of all features needed by CKEditor, we create a
* hidden CKEditor instance, then check the CKEditor's "allowedContent"
* filter settings. Because creating an instance is expensive, a callback
* must be provided that will receive a hash of Drupal.EditorFeature
* must be provided that will receive a hash of {@link Drupal.EditorFeature}
* features keyed by feature (button) name.
*
* @param Object CKEditorConfig
* @param {object} CKEditorConfig
* An object that represents the configuration settings for a CKEditor
* editor component.
* @param Function callback
* @param {function} callback
* A function to invoke when the instanceReady event is fired by the
* CKEditor object.
*/
......@@ -192,9 +198,10 @@
* Retrieves the feature for a given button from featuresMetadata. Returns
* false if the given button is in fact a divider.
*
* @param String button
* @param {string} button
* The name of a CKEditor button.
* @return Object
*
* @return {object}
* The feature metadata object for a button.
*/
getFeatureForButton: function (button) {
......@@ -218,8 +225,8 @@
/**
* Checks buttons against filter settings; disables disallowed buttons.
*
* @param Object features
* A map of Drupal.EditorFeature objects.
* @param {object} features
* A map of {@link Drupal.EditorFeature} objects.
*/
disableFeaturesDisallowedByFilters: function (features) {
this.model.set('featuresMetadata', features);
......@@ -272,7 +279,7 @@
/**
* Sets up broadcasting of CKEditor toolbar configuration changes.
*
* @param jQuery $ckeditorToolbar
* @param {jQuery} $ckeditorToolbar
* The active toolbar DOM element wrapped in jQuery.
*/
broadcastConfigurationChanges: function ($ckeditorToolbar) {
......@@ -329,14 +336,15 @@
/**
* Returns the list of buttons from an editor configuration.
*
* @param Object config