Skip to content
Snippets Groups Projects
Commit c8b9ed6f authored by Angie Byron's avatar Angie Byron
Browse files

Issue #2501913 by nod_, jhodgdon: JSDoc drupal.js

parent b1d31da9
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 91 additions and 68 deletions
core/misc/drupal.js
+ 91
− 68
View file @ c8b9ed6f
/**
* @file
* Defines the Drupal JS API.
* Defines the Drupal JavaScript API.
*/
/**
* A jQuery object.
* A jQuery object, typically the return value from a `$(selector)` call.
*
* Holds an HTMLElement or a collection of HTMLElements.
*
* @typedef {object} jQuery
*
* @prop {number} length=0
* Number of elements contained in the jQuery object.
*/
/**
* Variable generated by Drupal that holds all translated strings from PHP.
*
* Content of this variable is automatically created by Drupal when using the
* Interface Translation module. It holds the translation of strings used on
* the page.
*
* This variable is used to pass data from the backend to the frontend. Data
* contained in `drupalSettings` is used during behavior initialization.
*
* @global
*
* @var {object} drupalTranslations
......@@ -22,13 +32,15 @@
/**
* Global Drupal object.
*
* All Drupal JavaScript APIs are contained in this namespace.
*
* @global
*
* @namespace
*/
window.Drupal = {behaviors: {}, locale: {}};
// Class indicating that JS is enabled; used for styling purpose.
// Class indicating that JavaScript is enabled; used for styling purpose.
document.documentElement.className += ' js';
// Allow other JavaScript libraries to use $.
......@@ -56,25 +68,30 @@ if (window.jQuery) {
};
/**
* Callback function initializing code run on page load and Ajax requests.
* Custom error thrown after attach/detach if one or more behaviors failed.
* Initializes the JavaScript behaviors for page loads and Ajax requests.
*
* @callback Drupal~behaviorAttach
*
* @param {HTMLElement} context
* @param {object} settings
* @param {HTMLDocument|HTMLElement} context
* An element to detach behaviors from.
* @param {?object} settings
* An object containing settings for the current context. It is rarely used.
*
* @see Drupal.attachBehaviors
*/
/**
* Callback function for reverting and cleaning up behavior initialization.
* Reverts and cleans up JavaScript behavior initialization.
*
* @callback Drupal~behaviorDetach
*
* @param {HTMLElement} context
* @param {HTMLDocument|HTMLElement} context
* An element to attach behaviors to.
* @param {object} settings
* An object containing settings for the current context.
* @param {string} trigger
* One of 'unload', 'serialize' or 'move'.
* One of `'unload'`, `'move'`, or `'serialize'`.
*
* @see Drupal.detachBehaviors
*/
......@@ -83,7 +100,7 @@ if (window.jQuery) {
* @typedef {object} Drupal~behavior
*
* @prop {Drupal~behaviorAttach} attach
* Function run on page load and after an AJAX call.
* Function run on page load and after an Ajax call.
* @prop {Drupal~behaviorDetach} detach
* Function run when content is serialized or removed from the page.
*/
......@@ -97,42 +114,42 @@ if (window.jQuery) {
*/
/**
* Attach all registered behaviors to a page element.
* Defines a behavior to be run during attach and detach phases.
*
* Attaches all registered behaviors to a page element.
*
* Behaviors are event-triggered actions that attach to page elements,
* enhancing default non-JavaScript UIs. Behaviors are registered in the
* {@link Drupal.behaviors} object using the method 'attach' and optionally
* also 'detach' as follows:
* also 'detach'.
*
* {@link Drupal.attachBehaviors} is added below to the jQuery.ready event and
* therefore runs on initial page load. Developers implementing Ajax in their
* solutions should also call this function after new page content has been
* loaded, feeding in an element to be processed, in order to attach all
* {@link Drupal.attachBehaviors} is added below to the `jQuery.ready` event
* and therefore runs on initial page load. Developers implementing Ajax in
* their solutions should also call this function after new page content has
* been loaded, feeding in an element to be processed, in order to attach all
* behaviors to the new content.
*
* Behaviors should use
* `var elements = $(context).find(selector).once('behavior-name');`
* to ensure the behavior is attached only once to a given element. (Doing so
* enables the reprocessing of given elements, which may be needed on
* occasion despite the ability to limit behavior attachment to a particular
* element.)
* Behaviors should use `var elements =
* $(context).find(selector).once('behavior-name');` to ensure the behavior is
* attached only once to a given element. (Doing so enables the reprocessing
* of given elements, which may be needed on occasion despite the ability to
* limit behavior attachment to a particular element.)
*
* @example
* Drupal.behaviors.behaviorName = {
* attach: function (context, settings) {
* ...
* // ...
* },
* detach: function (context, settings, trigger) {
* ...
* // ...
* }
* };
*
* @param {Element} context
* An element to attach behaviors to. If none is given, the document
* element is used.
* @param {object} settings
* @param {HTMLDocument|HTMLElement} [context=document]
* An element to attach behaviors to.
* @param {object} [settings=drupalSettings]
* An object containing settings for the current context. If none is given,
* the global drupalSettings object is used.
* the global {@link drupalSettings} object is used.
*
* @see Drupal~behaviorAttach
* @see Drupal.detachBehaviors
......@@ -161,29 +178,27 @@ if (window.jQuery) {
domready(function () { Drupal.attachBehaviors(document, drupalSettings); });
/**
* Detach registered behaviors from a page element.
* Detaches registered behaviors from a page element.
*
* Developers implementing AHAH/Ajax in their solutions should call this
* function before page content is about to be removed, feeding in an element
* to be processed, in order to allow special behaviors to detach from the
* content.
* Developers implementing Ajax in their solutions should call this function
* before page content is about to be removed, feeding in an element to be
* processed, in order to allow special behaviors to detach from the content.
*
* Such implementations should use .findOnce() and .removeOnce() to find
* elements with their corresponding Drupal.behaviors.behaviorName.attach
* implementation, i.e. .removeOnce('behaviorName'), to ensure the behavior
* Such implementations should use `.findOnce()` and `.removeOnce()` to find
* elements with their corresponding `Drupal.behaviors.behaviorName.attach`
* implementation, i.e. `.removeOnce('behaviorName')`, to ensure the behavior
* is detached only from previously processed elements.
*
* @param {Element} context
* An element to detach behaviors from. If none is given, the document
* element is used.
* @param {object} settings
* @param {HTMLDocument|HTMLElement} [context=document]
* An element to detach behaviors from.
* @param {object} [settings=drupalSettings]
* An object containing settings for the current context. If none given,
* the global drupalSettings object is used.
* @param {string} trigger
* the global {@link drupalSettings} object is used.
* @param {string} [trigger='unload']
* A string containing what's causing the behaviors to be detached. The
* possible triggers are:
* - unload: (default) The context element is being removed from the DOM.
* - move: The element is about to be moved within the DOM (for example,
* - `'unload'`: The context element is being removed from the DOM.
* - `'move'`: The element is about to be moved within the DOM (for example,
* during a tabledrag row swap). After the move is completed,
* {@link Drupal.attachBehaviors} is called, so that the behavior can undo
* whatever it did in response to the move. Many behaviors won't need to
......@@ -191,7 +206,7 @@ if (window.jQuery) {
* IFRAME elements reload their "src" when being moved within the DOM,
* behaviors bound to IFRAME elements (like WYSIWYG editors) may need to
* take some action.
* - serialize: When an Ajax form is submitted, this is called with the
* - `'serialize'`: When an Ajax form is submitted, this is called with the
* form as the context. This provides every behavior within the form an
* opportunity to ensure that the field elements have correct content
* in them before the form is serialized. The canonical use-case is so
......@@ -223,11 +238,14 @@ if (window.jQuery) {
};
/**
* Helper to test document width for mobile configurations.
* Tests the document width for mobile configurations.
*
* @param {number} [width=640]
* Value of the width to check for.
*
* @return {bool}
* true if the document's `clientWidth` is bigger than `width`, returns
* false otherwise.
*
* @deprecated Temporary solution for the mobile initiative.
*/
......@@ -237,7 +255,7 @@ if (window.jQuery) {
};
/**
* Encode special characters in a plain-text string for display as HTML.
* Encodes special characters in a plain-text string for display as HTML.
*
* @param {string} str
* The string to be encoded.
......@@ -257,7 +275,7 @@ if (window.jQuery) {
};
/**
* Replace placeholders with sanitized values in a string.
* Replaces placeholders with sanitized values in a string.
*
* @param {string} str
* A string with placeholders.
......@@ -265,11 +283,11 @@ if (window.jQuery) {
* An object of replacements pairs to make. Incidences of any key in this
* array are replaced with the corresponding value. Based on the first
* character of the key, the value is escaped and/or themed:
* - !variable: inserted as is
* - @variable: escape plain text to HTML ({@link Drupal.checkPlain})
* - %variable: escape text and theme as a placeholder for user-submitted
* content ({@link Drupal.checkPlain} +
* {@link Drupal.theme}('placeholder'))
* - `'!variable'`: inserted as is.
* - `'@variable'`: escape plain text to HTML ({@link Drupal.checkPlain}).
* - `'%variable'`: escape text and theme as a placeholder for user-
* submitted content ({@link Drupal.checkPlain} +
* `{@link Drupal.theme}('placeholder')`).
*
* @return {string}
*
......@@ -304,7 +322,7 @@ if (window.jQuery) {
};
/**
* Replace substring.
* Replaces substring.
*
* The longest keys will be tried first. Once a substring has been replaced,
* its new value will not be searched again.
......@@ -314,10 +332,10 @@ if (window.jQuery) {
* @param {object} args
* Key-value pairs.
* @param {Array|null} keys
* Array of keys from the "args". Internal use only.
* Array of keys from `args`. Internal use only.
*
* @return {string}
* Returns the replaced string.
* The replaced string.
*/
Drupal.stringReplace = function (str, args, keys) {
if (str.length === 0) {
......@@ -356,7 +374,7 @@ if (window.jQuery) {
};
/**
* Translate strings to the page language or a given language.
* Translates strings to the page language, or a given language.
*
* See the documentation of the server-side t() function for further details.
*
......@@ -367,10 +385,12 @@ if (window.jQuery) {
* of any key in this array are replaced with the corresponding value.
* See {@link Drupal.formatString}.
* @param {object} [options]
* Additional options for translation.
* @param {string} [options.context='']
* The context the source string belongs to.
*
* @return {string}
* The formatted string.
* The translated string.
*/
Drupal.t = function (str, args, options) {
......@@ -395,6 +415,7 @@ if (window.jQuery) {
* Drupal path to transform to URL.
*
* @return {string}
* The full URL.
*/
Drupal.url = function (path) {
return drupalSettings.path.baseUrl + drupalSettings.path.pathPrefix + path;
......@@ -403,10 +424,10 @@ if (window.jQuery) {
/**
* Returns the passed in URL as an absolute URL.
*
* @param url
* @param {string} url
* The URL string to be normalized to an absolute URL.
*
* @return
* @return {string}
* The normalized, absolute URL.
*
* @see https://github.com/angular/angular.js/blob/v1.4.4/src/ng/urlUtils.js
......@@ -435,11 +456,11 @@ if (window.jQuery) {
/**
* Returns true if the URL is within Drupal's base path.
*
* @param url
* @param {string} url
* The URL string to be tested.
*
* @return
* Boolean true if local.
* @return {bool}
* `true` if local.
*
* @see https://github.com/jquery/jquery-ui/blob/1.11.4/ui/tabs.js#L58
*/
......@@ -476,7 +497,7 @@ if (window.jQuery) {
};
/**
* Format a string containing a count of items.
* Formats a string containing a count of items.
*
* This function ensures that the string is pluralized correctly. Since
* {@link Drupal.t} is called by this function, make sure not to pass
......@@ -536,22 +557,24 @@ if (window.jQuery) {
* Unencoded path.
*
* @return {string}
* The encoded path.
*/
Drupal.encodePath = function (item) {
return window.encodeURIComponent(item).replace(/%2F/g, '/');
};
/**
* Generate the themed representation of a Drupal object.
* Generates the themed representation of a Drupal object.
*
* All requests for themed output must go through this function. It examines
* the request and routes it to the appropriate theme function. If the current
* theme does not provide an override function, the generic theme function is
* called.
*
* For example, to retrieve the HTML for text that should be emphasized and
* displayed as a placeholder inside a sentence, call
* `Drupal.theme('placeholder', text)`.
* @example
* <caption>To retrieve the HTML for text that should be emphasized and
* displayed as a placeholder inside a sentence.</caption>
* Drupal.theme('placeholder', text);
*
* @namespace
*
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment