Frontfire Core

Version 2.1.0

No search results

DOM, style and event handling with extra comfort!

What?

The Frontfire Web Frontend Toolkit offers essential styles and effects combined with a consistent set of interactive widgets and layout utilities. It is suitable for web pages and web applications that need a modern and consistent look and feel and use responsive design to work on all devices and screen sizes. All interactions are fully touch-aware and work with any type of pointing device.

Frontfire Core is the foundation of the entire Frontfire toolkit. Its Frontfire class aims to provide simpler access to the JavaScript DOM features with less code. The class works in a similar way as jQuery by selecting and collecting elements through its constructor function and applying operations on all selected elements. This approach lets you work with a number of elements without explicit loop code.

Unlike jQuery, however, the Frontfire API is much closer to the original DOM API. Many of its properties and methods have the same name and behaviour as in the native Node and Element classes. Also, not every Node or Element member is mirrored in Frontfire, because the web lives and changes quickly and Frontfire doesn’t want to stand in the way of web API progress. You can mix native and Frontfire code naturally and it looks very similar. This also means that there is very little chaining of method calls possible. What leads to more code than with jQuery also allows you to use your existing knowledge of native web APIs and only make use of Frontfire where it adds value.

Why?

Most of us have used jQuery at some point in the past. It was a great way to fill in the missing parts of the native DOM API and worked in every browser. But jQuery has kind of grown to its own complete language and framework, and element properties or events even lived inside their own bubble. jQuery and non-jQuery do not play well together.

Over the years, the native DOM API has caught up quite a bit. Not only have all modern browsers implemented the standards very closely, they also provided methods that were previously only available in jQuery in a concise form. Most tasks can now be done with plain JavaScript and are really not that complicated. Many have come to the conclusion that jQuery may not be needed anymore and newer frameworks have dropped dependencies on it.

The first version of Frontfire was made as a jQuery plugin. To remove that dependency of around 40 KiB minified and compressed size, Frontfire 2 provides the lower DOM access layer itself. This is Frontfire Core, a small convenience library that allows about the same comfort, closer to native APIs, at 12 KiB size. It already includes the elementary plugin infrastructure that Frontfire brought to jQuery (around 1 KiB). And since its elements collection core is powered by the ArrayList class (as seen in the many inherited methods, in italic type in the side overview), all Frontfire users get a comfortable and comprehensive array collection class included for free!

How?

Application code should normally not store or pass around Frontfire instances but only native elements. This makes element handling a lot simpler in many places as it is clear what type to expect. Also, comparing element objects is intuitive, whereas Frontfire instances (like jQuery instances) are only wrappers that change with each creation. You can use all native element APIs directly, and always shift to the Frontfire API with a single “F” extension property that is added to all Nodes. (This is the only change to existing prototypes.) It allows using Frontfire methods on an Element with minimal effort and clutter.

The only exception to this recommended use of Frontfire objects is collections of elements. Since neither HTMLCollection nor NodeList can be constructed, the only way to transport multiple elements is by an Array. None of the DOM API methods return an Array though, so a Frontfire collection instance that has already been created to select elements might well be used here. Such variable names can usually be recognised by their plural form.

// Get an element from somewhere let elem = document.getElementById("panel"); // Change many styles elem.F.style = { border: "solid 1px red", backgroundColor: "lightgreen", padding: "5px 10px", "max-width": "400px" }; // Show the element elem.F.show(); // Get multiple elements from somewhere and hide them let elems = document.querySelectorAll(".box"); elems.F.hide(); // Alternatively, select elements with Frontfire let elemF = F("#panel"); let elemF = F.id("panel"); let elemsF = F(".box");

Frontfire objects can be turned back into their native Node object (the first in the collection) with the “first” property. Other collection access properties exist, e.g. “last”.

// Select element with Frontfire let elemF = F("#panel"); // Get the native Element and use it let elem = elemF.first; elem.someNativeAPI();

jQuery compatibility is also provided by the Frontfire’s “$” property and the same “F” extension property added to all jQuery objects. These interop properties are only available when the window.jQuery property is set at the time of loading Frontfire Core. This can be achieved by loading the jQuery script file before Frontfire (and not asynchronously or deferred).

// Select element with Frontfire let elemF = F("#panel"); // Use it with jQuery elemF.$.css("color", "blue"); // Select element with jQuery let elem$ = $("#panel"); // Use it with Frontfire elem$.F.style.color = "red";

Where?

As a modern JavaScript library, this code is compatible with the following environments:

Firefox 62 and later (released 2018-09)
Chrome 70 and later (released 2018-10, and browsers derived thereof)
Safari 12 and later (released 2018-09; by spec; little tested due to the lack of Apple hardware)

The following requirements apply to most parts of Frontfire UI:

Firefox 82 and later (released 2020-10)
Chrome 88 and later (released 2021-01, and browsers derived thereof)
Safari 14 and later (released 2020-09; by spec; little tested due to the lack of Apple hardware)

Earlier versions may work for a limited feature set. The vastly outdated and now abandoned Internet Explorer is explicitly incompatible with this code. Should you be stuck in the past for whatever reason, a transpiler like Babel and a few polyfills might help you out.

This library is released under the terms of the MIT licence. See the complete licence text in the code repository for details.

Documentation

This documentation lists all public members of the Frontfire class. The available parameters are listed for each method, describing which of them are optional or alternative in which combination. The description explains the behaviour and parameter requirements. The return value is shown after the arrow. A link to the native DOM or jQuery class method is provided where there’s great similarity in their function.

A few examples further describe the usage and effect of a method. More examples of inherited methods can often be found at the description of the base class method.

Search

The members are categorised and can be searched (just type ahead). The search also uses aliases for many entries. Start the search text with an equals sign (=) to ignore aliases. Start the search text with the ^ sign to also only find names starting with the search term. Start the search text with the at sign (@) to search by source plugins. Press Escape to reset the search.

Constructor

Frontfire, F

new Frontfire(selector) → Frontfire
new Frontfire(nodes) → Frontfire
new Frontfire(html) → Frontfire
Frontfire(…) → Frontfire
new F(…) → Frontfire
F(…) → Frontfire

Creates a new Frontfire instance that contains the nodes that were selected by the CSS selector, that were specified in an iterable, or that were created from the specified HTML code. The use of the new keyword is optional. F is an alias for Frontfire that is weakly defined, i.e. it will not overwrite an existing definition in the global scope (window object).

Array.F

Array.F → Frontfire

The F property for Array instances provides access to the additional features implemented in Frontfire. The array must only contain Node items. These F extension properties are the only additions to other prototypes made by this library. array.F is a shortcut for: new Frontfire(array)

// Get multiple elements from somewhere let nodes = Array.from(document.getElementsByClassName("box")); // Show the elements nodes.F.show();

See also: Frontfire.array, Frontfire.toArray() (reverse operation)

ArrayList.F

ArrayList.F → Frontfire

The F property for ArrayList instances provides access to the additional features implemented in Frontfire. The array must only contain Node items. These F extension properties are the only additions to other prototypes made by this library. arrayList.F is a shortcut for: new Frontfire(arrayList)

// Get multiple elements from somewhere let nodes = new ArrayList(document.getElementsByClassName("box")); // Show the elements nodes.F.show();

See also: Frontfire.array, Frontfire.toArray(), Frontfire.L (reverse operation)

HTMLCollection.F

HTMLCollection.F → Frontfire

The F property for HTMLCollection instances provides access to the additional features implemented in Frontfire. These F extension properties are the only additions to other prototypes made by this library. nodes.F is a shortcut for: new Frontfire(nodes)

// Get multiple elements from somewhere let htmlCollection = document.getElementsByClassName("box"); // Show the elements htmlCollection.F.show();

Node.F

Node.F → Frontfire

The F property for Node instances provides access to the additional features implemented in Frontfire. These F extension properties are the only additions to other prototypes made by this library. node.F is a shortcut for: new Frontfire(node)

// Get an element from somewhere let node = document.getElementById("panel"); // Show the element node.F.show();

NodeList.F

NodeList.F → Frontfire

The F property for NodeList instances provides access to the additional features implemented in Frontfire. These F extension properties are the only additions to other prototypes made by this library. nodes.F is a shortcut for: new Frontfire(nodes)

// Get multiple elements from somewhere let nodeList = document.querySelectorAll(".box"); // Show the elements nodeList.F.show();

Instance properties

array

Inherited from: ArrayList

array → Array

Gets the internal array of the Frontfire instance. This property cannot be written.

The returned array is the actual object used by the Frontfire instance to collect Nodes. Any changes done to this array will also be reflected in the Frontfire instance.

F

F → this

The F property for other types is also available for Frontfire instances. This allows simply using that operator without type-checking a variable first. It simply returns the same instance and does not allocate any memory, so it is generally safe and efficient to use.

// Get multiple elements from somewhere let nodes = F(".box"); // Forget what the actual collection type was // Now call a Frontfire method on the elements nodes.F.show();

See also: Node.F, NodeList.F, HTMLCollection.F

first

Inherited from: ArrayList

first → Node

Gets or sets the first selected Node. If there is no first Node, undefined is returned.

This is an alternative to: frontfire.array[0] or frontfire.get(0)

Note:
This property returns a Node, not a Frontfire instance containing the first node which would be the behaviour of the jQuery.first() method. To retrieve a Frontfire instance containing the first selected node, use .take(1).

L

L → ArrayList

Gets a new ArrayList instance wrapping the internal array of the Frontfire instance. This property cannot be written.

The returned array is the actual object used by the Frontfire instance to collect Nodes. Any changes done to this array will also be reflected in the Frontfire instance.

This is an alternative to: new ArrayList(frontfire.array)

// Select multiple elements with Frontfire let nodesF = F(".box"); // Use as ArrayList instance, e.g. to call hidden base methods // (ArrayList.remove methods manipulate the collection, not the document) nodesF.L.removeFirst(); // Or keep the ArrayList instance let arrayList = nodesF.L;

See also: Frontfire.array, Frontfire.toArray(), ArrayList.F (reverse operation)

last

Inherited from: ArrayList

last → Node

Gets or sets the last selected Node. If there are no Nodes selected, undefined is returned and setting the property throws an error.

This is an alternative to: frontfire.array[frontfire.length - 1] or frontfire.get(-1)

Note:
This property returns a Node, not a Frontfire instance containing the last node which would be the behaviour of the jQuery.last() method. To retrieve a Frontfire instance containing the last selected node, use .takeLast(1).

length

Inherited from: ArrayList

length → Number

Gets the number of selected Nodes. This property cannot be written.

This returns the same value as: frontfire.array.length

second

Inherited from: ArrayList

second → Node

Gets or sets the second selected Node. If there is no second Node, undefined is returned.

This is an alternative to: frontfire.array[1]

Tree access properties

childElementCount

