Utilities

This module contains various, individually documented tools for front-end software development using JavaScript. The original code is implemented in TypeScript 2, and follows the ECMA 2016 standards and protocols.

JavaScript ECMA 5 files formatted as .js or .min.js are trans-compiled files. Please do not modify such files as all changes will be lost. To contribute, please edit static-src/markdownx/js/utils.ts. See contributions in the documentations for additional instructions.

Note

Typescript type definitions of this module are defined in static-src/markdownx/js/types.ts.

getCookie(name)

Looks for a cookie, and if found, returns the values.

Note

Only the first item in the array is returned to eliminate the need for array deconstruction in the target.

Attention

The function catches the TypeError and returns null if the name provided for the cookie is not found. A notification is then provided in the console to inform the developer that the requested cookie does not exist.

Arguments:
  • name (string) – The name of the cookie.
Returns:

Value of the cookie with the key name or null.
Return type:

string | null
zip(...rows)

JavaScript implementation of Python’s zip function.

Arguments:
  • rows – Array or arrays to zipped together.
Returns:

Array of zipped items.
Return type:

Array[]
Example:
>>> let zipped = zip([1, 'H'], [5, 'i']);

>>> zipped.map(row => row.reduce((m, n) => m + n))
// [6, "Hi"]
mountEvents(...collections)

Mounts a set of events defined in an object onto the document.

Arguments:
  • collections – Must be JSON object and follow the structure outlined in the example.
Returns:

Listeners
Return type:

Event
Example:
>>> let editorListeners = {
...         object: document.getElementById('my-editor'),
...         listeners: [
...             { type: "input",            capture: true , listener: inputChanged },
...             { type: "compositionstart", capture: true , listener: onKeyDown    }
...         ]
... };
triggerEvent(element, type)

Triggers an existing HTML event manually.

Arguments:
  • element (Element) – Element whose event is to be created and triggered.
  • type (string) – Type of the event to be triggered.
triggerCustomEvent(type, element, args)

Triggers an already defined custom event manually.

Arguments:
  • element (Element|Document) – Element whose event is to be triggered.
  • type (string) – Type of the event to be triggered.
  • args – Values to be passed as custom argument to event.details. (Default = null)
preparePostData(data)

Creates a new instance of FormData to be used in AJAX calls.

Arguments:
  • data (Object) – Data to be embedded in the form in JSON format, where the key is the name/ID of the field whose values are to be altered/created and corresponds to dict keys in Django request.POST.
  • csrf (Boolean) – If true, includes the CSRF token (under the name csrfmiddlewaretoken) in the form. Default is true.
Returns:

A new instance FormData that incorporated the data embedded in data and the CSRF token if enabled.
Return type:

FormData
AJAXRequest()

Determines the supported AJAX requests API in IE6+ browsers.

Return type:XMLHttpRequest
Throws:TypeError – AJAX request is not supported.
class Request(url, data)

An XMLHttpRequest wrapper object to initialize AJAX POST requests.

Example:
>>> let value   = "This is a test value",
        postUrl = "https://example.com/";

>>> const xhr = new utils.Request(
...         postUrl,                           // URL
...         preparePostData({content: value})  // Data
...     );

>>> xhr.success  = response => console.log(response);

>>> xhr.error    = response => console.error(response);

>>> xhr.progress = event    => {
...
...     if (event.lengthComputable)
...         console.info(`${(event.loaded / event.total) * 100}% uploaded.`)
...
... };

>>> xhr.send();
url
  • (string) - URL to which the data is to be posted.
data
  • (FormData) - Data, as an instance of FromData, to be posted.
xhr

private

  • (any) - Value obtained automatically by calling AjaxRequest().
constructor(url, data)
Arguments:
  • url (string) – URL to which the data is to be posted.
  • data (FormData) – Data, as an instance of FromData, to be posted.
progress(event)

Progress callback.

Arguments:
  • event (Event) – The entire event (see the example for additional information on usage).
success(response)

Success callback.

Arguments:
  • response (any) – Success values; first available one of responseText, responseXML, or response.
error(response)

Error callback.

Arguments:
  • response (any) – Error value: responseText.
send()

Starts the transfer.

addClass(element, ...classNames)

Given an instance of an element, adds classes to it.

Arguments:
  • element (Element) – Instance of an element.
  • classNames (string[]) – Can be a single string, or multiple strings.
Example:
>>> addClass(document.getElementById('my-element'), 'className');

// or

>>> addClass(document.getElementById('my-element'), 'classA', 'classB', 'classC');
hasClass(element, className)

Given an instance of an element, confirms whether or not the element has the class.

Arguments:
  • element (Element) – Instance of an element.
  • className (string[]) – Can be a single string, or multiple strings.
Returns:

true if the element has the class, otherwise false.
Return type:

boolean
Example:
>>> hasClass(document.getElementById('my-element'), 'className')
// returns True if the element with id "my-element" has the class "className", otherwise False.
removeClass(element, ...classNames)

Given an instance of an element, removes classes to it.

Arguments:
  • element (Element) – Instance of an element.
  • classNames (string[]) – Can be a single string, or multiple strings.
Example:
>>> removeClass(document.getElementById('my-element'), 'className');

// or

>>> removeClass(document.getElementById('my-element'), 'classA', 'classB', 'classC');

MIT Software License

Copyright 2017:Pouria Hadjibagheri

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.