opdavies/drupalcampbristol
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update to Drupal 8.0.0-beta15. For more information, see: https://www.drupal.org/node/2563023

Browse source
This commit is contained in:
Pantheon Automation 2015-09-04 13:20:09 -07:00 • committed by Greg Anderson
parent 2720a9ec4b
commit f3791f1da3
1898 changed files with 54300 additions and 11481 deletions
Download patch file Download diff file Expand all files Collapse all files

306
core/misc/drupal.js
View file

@ -1,27 +1,29 @@
/**
* @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
*/
/**
* Variable generated by Drupal with all the configuration created from PHP.
*
* @global
*
* @var {object} drupalSettings
* 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
@ -30,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 $.
@ -51,82 +55,43 @@ if (window.jQuery) {
"use strict";
/**
* Custom error type thrown after attach/detach if one or more behaviors
* failed.
* Helper to rethrow errors asynchronously.
*
* @memberof Drupal
* This way Errors bubbles up outside of the original callstack, making it
* easier to debug errors in the browser.
*
* @constructor
*
* @augments Error
*
* @param {Array} list
* An array of errors thrown during attach/detach.
* @param {string} event
* A string containing either 'attach' or 'detach'.
*
* @inner
* @param {Error|string} error
* The error to be thrown.
*/
function DrupalBehaviorError(list, event) {
/**
* Setting name helps debuggers.
*
* @type {string}
*/
this.name = 'DrupalBehaviorError';
/**
* Execution phase errors were triggered.
*
* @type {string}
*/
this.event = event || 'attach';
/**
* All thrown errors.
*
* @type {Array.<Error>}
*/
this.list = list;
// Makes the list of errors readable.
var messageList = [];
messageList.push(this.event);
var il = this.list.length;
for (var i = 0; i < il; i++) {
messageList.push(this.list[i].behavior + ': ' + this.list[i].error.message);
}
/**
* Final message to send to debuggers.
*
* @type {string}
*/
this.message = messageList.join(' ; ');
}
DrupalBehaviorError.prototype = new Error();
Drupal.throwError = function (error) {
setTimeout(function () { throw error; }, 0);
};
/**
* 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
*/
@ -135,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.
*/
@ -149,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
@ -194,7 +159,6 @@ if (window.jQuery) {
Drupal.attachBehaviors = function (context, settings) {
context = context || document;
settings = settings || drupalSettings;
var errors = [];
var behaviors = Drupal.behaviors;
// Execute all of them.
for (var i in behaviors) {
@ -204,43 +168,37 @@ if (window.jQuery) {
behaviors[i].attach(context, settings);
}
catch (e) {
errors.push({behavior: i, error: e});
Drupal.throwError(e);
}
}
}
// Once all behaviors have been processed, inform the user about errors.
if (errors.length) {
throw new DrupalBehaviorError(errors, 'attach');
}
};
// Attach all behaviors.
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
@ -248,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
@ -264,7 +222,6 @@ if (window.jQuery) {
context = context || document;
settings = settings || drupalSettings;
trigger = trigger || 'unload';
var errors = [];
var behaviors = Drupal.behaviors;
// Execute all of them.
for (var i in behaviors) {
@ -274,22 +231,21 @@ if (window.jQuery) {
behaviors[i].detach(context, settings, trigger);
}
catch (e) {
errors.push({behavior: i, error: e});
Drupal.throwError(e);
}
}
}
// Once all behaviors have been processed, inform the user about errors.
if (errors.length) {
throw new DrupalBehaviorError(errors, 'detach:' + trigger);
}
};
/**
* 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.
*/
@ -299,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.
@ -319,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.
@ -327,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}
*
@ -366,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.
@ -376,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) {
@ -418,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.
*
@ -429,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) {
@ -457,13 +415,89 @@ 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;
};
/**
* Format a string containing a count of items.
* Returns the passed in URL as an absolute URL.
*
* @param {string} url
* The URL string to be normalized to an absolute URL.
*
* @return {string}
* The normalized, absolute URL.
*
* @see https://github.com/angular/angular.js/blob/v1.4.4/src/ng/urlUtils.js
* @see https://grack.com/blog/2009/11/17/absolutizing-url-in-javascript
* @see https://github.com/jquery/jquery-ui/blob/1.11.4/ui/tabs.js#L53
*/
Drupal.url.toAbsolute = function (url) {
var urlParsingNode = document.createElement('a');
// Decode the URL first; this is required by IE <= 6. Decoding non-UTF-8
// strings may throw an exception.
try {
url = decodeURIComponent(url);
}
catch (e) {
// Empty.
}
urlParsingNode.setAttribute('href', url);
// IE <= 7 normalizes the URL when assigned to the anchor node similar to
// the other browsers.
return urlParsingNode.cloneNode(false).href;
};
/**
* Returns true if the URL is within Drupal's base path.
*
* @param {string} url
* The URL string to be tested.
*
* @return {bool}
* `true` if local.
*
* @see https://github.com/jquery/jquery-ui/blob/1.11.4/ui/tabs.js#L58
*/
Drupal.url.isLocal = function (url) {
// Always use browser-derived absolute URLs in the comparison, to avoid
// attempts to break out of the base path using directory traversal.
var absoluteUrl = Drupal.url.toAbsolute(url);
var protocol = location.protocol;
// Consider URLs that match this site's base URL but use HTTPS instead of HTTP
// as local as well.
if (protocol === 'http:' && absoluteUrl.indexOf('https:') === 0) {
protocol = 'https:';
}
var baseUrl = protocol + '//' + location.host + drupalSettings.path.baseUrl.slice(0, -1);
// Decoding non-UTF-8 strings may throw an exception.
try {
absoluteUrl = decodeURIComponent(absoluteUrl);
}
catch (e) {
// Empty.
}
try {
baseUrl = decodeURIComponent(baseUrl);
}
catch (e) {
// Empty.
}
// The given URL matches the site's base URL, or has a path under the site's
// base URL.
return absoluteUrl === baseUrl || absoluteUrl.indexOf(baseUrl + '/') === 0;
};
/**
* 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
@ -523,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
*