childElementCount → Number

Gets the total number of child elements of all selected Nodes. This property cannot be written.

childNodes

childNodes → Frontfire

Gets all child nodes of all selected Nodes. This property cannot be written.

children

children → Frontfire

Gets or sets all child elements of all selected Nodes.

closestPositionedParent

closestPositionedParent → Frontfire

Gets the closest positioned parent element of the first selected Node. An element is positioned if its position style property is set to another value than "static". If no positioned parent was found, null is returned. This property cannot be written.

dataset

dataset → Proxy (setter: Object)
dataset(key) → Any
dataset(key, value) → this
dataset(keysValuesObject) → this

Gets a proxy that gets the dataset of the first selected Node, or sets the dataset of all nodes. If there are no Nodes selected, undefined is returned for each data access and setting the property does nothing. All dataset key names are converted to camelCase automatically. Note that the DOM dataset can only contain string values. Setting any other value type (except null) will convert it to a string implicitly.

Difference from DOM API:
Setting the value null will actually remove the entry whereas the DOM API will set the string “null” instead.

// Select multiple elements let nodesF = F(".box"); // Read data nodesF.dataset.customId → The "customId" data value of the first node nodesF.dataset["first-name"] → The "firstName" data value of the first node // Write data nodesF.dataset.customId = 123; → The "customId" data value of all selected nodes is now "123"

Sets the keys and values of the object in the dataset of all selected Nodes.

// Write data (multiple at once) nodesF.dataset = { customId: 123, firstName: "Alex" }; → The "customId" and "firstName" data values of all selected nodes are set to "123" and "Alex"

The proxied object is a function that can also be called directly. When the function is called as a setter, it returns the original Frontfire instance for call chaining. This usage is not recommended, see Method chaining variants.

// Read data nodesF.dataset("customId") → The "customId" data value of the first node // Write data nodesF.dataset("custom-id", 123); → The "customId" data value of all selected nodes is now "123" nodesF.dataset({ customId: 123, firstName: "Alex" }); → The "customId" and "firstName" data values of all selected nodes are set to "123" and "Alex"

datasetJSON

datasetJSON → Proxy (setter: Object)
datasetJSON(key) → Any
datasetJSON(key, value) → this
datasetJSON(keysValuesObject) → this

Gets a proxy that gets the JSON-interpreted dataset of the first selected Node, or sets the JSON-interpreted dataset of all nodes. If there are no Nodes selected, undefined is returned for each data access and setting the property does nothing. All dataset key names are converted to camelCase automatically. The DOM dataset can only contain string values so any value assigned with this property is run through JSON.stringify() and the values retrieved with this property are run through JSON.parse(). If a dataset string value is the empty string, null is returned. Setting null removes the dataset entry.

// Set data F("#id").datasetJSON.record = { id: 1, names: ["A", "B"] }; // Read string data F("#id").dataset.record → '{"id":1,"names":["A","B"]}' // Read JSON-interpreted data F("#id").datasetJSON.record → { id: 1, names: ["A", "B"] }

Sets the keys and values of the object in the dataset of all selected Nodes. See the dataset property for examples.

firstChild

firstChild → Frontfire

Gets the first child node (including non-elements) of each selected Node. This property cannot be written.

firstElementChild

firstElementChild → Frontfire

Gets the first child Element of each selected Node. This property cannot be written.

index

index → Number

Gets the index of the first selected Node among its siblings. If no element is selected, -1 is returned. This property cannot be written.

innerHTML

innerHTML → String

Gets the concatenated HTML content of all selected Nodes, or sets the HTML content of each selected Node. If there are no Nodes selected, an empty string is returned and setting the property does nothing.

lastChild

lastChild → Frontfire

Gets the last child node (including non-elements) of each selected Node. This property cannot be written.

lastElementChild

lastElementChild → Frontfire

Gets the last child Element of each selected Node. This property cannot be written.

nextElementSibling

nextElementSibling → Frontfire

Gets the next sibling Element of each selected Node. This property cannot be written.

nextElementSiblings

nextElementSiblings → Frontfire

Gets all distinct following sibling Elements of all selected Nodes. This property cannot be written.

nextSibling

nextSibling → Frontfire

Gets the next sibling node (including non-elements) of each selected Node. This property cannot be written.

nextSiblings

nextSiblings → Frontfire

Gets all distinct following sibling nodes (including non-elements) of all selected Nodes. This property cannot be written.

nodeName

nodeName → String

Gets the unchanged name of the first selected Node. In HTML documents, this is written in upper-case. In XML documents (including SVG and XHTML), the name casing is as in the document. This property cannot be written.

nodeNameLower

nodeNameLower → String

Gets the lower-case name of the first selected Node. This property cannot be written.

outerHTML

outerHTML → String

Gets the concatenated HTML of all selected Nodes, or sets the HTML of each selected Node. If there are no Nodes selected, an empty string is returned and setting the property does nothing.

parentElement

parentElement → Frontfire

Gets the parent element of the first selected Node. If the first selected Node has no parent, null is returned. This property cannot be written.

parentNode

parentNode → Frontfire

Gets the parent node of the first selected Node. If the first selected Node has no parent, null is returned. This property cannot be written.

parents

parents → Frontfire

Gets all distinct ancestor elements of all selected Nodes. This property cannot be written.

previousElementSibling

previousElementSibling → Frontfire

Gets the preceding sibling Element of each selected Node. This property cannot be written.

previousElementSiblings

previousElementSiblings → Frontfire

Gets all distinct preceding sibling Elements of all selected Nodes. This property cannot be written.

previousSibling

previousSibling → Frontfire

Gets the preceding sibling node (including non-elements) of each selected Node. This property cannot be written.

previousSiblings

previousSiblings → Frontfire

Gets all distinct preceding sibling nodes (including non-elements) of all selected Nodes. This property cannot be written.

siblings

siblings → Frontfire

Gets all distinct sibling elements of all selected Nodes, not including the selected Node itself (unless it is a sibling of another selected Node). This property cannot be written.

textContent

textContent → String

Gets the concatenated text content of all selected Nodes, or sets the text content of each selected Node. If there are no Nodes selected, an empty string is returned and setting the property does nothing.

Style access properties

borderHeight

borderHeight → Number

Gets the computed border box height of the first selected Node, or sets the border box height of all selected Nodes, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is unaffected by the element’s box-sizing and will be compensated for as necessary. The border box size includes the element’s content, padding and border.

borderWidth

borderWidth → Number

Gets the computed border box width of the first selected Node, or sets the border box width of all selected Nodes, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is unaffected by the element’s box-sizing and will be compensated for as necessary. The border box size includes the element’s content, padding and border.

bottom

bottom → Number

Gets the bottom location of the first selected Node in the document, considering its border height, in pixels. If there are no Nodes selected, 0 is returned. Note that this is the rendered position that may be affected by CSS transforms.

checked

checked → Boolean

Gets a value indicating whether all selected Nodes are checked, or sets the checked property of all selected Nodes. If there are no Nodes selected, false is returned. If a Node does not support the checked property, its attribute with the same name is accessed. Triggers the “checkedchange” event for each Node if the state was changed.

classList

classList → Object

Gets an object with methods to manage the CSS classes of the selected Nodes. The methods and properties in the returned object are described separately below.

Sets the CSS classes of all selected Nodes and overwrites all existing classes. Only strings with one or more space-separated class names as well as arrays with each one or more space-separated class names are accepted.

F(".box").classList = "panel"; → All selected nodes have only the class "panel" F(".box").classList = "box panel"; F(".box").classList = ["box", "panel"]; → All selected nodes have only the classes "box" and "panel"

classList.add

add(classNames) → void

Adds class names to the selected Nodes. The class names can be specified as space-separated string, array (iterable), multiple arguments, or any combination thereof.

F(".box").classList.add("panel") → All "box" elements now also have the "panel" class

classList.contains

contains(classNames) → Boolean

Determines whether any of the selected Nodes has all of the specified class names. The class names can be specified as space-separated string, array (iterable), or any combination thereof. If there are no Nodes selected, false is returned.

F(".box").classList.contains("box") → true

classList.forEach

forEach(action) → void
forEach(action, thisArg) → void

Calls a function once for each class name in the selected Nodes. The callback function gets three arguments:

The class name
Its index in the array
The entire array to iterate

If thisArg is set, it is assigned to this when executing the callback function. The parameter semantics is the same as the Array.forEach() method.

classList.length

length → Number

Gets the number of distinct classes of the selected Nodes. If there are no Nodes selected, 0 is returned.

classList.remove

remove(classNames) → void

Removes class names from the selected Nodes. The class names can be specified as space-separated string, array (iterable), multiple arguments, or any combination thereof.

classList.replace

replace(oldClass, newClass) → Boolean

Replaces a class name with a new class name in the selected Nodes. Returns a value indicating whether the oldClass was replaced in any of the selected Nodes.

classList.toArray

toArray() → Array

Returns an Array of the distinct class names in the selected Nodes.

classList.toggle

toggle(classNames) → Boolean
toggle(classNames, force) → Boolean

Toggles class names on the selected Nodes. The class names can be specified as space-separated string, array (iterable), or any combination thereof. If the force parameter is set to true or false, it forces the classes to always be added or removed instead of toggled. Returns a value indicating whether all classes are set in all selected Nodes after the operation.

computedStyle

computedStyle → Style

Gets the computed style of the first selected Node. If there are no Nodes selected, an error is thrown. This property cannot be written.

contentHeight

contentHeight → Number

Gets the computed content box height of the first selected Node, or sets the content box height of all selected Nodes, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is unaffected by the element’s box-sizing and will be compensated for as necessary. The content box size includes the element’s content, but not the padding and border.

contentWidth

contentWidth → Number

Gets the computed content box width of the first selected Node, or sets the content box width of all selected Nodes, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is unaffected by the element’s box-sizing and will be compensated for as necessary. The content box size includes the element’s content, but not the padding and border.

dark

dark → Boolean

Gets a value indicating whether all selected Nodes have the dark theme (CSS class from Frontfire UI). An element uses the dark theme if itself or any parent has the dark CSS class and no intermediate parent has the not-dark CSS class. If there are no Nodes selected, false is returned.

Added in v2.1.0

disabled

disabled → Boolean

Gets a value indicating whether all selected Nodes are disabled, or sets the disabled property of all selected Nodes. If there are no Nodes selected, false is returned. If a Node does not support the disabled property, its attribute with the same name is accessed. Triggers the “disabledchange” event for each Node if the state was changed.

Setting this property will also set it on the parent or referenced <label> element. In the Frontfire UI form layout, it will also find the previous sibling with the “label” class up on the level of the “form-row” class.

Setting this property on <a> elements stashes and restores the href attribute to fully disable the hyperlink.

effectiveBackgroundColor

