Custom Tags and Components

<a-closure>

The <a-closure> tag serves as the backbone of a.js functionality. It encapsulates JavaScript code inside a closure, preventing unintended interactions with the global scope.

Features:

• Automatically wraps the script content in an IIFE (Immediately Invoked Function Expression).
• Ensures variable isolation and reduces the risk of conflicts.
• Offers seamless access to a.js reactive variables and utilities.

Syntax:

<a-closure>
  // JavaScript code here
</a-closure>

Example:

<a-closure>
  let localVar = 'Scoped Variable';
  console.log(localVar);
  currentElement.innerHTML = 'This is scoped.';
</a-closure>

<a-tagDef>

The <a-tagDef> tag enables developers to define custom, reusable components. These components are instantiated dynamically in the DOM, promoting modular and maintainable code.

Features:

• Allows the creation of custom elements with specific behavior and styles.
• Simplifies code reuse and encapsulation.
• Supports redefinition for existing tags with the redefine attribute.

Syntax:

<a-tagDef forTag="custom-tag">
  // Code defining behavior for <custom-tag>
</a-tagDef>

Example:

<a-tagDef forTag="custom-button">
  currentElement.innerHTML = '<button>Click Me</button>';
  currentElement.addEventListener('click', () => {
    alert('Button clicked!');
  });
</a-tagDef>

<custom-button></custom-button>

<a-tagdef>attributes

forTag

Description:

The forTag attribute is used in <a-tagDef> elements to define a custom tag. This attribute specifies the name of the custom tag being defined.

Behavior:

• If a custom tag with the specified name already exists, a.js will throw an error unless the redefine attribute is present.
• It associates the <a-tagDef> content with the defined custom tag name.

Syntax:

<a-tagDef forTag="custom-box">
  currentElement.innerHTML = '<div>Custom Box</div>';
</a-tagDef>

<custom-box></custom-box>

redefine

Description:

The redefine attribute allows redefining an existing custom tag. Without this attribute, a.js will ignore the redefinition attempt.

Behavior:

• Mandatory for redefining a tag.
• Applies only to newly connected custom tags unless A.replayCustomTag(element) or A.replayCustomTagsByName("tagname") is called.

Syntax:

<a-tagDef forTag="custom-box" redefine>
  currentElement.innerHTML = '<div>Updated Custom Box</div>';
</a-tagDef>

when you add the above to the DOM, the <custom-box> tags that already are in the document will still display Custom box, but any new <custom-box> tag you append to the DOM will display Updated Custom Box. If you want the existing <custom-box> tags to adopt the new definition, you have to call A.replayCustomTag(element) on each of them individually, or A.replayCustomTagsByName("custom-box") to update all of them at once.

Example of replaying:

A.replayCustomTagsByName('custom-box');

<a-script>

The <a-script> tag is a customized replacement for the native <script> tag, providing additional functionality specific to a.js. It allows developers to run JavaScript code within a controlled context while integrating deeply with a.js features.

Features:

• Supports scoped execution, reducing the risk of global variable pollution.
• Offers access to special variables currentScript and currentElement for targeting the relevant script and element.
• Compatible with the closure attribute to encapsulate the script within a closure.

Syntax:

<a-script>
  // JavaScript code here
</a-script>

Example:

<a-script>
  console.log('Executed within <a-script>');
  currentElement.innerHTML = 'Hello from a.js';
</a-script>

Special Variables and Behaviors

currentScript

currentScript refers to the <script> tag of the custom a.js tag containing the variable. This variable allows direct access to the running script element, enabling dynamic manipulation or introspection.

Example:

<a-script>
  console.log('The script:', currentScript);
</a-script>

currentElement

currentElement provides a reference to the DOM element targeted by the custom or <a-xxxx> a.js tag. This variable is essential for modifying the target element dynamically.

Example:

<a-closure>
  currentElement.innerHTML = 'Hello from currentElement!';
</a-closure>

(...), {(...)} and ${...}

Inside an <a-xxxx></a-xxxx> element, you can write any html tag between parenthesis ( and ) and before the runtime it will be converted to a javascript code generating the corresponding HTMLElement in the context of the <a-xxxx></a-xxxx> element.

• (...) generates the element and returns it.

Example:

<a-closure>
  currentElement.appendChild(<b>Bold text</b>)
</a-closure>

will append a <b> containing a text node "Bold text" to currentElement

<a-closure>
  document.body.appendChild(<b>Bold text</b>)
</a-closure>

will append a <b> containing a text node "Bold text" to the body

• {(...)} generates the element and append it to currentElement.

Example:

<a-closure>
  {(<b>Bold text</b>)}
</a-closure>

will append a <b> containing a text node "Bold text" to currentElement

• ${...} leverages JavaScript template litterals to allow you to display the value of any JavaScript variable or expression evaluated in the context inside (...) or {(...)}. Additionnaly, if ${...} refers to a watched variable, the corersponding content will become reactive.

<a-closure>
  <let>
  global watched bold.text;
  </let>
  bold.text = "Bold text"
  {(<b>${bold.text}</b>)}
  bold.text = "reactive bold text"
</a-closure>

Every time bold.text is updated to a new value, the text of the text node inside the <b> tag will be updated to this new value too.

Utility Functions

watch(callback[,onOkCallback][,onErrorCallback])

• Tracks changes to reactive variables and executes callback when changes occur. Nested watch calls optimize dependency tracking. onOkCallback, if provided, gets called with the result of callback each time it is called. onErrorCallback is called when a call to callback throws an error.
• returns {result} where result is what callback returns. The result property gets updated whenever callback is called.
• You can set the suspend property of the returned object to true to pause the calls to callback on changes.

Example:

<a-closure>
  <let>
    global watched app.data.value;
  </let>
  app.data.value = 42;

  watch(() => {
    console.log('Value updated:', app.data.value);
  });
</a-closure>

unwatch(base)

Creates a static (non-reactive) copy of the base object of a watched variable.

Example:

<a-closure>
  <let>
    global watched app.data.value;  //app is the base object
  </let>
  app.data.value = 42;

  const staticApp = unwatch(app);
  watch(() => {
    console.log('Value updated:', staticApp.data.value); // Static value that does not trigger reactivity
  });
</a-closure>

expose(function[, name])

Attaches a function to currentElement.A with a specified name.

Example:

<a-closure>
  expose(function sayHello() {
    console.log('Hello from exposed function!');
  }, 'sayHello');

  currentElement.A.sayHello();
</a-closure>

injectFunction(callback)

Wraps a function to execute within the context of the current script and element.

Example:

<script>
  const injected = element.A.injectFunction(() => {
    console.log('Injected function context:', currentElement);
  });

  injected();
</script>