Drupal

Drupal

Source:
Global Drupal object. All Drupal JavaScript APIs are contained in this namespace.

Classes

Ajax
AjaxCommands
AjaxError
DetailsSummarizedContent
Message
ProgressBar
tableDrag
TableHeader
TableResponsive
verticalTab
TabbingContext
TabbingManager

Namespaces

autocomplete
behaviors
states
theme

Members

(static) tabbingManager :Drupal~TabbingManager

Source:
Type:

Methods

(static) ajax(settings) → {Drupal.Ajax}

Source:
See:
Provides Ajax page updating via jQuery $.ajax. This function is designed to improve developer experience by wrapping the initialization of Drupal.Ajax objects and storing all created objects in the Drupal.ajax.instances array.
Example
Drupal.behaviors.myCustomAJAXStuff = {
  attach: function (context, settings) {

    var ajaxSettings = {
      url: 'my/url/path',
      // If the old version of Drupal.ajax() needs to be used those
      // properties can be added
      base: 'myBase',
      element: $(context).find('.someElement')
    };

    var myAjaxObject = Drupal.ajax(ajaxSettings);

    // Declare a new Ajax command specifically for this Ajax object.
    myAjaxObject.commands.insert = function (ajax, response, status) {
      $('#my-wrapper').append(response.data);
      alert('New content was appended to #my-wrapper');
    };

    // This command will remove this Ajax object from the page.
    myAjaxObject.commands.destroyObject = function (ajax, response, status) {
      Drupal.ajax.instances[this.instanceIndex] = null;
    };

    // Programmatically trigger the Ajax request.
    myAjaxObject.execute();
  }
};
Parameters:
Name Type Description
settings object The settings object passed to Drupal.Ajax constructor.
Properties
Name Type Attributes Description
base string <optional>
 Base is passed to Drupal.Ajax constructor as the 'base' parameter.
element HTMLElement <optional>
 Element parameter of Drupal.Ajax constructor, element on which event listeners will be bound.
Returns:
The created Ajax object.
Type
Drupal.Ajax

(static) announce(text, priorityopt) → {function}

Source:
See:
Triggers audio UAs to read the supplied text. The aria-live region will only read the text that currently populates its text node. Replacing text quickly in rapid calls to announce results in only the text from the most recent call to Drupal.announce being read. By wrapping the call to announce in a debounce function, we allow for time for multiple calls to Drupal.announce to queue up their messages. These messages are then joined and append to the aria-live region as one text node.
Parameters:
Name Type Attributes Default Description
text string A string to be read by the UA.
priority string <optional>
 'polite' A string to indicate the priority of the message. Can be either 'polite' or 'assertive'.
Returns:
The return of the call to debounce.
Type
function

(static) attachBehaviors(contextopt, settingsopt)

Source:
See:
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 Drupal.behaviors object using the method 'attach' and optionally also 'detach'. 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 = once('behavior-name', selector, context);` 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) {
    // ...
  }
};
Parameters:
Name Type Attributes Default Description
context HTMLDocument | HTMLElement <optional>
 document An element to attach behaviors to.
settings object <optional>
 drupalSettings An object containing settings for the current context. If none is given, the global drupalSettings object is used.
Throws:
Drupal~DrupalBehaviorError

(static) checkPlain(str) → {string}

Source:
Encodes special characters in a plain-text string for display as HTML.
Parameters:
Name Type Description
str string The string to be encoded.
Returns:
The encoded string.
Type
string

(static) debounce(func, wait, immediate) → {function}

Source:
Limits the invocations of a function in a given time frame. The debounce function wrapper should be used sparingly. One clear use case is limiting the invocation of a callback attached to the window resize event. Before using the debounce function wrapper, consider first whether the callback could be attached to an event that fires less frequently or if the function can be written in such a way that it is only invoked under specific conditions.
Parameters:
Name Type Description
func function The function to be invoked.
wait number The time period within which the callback function should only be invoked once. For example if the wait period is 250ms, then the callback will only be called at most 4 times per second.
immediate boolean Whether we wait at the beginning or end to execute the function.
Returns:
The debounced function.
Type
function

(static) deprecatedProperty(deprecation) → {Object}

Source:
See:
Triggers deprecation error when object property is being used.
Parameters:
Name Type Description
deprecation Object The deprecation options.
Properties
Name Type Description
target Object The targeted object.
deprecatedProperty string A key of the deprecated property.
message string The deprecation message.
Returns:
Type
Object

(static) deprecationError(deprecation)

Source:
See:
Triggers deprecation error. Deprecation errors are only triggered if deprecation errors haven't been suppressed.
Parameters:
Name Type Description
deprecation Object The deprecation options.
Properties
Name Type Description
message string The deprecation message.

(static) detachBehaviors(contextopt, settingsopt, triggeropt)

Source:
See:
Detaches registered behaviors from a page element. 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 `once.filter()` and `once.remove()` to find elements with their corresponding `Drupal.behaviors.behaviorName.attach` implementation, i.e. `once.remove('behaviorName', selector, context)`, to ensure the behavior is detached only from previously processed elements.
Parameters:
Name Type Attributes Default Description
context HTMLDocument | HTMLElement <optional>
 document An element to detach behaviors from.
settings object <optional>
 drupalSettings An object containing settings for the current context. If none given, the global drupalSettings object is used.
trigger string <optional>
 'unload' A string containing what's causing the behaviors to be detached. The possible triggers are: - `'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, Drupal.attachBehaviors is called, so that the behavior can undo whatever it did in response to the move. Many behaviors won't need to do anything simply in response to the element being moved, but because 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 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 that WYSIWYG editors can update the hidden textarea to which they are bound.