effectiveBackgroundColor → Color

Gets the effective background colour of an element, considering all parents for non-opaque colours. Requires the Color class and returns a Color instance.

Added in v2.1.0

effectivelyVisible

effectivelyVisible → Boolean

Gets a value indicating whether all selected Nodes are effectively visible. A node is considered visible if it has dimensions and its computed "visibility" style is "visible". If there are no Nodes selected, false is returned. This property cannot be written.

height

height → Number

Gets the computed height of the first selected Node, or sets the height property of all selected Nodes. Getting the property returns a number in pixels. Setting the property accepts a number in pixels, or any string that is allowed for the height style. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is affected by the element’s box-sizing.

left

left → Number

Gets the left location of the first selected Node, or sets the left location of all selected Nodes, relative to the document, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. Note that this is the rendered position that may be affected by CSS transforms.

paddingHeight

paddingHeight → Number

Gets the computed padding box height of the first selected Node, or sets the padding box height of all selected Nodes, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is unaffected by the element’s box-sizing and will be compensated for as necessary. The padding box size includes the element’s content and padding, but not the border.

paddingWidth

paddingWidth → Number

Gets the computed padding box width of the first selected Node, or sets the padding box width of all selected Nodes, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is unaffected by the element’s box-sizing and will be compensated for as necessary. The padding box size includes the element’s content and padding, but not the border.

readonly

readonly → Boolean

Gets a value indicating whether all selected Nodes are readonly, or sets the readonly property of all selected Nodes. If there are no Nodes selected, false is returned. If a Node does not support the readonly property, its attribute with the same name is accessed. Triggers the “readonlychange” event for each Node if the state was changed.

If a Node does not support the readonly property but instead the disabled property, that property is accessed instead and the “disabledchange” event might be triggered.

rect

rect → Object

Gets the location and border size of the first selected Node in the document. Note that this is the rendered position that may be affected by CSS transforms. This property cannot be written. The returning object has the following keys:

left: The left location in the document, in pixels.
top: The top location in the document, in pixels.
width: The computed border box width, in pixels.
height: The computed border box height, in pixels.
right: The sum of left and width, i.e. the left location of the right edge.
bottom: The sum of top and height, i.e. the top location of the bottom edge.

right

right → Number

Gets the right location of the first selected Node in the document, considering its border width, in pixels. If there are no Nodes selected, 0 is returned. Note that this is the rendered position that may be affected by CSS transforms.

selected

selected → Boolean

Gets a value indicating whether all selected Nodes (in the Frontfire collection) are selected, or sets the selected property of all selected Nodes. If there are no Nodes selected, false is returned. If a Node does not support the selected property, its attribute with the same name is accessed. Triggers the “selectedchange” event for each Node if the state was changed.

style

style → Proxy (setter: Object)
style(key) → String
style(key, value) → this
style(keysValuesObject) → this

Gets a proxy that gets the style of the first selected Node, or sets the style of all nodes. If there are no Nodes selected, undefined is returned for each style access and setting the property does nothing. All style key specifications are converted to camelCase automatically.

// Select multiple elements let nodesF = F(".box"); // Read style nodesF.style.marginTop → The "margin-top" style of the first node nodesF.style["background-color"] → The "background-color" style of the first node // Write style nodesF.style.marginTop = "10px"; → The "margin-top" style of all selected nodes is now 10px

Sets the keys and values of the object in the style of all selected Nodes.

// Write style (multiple at once) nodesF.style = { marginTop: "10px", "background-color": "yellow" }; → The "margin-top" and "background-color" style of all selected nodes are set to 10px and yellow

// Read style nodesF.style("margin-top") → The "margin-top" style of the first node // Write style nodesF.style("margin-top", "10px"); → The "margin-top" style of all selected nodes is now 10px nodesF.style({ marginTop: "10px", "background-color": "yellow" }; → The "margin-top" and "background-color" style of all selected nodes are set to 10px and yellow

See also: HTMLElement.style, jQuery.css() (reads computedStyle instead)

top

top → Number

Gets the top location of the first selected Node, or sets the top location of all selected Nodes, relative to the document, in pixels. If there are no Nodes selected, 0 is returned and setting the property does nothing. Note that this is the rendered position that may be affected by CSS transforms.

visible

visible → Boolean

Gets or sets a value indicating whether all selected Nodes are visible. A node is considered invisible (to the layout) if it has the style "display: none", and visible in all other cases. If there are no Nodes selected, false is returned.

width

width → Number

Gets the computed width of the first selected Node, or sets the width property of all selected Nodes, in pixels. Getting the property returns a number in pixels. Setting the property accepts a number in pixels, or any string that is allowed for the width style. If there are no Nodes selected, 0 is returned and setting the property does nothing. The value is affected by the element’s box-sizing.

Node selection methods

These instance methods retrieve one or more Nodes from the document.

closest

closest(selector) → Frontfire
closest(predicate) → Frontfire

Traverses each selected Node and its parents (heading toward the document root) until it finds a node that matches the CSS selector or satisfies a condition. Will return itself or the matching ancestor, with duplicates removed. If no matching element is found for a selected Node, it will not add to the returned collection. If no match was found, an empty collection is returned.

findElements

findElements(predicate) → Frontfire

Returns a list of the descendant elements within the selected Nodes that satisfy a condition. The predicate function is called for each Node with the node as its only argument. The node is included in the collection if the predicate function returns true. If no match was found, an empty collection is returned.

having

having(selector) → Frontfire

Reduces the selected Nodes to those that have a descendant that matches the CSS selector.

matches

matches(selector) → Boolean

Determines whether all selected Nodes would be selected by the CSS selector, in other words, determines whether the element “is” the selector. If there are no Nodes selected, false is returned.

queryFocusable

queryFocusable() → Frontfire

Returns a list of the elements within the selected Nodes that are focusable (tabbable). If no match was found, an empty collection is returned.

querySelector

querySelector(selector) → Frontfire

Returns the first element within the selected Nodes that match the specified CSS selector. If the first selected Node has no match, the other selected Nodes are considered. If no match was found, null is returned.

querySelectorAll

querySelectorAll(selector) → Frontfire

Returns a list of the elements within the selected Nodes that match the specified CSS selector. If no match was found, an empty collection is returned.

DOM methods

These instance methods insert or move elements in the document tree or change their visibility.

after

after(html, …) → this
after(node, …) → this
after(nodes, …) → this

Inserts the content after each selected Node. The content can be specified as an HTML string, a Node, or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList). Multiple arguments can be passed to insert each of them.

animateFromTo

animateFromTo(data, duration) → Animation
animateFromTo(data, duration, easing) → Animation
animateFromTo(data, duration, easing, keep) → Animation

Starts an animation of two keyframes on the first selected Node and returns the new Animation instance. If there are no Nodes selected, null is returned. The animation will run once and the keyframes are specified with their style property first and each the values to animate the element from and to. The animation uses the fill-mode “forwards” so that its final frame remains active.

The data parameter is an object that contains the CSS properties to animate and each an array of the start and end value of the animation. The duration of the animation is specified in milliseconds. The easing function defaults to the symmetric “ease-in-out”.

By default, the element will keep its final animation state. If the keep parameter is set to false, the animation’s effects will not be retained after the animation has completed playing. This can be used to display one-time effects on an element, e.g. as visual confirmation after an interaction.

This method runs the animation immediately and removes the need to set up CSS classes with a CSS transition and the use of forceReflow().

F("#panel").animateFromTo({ marginTop: ["0", "50px"], "background-color": ["white", "yellow"] }, 500); → Animates the panel element from: → margin-top: 0; background-color: white; → to: → margin-top: 50px; background-color: yellow; → over 500 milliseconds

For more advanced animations, use the Element.animate() method or the Animation class directly.

append

append(html, …) → this
append(node, …) → this
append(nodes, …) → this

Inserts the content at the end of each selected Node. The content can be specified as an HTML string, a Node, or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList). Multiple arguments can be passed to insert each of them.

appendTo

appendTo(node) → this
appendTo(nodes) → this

Inserts the selected Nodes at the end of the target. The target can be specified as a Node or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList).

assignId

assignId() → String
assignId(prefix) → String

Assigns the first selected Node a unique ID if none is set, and returns the element’s ID. This can be used to retrieve an element’s ID attribute but at the same time make sure the element actually has an ID.

A prefix for the new ID can be specified. If unset, “autoid” is used. The prefix is appended by the lowest numeric counter value that makes the ID unique, starting at 1.

before

before(html, …) → this
before(node, …) → this
before(nodes, …) → this

Inserts the content before each selected Node. The content can be specified as an HTML string, a Node, or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList). Multiple arguments can be passed to append each of them.

clone

clone() → Frontfire

Returns a clone, or duplicate, of the selected Nodes, including their subtrees but not including any event listeners.

For <template> elements, their content will be cloned and all children will be collected in the returned instance.

Note:
The effect of this method differs from the base class ArrayList.clone(). To call the base class implementation, change the interface with the L property.

disable

disable() → this

Disables the selected Nodes.

This is an alternative to: nodes.F.disabled = true;

empty

empty() → this

Removes all children from the selected Nodes.

enable

enable() → this

Enables the selected Nodes.

This is an alternative to: nodes.F.disabled = false;

getAttribute

getAttribute(name) → Any

Gets an attribute value from the first selected Node. If the attribute does not exist or there are no Nodes selected, null is returned.

hasAttribute

hasAttribute(name) → Boolean

Determines whether all selected Nodes have the specified attribute (or all specified attributes). Multiple attribute names can be specified as space-separated string, array (iterable), multiple arguments, or any combination thereof. If there are no Nodes selected, false is returned.

hide

hide() → this

Hides the selected Nodes.

This is an alternative to: nodes.F.visible = false;

insertAfter

insertAfter(node) → this
insertAfter(nodes) → this

Inserts the selected Nodes after the target. The target can be specified as a Node or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList).

See also: Element.after(), Element.insertAdjacentElement("afterend") (reversed notation), jQuery.insertAfter()

insertBefore

insertBefore(node) → this
insertBefore(nodes) → this

Inserts the selected Nodes before the target. The target can be specified as a Node or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList).

moveTo

moveTo(left, top) → this

Moves the selected Nodes to the specified position relative to the document. If a Node’s position style property is currently “static”, it will be set to “relative” to allow for this repositioning.

observeDisabled

observeDisabled(action) → Object

Calls a function when the disabled state of any of the selected Nodes changes. This applies to the disabled HTML attribute of any element, which is usually also updated when setting the disabled property of a supporting input element. The callback function gets two arguments:

The disabled state (boolean)
The changed element

The return value is an object with methods to control the created MutationObserver instances:

undo(): Stops the MutationObserver instances from receiving further notifications.

prepend

prepend(html, …) → this
prepend(node, …) → this
prepend(nodes, …) → this

