A Global Object Methods and Functions

A.initialized()

Returns a promise that resolves once a.js has fully initialized, including defining all <a-xxxx> tags.

Syntax:

A.initialized().then(() => {
  console.log('a.js is fully initialized.');
});

Returns:

• Promise: Resolves when a.js is ready for use.

A.allParsed()

Returns a promise that resolves once all <a-xxxx> elements present at initialization have been parsed.

Syntax:

A.allParsed().then(() => {
  console.log('All a-elements have been parsed.');
});

Returns:

• Promise: Resolves when all <a-xxxx> elements are fully parsed.

A.waitUntilAParsedIfExists(element)

Waits for a specified element to be parsed if it exists. If the element does not exist, the promise resolves immediately.

Parameters:

• element (HTMLElement): The element to wait for.

Returns:

• Promise: Resolves when the specified element has been parsed or if it does not exist.

Syntax:

A.waitUntilAParsedIfExists(document.querySelector('my-element')).then(() => {
  console.log('my-element parsed or does not exist.');
});

A.dumpAllStates()

Dumps all <let> variable states into a JSON string. This is useful for persisting the application state.

Returns:

• String: A JSON string representing the current state of all <let> variables.

Syntax:

const stateDump = A.dumpAllStates();
console.log(stateDump);

A.restoreAllStates(dump)

Restores <let> variable states from a previously dumped state string.

Parameters:

• dump (String): The JSON string returned by A.dumpAllStates.

Syntax:

A.restoreAllStates(stateDump);

Behavior:

• Reinstates the values of variables defined in <let> tags.
• Handles scope-specific variables using the HTML tree structure.

A.importIn(elem, url[, type][, removeAfterImport][, onloaded])

Imports content from the specified url into the given element elem by creating an <a-closure><import> in it. This can dynamically load HTML, CSS, JavaScript, or other resources.

Parameters:

• elem (HTMLElement): The target element for the imported content.
• url (String): The URL to import from.
• type (String, optional): The type of content to import. Defaults to text/html. Other valid values include css, javascript, json.
• removeAfterImport (Boolean, optional): If true, removes the <a-closure> tag after execution. Defaults to true.
• onloaded (Function, optional): A callback function executed after the import is complete.

Syntax:

A.importIn(currentElement, './fragment.html', 'html', true, () => {
  console.log('Import completed.');
});

A.getOrCreateKeyedElement(tagName, key, htmlElement[, namespace])

Retrieves or creates a keyed element associated with the provided key.

Parameters:

• tagName (String): The tag name of the element to create.
• key (String): A unique identifier for the element.
• htmlElement (HTMLElement): The parent element.
• namespace (String, optional): A namespace for the key.

Returns:

• HTMLElement: The created or retrieved keyed element.

Syntax:

const keyedElem = A.getOrCreateKeyedElement('div', 'unique-key', document.body);

A.removeKeyedElement(key, htmlElement[, namespace])

Removes a keyed element from the DOM and deletes its key association.

Parameters:

• key (String): The unique identifier of the element.
• htmlElement (HTMLElement): The parent element.
• namespace (String, optional): A namespace for the key.

Returns:

• HTMLElement: The removed element, if it exists.

Syntax:

A.removeKeyedElement('unique-key', document.body);

A.getAllKeyedElementsKeysArray(htmlElement[, namespace])

Retrieves an array of all keys associated with a specific element and namespace.

Parameters:

• htmlElement (HTMLElement): The parent element.
• namespace (String, optional): A namespace for the keys.

Returns:

• Array: An array of keys.

Syntax:

const keys = A.getAllKeyedElementsKeysArray(document.body);
console.log(keys);

A.getAllKeyedElementsKeysSet(htmlElement[, namespace])

Retrieves an array of all keys associated with a specific element and namespace.

Parameters:

• htmlElement (HTMLElement): The parent element.
• namespace (String, optional): A namespace for the keys.

Returns:

• Set: A Set of keys.

Syntax:

const keys = A.getAllKeyedElementsKeysArray(document.body);
console.log(keys);

A.getAllKeyedElementsKeysObject(htmlElement[, namespace])

Retrieves an array of all keys associated with a specific element and namespace.

Parameters:

• htmlElement (HTMLElement): The parent element.
• namespace (String, optional): A namespace for the keys.

Returns:

• Object: An object { key : true} of keys.

Syntax:

const keys = A.getAllKeyedElementsKeysArray(document.body);
console.log(keys);

A.updateObject(target, source)

Merges the properties of the source object into the target object. Only differing properties are updated.

Parameters:

• target (Object): The object to be updated.
• source (Object): The object providing new values.

Returns:

• void

Syntax:

let target = { a: 1, b: 2 };
let source = { b: 3, c: 4 };
A.updateObject(target, source);
console.log(target); // { a: 1, b: 3, c: 4 }

A.getJSONPath(obj, tpath[, value])

Retrieves or sets a value in an object or array using a JSON path.

Parameters:

• obj (Object | Array): The target object or array.
• tpath (String): The JSON path.
• value (Any, optional): The value to set at the specified path.

Returns:

• Any: The value at the specified path, or the updated object.

Syntax:

let data = { a: { b: [1, 2, 3] } };
const value = A.getJSONPath(data, 'a.b.1');
console.log(value); // value is 2 => logs 2

A.getJSONPath(data, 'a.b.1', 42);
console.log(data); // data has been modified => logs { a: { b: [1, 42, 3] } }

A.getNonATextContent(element)

Retrieves the content of an element, excluding everything that is an a-element or inside one.

Parameters:

• element (HTMLElement): The element whose text content is to be retrieved.

Returns:

• String: The plain text content of the element.

Syntax:

const text = A.getNonATextContent(document.querySelector('my-element'));
console.log(text);

A.getTextContent(element)

Retrieves the content of an element, including content inside <a-xxxx> elements but removes any <script type="a/unparsed"> and the corresponding closing tag.

Parameters:

• element (HTMLElement): The element whose text content is to be retrieved.

Returns:

• String: The text content of the element, including content from a.js elements.

Syntax:

const text = A.getTextContent(document.querySelector('my-element'));
console.log(text);

A.getSourceContent(element)

Retrieves the content of an element, as it would appear when explored in the browser developer tools Elements tab.

Parameters:

• element (HTMLElement): The element whose source content is to be retrieved.

Returns:

• String: The raw HTML content of the element.

Syntax:

const source = A.getSourceContent(document.querySelector('my-element'));
console.log(source);