◁ [Getting Started](getting-started.md)
     ≡ [Table of Contents](README.md#expression-language)
     [Markup](markup.md) ▷
- - -

# Expression Language
The expression language provides access to client-side JavaScript and to
application modules (modules) in Seanox aspect-js. Expressions support the
JavaScript API and additional keywords for arithmetic and logical operators.

```
{% raw %}{{'Hello World!'}}{% endraw %}
```

The expression language can be used in markup from the HTML element `BODY`.
It can be used as free text and in attributes. The content of the HTML elements
`STYLE` and `SCRIPT` is not supported.

The renderer interprets the expression syntax `{% raw %}{{...}}{% endraw %}`. Inside an expression,
the character sequences `{% raw %}{{` and `}}{% endraw %}` must be escaped as `\{\{` and `\}\}`.

## Contents Overview
- [Elements](#elements)
  - [Text](#text)
  - [Literal](#literal)
  - [Keyword](#keyword)
  - [Value](#value)
  - [Method](#method)
  - [Logic](#logic)
- [Expressions](#expressions)
  - [Value-Expression](#value-expression)
  - [Method-Expression](#method-expression)
  - [Element-Expression](#element-expression)
  - [Variable-Expression](#variable-expression)
  - [Combination](#combination)
  - [(?...) tolerate](#-tolerate)
- [Notes](#notes)

## Elements
An expression is a set of words. The words are classified by their
characteristics.

```
+-------------------------------------------------------------+
|            Words (all elements of an expression)            |
+--------+----------------------------------------------------+
|  Text  |                     Expression                     |
|        +-----------+----------------------------------------+
|        |  Literal  |                 Script                 |
|        |           +-----------+----------------------------+
|        |           |  Keyword  |           Others           |
|        |           |           +---------+----------+-------+
|        |           |           |  Value  |  Method  | Logic |
+--------+-----------+-----------+---------+----------+-------+
```

### Text
Text is not a regular expression element. It occurs in attributes when the
expression language is combined with text.

```html
<p output="Today is {% raw %}{{Calendar.weekday}} and it's {{Clock.time}}{% endraw %}."></p>
```

### Literal
Literals are text embedded in an expression with single, double or backtick
quotation marks. They support the usual control characters and escape
sequences.

```
{% raw %}{{'Hello World!'}}{% endraw %}
{% raw %}{{"Hello World!"}}{% endraw %}
{% raw %}{{`Hello World!`}}{% endraw %}
```

### Keyword
The following standard JavaScript syntax keywords are supported in the
expression language:

```
true
false
null
instanceof
typeof
undefined
new
```

The JavaScript syntax for the expression language has been extended with these
keywords to support valid markup:

| Keyword | Function                  |
|---------|---------------------------|
| `and`   | `&&`                      |
| `div`   | `/`                       |
| `empty` | `!`                       |
| `eeq`   | `===`                     |
| `eq`    | `==`                      |
| `ge`    | `>=`                      |
| `gt`    | `> `                      |
| `le`    | `<=`                      |
| `lt`    | `<`                       |
| `mod`   | `%`                       |  
| `ne`    | `!=`                      |
| `nee`   | `!==`                     |
| `not`   | `!`                       |  
| `or`    | <code>&#124;&#124;</code> |

### Value
Anything that is not a literal or keyword is potentially a Value. A Value
represents an object property or variable. Object properties are accessed
directly or through a corresponding getter. If neither an object property nor a
variable can be determined, a method or other logic is assumed.

### Method
Everything that is not literal, keyword and value is potentially a method. If no
method can be determined, other logic is assumed.

### Logic
Everything that is not literal, keyword, value and method is potentially
executable logic.

## Expressions
Different expression types can be combined.

Expressions output all values except the value `undefined`. The string
`undefined` is interpreted as normal text.

### Value-Expression
Anything that is not a literal and keyword is potentially a Value. Value
represents the value of an object property or a variable. In the case of object
properties, this is referred to directly or, if available, to a corresponding
getter.

```
{% raw %}{{Example.object.field}}{% endraw %}
```

### Method-Expression
Everything that is not literal, keyword and value is potentially a method

```
{% raw %}{{Example.getData()}}{% endraw %}
```

### Element-Expression
If a variable starts with `#` in an expression, this variable refers to an HTML
element with the same ID. If no matching HTML element can be found, the value of
the variable corresponds to `undefined`.

```
{% raw %}{{#ExampleElement.value}}{% endraw %}

<input type="text" id="ExampleElement"/>
```

More complex IDs that do not contain only word characters (`_ a-z A-Z 0-9`) can
be enclosed in square brackets.

```
{% raw %}{{#[ExampleElement:1].value}}{% endraw %}

<input type="text" id="ExampleElement:1"/>
```

### Variable-Expression
The expression language can create and set variables in the page scope at
runtime. The expression must start with the variable name (identifier), which
uses the word characters `_ a-z A-Z 0-9` and is separated from the expression by
a colon.

```
{% raw %}{{foo:1 +2 +3 + 'x hello'}}{% endraw %}
```

Creates or sets the value for variable `foo` in the page scope with `6x hello`.

The expression corresponds to the JavaScript syntax:
    `var foo = 1 +2 +3 + 'x hello';`

> __Important__  
> __Page Scope:__ Variables can only be used in the markup and are isolated from
> the rest of the JavaScript. They are intended for output and data processing
> in HTML markup and are not accessible in general JavaScript code.

### Combination
All types of expressions can be combined.

```
{% raw %}{{foo:not empty Foo.data and not empty Foo.data.items ? String(Foo.data.items[0].fieldA).substring(2) : ''}}{% endraw %}
```

### (?...) tolerate
Expressions are executed like JavaScript and can cause corresponding errors.
Object-based approaches often require checks for specific object levels, which
can make expressions unclear.

For these cases, expressions can use the tolerating syntax `(?...)`. If the
logic inside the brackets causes an error, no error is raised and no output is
written to the browser console. Instead, the brackets represent the value
`false`. Syntax errors are excluded from this tolerating behavior.

```
{% raw %}{{"Expression with an error " + (?object.that.does.not.exist()) + "!"}}{% endraw %}
```

## Notes
Expressions are interpreted by the renderer after the page has loaded. They can
therefore be visible during page loading. Use the attribute
[release](markup.md#release) to prevent this.

```html
<h1 release>{% raw %}{{'Hello World!'}}{% endraw %}</h1>
```

Alternatively, content can be stored in the DataSource in combination with the
attributes [output](markup.md#output) and [import](markup.md#import).

```css
h1:after {
  content:attr(title)
}
```

```html
<h1 title="{% raw %}{{'Hello World!'}}{% endraw %}"/>

<h1 output="{% raw %}{{'Hello World!'}}{% endraw %}"/>
<h1 output="{% raw %}{{'xml://example/content'}}{% endraw %}"/>
<h1 output="xml://example/content"/>
<h1 output="{% raw %}{{Messages['hello']}}{% endraw %}"/>

<h1 import="{% raw %}{{'Hello World!'}}{% endraw %}"/>
<h1 import="{% raw %}{{'xml://example/content'}}{% endraw %}"/>
<h1 import="xml://example/content"/>
<h1 import="{% raw %}{{Messages['hello']}}{% endraw %}"/>
```



- - -
&#9665; [Getting Started](getting-started.md)
&nbsp;&nbsp;&nbsp;&nbsp; &#8801; [Table of Contents](README.md#expression-language)
&nbsp;&nbsp;&nbsp;&nbsp; [Markup](markup.md) &#9655;