Inserts the content at the beginning of each selected Node. The content can be specified as an HTML string, a Node, or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList). Multiple arguments can be passed to insert each of them.

prependTo

prependTo(node) → this
prependTo(nodes) → this

Inserts the selected Nodes at the beginning of the target. The target can be specified as a Node or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList).

See also: Element.prepend(), Element.insertAdjacentElement("afterbegin") (reversed notation), jQuery.prependTo()

remove

remove() → this

Removes the selected Nodes from their parents.

Note:
The effect of this method differs from the base class ArrayList.remove(). To call the base class implementation, change the interface with the L property.

removeAll

removeAll(predicate) → this

Removes the selected Nodes that satisfy a condition from their parents. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

Note:
The effect of this method differs from the base class ArrayList.removeAll(). To call the base class implementation, change the interface with the L property.

removeAt

removeAt(index) → this

Removes the selected Node by index from its parent. If the index is negative, it is counted from the end, i.e. -1 is the last, -2 the second-last node, etc. If index is greater than the array length, nothing is removed. If the negative index points to a position before the start of the array, the first node is removed.

Note:
The effect of this method differs from the base class ArrayList.removeAt(). To call the base class implementation, change the interface with the L property.

removeAttribute

removeAttribute(name) → this

Removes an attribute (or all specified attributes) from the selected Nodes. Multiple attribute names can be specified as space-separated string, array (iterable), multiple arguments, or any combination thereof.

removeFirst

removeFirst() → this

Removes the first selected Node from its parent (not the first child from selected Nodes).

Note:
The effect of this method differs from the base class ArrayList.removeFirst(). To call the base class implementation, change the interface with the L property.

removeLast

removeLast() → this

Removes the last selected Node from its parent (not the last child from selected Nodes).

Note:
The effect of this method differs from the base class ArrayList.removeLast(). To call the base class implementation, change the interface with the L property.

removeRange

removeRange(start) → ArrayList
removeRange(start, count) → ArrayList

Removes many of the selected Nodes from their parents, specified by index and count. If the start is negative, it is counted from the end, i.e. -1 is the last, -2 the second-last node, etc. If count is omitted, all nodes from the start index to the end of the array are removed. If count is negative, the nodes until (excluding) the count index from the end of the array are removed, i.e. -1 keeps the last, -2 keeps the 2 last nodes, etc.

Note:
The effect of this method differs from the base class ArrayList.removeRange(). To call the base class implementation, change the interface with the L property.

replaceWith

replaceWith(html) → this
replaceWith(nodes) → this
replaceWith(generator) → this

Replaces the selected Nodes with other content. The content can be specified as an HTML string, a Node, or a collection of Node instances (in a NodeList, HTMLCollection, Array or ArrayList). If existing Nodes are provided as new content and multiple Nodes are to be replaced, the source Nodes will be moved to the first target and then cloned from the second target on. Alternatively, the new content can be returned by a generator function that is called with the replaced Node as argument and returns the new content as HTML string, Node, or Nodes collection.

setAttribute

setAttribute(name, value) → this

Sets an attribute on the selected Nodes. Multiple attribute names can be specified as space-separated string, array (iterable), multiple arguments, or any combination thereof.

The value is converted to a string, so setting null will not remove the attribute (as in jQuery) but set it to the string “null”. Use the removeAttribute() method instead.

show

show() → this

Displays the selected Nodes.

This is an alternative to: nodes.F.visible = true;

toggle

toggle() → this
toggle(force) → this

Displays or hides the selected Nodes, each toggling their current state. If the force parameter is set to true or false, it forces all nodes to always be displayed or hidden instead of toggled.

This is an alternative to inverting or setting each selected node’s visibility property.

wrap

wrap(html) → this
wrap(node) → this
wrap(generator) → this

Wraps an HTML structure around each of the selected Nodes. The wrapping element can be specified as an HTML string or a Node (native or in a Frontfire object). If existing Nodes are provided as wrapper and multiple Nodes are to be wrapped, the source Node itself will wrap the first target and then cloned from the second target on. Alternatively, the wrapping element can be returned by a generator function that is called with the wrapped Node as argument and returns the wrapping element as HTML string or Node. If the wrapping element already contains children, the wrapped element is appended after them.

See also: jQuery.wrap(), Frontfire.unwrap() (reverse operation)

unwrap

unwrap() → this

Replaces the parent of each selected Node with the selected Node itself, removing their parents.

See also: jQuery.unwrap(), Frontfire.wrap() (reverse operation)

Scroll methods

closestScrollable

closestScrollable() → Frontfire

Returns the closest scrolling parent element of the first selected element. If the element itself can already scroll, it is returned.

getRelativeTop

getRelativeTop() → Number

Returns the vertical offset of the first selected element relative to the specified parent. If the parent ist not an ancestor of the element, undefined is returned.

isScrollable

isScrollable() → Boolean

Determines whether the first selected element is scrollable. An element is considered to be scrollable when it has a vertical overflow that is not hidden, i.e. a scrollbar is visible and can be moved.

isScrollVisible

isScrollVisible() → Boolean

Determines whether the first selected element is fully visible in its scrolling parent.

scrollbarHeight

scrollbarHeight() → Number

Returns the scrollbar height of the first selected element. If the element does not have a horizontal scrollbar, 0 is returned.

Added in v2.1.0

scrollbarWidth

scrollbarWidth() → Number

Returns the scrollbar width of the first selected element. If the element does not have a vertical scrollbar, 0 is returned.

Added in v2.1.0

scrollIntoView

scrollIntoView() → this
scrollIntoView(margin) → this
scrollIntoView(margin, smooth) → this
scrollIntoView(margin, smooth, recursive) → this
scrollIntoView([marginTop, marginBottom]) → this
scrollIntoView([marginTop, marginBottom], smooth) → this
scrollIntoView([marginTop, marginBottom], smooth, recursive) → this

Scrolls the first selected element into view in its scrolling parent, if it is not already fully visible. If the element does not fit in the view height, it is aligned at the top edge. If a margin is specified, the parent is scrolled further to keep the margin around the element visible. If the smooth parameter is true, the scrolling animates smoothly instead of an instant scroll. If the recursive parameter is set to true, parent scroll containers are also brought into view of their respective parents, up to the window.

The margin can be specified in three ways:

A single number that specifies the additional space at the top and bottom each, in pixels.
An array of two numbers as forementioned, for the top and bottom side separately.
An array of two strings in the format n* where n specifies the relative fill space. For example, the argument ["1*", "3*"] distributes the remaining scroll view space around the element so that 1/4 is at the top and 3/4 at the bottom. The argument ["1*", "1*"] scrolls the element to the centre of the view area. Any positive floating point numbers are accepted.

String parameters for margin added in v2.1.0

scrollToBottom

scrollToBottom() → this
scrollToBottom(bottomMargin) → this
scrollToBottom(bottomMargin, smooth) → this
scrollToBottom(bottomMargin, smooth, recursive) → this

Scrolls the first selected element to the bottom of its scrolling parent. If a margin is specified, the parent is scrolled further to keep the margin below the element visible. If the smooth parameter is true, the scrolling animates smoothly instead of an instant scroll. If the recursive parameter is set to true, parent scroll containers are also brought to the bottom of their respective parents, up to the window.

scrollToTop

scrollToTop() → this
scrollToTop(topMargin) → this
scrollToTop(topMargin, smooth) → this
scrollToTop(topMargin, smooth, recursive) → this

Scrolls the first selected element to the top of its scrolling parent. If a margin is specified, the parent is scrolled further to keep the margin above the element visible. If the smooth parameter is true, the scrolling animates smoothly instead of an instant scroll. If the recursive parameter is set to true, parent scroll containers are also brought to the top of their respective parents, up to the window.

Event methods

Note:
The event management methods on(), off() and once() are related to the DOM methods addEventListener() and removeEventListener(), but not strictly compatible. The Frontfire methods have a different behaviour in that they maintain their own event handler registration that is required for the enhanced comfort of removing a handler without specifying its function. Also, while the DOM method provides the “once” and “signal” options, these will remove the event handler without telling anybody so our registrations would not be updated correctly. It’s for this essential behavioural difference that the Frontfire methods deliberately use different (and shorter) names.

forwardEvent

forwardEvent(eventName, targetElement) → this

Forwards an event from the first selected element to another element, holding a weak reference to the target element. The internal forwarding entry is cleaned up if the target element was garbage-collected when an event is to be forwarded. No event data is set with the forwarded event.

forwardUIEvents

forwardUIEvents(target) → Object
forwardUIEvents(target, excludeTypes) → Object

Forwards the most common user interaction events from the first selected element to the specified target element. This can bridge the gap between an original element in the document and a visual replacement element that was generated by Frontfire. The forwarded events are cancelled on the target element to avoid double-invocation of events like “click”.

The forwarded event types are:

blur
click
contextmenu
dblclick
focus
focusin
focusout
input
keydown
keyup
pointercancel
pointerdown
pointerenter
pointerleave
pointermove
pointerout
pointerover
pointerup
wheel

Any types specified in the second parameter can be excluded from forwarding. Excluded type names can be specified as space-separated string, array (iterable), or any combination thereof. When an event type is excluded, it should be forwarded explicitly following appropriate logic.

The return value is an object with methods to control the added event handlers:

undo(): Removes the added event handlers.

getEventListeners

getEventListeners() → Array
getEventListeners(filterTypes) → Array

Returns all event listeners currently registered with the on() and once() methods. Multiple type names can be specified as space-separated string, array (iterable), or any combination thereof. The returned array contains objects with the following keys:

node: The node to which the listener is attached.
type: The plain event type (without Frontfire-specific extensions).
capture: Indicates whether the event is handled in the capture phase.
classList: An array containing the class names of the event listener.
userHandler: The handler that was specified for the on() or once() method.
realHandler: The handler that was added to the DOM object. This is a wrapper function for once() listeners.
once: Indicates whether the listener is unregistered after the first triggered event.

The objects in the returned array are copies, so changes to them will not affect the actual event listener registrations.

Type name additions

The type names can contain class names similar to a CSS selector to select the handlers to be returned by their set classes. Only those handlers are returned that have all specified class names set. If classes but no type was specified, all registered event types are considered.

If the type name starts with a greater-than sign (>), only handlers for the capture phase are returned.

hasEventListeners

hasEventListeners() → Boolean
hasEventListeners(filterTypes) → Boolean

Determines whether any event listener is currently registered with the on() or once() method. Multiple type names can be specified as space-separated string, array (iterable), or any combination thereof.

Type name additions

The type names can contain class names similar to a CSS selector to select the handlers to consider by their set classes. Only those handlers are considered that have all specified class names set. If classes but no type was specified, all registered event types are considered.

If the type name starts with a greater-than sign (>), only handlers for the capture phase are considered.

