JavaScript Helper Functions#
These helper functions are deprecated since version 5.4. Refer to our migration guide on how to replace them.
Introduction#
Since version 3.0, WoltLab Suite ships with a set of global helper functions that are
exposed on the window
-object and thus are available regardless of the context.
They are meant to reduce code repetition and to increase readability by moving
potentially relevant parts to the front of an instruction.
Elements#
elCreate(tagName: string): Element
#
Creates a new element with the provided tag name.
1 2 3 |
|
elRemove(element: Element)
#
Removes an element from its parent without returning it. This function will throw
an error if the element
doesn't have a parent node.
1 2 3 |
|
elShow(element: Element)
#
Attempts to show an element by removing the display
CSS-property, usually used
in conjunction with the elHide()
function.
1 2 3 |
|
elHide(element: Element)
#
Attempts to hide an element by setting the display
CSS-property to none
, this
is intended to be used with elShow()
that relies on this behavior.
1 2 3 |
|
elToggle(element: Element)
#
Attempts to toggle the visibility of an element by examining the value of the
display
CSS-property and calls either elShow()
or elHide()
.
Attributes#
elAttr(element: Element, attribute: string, value?: string): string
#
Sets or reads an attribute value, value are implicitly casted into strings and
reading non-existing attributes will always yield an empty string. If you want
to test for attribute existence, you'll have to fall-back to the native
Element.hasAttribute()
method.
You should read and set native attributes directly, such as img.src
rather
than img.getAttribute("src");
.
1 2 3 4 5 6 7 |
|
elAttrBool(element: Element, attribute: string): boolean
#
Reads an attribute and converts it value into a boolean value, the strings "1"
and "true"
will evaluate to true
. All other values, including a missing attribute,
will return false
.
1 2 3 |
|
elData(element: Element, attribute: string, value?: string): string
#
Short-hand function to read or set HTML5 data-*
-attributes, it essentially
prepends the data-
prefix before forwarding the call to elAttr()
.
1 2 3 4 5 6 7 |
|
elDataBool(element: Element, attribute: string): boolean
#
Short-hand function to convert a HTML5 data-*
-attribute into a boolean value. It
prepends the data-
prefix before forwarding the call to elAttrBool()
.
1 2 3 4 5 6 7 |
|
Selecting Elements#
Unlike libraries like jQuery, these functions will return null
if an element is not found. You are responsible to validate if the element exist and to branch accordingly, invoking methods on the return value without checking for null
will yield an error.
elById(id: string): Element | null
#
Selects an element by its id
-attribute value.
1 2 3 |
|
elBySel(selector: string, context?: Element): Element | null
#
The underlying querySelector()
-method works on the entire DOM hierarchy and can yield results outside of your context element! Please read and understand the MDN article on Element.querySelector()
to learn more about this.
Select a single element based on a CSS selector, optionally limiting the results to be a direct or indirect children of the context element.
1 2 3 4 5 6 7 8 |
|
elBySelAll(selector: string, context?: Element, callback: (element: Element) => void): NodeList
#
The underlying querySelector()
-method works on the entire DOM hierarchy and can yield results outside of your context element! Please read and understand the MDN article on Element.querySelector()
to learn more about this.
Finds and returns a NodeList
containing all elements that match the provided
CSS selector. Although NodeList
is an array-like structure, it is not possible
to iterate over it using array functions, including .forEach()
which is not
available in Internet Explorer 11.
1 2 3 4 5 6 7 8 |
|
Callback to Iterate Over Elements#
elBySelAll()
supports an optional third parameter that expects a callback function
that is invoked for every element in the list.
1 2 3 4 5 6 7 8 9 |
|
elClosest(element: Element, selector: string): Element | null
#
Returns the first Element
that matches the provided CSS selector, this will
return the provided element itself if it matches the selector.
1 2 3 |
|
Text Nodes#
If the provided context is a Text
-node, the function will move the context to
the parent element before applying the CSS selector. If the Text
has no parent,
null
is returned without evaluating the selector.
elByClass(className: string, context?: Element): NodeList
#
Returns a live NodeList
containing all elements that match the provided CSS
class now and in the future! The collection is automatically updated whenever
an element with that class is added or removed from the DOM, it will also include
elements that get dynamically assigned or removed this CSS class.
You absolutely need to understand that this collection is dynamic, that means that
elements can and will be added and removed from the collection even while you
iterate over it. There are only very few cases where you would need such a collection,
almost always elBySelAll()
is what you're looking for.
1 2 3 4 5 6 7 8 9 |
|
elByTag(tagName: string, context?: Element): NodeList
#
Returns a live NodeList
containing all elements with the provided tag name now
and in the future! Please read the remarks on elByClass()
above to understand
the implications of this.
1 2 3 4 5 6 7 8 |
|
Utility Functions#
elInnerError(element: Element, errorMessage?: string, isHtml?: boolean): Element | null
#
Unified function to display and remove inline error messages for input elements, please read the section in the migration docs to learn more about this function.
String Extensions#
hashCode(): string
#
Computes a numeric hash value of a string similar to Java's String.hashCode()
method.
1 2 |
|