Throws:
Drupal~DrupalBehaviorError

(static) displace(broadcastopt) → {Drupal~displaceOffset}

Source:
Properties:
Name Type Description
offsets Drupal~displaceOffset
Informs listeners of the current offset dimensions. Corresponding CSS custom variables are also updated. Corresponding CSS custom variables names are: - `--drupal-displace-offset-top` - `--drupal-displace-offset-right` - `--drupal-displace-offset-bottom` - `--drupal-displace-offset-left`
Parameters:
Name Type Attributes Default Description
broadcast boolean <optional>
 true When true, causes the recalculated offsets values to be broadcast to listeners. If none is given, defaults to true.
Fires:
Returns:
An object whose keys are the for sides an element -- top, right, bottom and left. The value of each key is the viewport displacement distance for that edge.
Type
Drupal~displaceOffset

(static) encodePath(item) → {string}

Source:
Encodes a Drupal path for use in a URL. For aesthetic reasons slashes are not escaped.
Parameters:
Name Type Description
item string Unencoded path.
Returns:
The encoded path.
Type
string

(static) formatPlural(count, singular, plural, argsopt, optionsopt) → {string}

Source:
Formats a string containing a count of items. This function ensures that the string is pluralized correctly. Since Drupal.t is called by this function, make sure not to pass already-localized strings to it. See the documentation of the server-side \Drupal\Core\StringTranslation\TranslationInterface::formatPlural() function for more details.
Parameters:
Name Type Attributes Description
count number The item count to display.
singular string The string for the singular case. Please make sure it is clear this is singular, to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not use @count in the singular string.
plural string The string for the plural case. Please make sure it is clear this is plural, to ease translation. Use @count in place of the item count, as in "@count new comments".
args object <optional>
 An object of replacements pairs to make after translation. Incidences of any key in this array are replaced with the corresponding value. See Drupal.formatString. Note that you do not need to include @count in this array. This replacement is done automatically for the plural case.
options object <optional>
 The options to pass to the Drupal.t function.
Returns:
A translated string.
Type
string

(static) formatString(str, args) → {string}

Source:
See:
Replaces placeholders with sanitized values in a string.
Parameters:
Name Type Description
str string A string with placeholders.
args object 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 (Drupal.checkPlain). - `'%variable'`: escape text and theme as a placeholder for user- submitted content (Drupal.checkPlain + `Drupal.theme('placeholder')`).
Returns:
The formatted string.
Type
string

(static) stringReplace(str, args, keys) → {string}

Source:
Replaces substring. The longest keys will be tried first. Once a substring has been replaced, its new value will not be searched again.
Parameters:
Name Type Description
str string A string with placeholders.
args object Key-value pairs.
keys Array | null Array of keys from `args`. Internal use only.
Returns:
The replaced string.
Type
string

(static) t(str, argsopt, optionsopt) → {string}

Source:
Translates strings to the page language, or a given language. See the documentation of the server-side t() function for further details.
Parameters:
Name Type Attributes Description
str string A string containing the English text to translate.
args Object.<string, string> <optional>
 An object of replacements pairs to make after translation. Incidences of any key in this array are replaced with the corresponding value. See Drupal.formatString.
options object <optional>
 Additional options for translation.
Properties
Name Type Attributes Default Description
context string <optional>
 '' The context the source string belongs to.
Returns:
The formatted string. The translated string.
Type
string

(static) tableSelect()

Source:
Callback used in Drupal.behaviors.tableSelect.

(static) tableSelectRange(from, to, state)

Source:
Parameters:
Name Type Description
from HTMLElement The HTML element representing the "from" part of the range.
to HTMLElement The HTML element representing the "to" part of the range.
state boolean The state to set on the range.

(static) throwError(error)

Source:
Helper to rethrow errors asynchronously. This way Errors bubbles up outside of the original callstack, making it easier to debug errors in the browser.
Parameters:
Name Type Description
error Error | string The error to be thrown.

(static) url(path) → {string}

Source:
Returns the URL to a Drupal page.
Parameters:
Name Type Description
path string Drupal path to transform to URL.
Returns:
The full URL.
Type
string

Type Definitions

behavior

Source:
Properties:
Name Type Attributes Description
attach Drupal~behaviorAttach Function run on page load and after an Ajax call.
detach Drupal~behaviorDetach <optional>
 Function run when content is serialized or removed from the page.
Type:
  • object

behaviorAttach(context, settingsnullable)

Source:
See:
Custom error thrown after attach/detach if one or more behaviors failed. Initializes the JavaScript behaviors for page loads and Ajax requests.
Parameters:
Name Type Attributes Description
context HTMLDocument | HTMLElement An element to detach behaviors from.
settings object <nullable>
 An object containing settings for the current context. It is rarely used.

behaviorDetach(context, settings, trigger)

Source:
See:
Reverts and cleans up JavaScript behavior initialization.
Parameters:
Name Type Description
context HTMLDocument | HTMLElement An element to attach behaviors to.
settings object An object containing settings for the current context.
trigger string One of `'unload'`, `'move'`, or `'serialize'`.

displaceOffset

Source:
Properties:
Name Type Description
top number
left number
right number
bottom number
Type:
  • object