off

off(types) → this
off(types, handler) → this

Removes an event handler from the selected Nodes for the specified event types. Removing without specifying a handler can only remove those handlers that were added with the on() or once() methods. Multiple type names can be specified as space-separated string, array (iterable), or any combination thereof.

Type name additions

The type names can contain class names similar to a CSS selector to select the handlers to be removed by their set classes. Only those handlers are removed that have all specified class names set. If classes but no type was specified, all registered event types are considered for removal. Event classes are ignored if a specific handler to remove is provided.

If the type name starts with a greater-than sign (>), the handler is removed for the capture phase.

See also: EventTarget.removeEventListener(), jQuery.off(), Frontfire.on() (reverse operation)

on

on(types, handler) → this

Adds an event handler to the selected Nodes for the specified event types. If the handler was already added with once(), it is changed to a permanent handler. A handler will only be added once for each event type (just like the DOM methods, and unlike jQuery). Multiple type names can be specified as space-separated string, array (iterable), or any combination thereof. The same event handler is attached to every specified event type.

Type name additions

The type names can contain class names similar to a CSS selector to identify them and allow them to be removed later.

If the type name starts with a greater-than sign (>), the handler is registered for the capture phase.

If the type name (without class names, i.e. before any period character) is appended by an exclamation mark (!), the handler is also called immediately, with a fake event object that contains the most important members:

currentTarget: The node that the event handler was added to.
isImmediate: Set and true only on the immediate handler invocation.
target: The node that the event handler was added to.
type: The event type without additional modifiers.
preventDefault(): A function that does nothing.
stopPropagation(): A function that does nothing.

See also: EventTarget.addEventListener(), jQuery.on(), Frontfire.off() (reverse operation), Frontfire.findEventTarget() (for delegated event handlers)

once

once(types, handler) → this

Adds an event handler to the selected Nodes for the specified event types. When the event is triggered, the event handler is removed for future events, i.e. the handler is only called once. If the handler was already added with on(), it is changed to a one-time handler. A handler will only be added once for each event type. Multiple type names can be specified as space-separated string, array (iterable), or any combination thereof. The same event handler is attached to every specified event type.

The function that is actually added as event listener is a wrapper that manages the remove-after-trigger logic. That wrapper function then calls the specified handler function with the event object. No such wrapper is used for the on() method. When a handler is converted from and to a once-only handler, the wrapper is removed or added automatically.

Type name additions

The type names can contain class names similar to a CSS selector to identify them and allow them to be removed later.

If the type name starts with a greater-than sign (>), the handler is registered for the capture phase.

See also: jQuery.one(), Frontfire.off() (reverse operation)

onReady

Frontfire.onReady(handler) → void

Adds an event handler for the DOMContentLoaded event and runs it if that event has already been triggered.

This event handler could only be removed again by directly calling: document.removeEventListener("DOMContentLoaded", handler)

F.onReady(() => loadDataFromServer());

trigger

trigger(types) → ArrayList(Event)
trigger(types, options) → ArrayList(Event)
trigger(types, options, eventInit) → ArrayList(Event)
trigger(types, options, eventInit, eventClass) → ArrayList(Event)

Triggers the specified event types on all selected Nodes, synchronously invoking all added handlers in the order they were added. Multiple type names can be specified as space-separated string, array (iterable), or any combination thereof. The options parameter is passed on to the Event constructor. The most important options properties here are:

bubbles: A boolean value indicating whether the event bubbles up from the innermost element that is the source of the event to each parent element. The default is false.
cancelable: A boolean value indicating whether the event can be cancelled with the preventDefault() method and tested with the defaultPrevented property. The default is false.

The eventInit parameter can be an object containing additional event properties to be set. The eventClass parameter can be set to a constructor function of the event object type to use, and defaults to CustomEvent if unset which is fine for most events.

Returns all dispatched events, for the caller to inspect their properties that may have been set by the event handlers. If only one element was selected and one event was triggered, the returned collection will contain a single Event object.

// Non-bubbling event without data F("#id").trigger("init"); // Bubbling event without data F("#id").trigger("change", { bubbles: true }); // Bubbling, cancellable event with data let events = F("#id").trigger("close", { bubbles: true, cancelable: true }, { closeReason: "userRequest" }); if (!events.first.defaultPrevented) { // Continue // (can read properties from events.first that were set in event handlers) }

Unlike jQuery that only calls its own added event handlers, this method triggers a native DOM event that will be visible to all event handlers added with the Frontfire or DOM methods alike. Unlike jQuery events that always bubble, this behaviour must be explicitly enabled with the bubbles eventInit property like with the DOM API.

Type name additions

The type names can contain class names similar to a CSS selector to select the handlers to be called by their set classes. Only those handlers are called directly that have all specified class names set. The downside of using classes is that the event cannot be natively dispatched to the elements. Instead, the event argument passed to the handler loses its type and is a full copy of the original event object. This is necessary to set its currentTarget and target properties that are otherwise read-only. If no class names are specified, the event is triggered natively.

unforwardEvent

unforwardEvent(eventName, targetElement) → this

Forgets an event forwarding set up with the forwardEvent() method.

Form methods

copyText

copyText() → Boolean

Copies the plain text value of the first selected text input element into the system clipboard. This method uses the DOM element and not the newer Clipboard API so it’s always available. The return value is true if the copy was successful; otherwise, false.

See also: Frontfire.copyText() (static method)

value

value() → Any
value(newValue) → this

Gets or sets the value of an HTML element that may occur in a form. The value is converted according to the input type.

For checkboxes and radio fields, the boolean checked value is used instead of the value property. The indeterminate state is represented as null.
For number-typed fields, the value is converted as Number with valueAsNumber. An empty or invalid input (including leading or trailing whitespace) is represented as null. Setting null empties the input field.
For date/time-typed fields (except week), the value is converted as Date similar to valueAsDate but in the local time zone. An empty or incomplete input is represented as null. Setting null empties the input field.
For select fields with the multiple attribute, the returned or new value is an Array containing the string value of each selected option. Setting a string or non-iterable selects only the option with that value.
For other fields, including select fields without the multiple attribute, the string value property is used.

If the new value is different (!==) from the current value, a “change” event is triggered on the element. Multi-value select fields are compared with setEquals().

Plugin methods

Frontfire has a comprehensive plugin mechanism that allows new modules to be added to the Frontfire object. These modules can work on the selected Nodes and add new features and capabilities to them. Frontfire UI consists of Frontfire plugins and other static methods added to the Frontfire class. These existing plugin methods are described below.

A plugin is always accessible under its property name of the Frontfire object. This property is a callable function that creates a plugin instance, and it has additional methods and properties to control that instance. A minimal complete example implementation of a plugin is shown at the registerPlugin() method.

You can still add normal Frontfire instance and static methods or properties by writing to the Frontfire function or its prototype. This is how Frontfire does it itself. There is no need to set up a Frontfire build environment, you can add plugins from your own JavaScript code.

