◁ Expression Language ≡ Table of Contents Scripting ▷
Seanox aspect-js extends the declarative approach of HTML. In addition to the expression language, HTML elements get attributes for runtime functions and View-Module Binding. The renderer is part of the composite implementation. It monitors the DOM from the BODY element with MutationObserver and reacts recursively to changes.
In Seanox aspect-js, the declarative approach is implemented with attributes.
They can be used and combined in all HTML elements starting with the HTML
element BODY. Attribute values can be static or dynamic through the expression
language. If an attribute contains an expression, the renderer updates the value
with each render cycle based on the initial expression.
Marks an element in the markup as a Composite. Composites are essential components that require an identifier (ID / Composite ID).
<article id="example" composite>
...
</article>
As a component, composites are composed of various resources (markup, CSS, JS). They can be outsourced to the module directory based on the Composite ID and are loaded at runtime when used.
Composites are also the basis for View-Module Binding. It connects HTML elements in the markup (view) with corresponding JavaScript objects. The view as presentation and user interface for interactions remains decoupled from the application module. Application modules provide the data, state and behavior that are exposed to the view through View-Module Binding. Binding links views and modules bidirectionally based on the Composite IDs, so manual declaration of events, interaction or synchronization is not required.
Routing uses composites as views. They can be path targets in the view flow, which controls the visibility of composites. When routing is active, composites can be marked with attribute route so that routing controls their visibility through paths and the permission concept.
<article id="example" composite route>
...
</article>
Details on the use of composites / modular components are described in chapter Composites and View-Module Binding.
As a condition, the attribute specifies whether an element remains contained in
the DOM. The expression specified as the value must explicitly return true to
retain the element. If the return value is different, the element is temporarily
removed from the DOM and can be reinserted later by refreshing the parent
element if the expression returns true.
<article condition="{{model.visible}}">
...
</article>
When combined with the attribute interval, it should be noted that when the element is removed from the DOM, the associated timer is also terminated. If the element is added back to the DOM with a later refresh, a new timer starts, so it is not continued.
<article interval="{{1000}}" condition="{{model.visible}}">
...
</article>
The use of the condition attribute in combination with embedded JavaScript is
possible as SCRIPT element with the type composite/javascript as Composite
JavaScript, because here the renderer has control over the script execution and
not the browser.
<script type="composite/javascript" condition="{{model.visible}}">
...
</script>
Details about using embedded JavaScript are described in chapter Scripting.
Binds one or more events to an HTML element. This allows for event-driven synchronization of HTML elements with corresponding JavaScript objects, validation of synchronized data (see validate) and event-driven control and refreshing of other HTML elements (see render).
As with all attributes, the expression language can be used here. Runtime changes have no effect because the attribute value for View-Module Binding is processed only initially while the HTML element exists in the DOM.
<span id="output1">{{#text1.value}}</span>
<input id="text1" type="text"
events="input change" render="#output1"/>
The example synchronously refreshes the HTML element output1 with the events Input or Change at the HTML element text1. The input value of text1 is output synchronously with output1.
const model = {
validate(element, value) {
return true;
},
text1: ""
};
<form id="model" composite>
<input id="text1" type="text"
validate events="input change"/>
<input type="submit" value="submit"
validate events="click"/>
</form>
The example combines the attributes events and validate. The input value
from the composite field text1 is transferred to the field of the same name in
the JavaScript object only if the event Input or Change occurs.
The ID (identifier) has a central role in Seanox aspect-js. It is the basis for View-Module Binding and is used by Routing for views in the view flow and as a destination for paths.
As with all attributes, the expression language can be used. The attribute is only read at the beginning. Due to View-Module Binding, changes to an existing element at runtime have no effect while it exists in the DOM.
Loads the content for the HTML element at runtime and inserts it as inner HTML. The behavior is similar to the output attribute, except that the import is done once and the import attribute is removed after successful loading. As value one or more elements are supported as NodeList or Array, as well as absolute or relative URLs to a remote resource and also the DataSource URL (locator) for transformed content from the DataSource.
The import attribute can be combined with the condition attribute and will then
only be executed if the condition is true.
const model = {
publishForm() {
const form = document.createElement("form");
const label = document.createElement("label");
label.textContent = "Input";
form.appendChild(label);
const input = document.createElement("input");
input.value = "123";
input.type = "text";
form.appendChild(input);
const submit = document.createElement("input");
submit.type = "submit";
form.appendChild(submit);
return form;
},
publishImg() {
const img = document.createElement("img");
img.src = "https://raw.githubusercontent.com/seanox/aspect-js/master/test/resources/smile.png";
return img;
}
};
<article import="{{model.publishImg()}}">
loading image...
</article>
<article import="{{model.publishForm()}}">
loading form...
</article>
Example of importing a remote resource using the HTTP method GET.
<article import="{{'https://raw.githubusercontent.com/seanox/aspect-js/master/test/resources/import_c.htmlx'}}">
loading resource...
</article>
<article import="https://raw.githubusercontent.com/seanox/aspect-js/master/test/resources/import_c.htmlx">
loading resource...
</article>
Example of importing via DataSource-URL. If only one URL is specified, the URI for data and transformation are derived from it.
<article import="{{'xml://example/content'}}">
loading resource...
</article>
<article import="xml://example/content">
loading resource...
</article>
<article import="xml://example/content?count(//item)">
loading resource...
</article>
Example of importing a DataSource-URL with a specific data URL (locator) and transformation URL. As a value, the data URL (locator of the XML file) and the transformation URL (locator of the XSLT template) are is specified, separated by a blank character.
<article import="{{'xml://example/data + xslt://example/style'}}">
loading resource...
</article>
<article import="xml://example/data + xslt://example/style">
loading resource...
</article>
<article import="xml://example/data + xslt">
loading resource...
</article>
If only xslt is specified without a locator, a corresponding XSLT locator with the same name is derived from the XML locator.
When inserting content from the DataSource, the type of JavaScript blocks is
automatically changed to composite/javascript and only executed by the
renderer. This results in JavaScript being executed depending on the enclosing
condition attribute.
Activates an interval-controlled refresh of the HTML element without the need to actively trigger the refresh. The interval uses the inner HTML as a template from which updated content is generated and inserted with each interval cycle. The attribute expects milliseconds as value, which can also be formulated as expression, where invalid values cause console output. Processing is concurrent or asynchronous but not parallel. Processing will start after the specified time when a previously started JavaScript procedure has finished. Therefore, the interval should be understood as timely but not exact. The interval starts refreshing automatically and ends when:
<span interval="1000">
...
</span>
<span interval="{{1000 +500}}">
...
</span>
The interval attribute can be used for HTML elements and complex HTML constructs. For example, the SPAN element is updated every 1000ms. An active interval reacts dynamically to DOM changes. It starts automatically when the HTML element is added to the DOM and ends when it is removed from the DOM. This makes the interval attribute controllable in combination with the condition attribute.
<span interval="1000" condition="{{model.isVisible()}}">
...
</span>
For example, interval and a variable expression can implement a permanent counter.
{{counter:0}}
<p interval="1000">
{{counter:parseInt(counter) +1}}
{{counter}}
</p>
It is also possible to use the interval attribute in combination with embedded JavaScript as a composite JavaScript.
<script type="composite/javascript" interval="1000">
...
</script>
Iterative output is based on lists, enumerations and arrays. If an HTML element
is declared as iterative, the inner HTML is used as a template from which
updated content is generated and inserted as inner HTML with each render cycle.
The attribute value expects a variable expression. It creates a meta-object that allows
access to the iteration in the template. The variable expression
iterate={{tempA:model.list}} creates the meta-object
tempA = {item, index, data}.
const model = {
months: ["Spring", "Summer", "Autumn", "Winter"]
};
<select iterate={{months:model.months}}>
<option value="{{months.index}}">
{{months.item}}
</option>
</select>
Note
If arrays are used with reactive objects, iterate accesses the arrays directly. If the array is a list of values, value changes also change the array and trigger re-rendering of the iterate. To change values at runtime without triggering re-rendering of the iterate, the array must contain objects with the values. Setting the value in the objects does not change the array itself and therefore does not trigger re-rendering.Alternatively, the length of the array can also be passed to the iterate. It then generates a list of values with the index without accessing the elements. The index can then be used by the expression within the iterate to access the array.
<select iterate={{months:model.months.length}}>
<option value="{{months.index}}">
{{model.months[months.index]}}
</option>
</select>
If the value for an iterator is a positive number, a list of values from 0 to (number -1) is used. If the value is negative, a descending list of values is used from (number +1) to 0.
Message is an optional part of Validation and is used for text and error output in case of an unconfirmed validation. This requires a combination with the attributes validate and events.
<form id="model" composite>
<input id="email" type="text" placeholder="email address"
pattern="^\w+([\w\.\-]*\w)*@\w+([\w\.\-]*\w{2,})$"
validate message="Valid e-mail address required"
events="input change" render="#model"/>
<input type="submit" value="submit" validate events="click"/>
</form>
<form id="model" composite>
<input id="email" type="text" placeholder="email address"
pattern="^\w+([\w\.\-]*\w)*@\w+([\w\.\-]*\w{2,})$"
validate message="{{Messages['model.email.validation.message']}}"
events="input change" render="#model"/>
<input type="submit" value="submit" validate events="click"/>
</form>
Sets for the HTML element the value or result of its expression as inner HTML. The behavior is similar to the import attribute, except that the output is updated with each render cycle. Supported values are text, one or more elements as NodeList or Array, as well as absolute or relative URLs to a remote resource and also the DataSource-URL (locator) for transformed content from the DataSource.
The output attribute can be combined with the condition attribute and will then
only be executed if the condition is true.
const model = {
publishForm() {
const form = document.createElement("form");
const label = document.createElement("label");
label.textContent = "Input";
form.appendChild(label);
const input = document.createElement("input");
input.value = "123";
input.type = "text";
form.appendChild(input);
const submit = document.createElement("input");
submit.type = "submit";
form.appendChild(submit);
return form;
},
publishImg() {
const img = document.createElement("img");
img.src = "https://raw.githubusercontent.com/seanox/aspect-js/master/test/resources/smile.png";
return img;
}
};
<article output="{{model.publishImg()}}">
loading image...
</article>
<article output="{{model.publishForm()}}">
loading form...
</article>
Example of outputting a remote resource using the HTTP method GET.
<article import="{{'https://raw.githubusercontent.com/seanox/aspect-js/master/test/resources/import_c.htmlx'}}">
loading resource...
</article>
<article import="https://raw.githubusercontent.com/seanox/aspect-js/master/test/resources/import_c.htmlx">
loading resource...
</article>
Example of outputting via DataSource-URL. If only one URL is specified, the URI for data and transformation are derived from it.
<article output="{{'xml://example/content'}}">
loading resource...
</article>
<article output="xml://example/content">
loading resource...
</article>
<article output="xml://example/content?count(//item)">
loading resource...
</article>
Example of outputting a DataSource-URL with a specific data URL (locator) and transformation URL. As a value, the data URL (locator of the XML file) and the transformation URL (locator of the XSLT template) are is specified, separated by a blank character.
<article output="{{'xml://example/data + xslt://example/style'}}">
loading resource...
</article>
<article output="xml://example/data + xslt://example/style">
loading resource...
</article>
<article output="xml://example/data + xslt">
loading resource...
</article>
If only xslt is specified without a locator, a corresponding XSLT locator with the same name is derived from the XML locator.
When inserting content from the DataSource, the type of JavaScript blocks is
automatically changed to composite/javascript and only executed by the
renderer. This results in JavaScript being only executed depending on the
enclosing condition attribute.
Inverse indicator that an HTML element was rendered. The renderer removes this attribute when an HTML element is rendered. This effect can be used for CSS to show elements only in rendered state. A corresponding CSS rule is automatically added to the HEAD when the page is loaded.
<span release>{{'Show me after rendering.'}}</span>
The attribute requires the combination with the events attribute. Together they define which targets are refreshed by the renderer with which occurring events. The expected value is one or more space-separated CSS or Query selectors that define the targets.
const model = {
_status1: 0,
getStatus1() {
return ++model._status1;
},
_status2: 0,
getStatus2() {
return ++model._status2;
},
_status3: 0,
getStatus3() {
return ++model._status3;
}
};
Target #1:
<span id="outputText1">{{model.status1}}</span>
Events: Wheel
<input id="text1" type="text"
events="wheel"
render="#outputText1, #outputText2, #outputText3"/>
Target #2:
<span id="outputText2">{{model.status2}}</span>
Events: MouseDown KeyDown
<input id="text1" type="text"
events="mousedown keydown"
render="#outputText2, #outputText3"/>
Target #3:
<span id="outputText3">{{model.status3}}</span>
Events: MouseUp KeyUp
<input id="text1" type="text"
events="mouseup keyup"
render="#outputText3"/>
The example contains 3 input fields with different events (events) and targets
(render), each of which represents an incremental text output and reacts to
corresponding events.
Alternatively, reactive rendering can be used, where changes in the data objects trigger a partial update of the view.
The route attribute marks a composite as a path-addressable destination and includes it in path-based control and the internal permission concept of routing. The attribute can be used in the BODY tag and otherwise only in combination with the attribute composite.
Note
The attribute route is not a core attribute of the renderer. It is added as a custom attribute by the Routing and is listed here for completeness.
The attribute validate requires the attribute events. Together they define
and control synchronization between the markup of a composite and the
corresponding JavaScript object. A property with the same name must exist as the
synchronization target.
Validation works in two steps and starts with standard HTML5 validation. If this
does not detect deviations from the expected result or no HTML5 validation is
specified, the JavaScript object validation is used. This requires a
corresponding validate method boolean validate(element, value) and an element
embedded in a composite.
Validation directly affects synchronization and the browser default action. It
can use four return states: true, not true, text, undefined/void.
Validation was successful. No error is shown and the browser default action is used. If possible, the value is synchronized.
The validation failed and an error is shown. The return value indicates that the default behavior (action) should not be executed by the browser and is thus blocked. With the strict default behaviour of Seanox aspect-js, the invalid value is not synchronized with the model.
The validation has failed with an error message. If the error message is empty, the message from the message attribute is used as an alternative. With the strict default behaviour of Seanox aspect-js, the invalid value is not synchronized with the model.
Validation failed and an error is shown. Without a return value, the default behavior (action) is executed by the browser. This behavior is important for validating input fields, for example, so that the input reaches the user interface. With the strict default behaviour of Seanox aspect-js, the invalid value is not synchronized with the model.
Validation works strictly by default. This means that the validation must
explicitly be true and only then is the input data of the HTML elements
synchronized with the model. This protects against invalid data in the models
which may then be reflected in the view. If attribute validate is declared as
optional, this behaviour can be specifically deactivated and the input data is
then always synchronized with the model. The effects of validation are then only
optional.
<form id="model" composite>
<input id="text1" type="text" placeholder="e-mail address"
validate="optional" events="input change" render="#model"/>
model.text1: {{model.text1}}
<input type="submit" value="submit" validate events="click"/>
</form>
By default, validation message are shown as a native browser toolbox for the
input element. The corresponding message is set via the attribute of the same
name. If custom validation and output need to be implemented, this behavior can
be changed by redirecting the message to an attribute of the input element. For
this purpose, the message, which at this point also includes the return value of
expressions, must begin as follows: @<attribute>:.
A general strategy or standard implementation for error output is deliberately not provided, as this is too strict in most cases and can be implemented individually as a central solution.
input[type='text']:not([fault]) {
background:#EEEEFF;
border-color:#7777AA;
}
input[type='text'][fault=''] {
background:#EEFFEE;
border-color:#77AA77;
}
input[type='text'][fault]:not([fault='']) {
background:#FFEEEE;
border-color:#AA7777;
}
const model = {
validate(element, value) {
const PATTERN_EMAIL_SIMPLE = /^\w+([\w\.\-]*\w)*@\w+([\w\.\-]*\w{2,})$/;
const test = PATTERN_EMAIL_SIMPLE.test(value);
return test || ("Invalid " + element.getAttribute("placeholder"));
},
text1: ""
};
<form id="model" composite>
<input id="text1" type="text" placeholder="e-mail address"
validate message="@fault:Wrong e-mail address"
events="input change" render="#model"/>
model.text1: {{model.text1}}
<input type="submit" value="submit" validate events="click"/>
</form>
In this example, the input field expects an e-mail address. The value is checked
continuously during the input and in case of an invalid value an error message
is written into the attribute fault, or in case of a valid value the content
is deleted from the attribute fault. Below the input field is the control
output of the corresponding field in the JavaScript object (model). This field
is only synchronized if the validate method return the value true.
Expressions are resolved only after the page is loaded by the renderer. For some HTML elements, this can be annoying if the attributes are already interpreted by the browser. For example, the src attribute for resources such as the img tag. For these cases @-attributes can be used. These work like templates for attributes. The renderer will resolve their value and then add the attributes of the same name to the element. After that, they behave like all other attributes, including being updated by the renderer if the attributes contain expressions.
<img @src="{{...}}"/>
The expression language can be used in the markup as free text and in the
attributes of the HTML elements. JavaScript and CSS elements are excluded. The
expression language is not supported here. When used as free text, pure text
(plain text) is always generated as output. The addition of markup, especially
HTML code, is not possible and is only supported with the attributes output
and import.
<article title="{{model.title}}">
{{'Hello World!'}}
...
</article>
Details about syntax and usage are described in chapter Expression Language.
Embedded scripting has specific runtime behavior. Standard scripts are executed
automatically by the browser and independently of rendering. Markup for
rendering therefore supports the additional script type composite/javascript.
It uses normal JavaScript, but the browser does not recognize it as
text/javascript and does not execute it directly. The renderer recognizes the
JavaScript code and executes it in every relevant render cycle. This allows
SCRIPT execution to be combined with the condition attribute.
<script type="composite/javascript">
...
</script>
Details about using composite JavaScript including modules are described in chapter Scripting.
Custom HTML elements (tags) take over the complete rendering on their own
responsibility. The return value determines whether the standard functions of
the renderer are used or not. Only the return value false (not void, not
empty) terminates the rendering for a custom HTML elements without using the
standard functions of the renderer.
Composite.customize("foo", function(element) {
...
});
<article>
<foo/>
</article>
Selectors work similarly to custom tags. Unlike custom tags, selectors use a CSS selector to recognize elements. This selector must address the element from the parent element. Different selectors with different functions can affect one element.
Selectors are iterated in order of registration and then their callback methods
are executed. The return value of the callback method determines whether the
iteration is terminated or not. Only the return value false (not void, not
empty) terminates the iteration over other selectors and the rendering for the
selector is terminated without using the standard functions.
Composite.customize("a:not([href])", function(element) {
...
});
Composite.customize("a.foo", function(element) {
...
});
<article>
<a class="foo"></a>
</article>
Interceptors customize rendering by manipulating elements before rendering. They can change attributes and/or markup before the renderer processes them. An interceptor has no effect on the rendering implementation.
Composite.customize(function(element) {
...
});
Seanox aspect-js provides markup protection that makes runtime manipulation of the markup more difficult. On the one hand, hidden markup with a condition is physically removed from the DOM and on the other hand, the renderer observes manipulations of attributes at runtime. This observation is based on a filter with static attributes. Static attributes are read when an element is created in the DOM and restored when manipulated (deleted/changed).
To configure static attributes, use the method Composite.customize(...) and
using the parameter @ATTRIBUTES-STATICS. The configuration can be done several
times. The individual static attributes are then merged. All @ parameters are
case insensitive.
Composite.customize("@ATTRIBUTES-STATICS", "action name src type");
Composite.customize("@Attributes-Statics", "required");
Composite.customize("@attributes-statics", "method action");
...
<form method="POST" action="/service">
<input type="user" name="user"
<input type="password" name="password"/>
<input type="submit"/>
</form>