# Expression Language (EL)

## Introduction

Web Flow uses EL to access its data model and invoke actions. This chapter will familiarize you with the EL syntax, and special EL variables you can reference from your flow definition.

## Supported EL implementations

### Unified EL

Web Flow attempts to use the Unified EL by default. `jboss-el` is currently the default EL implementation. When found in your classpath along with the `el-api`, it will be used automatically. You can find the JBoss EL jar in the SpringSource Bundle Repository.

The `el-api` dependency is typically provided by your web container. Tomcat 6 includes it, for example.

### OGNL

OGNL is the other EL supported by Web Flow 2. OGNL is the EL most familiar to Web Flow version 1.0 users. To use ognl, simply include `ognl` in your classpath instead of `jboss-el`. Please refer to the OGNL language guide for specifics on its EL syntax.

## EL portability

In general, you will find the Unified EL and OGNL have a very similar syntax. For basic variable resolution, property access, and method invocation the syntax is identical. We recommend adhering to Unified EL syntax whenever possible, and only relying on proprietary EL features when needed.

## EL usage

EL is used for many things within a flow, including:

1. Accessing data provided by the client, such as flow input attributes and request parameters.

2. Accessing internal data structures such as `flowScope.`

3. Invoking methods on Spring beans.

4. Resolving constructs such as state transition criteria, subflow ids, and view names.

Views rendered by flows typically access flow data structures using EL as well.

### Expression types

There are basically two types of expressions in Web Flow.

#### Standard eval expressions

The first, and most common, type of expression, is the standard eval expression. Such expressions are dynamically evaluated by the EL and should not be enclosed in delimiters like `${}` or `#{}`. For example:

    <evaluate expression="searchCriteria.nextPage()" />

The expression above is a standard expression that invokes the `nextPage` method on the `searchCriteria` variable when evaluated. Attempting to enclose this expression in special eval delimiters like `${}` or `#{}` will result in an `IllegalArgumentException`.

We view use of special eval delimiters as redundant in this context, as the only acceptable value for the `expression` attribute is a single eval expression string.

#### Template expressions

The second type of expression is a "template" expression. Such expressions allow a mixing of literal text with one or more eval blocks. Each eval block is explictly delimited with the `${}` delimiters. For example:

    <view-state id="error" view="error-${externalContext.locale}.xhtml" />

The expression above is a template expression. The result of evaluation will be a string that concatenates the literal text `error-` with the result of evaluating `externalContext.locale`. As you can see, explicit delimiters are necessary here to demarcate eval blocks within the template.

See the Web Flow XML schema for a complete listing of the XML attributes that accept standard expressions and template expressions.

## Special EL variables

There are several implicit variables you may reference from within a flow. These variables are discussed in this section.

### flowScope

Use `flowScope` to assign a flow variable. Flow scope gets allocated when a flow starts and destroyed when the flow ends. With the default implementation, any objects stored in flow scope need to be Serializable.

    <evaluate expression="searchService.findHotel(hotelId)" result="flowScope.hotel" />

### viewScope

Use `viewScope` to assign a view variable. View scope gets allocated when a `view-state` enters and destroyed when the state exits. View scope is only referenceable from within a `view-state`. With the default implementation, any objects stored in view scope need to be Serializable.

    <on-render>
        <evaluate expression="searchService.findHotels(searchCriteria)" result="viewScope.hotels"
                  result-type="dataModel" />
    </on-render>

### requestScope

Use `requestScope` to assign a request variable. Request scope gets allocated when a flow is called and destroyed when the flow returns.

    <set name="requestScope.hotelId" value="requestParameters.id" type="long" />

### flashScope

Use `flashScope` to assign a flash variable. Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends. With the default implementation, any objects stored in flash scope need to be Serializable.

    <set name="flashScope.statusMessage" value="'Booking confirmed'" />

### conversationScope

Use `conversationScope` to assign a conversation variable. Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends. Conversation scope is shared by a top-level flow and all of its subflows. With the default implementation, conversation scoped objects are stored in the HTTP session and should generally be Serializable to account for typical session replication.

    <evaluate expression="searchService.findHotel(hotelId)" result="conversationScope.hotel" />

### requestParameters

Use `requestParameters` to access a client request parameter:

    <set name="requestScope.hotelId" value="requestParameters.id" type="long" />

### currentEvent

Use `currentEvent` to access attributes of the current `Event`:

    <evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />

### currentUser

Use `currentUser` to access the authenticated `Principal`:

    <evaluate expression="bookingService.createBooking(hotelId, currentUser.name)"
              result="flowScope.booking" />

### messageContext

Use `messageContext` to access a context for retrieving and creating flow execution messages, including error and success messages. See the `MessageContext` Javadocs for more information.

    <evaluate expression="bookingValidator.validate(booking, messageContext)" />

### resourceBundle

Use `resourceBundle` to access a message resource.

    <set name="flashScope.successMessage" value="resourceBundle.successMessage" />

### flowRequestContext

Use `flowRequestContext` to access the `RequestContext` API, which is a representation of the current flow request. See the API Javadocs for more information.

### flowExecutionContext

Use `flowExecutionContext` to access the `FlowExecutionContext` API, which is a representation of the current flow state. See the API Javadocs for more information.

### flowExecutionUrl

Use `flowExecutionUrl` to access the context-relative URI for the current flow execution view-state.

### externalContext

Use `externalContext` to access the client environment, including user session attributes. See the `ExternalContext` API JavaDocs for more information.

    <evaluate expression="searchService.suggestHotels(externalContext.sessionMap.userProfile)"
              result="viewScope.hotels" />

## Scope searching algorithm

When assigning a variable in one of the flow scopes, referencing that scope is required. For example:

    <set name="requestScope.hotelId" value="requestParameters.id" type="long" />

When simply accessing a variable in one of the scopes, referencing the scope is optional. For example:

    <evaluate expression="entityManager.persist(booking)" />

If no scope is specified, like in the use of `booking` above, a scope searching algorithm will be employed. The algorithm will look in request, flash, view, flow, and conversation scope for the variable. If no such variable is found, an `EvaluationException` will be thrown.