Built In Variables

Evolve supplies a small handful of built in variables. Some are available everywhere and some are available contextually. Referring to a built in that is not available in the context that your code is in will result in a compile error.

Identifier	Always Available	Description
$runtime	yes	This provides a reference to the runtime. See UIRuntime for api listings
$root	no	Resolves to the top level ElementReference in a template declaration
$element	no	Resolves to the 'current' ElementReference. Not available in top level function declarations or outside of an element context (ie inside a render block but part of a specific element)
$parent	no	Resolves to the 'current' element's parent ElementReference.
`$oldValue	no	Available inside change handlers, refers the previous value
`$newValue	no	Available inside change handlers, refers to the new value
`$companion	no	Avaiable in any top level declaration that also supplied a companion type. Refers to the companion instance
$text	no	Available inside typography elements and typography decorators. Resolves to the current TextReference

$root, $element, and $parent

When inside of a top level declarations (except for function) you can always use $element to get the current element reference. Inside of a render block, $element becomes contextual based on where it is used and is only valid inside a binding expression. It is not valid inside a create, run, enable, var, state, repeat, if or any other expression that is not related to a property or lifecycle binding.

In a given element usage like Text("xyz"), the $element reference becomes available inside of bindings.

When inside of a render block, you can refer to $root to get an ElementReference for the current template root, in the example below it would point at Thing.

You can also use $parent to refer to an element's parent. This is available everywhere that $element is valid and always points to the currently executing element's parent.

template Thing {

    before:update => {
        $element.SetAttribute("ticked", true); // in a top level declaration $element points to Thing
    }
     
    render {
    
        Text($"the element is {$element}"); // refers to the Text element
        Text($"the element is {$root}"); // refers to the Thing, which is the template root
        
        run $element.SetAttribute("illegal", true); // $element points nowhere, this is not allowed
        run $root.SetAttribute("illegal", false); // $root points to Thing, totally fine
        
        run $parent.SetAttribute("fine, "yep"); // $parent points at Thing's parent. this MAY be invalid if Thing is a view root and has no parent. 
        
        Element1(value = $parent) { // $parent == Thing
           Element2(value = $parent) { // $parent == Element1
        }
        
    }
}

Inside of a decorator, $element points to the element being decorated.

decorator SomeDecorator {

    before:update => $element.stlye.BackgroundColor = `red`;
    
}