Skip to content
GitLab
Commit 5d458d92 authored by Frank Nägler's avatar Frank Nägler Committed by Christian Kuhn
Browse files

[TASK] Streamline JavaScript documentation 

Resolves: #70966
Releases: master
Change-Id: Ic78753be0facd860e5ab30ce6d7340e040dee59c
Reviewed-on: https://review.typo3.org/44170

Reviewed-by: Wouter Wolters's avatarWouter Wolters <typo3@wouterwolters.nl>
Tested-by: Wouter Wolters's avatarWouter Wolters <typo3@wouterwolters.nl>
Reviewed-by: Christian Kuhn's avatarChristian Kuhn <lolli@schwarzbu.ch>
Tested-by: Christian Kuhn's avatarChristian Kuhn <lolli@schwarzbu.ch>
parent 88287ba6
Hide whitespace changes
Inline Side-by-side
typo3/sysext/backend/Resources/Public/JavaScript/AjaxDataHandler.js
View file @ 5d458d92
......@@ -12,11 +12,17 @@
*/
/**
* Module: TYPO3/CMS/Backend/AjaxDataHandler
* AjaxDataHandler - Javascript functions to work with AJAX and interacting with tce_db.php
*/
define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/CMS/Backend/Notification'], function ($, Modal, Icons) {
'use strict';
/**
*
* @type {{identifier: {hide: string, delete: string, icon: string}}}
* @exports TYPO3/CMS/Backend/AjaxDataHandler
*/
var AjaxDataHandler = {
identifier: {
hide: '.t3js-record-hide',
......@@ -27,8 +33,9 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
/**
* generic function to call from the outside the script and validate directly showing errors
* @param parameters
* @return a jQuery deferred object (promise)
*
* @param {Object} parameters
* @return {Promise<Object>} a jQuery deferred object (promise)
*/
AjaxDataHandler.process = function(parameters) {
return AjaxDataHandler._call(parameters).done(function(result) {
......@@ -38,6 +45,9 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
});
};
/**
*
*/
AjaxDataHandler.initialize = function() {
// HIDE/UNHIDE: click events for all action icons to hide/unhide
......@@ -94,7 +104,7 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
/**
* Toggle row visibility after record has been changed
*
* @param $rowElement
* @param {Object} $rowElement
*/
AjaxDataHandler.toggleRow = function($rowElement) {
var $anchorElement = $rowElement.find(AjaxDataHandler.identifier.hide);
......@@ -150,7 +160,7 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
* delete record by given element (icon in table)
* don't call it directly!
*
* @param element
* @param {HTMLElement} element
*/
AjaxDataHandler.deleteRecord = function(element) {
var $anchorElement = $(element);
......@@ -202,7 +212,7 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
/**
* handle the errors from result object
*
* @param result
* @param {Object} result
* @private
*/
AjaxDataHandler.handleErrors = function(result) {
......@@ -224,6 +234,9 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
/**
* AJAX call to tce_db.php
* returns a jQuery Promise to work with
*
* @param {Object} params
* @returns {Object}
* @private
*/
AjaxDataHandler._call = function(params) {
......@@ -232,6 +245,8 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Backend/Icons', 'TYPO3/C
/**
* Replace the given icon with a spinner icon
*
* @param {Object} $iconElement
* @private
*/
AjaxDataHandler._showSpinnerIcon = function($iconElement) {
......
typo3/sysext/backend/Resources/Public/JavaScript/ClickMenu.js
View file @ 5d458d92
......@@ -12,11 +12,17 @@
*/
/**
* Module: TYPO3/CMS/Backend/ClickMenu
* Javascript container used to load the clickmenu via AJAX
* to render the result in a layer next to the mouse cursor
*/
define(['jquery'], function($) {
/**
*
* @type {{mousePos: {X: null, Y: null}, delayClickMenuHide: boolean}}
* @exports TYPO3/CMS/Backend/ClickMenu
*/
var ClickMenu = {
mousePos: {
X: null,
......@@ -25,6 +31,9 @@ define(['jquery'], function($) {
delayClickMenuHide: false
};
/**
* Initialize events
*/
ClickMenu.initializeEvents = function() {
$(document).on('click contextmenu', '.t3-js-clickmenutrigger', function(event) {
// if there is an other "inline" onclick setting, clickmenu is not triggered
......@@ -47,13 +56,13 @@ define(['jquery'], function($) {
};
/**
* main function, called from most clickmenu links
* Main function, called from most clickmenu links
*
* @param table Table from where info should be fetched
* @param uid The UID of the item
* @param listFr list Frame?
* @param enDisItems Items to disable / enable
* @param addParams Additional params
* @param {String} table Table from where info should be fetched
* @param {(String|Number)} uid The UID of the item
* @param {String} listFr list Frame?
* @param {String} enDisItems Items to disable / enable
* @param {String} addParams Additional params
* @return void
*/
ClickMenu.show = function(table, uid, listFr, enDisItems, addParams) {
......@@ -78,9 +87,9 @@ define(['jquery'], function($) {
};
/**
* make the AJAX request
* Make the AJAX request
*
* @param array parameters Parameters sent to the server
* @param {array} parameters Parameters sent to the server
* @return void
*/
ClickMenu.fetch = function(parameters) {
......@@ -108,8 +117,9 @@ define(['jquery'], function($) {
/**
* fills the clickmenu with content and displays it correctly
* depending on the mouse position
* @param data The data that will be put in the menu
* @param level The depth of the clickmenu
*
* @param {String} data The data that will be put in the menu
* @param {Number} level The depth of the clickmenu
*/
ClickMenu.populateData = function(data, level) {
this.initializeClickMenuContainer();
......@@ -166,7 +176,8 @@ define(['jquery'], function($) {
* event handler function that saves the
* actual position of the mouse
* in the Clickmenu object
* @param event The event object
*
* @param {Event} event The event object
*/
ClickMenu.storeMousePositionEvent = function(event) {
ClickMenu.mousePos.X = event.pageX;
......@@ -178,8 +189,8 @@ define(['jquery'], function($) {
/**
* hides a visible menu if the mouse has moved outside
* of the object
* @param obj The object to hide
* @result void
*
* @param {Object} obj The object to hide
*/
ClickMenu.mouseOutFromMenu = function(obj) {
var $element = $(obj);
......@@ -191,6 +202,13 @@ define(['jquery'], function($) {
}
};
/**
*
* @param {Object} $element
* @param {Number} x
* @param {Number} y
* @returns {Boolean}
*/
ClickMenu.within = function($element, x, y) {
var offset = $element.offset();
return (y >= offset.top &&
......@@ -202,8 +220,7 @@ define(['jquery'], function($) {
/**
* hides a clickmenu
*
* @param obj The clickmenu object to hide
* @result void
* @param {Object} obj The clickmenu object to hide
*/
ClickMenu.hide = function(obj) {
this.delayClickMenuHide = false;
......@@ -224,8 +241,6 @@ define(['jquery'], function($) {
/**
* manipulates the DOM to add the divs needed for clickmenu at the bottom of the <body>-tag
*
* @return void
*/
ClickMenu.initializeClickMenuContainer = function() {
if ($('#contentMenu0').length === 0) {
......
typo3/sysext/backend/Resources/Public/JavaScript/ContextHelp.js
View file @ 5d458d92
......@@ -12,6 +12,7 @@
*/
/**
* Module: TYPO3/CMS/Backend/ContextHelp
* API for context help.
*/
define(['jquery', 'TYPO3/CMS/Backend/Popover', 'bootstrap'], function($) {
......@@ -19,7 +20,8 @@ define(['jquery', 'TYPO3/CMS/Backend/Popover', 'bootstrap'], function($) {
/**
* The main ContextHelp object
*
* @type {{ajaxUrl: *, localCache: {}, openContext: null}}
* @type {{ajaxUrl: *, localCache: {}, helpModuleUrl: string, trigger: string, placement: string, selector: string}}
* @exports TYPO3/CMS/Backend/ContextHelp
*/
var ContextHelp = {
ajaxUrl: TYPO3.settings.ajaxUrls['context_help'],
......@@ -96,7 +98,7 @@ define(['jquery', 'TYPO3/CMS/Backend/Popover', 'bootstrap'], function($) {
/**
* Open the help popup
*
* @param {object} $trigger
* @param {Object} $trigger
*/
ContextHelp.showHelpPopup = function($trigger) {
var configuration = top.TYPO3.configuration.ContextHelpWindows || top.TYPO3.configuration.PopupWindow;
......@@ -119,7 +121,7 @@ define(['jquery', 'TYPO3/CMS/Backend/Popover', 'bootstrap'], function($) {
/**
* Load help data
*
* @param {object} $trigger
* @param {Object} $trigger
*/
ContextHelp.loadHelp = function($trigger) {
var table = $trigger.data('table');
......
typo3/sysext/backend/Resources/Public/JavaScript/DateTimePicker.js
View file @ 5d458d92
......@@ -12,11 +12,17 @@
*/
/**
* Module: TYPO3/CMS/Backend/DateTimePicker
* contains all logic for the date time picker used in FormEngine
* and EXT:belog and EXT:scheduler
*/
define(['jquery'], function ($) {
/**
*
* @type {{options: {fieldSelector: string, format: *}}}
* @exports TYPO3/CMS/Backend/DateTimePicker
*/
var DateTimePicker = {
options: {
fieldSelector: '.t3js-datetimepicker',
......
typo3/sysext/backend/Resources/Public/JavaScript/DebugConsole.js
View file @ 5d458d92
......@@ -12,11 +12,17 @@
*/
/**
* Module: TYPO3/CMS/Backend/DebugConsole
* The debug console shown at the bottom of the backend
*/
define(['jquery'], function ($) {
'use strict';
/**
*
* @type {{$consoleDom: null, settings: {autoscroll: boolean}}}
* @exports TYPO3/CMS/Backend/DebugConsole
*/
var DebugConsole = {
$consoleDom: null,
settings: {
......@@ -100,6 +106,10 @@ define(['jquery'], function ($) {
/**
* Adds a button and it's callback to the console's toolbar
*
* @param {Object} $button
* @param {function} callback
* @returns {{$consoleDom: null, settings: {autoscroll: boolean}}}
*/
DebugConsole.addButton = function($button, callback) {
$button.on('click', callback);
......@@ -120,6 +130,10 @@ define(['jquery'], function ($) {
/**
* Add the debug message to the console
*
* @param {String} message
* @param {String} header
* @param {String} [group=Debug]
*/
DebugConsole.add = function(message, header, group) {
DebugConsole.attachToViewport();
......@@ -178,6 +192,8 @@ define(['jquery'], function ($) {
/**
* Gets a proper console icon depending on the amount of tabs
*
* @param {Object} $tabs
*/
DebugConsole.identifyTabLengthPresentationIcon = function($tabs) {
var terminalIcon1 = true,
......@@ -195,6 +211,8 @@ define(['jquery'], function ($) {
/**
* Increment the counter of unread messages in the given tab
*
* @param {Object} $tab
*/
DebugConsole.incrementInactiveTabCounter = function($tab) {
if (!$tab.hasClass('active')) {
......
typo3/sysext/backend/Resources/Public/JavaScript/DocumentHeader.js
View file @ 5d458d92
......@@ -12,11 +12,17 @@
*/
/**
* Module: TYPO3/CMS/Backend/DocumentHeader
* Calculates the height of the docHeader and hides it upon scrolling
*/
define(['jquery'], function($) {
'use strict';
/**
*
* @type {{$documentHeader: null, $documentHeaderBars: null, $documentHeaderNavigationBar: null, $documentHeaderSearchBar: null, $moduleBody: null, direction: string, reactionRange: number, lastPosition: number, currentPosition: number, changedPosition: number, settings: {margin: number, offset: number, selectors: {moduleDocumentHeader: string, moduleDocheaderBar: string, moduleNavigationBar: string, moduleButtonBar: string, moduleSearchBar: string, moduleBody: string}}}}
* @exports TYPO3/CMS/Backend/DocumentHeader
*/
var DocumentHeader = {
$documentHeader: null,
$documentHeaderBars: null,
......
typo3/sysext/backend/Resources/Public/JavaScript/DragUploader.js
View file @ 5d458d92
......@@ -12,7 +12,7 @@
*/
/**
* JavaScript RequireJS module called "TYPO3/CMS/Backend/DragUploader"
* Module: TYPO3/CMS/Backend/DragUploader
*
*/
define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/Lang/Lang'], function($, moment, NProgress, Modal) {
......@@ -20,7 +20,7 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
/**
* Array of files which are asked for being overridden
*
* @type {Array}
* @type {array}
*/
var askForOverride = [],
percentagePerFile = 1;
......@@ -40,6 +40,12 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
*/
// register the constructor
/**
*
* @param {HTMLElement} element
* @constructor
* @exports TYPO3/CMS/Backend/DragUploader
*/
var DragUploaderPlugin = function(element) {
var me = this;
me.$body = $('body');
......@@ -70,16 +76,28 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
Progress: "upload" in new XMLHttpRequest
};
/**
*
*/
me.showDropzone = function() {
me.$dropzone.show();
};
/**
*
* @param {Event} event
*/
me.hideDropzone = function(event) {
event.stopPropagation();
event.preventDefault();
me.$dropzone.hide();
};
/**
*
* @param {Event} event
* @returns {Boolean}
*/
me.dragFileIntoDocument = function(event) {
event.stopPropagation();
event.preventDefault();
......@@ -88,6 +106,11 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
return false;
};
/**
*
* @param {Event} event
* @returns {Boolean}
*/
me.dragAborted = function(event) {
event.stopPropagation();
event.preventDefault();
......@@ -95,6 +118,11 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
return false;
};
/**
*
* @param {Event} event
* @returns {Boolean}
*/
me.ignoreDrop = function(event) {
// stops the browser from redirecting.
event.stopPropagation();
......@@ -103,12 +131,20 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
return false;
};
/**
*
* @param {Event} event
*/
me.handleDrop = function(event) {
me.ignoreDrop(event);
me.processFiles(event.originalEvent.dataTransfer.files);
me.$dropzone.removeClass('drop-status-ok');
};
/**
*
* @param {Array} files
*/
me.processFiles = function(files) {
me.queueLength = files.length;
......@@ -155,16 +191,27 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
me.$fileInput.val('');
};
/**
*
* @param {Event} event
*/
me.fileInDropzone = function(event) {
me.$dropzone.addClass('drop-status-ok');
};
/**
*
* @param {Event} event
*/
me.fileOutOfDropzone = function(event) {
me.$dropzone.removeClass('drop-status-ok');
};
// bind file picker to default upload button
/**
* bind file picker to default upload button
*
* @param {Object} button
*/
me.bindUploadButton = function(button) {
button.click(function(event) {
event.preventDefault();
......@@ -219,6 +266,9 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
me.bindUploadButton(me.$trigger.length ? me.$trigger : me.$element);
}
/**
*
*/
me.decrementQueueLength = function() {
if (me.queueLength > 0) {
me.queueLength--;
......@@ -239,6 +289,9 @@ define(['jquery', 'moment', 'nprogress', 'TYPO3/CMS/Backend/Modal', 'TYPO3/CMS/L
}
};
/**
*
*/
me.drawOverrideModal = function() {
var amountOfItems = Object.keys(askForOverride).length;
if (amountOfItems === 0) {
......
typo3/sysext/backend/Resources/Public/JavaScript/FormEngine.js
View file @ 5d458d92
......@@ -27,11 +27,16 @@ var setFormValueOpenBrowser
,setFormValueManipulate
,setFormValue_getFObj;
/**
* Module: TYPO3/CMS/Backend/FormEngine
*/
define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
// main options
/**
*
* @type {{formName: *, backPath: *, openedPopupWindow: null, legacyFieldChangedCb: Function, browserUrl: string}}
* @exports TYPO3/CMS/Backend/FormEngine
*/
var FormEngine = {
formName: TYPO3.settings.FormEngine.formName
,backPath: TYPO3.settings.FormEngine.backPath
......@@ -40,6 +45,10 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
,browserUrl: ''
};
/**
*
* @param {String} browserUrl
*/
FormEngine.setBrowserUrl = function(browserUrl) {
FormEngine.browserUrl = browserUrl;
};
......@@ -49,10 +58,10 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
/**
* opens a popup window with the element browser (browser.php)
*
* @param mode can be "db" or "file"
* @param params additional params for the browser window
* @param width width of the window
* @param height height of the window
* @param {String} mode can be "db" or "file"
* @param {String} params additional params for the browser window
* @param {Number} width width of the window
* @param {Number} height height of the window
*/
FormEngine.openPopupWindow = setFormValueOpenBrowser = function(mode, params, width, height) {
var url = FormEngine.backPath + FormEngine.browserUrl + '&mode=' + mode + '&bparams=' + params;
......@@ -68,11 +77,11 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
* or from a multi-select (two selects side-by-side)
* previously known as "setFormValueFromBrowseWin"
*
* @param fieldName formerly known as "fName" name of the field, like [tt_content][2387][header]
* @param value the value to fill in (could be an integer)
* @param label the visible name in the selector
* @param title the title when hovering over it
* @param exclusiveValues if the select field has exclusive options that are not combine-able
* @param {String} fieldName formerly known as "fName" name of the field, like [tt_content][2387][header]
* @param {(String|Number)} value the value to fill in (could be an integer)
* @param {String} label the visible name in the selector
* @param {String} title the title when hovering over it
* @param {String} exclusiveValues if the select field has exclusive options that are not combine-able
*/
FormEngine.setSelectOptionFromExternalSource = setFormValueFromBrowseWin = function(fieldName, value, label, title, exclusiveValues) {
exclusiveValues = String(exclusiveValues);
......@@ -182,8 +191,8 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
* sets the value of the hidden field, from the select list, always executed after the select field was updated
* previously known as global function setHiddenFromList()
*
* @param selectFieldEl the select field
* @param originalFieldEl the hidden form field
* @param {HTMLElement} selectFieldEl the select field
* @param {HTMLElement} originalFieldEl the hidden form field
*/
FormEngine.updateHiddenFieldValueFromSelect = setHiddenFromList = function(selectFieldEl, originalFieldEl) {
var selectedValues = [];
......@@ -196,7 +205,13 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
$(originalFieldEl).val(selectedValues.join(','));
};
// legacy function, can be removed once this function is not in use anymore
/**
* legacy function, can be removed once this function is not in use anymore
*
* @param {String} fName
* @param {String} type
* @param {Number} maxLength
*/
setFormValueManipulate = function(fName, type, maxLength) {
var $formEl = FormEngine.getFormElement(fName);
if ($formEl.length > 0) {
......@@ -362,12 +377,12 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
/**
* legacy function
* Legacy function
* returns the DOM object for the given form name of the current form,
* but only if the given field name is valid, legacy function, use "getFormElement" instead
*
* @param fieldName the name of the field name
* @returns {*|DOMElement}
* @param {String} fieldName the name of the field name
* @returns {*|HTMLElement}
*/
setFormValue_getFObj = function(fieldName) {
var $formEl = FormEngine.getFormElement(fieldName);
......@@ -384,7 +399,7 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
* if the parameter "fieldName" is given, then the form element is only returned if the field name is available
* the latter behaviour mirrors the one of the function "setFormValue_getFObj"
*
* @param fieldName the field name to check for, optional
* @param {String} fieldName the field name to check for, optional
* @returns {*|HTMLElement}
*/
FormEngine.getFormElement = function(fieldName) {
......@@ -412,12 +427,12 @@ define(['jquery', 'TYPO3/CMS/Backend/Modal'], function ($, Modal) {
/**
* returns a jQuery object of the field DOM element of the current form, can also be used to
* Returns a jQuery object of the field DOM element of the current form, can also be used to
* request an alternative field like "_hr", "_list" or "_mul"
*