Frontfire.prototype.instanceMethod = function (args) { // Selected Nodes are in 'this.array' (needs a full function) // Do or return something useful }; Object.defineProperty(Frontfire.prototype, "instanceProperty", { get: function () { // Selected Nodes are in 'this.array' (needs a full function) // Return the property value }, set: function (value) { // Selected Nodes are in 'this.array' (needs a full function) } }); Frontfire.staticMethod = args => { // Do or return something useful }; // Define static properties in Frontfire instead of its prototype

Warning:
In any way, be careful not to choose names that might be added to Frontfire Core (or UI) in the future. There is no official plugin registry or compatibility certification so you can break essential functions with your extension!

autostart

autostart() → this

Applies all Frontfire plugins to the selected nodes except those that have the no-frontfire CSS class, or descendants of an element with that class. The plugins are activated on each element based on its node name or CSS classes, as defined in the registered plugin selectors.

This method is called automatically when loading the Frontfire UI JavaScript source file. This only works if the JavaScript file is loaded at the end of the <body> element after all content elements, or alternatively (not recommended) in the document <head>.

This method only needs to be called when new elements have been created and added to the document that need features provided by plugins, excluding those that should not be applied at this time or are permanently exempt from Frontfire UI CSS styles.

let div = F.c("div"); div.classList.add("..."); document.body.append(div); div.F.autostart();

deinit

deinit() → this

Removes all Frontfire plugins from the selected nodes. This reverts all changes made and restores the state in which the element was before applying Frontfire plugins. Additionally created elements and event handlers are also removed.

This method relies on each plugin’s own deinit() method which is simply called with all selected nodes for each plugin that provides that method. It needs to decide for itself whether it is responsible for any of the selected nodes.

let div = F.c("div"); // Set up element div.F.frontfire(); // Later: div.F.deinit();

deleteOptions

Frontfire.deleteOptions(pluginName, element) → void

Deletes the initialised plugin options from the element. This method is used by deinit() methods of plugins.

frontfire

frontfire() → this

Applies all Frontfire plugins to the selected nodes. The no-frontfire CSS class is removed from the selected nodes and all their descendants (but not their parents) to also activate the CSS features (where not disabled on an ancestor element). The plugins are activated on each element based on its node name or CSS classes, as defined in the registered plugin selectors.

This method only needs to be called when new elements have been created and added to the document that need features provided by plugins.

let div = F.c("div"); div.classList.add("..."); document.body.append(div); div.F.frontfire();

initOptions

Frontfire.initOptions(pluginName, element) → Object
Frontfire.initOptions(pluginName, element, converters) → Object
Frontfire.initOptions(pluginName, element, converters, params) → Object

Determines the options to use for a plugin. The pluginName is the same as specified in the registerPlugin method. The element is used to find data attributes that can set options for this plugin. converters is an object that specifies a conversion function for each special data attribute. Such a conversion function maps the data attribute string value to the desired option value. Finally, the params are the options that are passed to the plugin function, if any.

See the registerPlugin() method for an example of this method.

loadOptions

Frontfire.loadOptions(pluginName, element) → Object

Loads the initialised plugin options for additional plugin functions. If the plugin options have not been initialised for the element, undefined is returned. This method is used by plugin operations that work with a plugin instance after it has been created on an element. Any options, including references to internal functions, that were set in the plugin’s create function can be accessed with this method in the additional operation methods.

See the registerPlugin() method for an example of this method.

registerPlugin

Frontfire.registerPlugin(pluginName, createFn) → void
Frontfire.registerPlugin(pluginName, createFn, data) → void

Registers a Frontfire plugin. The pluginName specifies the name under which the plugin will be accessible in Frontfire objects. When that plugin property is called, the createFn function is called to execute the plugin. The data parameter is an optional object that further defines the plugin with the following keys:

defaultOptions: The initial options that are set for the plugin and can be overridden when called. Only properties defined in here are considered for data attributes in the HTML element.
methods: An object containing additional plugin methods and properties. These operations are accessible as methods in the plugin property.
selectors: An array of CSS selectors for the autostart function. The plugin will be applied on all elements that match any of these selectors in the autostart() or frontfire() methods. If the initial application of the plugins on the document has already run, the plugin will be applied upon registration.

The following example shows a minimal complete implementation of a plugin.

// Default options for the plugin var myPluginDefaults = { state: false }; // The plugin create function function myPlugin(options) { let element = this.first; if (!element) return; // Nothing to do // Initialise the plugin instance options let opt = F.initOptions("myPlugin", element, {}, options); opt._setState = setState; // Do something with the element // An internal action function setState(newState) { // Do something with the element } // Return current plugin instance return F(element).myPlugin; } // Gets the state of the element. function getState() { let element = this.first; if (!element) return this; // Nothing to do // Load the plugin instance options let opt = F.loadOptions("myPlugin", element); return opt?.state; } // Sets the state of the element. function setState(newState) { return this.forEach(element => { // Load the plugin instance options let opt = F.loadOptions("myPlugin", element); opt && opt._setState(newState); }); } // Makes the element blink for attention. function blink() { return this.forEach(element => { // Do something with the element }); } // Register the plugin with Frontfire, automatically apply // to all elements with the "my-plugin" CSS class F.registerPlugin("myPlugin", myPlugin, { defaultOptions: myPluginDefaults, methods: { state: { get: getState, set: setState }, blink: blink }, selectors: [".my-plugin"] });

This is how to use the registered plugin:

// Activate the plugin on the selected elements // (already included in autostart if the selector was specified) F(".my-plugin").myPlugin(); // Use the plugin’s properties and methods F(".my-plugin").myPlugin.state = true; F(".my-plugin").myPlugin.blink(); // Keep a reference to the plugin // (only if the plugin function returns a plugin instance) let plugin = F(".my-plugin").myPlugin(); plugin.state = true; plugin.blink();

The plugin default options, if specified, can be accessed through the plugin property defaults. Assigning this property overwrites those default settings that are set in the new value and preserves the existing settings.

let defaultOptions = F().myPlugin.defaults; F().myPlugin.defaults = { // All new plugins shall have their initial state as true from now on state: true // (all existing keys not included here remain unchanged) }

Collection retrieval methods

These instance methods retrieve a single item from the array or a single aggregated value computed from the array.

aggregate

Inherited from: ArrayList

aggregate(reducer) → Any
aggregate(initialValue, reducer) → Any

Applies an accumulator function over the array of selected Nodes. The reducer function is called with two arguments and returns a single value that combines both. Then the function is called with the previous return value and the next array item, until the last item. If the initialValue is unset and the array is empty, undefined is returned. If the initialValue is set, it is the first argument of the first call of the reducer function.

aggregateReversed

Inherited from: ArrayList

aggregateReversed(reducer) → Any
aggregateReversed(initialValue, reducer) → Any

Applies an accumulator function over the array in reversed order. See the aggregate() method for more details.

all

Inherited from: ArrayList

all(predicate) → Boolean
all(predicate, thisArg) → Boolean

Determines whether all selected Nodes satisfy a condition. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If thisArg is set, it is assigned to this when executing the predicate function. If the array is empty, true is returned. The parameter semantics is the same as the Array.every() method.

any

Inherited from: ArrayList

any() → Boolean
any(predicate) → Boolean
any(predicate, thisArg) → Boolean

Determines whether any selected Node satisfies a condition. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If no predicate is specified, the return value is true only if the array contains any items. If thisArg is set, it is assigned to this when executing the predicate function. If the array is empty, false is returned. The parameter semantics is the same as the Array.some() method.

average

Inherited from: ArrayList

average(selector) → Number

Computes an average value of the selected Nodes. The selector function is called for each Node and returns the value to use for the average computation. In this class, the selector must not be omitted. If the array is empty, undefined is returned.

binarySearch

Inherited from: ArrayList

binarySearch(node, comparer) → Number

Searches the sorted array for an item using the comparer and returns the zero-based index of the item. If the item is not found, the return value is a negative number that is the bitwise complement (~) of the index of the next item that is larger than item or, if there is no larger item, the bitwise complement of the length property. In this class, the comparer must not be omitted.

contains

Inherited from: ArrayList

contains(node) → Boolean
contains(node, startIndex) → Boolean

Determines whether a Node exists in the array of selected Nodes. The parameter semantics is the same as the Array.includes() method.

count

Inherited from: ArrayList

count() → Number
count(predicate) → Number

Counts the selected Nodes that satisfy a condition. If no predicate is specified, the array length is returned.

equals

Inherited from: ArrayList

equals(other) → Boolean

Determines whether two arrays contain the same items in the same order. The values are compared with the === operator.

find

Inherited from: ArrayList

find(predicate) → Node
find(predicate, thisArg) → Node

Returns the first selected Node that satisfies a condition. If no nodes satisfy the condition, undefined is returned. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If thisArg is set, it is assigned to this when executing the predicate function. The parameter semantics is the same as the Array.find() method.

Note:
This method finds items in its array of selected Nodes, not other Nodes in the document. Use the querySelector methods to find other descendant nodes.

findIndex

Inherited from: ArrayList

findIndex(predicate) → Number
findIndex(predicate, thisArg) → Number

Returns the index of the first selected Node that satisfies a condition. If no Nodes satisfy the condition, the return value is -1. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If thisArg is set, it is assigned to this when executing the predicate function. The parameter semantics is the same as the Array.findIndex() method.

findLast

Inherited from: ArrayList

findLast(predicate) → Node
findLast(predicate, thisArg) → Node

Returns the last selected Node that satisfies a condition. If no Nodes satisfy the condition, undefined is returned. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If thisArg is set, it is assigned to this when executing the predicate function. The parameter semantics is the same as the Array.find() method.

Note:
This method finds items in its array of selected Nodes, not other Nodes in the document. Use the querySelectorAll method to find other descendant nodes.

findLastIndex

Inherited from: ArrayList

findLastIndex(predicate) → Number
findLastIndex(predicate, thisArg) → Number

Returns the index of the last selected Node that satisfies a condition. If no Nodes satisfy the condition, the return value is -1. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If thisArg is set, it is assigned to this when executing the predicate function. The parameter semantics is the same as the Array.findIndex() method.

get

Inherited from: ArrayList

get(index) → Node

Returns the selected Node at the positive or negative index of the array. If the index is negative, it is counted from the end, i.e. -1 is the last, -2 the second-last Node, etc. If the index is outside the range of the array, undefined is returned.

indexOf

Inherited from: ArrayList

indexOf(node) → Number

Returns the first index of the Node among the selected Nodes. If the Node does not exist in the array, the return value is -1.

join

Inherited from: ArrayList

join() → String
join(separator) → String

Returns a string by concatenating all of the elements of the array, separated by commas or the specified separator string. If the array has only one item, then that item will be returned without using the separator. If the array is empty, an empty string is returned.

lastIndexOf

Inherited from: ArrayList

lastIndexOf(node) → Number

Returns the last index of the Node among the selected Nodes. If the Node does not exist in the array, the return value is -1.

max

Inherited from: ArrayList

max(selector) → Number

Computes the maximum value of the selected Nodes. The selector function is called for each Node of the array and returns the value to use for the maximum computation. In this class, the selector must not be omitted. If the array is empty, undefined is returned.

min

Inherited from: ArrayList

min(selector) → Number

Computes the minimum value of the selected Nodes. The selector function is called for each Node of the array and returns the value to use for the minimum computation. In this class, the selector must not be omitted. If the array is empty, undefined is returned.

sum

Inherited from: ArrayList

sum(selector) → Number

Computes the sum of the selected Nodes. The selector function is called for each Node and returns the value to use for the sum computation. In this class, the selector must not be omitted. If the array is empty, undefined is returned.

Collection manipulation methods

These instance methods alter the contents of the array of selected Nodes. Most of these methods return the instance for chained calls, except the remove and replace methods.

add

add(node) → this
add(nodeList) → this
add(nodeList, single) → this
add(htmlCollection) → this
add(htmlCollection, single) → this
add(array) → this
add(array, single) → this
add(html) → this
add(html, single) → this
add(selector) → this
add(selector, single) → this

Adds nodes to the end of the array or creates new nodes. The following types can be passed as first argument:

Node: A Node to add to this instance.
NodeList: A collection of Nodes copied into this instance.
HTMLCollection: A collection of Nodes copied into this instance.
Array or ArrayList: A collection of which only the Nodes are copied into this instance.
String: A CSS selector that selects the nodes to add to this instance, or HTML code starting with “<”.

If the optional single parameter is true, only the first of the specified nodes will be added to this instance.

Note:
In this class, the method only accepts Node items to add, while the base class ArrayList.add() accepts any item types.

addRange

addRange(…) → this

In this class, this is an alias for the add() method that can already handle collections of Nodes to add.

See also: Frontfire.add(), Frontfire.concat() (copying alternative)

clear

Inherited from: ArrayList

clear() → this

Removes all Nodes from the array. This will not alter the document or any Nodes themselves. This is equivalent of setting array.length = 0.

insert

insert(index, node) → this
insert(index, nodeList) → this
insert(index, htmlCollection) → this
insert(index, array) → this
insert(index, html) → this
insert(index, selector) → this

Inserts nodes into the array at the specified index. If the index is negative, it is counted from the end, i.e. -1 is the last, -2 the second-last node, etc. If index is greater than the array length, the node is added at the end of the array. If the negative index points to a position before the start of the array, the node is inserted at the beginning of the array. The same types can be passed as second argument as for the add() method.

Note:
In this class, the method only accepts Node items to insert, while the base class ArrayList.insert() accepts any item types.

insertRange

insertRange(…) → this

In this class, this is an alias for the insert() method that can already handle collections of Nodes to insert.

replace

Inherited from: ArrayList

replace(oldNode, newNode) → Boolean

Replaces the first Node by the value of oldNode in the array. The return value is true if the old node was found; otherwise, false.

reverse

Inherited from: ArrayList

reverse() → this

Reverses the array in-place.

See also: Array.reverse(), Frontfire.reversed() (copying alternative)

set

Inherited from: ArrayList

set(index, node) → this

Sets the Node at the positive or negative index of the array. If the index is negative, it is counted from the end, i.e. -1 is the last, -2 the second-last node, etc. If index is greater than the array length, empty slots will be created between the old last and the new node. If the negative index points to a position before the start of the array, the property representing the negative number is created but the set value is not part of the iterable items of the array. This behaviour is identical to setting arbitrary indexes of a plain Array.

shuffle

Inherited from: ArrayList

shuffle() → this

Shuffles the selected Nodes using a Fisher-Yates algorithm.

sort

Inherited from: ArrayList

sort(comparer) → this

Sorts the selected Nodes using the comparer function. In this class, the comparer must not be omitted.

sortBy

Inherited from: ArrayList

sortBy(keySelector, …) → this

Sorts the selected Nodes in ascending order according to a key. Secondary sorting is done by providing more key selector arguments. An argument of 1 or -1 sets the sort direction of the following keys ascending or descending, respectively.

The comparison is done with the < (less than) and > (greater than) operators. Two numbers are compared by their numeric value, two strings are compared lexically. Mixed-type comparisons have unpredictable results.

See the base class method for an example.

See also: Frontfire.orderBy() (copying alternative)

sortByDescending

Inherited from: ArrayList

sortByDescending(keySelector, …) → this

Sorts the selected Nodes in descending order according to a key. Secondary sorting is done by providing more key selector arguments. An argument of 1 or -1 sets the sort direction of the following keys ascending or descending, respectively.

See the sortBy() method for an example. This method differs in that the initial sort order is descending instead of ascending. Both methods behave identically if the first argument is 1 or -1.

See also: ArrayList.orderByDescending() (copying alternative)

Collection copy methods

These instance methods return multiple Nodes from the array in a new collection and do not alter the contents of the instance.

chunk

Inherited from: ArrayList

chunk(length) → ArrayList
chunk(length, pad) → ArrayList

Chunks the array of selected Nodes into multiple arrays of a maximum length, with an optional padding value for the last shorter chunk to bring it to the specified length. In this class, each subarray is a Frontfire instance. The result can be converted to a plain Array of Arrays with the toArray() method.

concat

Inherited from: ArrayList

concat() → Frontfire
concat(array, …) → Frontfire

Concatenates the selected Nodes with the other specified arrays. If no parameter is specified, this method behaves the same as the clone() method.

See also: Array.concat(), Frontfire.addRange() (manipulating alternative)

getRange

Inherited from: ArrayList

getRange(start) → Frontfire
getRange(start, count) → Frontfire

Returns Nodes from the array of selected Nodes. If the start is negative, it is counted from the end, i.e. -1 is the last, -2 the second-last node, etc. If count is omitted, all nodes from the start index to the end of the array are returned. If count is negative, the nodes until (excluding) the count index from the end of the array are returned, i.e. -1 excludes the last, -2 excludes the 2 last nodes, etc.

groupBy

Inherited from: ArrayList

groupBy(keySelector) → Map
groupBy(keySelector, elementSelector) → Map

Groups the selected Nodes according to the key selector function and returns a new Map from each group key and a Frontfire instance of the Nodes in the group. The order of the Nodes in each returned group is the same as in the original array. In this class, each group value is a Frontfire instance.

orderBy

Inherited from: ArrayList

orderBy(keySelector, …) → Frontfire

Returns a copy of the array in ascending order according to a key. Secondary sorting is done by providing more key selector arguments. An argument of 1 or -1 sets the sort direction of the following keys ascending or descending, respectively.

See also: ArrayList.sortBy() (manipulating alternative)

orderByDescending

Inherited from: ArrayList

orderByDescending(keySelector, …) → Frontfire

Returns a copy of the array in descending order according to a key. Secondary sorting is done by providing more key selector arguments. An argument of 1 or -1 sets the sort direction of the following keys ascending or descending, respectively.

See the orderBy() method for an example. This method differs in that the initial sort order is descending instead of ascending. Both methods behave identically if the first argument is 1 or -1.

See also: ArrayList.sortByDescending() (manipulating alternative)

rearrange

Inherited from: ArrayList

rearrange(mapper) → Frontfire

Returns a copy of the array with the selected Nodes rearranged by a mapping function that maps the source index to the target index. The Nodes are rearranged in their order in the array. If the mapping function returns a target index twice, the last assigned Node will overwrite previous Nodes at that index.

reversed

Inherited from: ArrayList

reversed() → Frontfire

Returns a reversed copy of the selected Nodes.

See also: ArrayList.reverse() (manipulating alternative)

select

Inherited from: ArrayList

select(selectorFn) → ArrayList
select(selectorFn, thisArg) → ArrayList

Projects each item in the array into a new form by calling the selector function for each item. The returned array contains as many items as the array, with each return value of the selector function called with the original item as parameter. If thisArg is set, it is assigned to this when executing the selector function. The parameter semantics is the same as the Array.map() method.

skip

Inherited from: ArrayList

skip(count) → Frontfire

Returns a copy of the array without the first Nodes.

See also: Array.slice(), ArrayList.removeFirst() (manipulating alternative)

skipLast

Inherited from: ArrayList

skipLast(count) → Frontfire

Returns a copy of the array without the last Nodes.

See also: Array.slice(), ArrayList.removeLast() (manipulating alternative)

skipWhile

Inherited from: ArrayList

skipWhile(predicate) → Frontfire

Returns a copy of the array without the first Nodes that satisfy a condition. As soon as a Node does not satisfy the condition, that and all subsequent Nodes until the end of the array are returned, satisfying the condition or not.

take

Inherited from: ArrayList

take(count) → Frontfire

Returns the first Nodes of the array.

takeAfter

Inherited from: ArrayList

takeAfter(node) → Frontfire

Returns all Nodes in the array that occur after the specified node, not including the node itself.

takeBefore

Inherited from: ArrayList

takeBefore(item) → Frontfire

Returns all Nodes in the array that occur before the specified node, not including the node itself.

takeEvery

Inherited from: ArrayList

takeEvery(step) → Frontfire
takeEvery(step, start) → Frontfire
takeEvery(step, start, count) → Frontfire

Returns every nth Node of the array. If start is omitted, the first returned node is the first node of the array. The count defines how many nodes will be returned (if available), not how many nodes from the array will be considered.

takeLast

Inherited from: ArrayList

takeLast(count) → Frontfire

Returns the last Nodes of the array.

takeWhile

Inherited from: ArrayList

takeWhile(predicate) → Frontfire

Returns the first Nodes of the array that satisfy a condition. As soon as a node does not satisfy the condition, no further nodes of the array are returned, satisfying the condition or not.

toArray

Inherited from: ArrayList

toArray() → Array

Returns a plain Array of the selected Nodes. The returned array is a new instance that contains the nodes from the internal array. Any changes done to this array will not affect the Frontfire instance.

toMap

Inherited from: ArrayList

toMap(keySelector) → Map

Returns a Map of the selected Nodes. The map key is determined by calling the keySelector function. The nodes are copied in their order in the array. If the key function returns a key twice, the last assigned node will overwrite previous nodes for that key.

toObject

Inherited from: ArrayList

toObject(keySelector) → Object

Returns an Object of the selected Nodes. The object key is determined by calling the keySelector function which must return a string value suitable for a JavaScript object property name. The nodes are copied in their order in the array. If the key function returns a key twice, the last assigned node will overwrite previous nodes for that key.

where

Inherited from: ArrayList

where(selector) → Frontfire
where(predicate) → Frontfire
where(inCollection) → Frontfire

Returns the selected Nodes that match the specified CSS selector string, satisfy a condition function or are contained in the specified node collection. Nodes that do not satisfy the condition are skipped in the returned collection. The order of the returned Nodes is the same as the original array. The predicate function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

The parameter semantics is the same as the Array.filter() method. In this class, the method accepts more parameter types than in the base class: String (CSS selector), Array/ArrayList/Frontfire (node collection to intersect with)

Collection set methods

These instance methods provide set operations on the array. Most of these methods should be available in the built-in Set type, but unfortunately are not.

distinct

Inherited from: ArrayList

distinct() → Frontfire

Returns a new collection with the selected Nodes, without duplicates. The order of the returned nodes is the same as the original array.

except

Inherited from: ArrayList

except(other) → Frontfire

Returns a new collection with the unique selected Nodes, without (“minus”) all Nodes from the other array, also called set difference. The order of the returned nodes is the same as the original array.

intersect

Inherited from: ArrayList

intersect(other) → Frontfire

Returns a new collection with the unique selected Nodes that exist in both the array and the other array. This corresponds to the boolean operator AND. The order of the returned nodes is the same as the original array.

isSubsetOf

Inherited from: ArrayList

isSubsetOf(other) → Boolean

Determines whether the array is a subset of the other array. If both arrays contain the same distinct Nodes, the return value is true.

isSupersetOf

Inherited from: ArrayList

isSupersetOf(other) → Boolean

Determines whether the array is a superset of the other array. If both arrays contain the same distinct Nodes, the return value is true.

setEquals

Inherited from: ArrayList

setEquals(other) → Boolean

Determines whether two arrays contain the same unique Nodes but not necessarily in the same order (or quantity).

symmetricDifference

Inherited from: ArrayList

symmetricDifference(other) → Frontfire

Returns a new collection with the unique selected Nodes that exist in either the array or the other array but not in both (called symmetric difference). This corresponds to the boolean operator XOR (exclusive OR). The order of the returned nodes is the same as the original array, followed by the new nodes from the other array.

union

Inherited from: ArrayList

union(other) → Frontfire

Returns a new collection with the unique selected Nodes from the array and also from the other array. This corresponds to the boolean operator OR. The order of the returned nodes is the same as the original array, followed by the new nodes from the other array.

Void methods

These instance methods do not return items from the array and do not alter the contents of the instance.

forEach

Inherited from: ArrayList

forEach(action) → this
forEach(action, thisArg) → this

Calls a function once for each selected Node. The callback function gets three arguments:

The Node
Its index in the array
The entire array (the internal Array instance)

If thisArg is set, it is assigned to this when executing the callback function. The parameter semantics is the same as the Array.forEach() method.

// Show all .box elements (except the first) that contain "Info" F(".box").forEach((box, index) => { if (index > 0 && box.textContent.includes("Info")) { box.F.show(); } });

Method chaining variants

These instance methods provide an alternative way to use the method chaining syntax for features that would not be chainable in a DOM-style API. All of these methods can be replaced by reading or writing properties or calling other methods that would not return the current instance. These methods are mainly provided to ease the migration of jQuery code, especially when creating element structures without keeping separate references of any of the child elements in the created structure. They should not be used in new code but are nevertheless part of the supported Frontfire API.

addClass

addClass(classNames) → this

Method chaining variant of .classList.add().

attr

attr(name) → String
attr(name, value) → this

Method chaining variant of getAttribute/setAttribute/removeAttribute. If value is null, the attribute is removed.

html

html() → String
html(htmlCode) → this

Method chaining variant of the innerHTML getter/setter.

prop

prop(key) → Any
prop(key, value) → this

Method chaining variant of an element property getter/setter. The property name (key) is passed as string here. If no value is specified, the property’s value is returned. If a value is specified, the property is set to this value and the current instance is returned for method chaining.

removeClass

removeClass(classNames) → this

Method chaining variant of .classList.remove().

text

text() → String
text(textContent) → this

Method chaining variant of the textContent getter/setter.

toggleClass

toggleClass(classNames) → this
toggleClass(classNames, force) → this

Method chaining variant of .classList.toggle().

Static methods

version

Frontfire.version → String

Returns the version identifier string of the Frontfire library.

Frontfire.version → "2.0.0"

c

Frontfire.c(name) → Node

Creates an HTML element. Shortcut for document.createElement. Similar to F("<div>"), but the return value is not a Frontfire instance.

F.c("div") → A new <div> element

camelCase

Frontfire.camelCase(name) → String

Converts a string with hyphens like “camel-case” to “camelCase”. This can be used in scenarios like style or dataset access which translates between CSS/HTML attributes and JavaScript object properties.

F.camelCase("margin-top") → "marginTop"

clamp

Frontfire.clamp(value, min, max) → Number

Returns the value limited to the range between min and max.

This is an alternative to: Math.max(min, Math.min(value, max))

F.clamp(5, 0, 10) → 5 F.clamp(15, 0, 10) → 10 F.clamp(-5, 0, 10) → 0

copyText

Frontfire.copyText(text) → Boolean

Copies the specified plain text into the system clipboard. This method uses a temporary dummy DOM element and not the newer Clipboard API so it’s always available. The return value is true if the copy was successful; otherwise, false.

See also: Frontfire.copyText() (instance method)

encodeHTML

Frontfire.encodeHTML(text) → String

Encodes a string for use in HTML code. This does not change any quote characters so it cannot be used in HTML attribute values.

F.encodeHTML("Is a < 5 & b > 10?") → "Is a < 5 & b > 10?"

findEventTarget

Frontfire.findEventTarget(event, selector) → Node
Frontfire.findEventTarget(event, node) → Node

Finds an element (by a CSS selector, or a specific node) along the event capturing or bubbling path. This can be used to implement delegated event handlers. While the handler is called for the registered element, it can check if the event was actually triggered for one of its descendant elements.

In the event capturing phase, returns the first matched element (from currentTarget, where the event handler has been attached, downwards to target, where the event occurred), or null if none was found.

In the event bubbling phase, returns the first matched element (from target, where the event occurred, upwards to currentTarget, where the event handler has been attached), or null if none was found.

Along the search path, event.target is always included and event.currentTarget is always excluded.

Attaching an event handler explicitly to one or more elements requires these elements to exist at that time. Elements that might match but are only created later will not have this event handler. Delegated event handlers can be attached to an ancestor element and will process the event for all descendant elements, also those that were created later. Using this technique, you do not need to frequently attach and remove many event handlers from dynamically created elements. A single event handler will also cause less overhead than a separate handler for each descendant element.

// Handle click event for all rows on the table level F("table").on("click", event => { let clickedRow = Frontfire.findEventTarget(event, "tr"); // Use clickedRow });

forceReflow

Frontfire.forceReflow() → void

Forces a browser layout reflow. This can be used to start CSS transitions on new elements. Note that animations can also be started directly with the animateFromTo() method.

F("#panel").style = { transition: "background 2s", background: "yellow" }; // Start the new transition immediately F.forceReflow();

getJSON

Frontfire.getJSON(url, data, init) → Promise(response)

Executes a GET request to a URL and returns the JSON-data result. If an error occurs, the error is logged to the console and the returned Promise resolves to undefined.

The data parameter accepts an object containing additional URL query parameters. These entries are appended to already existing query parameters in the URL.

The init parameter is an optional object with additional options to the fetch() call init argument.

let response = await F.getJSON("controller.php", { id: 1, name: "Abc" }); → e.g. { success: true }

For more advanced network requests, use the fetch() function or XMLHttpRequest object directly.

See also: getText() (receives data as text), postJSON()

getText

Frontfire.getText(url, data, init) → Promise(response)

Executes a GET request to a URL and returns the text-data result. If an error occurs, the error is logged to the console and the returned Promise resolves to undefined.

The data parameter accepts an object containing additional URL query parameters. These entries are appended to already existing query parameters in the URL.

The init parameter is an optional object with additional options to the fetch() call init argument.

let response = await F.getText("controller.php", { id: 1, name: "Abc" }); → e.g. "success"

For more advanced network requests, use the fetch() function or XMLHttpRequest object directly.

See also: getJSON() (receives data as JSON), postFormText()

getTranslator

Frontfire.getTranslator(dictionary) → Function
Frontfire.getTranslator(dictionary, language) → Function

Builds a translation function with a text dictionary for the specified language. If no language is specified, the language is determined by the lang attribute of the document root element (<html>). The dictionary contains a key for each supported language, which is an object that contains a key for each text. The language keys must be defined in lower case. The language “en” is the fallback and must be complete.

The returned function can be called with a single argument:

Text key as defined in the dictionary

It then returns the translated text from the dictionary, in the selected language or a fallback language if that text is undefined in the selected language. If the language contains a region, like “pt-BR”, then the language alone (here “pt”) is also considered.

Note that this is only a very basic translation system. It can be used for simple words or short phrases but does not support any more advanced features like placeholders or counting. This method is used by Frontfire UI plugins for their UI labels. Websites and applications should consider a more comprehensive translation solution to build on.

id

Frontfire.id(id) → Frontfire

Creates a new Frontfire instance selecting a single element by its ID. This has a performance benefit against Frontfire("#id") and is similar to document.getElementById(id).

F.id("panel1") → Selected an element like <div id="panel1">

postFormJSON

Frontfire.postFormJSON(url, data, init) → Promise(response)

Executes a form-data POST request to a URL and returns the JSON-data result. The data is specified as an object containing the keys and values to send as form fields in the request body. If an error occurs, the error is logged to the console and the returned Promise resolves to undefined.

The init parameter is an optional object with additional options to the fetch() call init argument.

let response = await F.postFormJSON("controller.php", { id: 1, name: "Abc" }); → e.g. { success: true }

For more advanced network requests, use the fetch() function or XMLHttpRequest object directly.

See also: postFormText() (receives data as text), postJSON() (sends data as JSON), getJSON()

postFormText

Frontfire.postFormText(url, data, init) → Promise(response)

Executes a form-data POST request to a URL and returns the text-data result. The data is specified as an object containing the keys and values to send as form fields in the request body. If an error occurs, the error is logged to the console and the returned Promise resolves to undefined.

The init parameter is an optional object with additional options to the fetch() call init argument.

let response = await F.postFormText("controller.php", { id: 1, name: "Abc" }); → e.g. "success"

For more advanced network requests, use the fetch() function or XMLHttpRequest object directly.

See also: postFormText() (receives data as JSON), postJSON() (sends and receives data as JSON), getText()

postJSON

Frontfire.postJSON(url, data, init) → Promise(response)

Executes a JSON-data POST request to a URL and returns the JSON-data result. The data is specified as the object to send as JSON-serialized request body. If an error occurs, the error is logged to the console and the returned Promise resolves to undefined.

The init parameter is an optional object with additional options to the fetch() call init argument.

let response = await F.postJSON("controller.php", { id: 1, name: "Abc" }); → e.g. { success: true }

For more advanced network requests, use the fetch() function or XMLHttpRequest object directly.

See also: postFormJSON() (sends data as traditional form fields), postJSONText() (receives data as text), getJSON()

postJSONText

Frontfire.postJSONText(url, data, init) → Promise(response)

Executes a JSON-data POST request to a URL and returns the text-data result. The data is specified as the object to send as JSON-serialized request body. If an error occurs, the error is logged to the console and the returned Promise resolves to undefined.

The init parameter is an optional object with additional options to the fetch() call init argument.

let response = await F.postJSONText("controller.php", { id: 1, name: "Abc" }); → e.g. "success"

For more advanced network requests, use the fetch() function or XMLHttpRequest object directly.

See also: postJSON() (receives data as JSON), getText()

preventScrolling

Frontfire.preventScrolling() → void
Frontfire.preventScrolling(state) → void

Prevents scrolling the document. The state parameter controls whether to enable or disable the scrolling prevention. If not specified, true is assumed.

// Prevent scrolling the page F.preventScrolling(); // Allow scrolling the page again F.preventScrolling(false);

regExpEscape

Frontfire.regExpEscape(text) → String

Escapes a string for use in a regular expression so that it will not contain any effective control characters.

F.regExpEscape("Hello (world)?") → "Hello \$world\$\\?" (backslashes shown escaped, appear only once each)

round

Frontfire.round(value, decimals) → Number

Returns the value rounded to the specified number of decimals.

F.round(1.234, 0) → 1 F.round(1.234, 2) → 1.23 F.round(1.899, 1) → 1.9 F.round(1.234, 5) → 1.234

single

Frontfire.single(…) → Frontfire

Creates a new Frontfire instance selecting only a single element. Accepts the same argument types as the add() method.

let p = F.single("p") → p.length: 1

delay

Frontfire.delay(ms) → Promise
Frontfire.delay(ms, abortSignal) → Promise

Asynchronously waits for the specified time in milliseconds. Returns a Promise that resolves after the specified time or rejects with an AbortError, or whatever reason was specified with AbortController.abort(), when the abortSignal was signalled.

Without the AbortSignal, this is an alternative to: await new Promise(r => setTimeout(r, ms));

// Wait for 500 ms await F.delay(500); // Now the time has passed // Catch default AbortError try { await F.delay(2000, AbortSignal.timeout(1000)); } catch (error) { if (error instanceof DOMException && error.name === "AbortError") { // Wait was aborted } else { // Other error } }

abortSignal parameter added in v2.1.0

Renamed from sleep to delay in v2.1.0, old name kept as alias (to be removed in v3.0.0)

Static variable tests

isBoolean

Frontfire.isBoolean(value) → Boolean

Determines whether the value is boolean.

isEven

Frontfire.isEven(value) → Boolean

Determines whether the value is an even integer number (e.g. 0, 2, 4, 6 etc.).

isFunction

Frontfire.isFunction(value) → Boolean

Determines whether the value is a function.

Added in v2.1.0

isIterable

Frontfire.isIterable(value) → Boolean

Determines whether an object is iterable, i.e. usable in for-of loops.

isNumber

Frontfire.isNumber(value) → Boolean

Determines whether the value is a number.

isOdd

Frontfire.isOdd(value) → Boolean

Determines whether the value is an odd integer number (e.g. 1, 3, 5, 7 etc.).

isSet

Frontfire.isSet(value) → Boolean

Determines whether the value is set (i.e. not undefined or null).

isString

Frontfire.isString(value) → Boolean

Determines whether the value is a string.

Static browser tests

These methods prefer detection techniques that do not depend on the User-Agent string which can be manipulated by the user. This means that the results may vary over different versions of the browser applications. These methods are intended to be used to work around bugs in certain browser engines, not to tell precisely what application UI is used. Only detection methods for browsers supported by Frontfire are provided.