hyTags
Selection
Overview
Every hyTags code block runs in the context of a DOM element called the selection. The selection determines which element commands operate on. By default, it's the element the event handler is attached to.
Default Selection
When an event handler runs, the selection starts as the element the handler is attached to. In this example, clicking the button changes its own text because the button is the current selection:
<button>Click me</button> <on click> <!-- Selection is the button --> <selection-set-text text="Clicked!"> </on>
Navigating the Selection
Use
selection-change to navigate to a different element. Navigation strategies include:
- parent: Find an element among ancestors. Use a CSS selector or leave empty to select the direct parent.
- first-child / last-child: Find among children of the current selection.
- next-sibling / previous-sibling: Find among siblings of the current selection.
- first-descendant / last-descendant: Find anywhere in the subtree of the current selection.
- global: Find anywhere in the document using a CSS selector.
Example: Navigate to a sibling element and modify it:
<button>Update</button> <on click> <selection-change next-sibling="div"> <selection-set-text text="Updated!"> </on> <div>Waiting...</div>
Temporary Scoping
Use
selection-scope to temporarily change the selection. After the scope ends, the selection automatically returns to its previous value. This is useful when you need to read from or write to another element without losing your current context:
<button>Read child</button>
<on click>
<selection-scope next-sibling="div" return="string">
<selection-get-text>
</selection-scope>
<!-- Selection is back to button -->
<!-- Text from div is on the stack -->
<debug-log>
</on>
<div>Hello from div</div>
Looping Over Elements
Use
selection-loop to iterate over children or descendants. The code block runs once for each matching element, with the selection set to that element. Clicking the list below logs the count (3) to the console:
- Apple
- Banana
- Cherry
<ul>
<li>Apple</li>
<li>Banana</li>
<li>Cherry</li>
</ul>
<on click>
<var-set name="count" value="0" type="number"></var-set>
<selection-loop children="li">
<var-update name="count">
<number-add value="1">
</var-update>
</selection-loop>
<var-get name="count">
<debug-log>
</on>
Common Commands
Commands that read from the selection:
- selection-get-text: Gets the text content of the selected element.
- selection-get-value: Gets the value of a form input.
- selection-get-html: Gets the inner HTML of the selected element.
Commands that modify the selection:
- selection-set-text: Sets the text content of the selected element.
- selection-set-value: Sets the value of a form input.
- selection-append-children: Appends new elements as children of the selection.
- selection-delete: Removes the selected element from the DOM.
