D
Edge Side Includes Language

This appendix describes the Edge Side Includes (ESI) tag library provided for content assembly of dynamic fragments.

This appendix contains these topics:

Overview of ESI Tag Library

ESI is an open specification co-authored by Oracle Corporation, the purpose being to develop a uniform programming model to assemble dynamic pages on the edge of the Internet.

ESI is an XML-based markup language that enables dynamic content assembly of fragments by Oracle9iAS Web Cache. A template page is configured with ESI markup tags that fetch and include dynamic HTML fragments. The fragments themselves can also contain ESI markup. You can assign cacheability rules to the template page and HTML fragments. By enabling Oracle9iAS Web Cache to assemble dynamic pages rather than the application Web server, you can increase the overall cacheable content.

See Also:

"Configuring Pages for Content Assembly and Partial Page Caching"
"Configuring Caching Attributes in Response Headers"
http://www.edge-delivery.org for the ESI language release 1.0 specification

The following topics provide an overview of ESI usage:

ESI Language Elements Supported

ESI supports the language elements listed in Table D-1.

Table D-1 Language Elements Supported in ESI Release

ESI Language Element	See Also
`<esi:include>` tag	"ESI include Tag"
`src` attribute	"ESI include Tag"
`onerror` attribute	"ESI include Tag"
`<esi:inline>` tag	"ESI inline Tag"
`<esi:choose>` \| `<esi:when>` \| `<esi:otherwise>` tags	"ESI choose \| when \| otherwise Tags"
`<esi:try>` \| `<esi:attempt>` \| `<esi:accept>` tags	"ESI try \| attempt \| except Tags"
`<esi:comment>` tag	"ESI comment Tag"
`<esi:remove>` tag	"ESI remove Tag"
`<esi:vars>` tag	"ESI vars Tag"
`<!--esi...--->` tag	"ESI <!--esi--->Tag"

In addition to the ESI elements, Oracle supplies the proprietary language elements listed in Table D-2.

Table D-2 Oracle Language Elements

Oracle Language Elements	See Also
`<esi:environment>` tag	"ESI environment Tag"
`<esi:include>` tag	"ESI include Tag"
`name` attribute	"ESI include Tag"
`max-age` attribute	"ESI include Tag"
`timeout` attribute	"ESI include Tag"
`<esi:request_header>` element	"ESI include Tag"
`<esi:request_body>` element	"ESI include Tag"

Syntax Rules

ESI elements and attributes adhere to XML syntax but can be embedded in other documents such as HTML or XML documents. When Oracle9iAS Web Cache processes the page, the ESI elements themselves are stripped from the output.

ESI syntax generally adheres to XML syntax rules. Keep the following in mind when using the tags:

ESI tags and attributes are case sensitive.

They are generally lowercase.
Supported CGI environment variables are case sensitive.

They are generally uppercase.
ESI does not support the use of whitespace next to the equal sign (=) or between the "<" and "esi:"

The following shows an invalid construction:
```
<esi:include src = "www.foo.com"/>
```
The following shows the correct form:
```
<esi:include src="www.foo.com"/>
```

Nesting Elements

As shown in Figure D-1, an ESI tag can contain nested ESI elements and other HTML markup.

Figure D-1 Nested ESI Elements

<esi:choose>
  <esi:when test="$(HTTP_HOST) == 'www.company.com'">
    <esi:include src="/company.html" />
    <h4>Another</h4>
    <esi:include src="/another.html" />
  </esi:when>
  <esi:when test="$(HTTP_COOKIE{fragment) == 'First Fragment'">
    <esi:try>
      <esi:attempt>
        <esi:include src="/fragment1.html" />
      </esi:attempt>
      <esi:except>
        <esi:choose>
          <esi:when test="$(HTTP_COOKIE{otherchoice}) == 'image'" >
            <img src="/img/TheImage.gif">
          </esi:when>
          <esi:otherwise>
            The fragment is unavailable.
         </esi:otherwise>
        </esi:choose>
      </esi:except>
    </esi:try>
  </esi:when>
  <esi:otherwise>
   The default selection.
  </esi:otherwise>
</esi:choose>

Variable Expressions

Table D-3 lists the variables that are supported by ESI. Except for QUERY_STRING, the values for the variables are taken from HTTP request-header fields. In the case of QUERY_STRING, the value is taken from either the HTTP request body or the URL. Variables are only interpreted when enclosed within ESI tags.

Table D-3 ESI-Supported Variables

Variable Name	HTTP Header Field	Substructure Type/Variable Type	Description	Example
`$(HTTP_ACCEPT_LANGUAGE{``language``})`	`Accept-Language` request-header field Specifies the set of languages that are preferred as a response. The language is used as the key.	List/Boolean	Specifies the language to use as the key and evaluates to to the language specified in the HTTP request header	Variable Setting: `$(HTTP_LANGUAGE{en-gb})` HTTP Request Header Contains: `Accept_Language:en-gb` Result: Evaluates to `en-gb`.
`$(HTTP_COOKIE{``cookie``})`	`Set-Cookie` response-header field or `Cookie` request-header field Specifies cookie name and value pairs.A cookie name is used as the key. If the `Cookie` request-header and `Set-Cookie` response-header have different values for the same cookie name, then the name value pair from the `Set-Cookie` response header is used.	Dictionary/ String	Specifies the cookie name to use as the key and returns that cookie's value	Variable Setting: `$(HTTP_COOKIE{visits})` HTTP Request Header Contains: `Cookie:visits=42` Result: Returns a value of `42`.
`$HTTP_HEADER{``header``})`	Any HTTP request header	Dictionary/ String	Specifies an HTTP request header name to use as the key and returns that header's value	Variable Setting: `$(HTTP_HEADER{Referer})` HTTP Request Header Contains: `Referer: http://www.company.com:80` Result: Returns a value of `http://www.company.com:80`
`$HTTP_HOST`	`Host` request-header field Specifies the host name and port number of the resource. Port 80 is the default port number.	Not Applicable/ String	Returns the value of the `HOST` header	Variable Setting: `$(HTTP_HOST)` HTTP Request Header Contains: `Host:http://www.company.com:80` Result: Returns a value of `http://www.company.com:80`
`$HTTP_REFERER`	`Referer` request-header field Specifies the URL of the reference resource	Not Applicable/ String	Returns the value of the `REFERER` header	Variable Setting: `$(HTTP_REFERER)` HTTP Request Header Contains: `Referer:http://www.company.com:80` Result: Returns `http://www.company.com:80`
`$(HTTP_USER_AGENT{browser})` `$HTTP_USER_AGENT{version})` `$HTTP_USER_AGENT{os})`	`User-Agent` request-header field Specifies the Web browser type, browser version, or operating system that initiated the request.	Dictionary/ String	Specifies one of three keys: `browser` for browser type, `version` for browser version, and `os` for operating system	Variable Setting: `$(HTTP_USER_AGENT{browser})` HTTP Request Header Contains: `User-Agent:Mozilla/4.0 (compatible, MSIE 5.5, Windows NT 4.0)` Result: Returns `Mozilla` `$(HTTP_USER_AGENT{version})` Returns `4.0`. `$(HTTP_USER_AGENT{os})` Returns `Windows NT 4.0`.
`$(QUERY_STRING{``parameter``})`	Not Applicable	Dictionary/ String	Given a parameter name in a query string, returns the value of the parameter without URL encoding. The query string can be in an URL or a request body. See Also: `http://rfc.net/rfc1738.html` for further information about URL encoding.	Variable Setting: `$(QUERY_STRING{CEO})` Result: Returns the value of `fullname` decoded. In this example, `CEO` returns a value of `Jane Doe.`
`$(QUERY_STRING`)	Not Applicable	Not Applicable/ String	Specifies to return the entire query string encoded	Variable Setting: `$(QUERY_STRING)` Result: Returns the entire query string encoded: `CEO=Jane%20Doe&CFO=John%20Doe`
`$(QUERY_STRING_ENCODED{``parameter``})`	Not Applicable	Dictionary/ String	Given a parameter name in a query string, returns the value of the parameter with URL encoding. The query string can be in an URL or a request body.	Variable Setting: `$(QUERY_STRING{CEO})` Result: Returns the value of `fullname` encoded: `Jane%20Doe`
`$(QUERY_STRING_ENCODED)`	Not Applicable	Not Applicable/ String	The same as `$(QUERY_STRING`)	Variable Setting: `$(QUERY_STRING_ENCODED)` Result: Returns the entire query string encoded: `CEO=Jane%20Doe&CFO=John%20Doe`
`$(QUERY_STRING_DECODED{``parameter``})`	Not Applicable	Dictionary/ String	The same as `$(QUERY_STRING{parameter}`)	Variable Setting: `$(QUERY_STRING_DECODED{CEO})` Result: Returns the value of `fullname` decoded. In this example, `CEO` returns a value of `Jane Doe.`

See Also:

"ESI environment Tag" for instructions on including custom variables

Usage

Variable names must be in uppercase.

To reference a variable, surround the variable name with parenthesis and append a dollar sign:

$(VARIABLE_NAME)

For example:

$(HTTP_HOST)

Variable Substructure Access

Variables with a substructure type of List or Dictionary in Table D-3 are accessed by a key as follows:

$(VARIABLE_NAME{key})

To access a variable's substructure, append the variable name with braces containing the key which is being accessed. For example:

$(HTTP_COOKIE{username})

The key is case sensitive and optional. If a key is not specified, then the environment variable returns the whole content of the environment fragment. Oracle Corporation advises specifying an environment variable without a key only for testing whether the environment is empty. In the following ESI markup, $(logindata) is a variable that is evaluated against a null value.

<esi:choose>
  <esi:when test="$(logindata) != null">
    <esi:include src=/login/$(logindata)"/>
 </esi:when>
 <esi:otherwise>
   <esi:include src=/login/guest.html"/>
 <esi:otherwise>
</esi:choose>

Variables identified with a substructure type of Dictionary in Table D-3 make access to strings available through their appropriate keys. Dictionary keys are case sensitive.

Variables identified with a substructure type of List in Table D-3 return a boolean value depending on whether the requested value is present.

Variable Default Values

Variables with empty values or nonexistent values, or variables with undefined keys evaluate to an empty string when they are accessed. You can use the logical or (|) operator to specify a default value in the following form:

$(VARIABLE|default)

The following example results in Oracle9iAS Web Cache fetching http://example.com/default.html if the cookie id is not in the request:

<esi:include src="http://example.com/$(HTTP_COOKIE{id}|default).html"/>

As with other literals, if whitespace needs to be specified, then the default value must be single-quoted. For example:

$(HTTP_COOKIE{first_name}|'new user')

Note:

HTTP_HOST and HTTP_REFERER do not support default values in this release.

Exceptions and Errors

ESI uses two mechanisms for exception and error handling. In a given situation, you can make use of both mechanisms simultaneously, use one at a time, or use neither, depending on the business logic you are developing. The mechanisms are described in the following topics:

Apology Page

The first mechanism is to use an apology page in place of an included fragment.

To configure an apology page:

Create an apology page in $ORACLE_HOME/webcache/docs on UNIX and ORACLE_HOME\webcache\docs on Windows.
Specify the file name of the apology page in the Apology Page (General Configuration > Apology Pages) of Oracle9iAS Web Cache Manager.

See Also:
Step 4 in"Task 10: Configure Web Site Settings"

ESI Language Control

The second mechanism is found in the ESI language, which provides two specific elements for fine-grain control over content assembly in error scenarios:

The onerror attribute of the <esi:include> tag
The try |attempt |except block

The onerror attribute is used before the try |attempt |except block. If the try |attempt |except block does not exist, then the exception handling is propagated to the parent or template page. The parent page will use the apology page, onerror attribute, or try |attempt |except block to handle the error. The template page will return an internal error.

See Also:

Enabling ESI

To enable Oracle9iAS Web Cache to process ESI tags, an HTTP Surrogate-Control header is set in the HTTP response message of the pages that use ESI tags.

ESI Tag Descriptions

This section describes the following ESI tags, which are used for partial page caching operations:

ESI include Tag

The <esi:include> tag provides syntax for including fragments.

See Also:

"Fragmentation with the Inline and Include Tags" for a comparison of <esi:inline> and <esi:include> usage

Syntax

In this form, <esi:include> does not have a closing </esi:include>:

<esi:include src="URL_fragment"
[max-age="expiration_time [+ removal_time]]" [method="GET|POST"] 
[onerror="continue"] [timeout="fetch_time"]/>

In this form with elements, <esi:include> has a closing </esi:include>:

<esi:include src="URL_fragment" 

[max-age="expiration_time [+ removal_time]"] [method="GET|POST"] 
[onerror="continue"] [timeout="fetch_time"]>
  [<esi:request_header name="request_header" name="request_header" 
value="value"/>]
  [<esi:request_body value="value"/>]
</esi:include>

Attributes

src--Specifies the fragment to fetch. The fragment can be a file referenced by a URL or it can include variables. You can specify an XML fragment as long as the XML file fragment includes the following code at the beginning of the file:
```
<?xml version="1.0"?>
<?xml-stylesheet type="text/xml" href="stylesheet.css"?>
```
Oracle9iAS Web Cache uses XSL Transformations (XSLT) to transform the XML into HTML using a stylesheet. The stylesheet maps XML formats to HTML formats.

See Also:
http://www.xslt.com/ for complete information about XSLT
max-age--Specifies the time, in seconds, to expire the fragment, and optionally, specifies the time, in seconds, to remove the fragment after the expiration time. Use this attribute if the template page has a higher tolerance for stale fragments than specified by the time-to-live parameters in fragment responses.
method--Specifies the HTTP request method of the document(s). Valid values are GET or POST.
onerror--Specifies that if the fetch failed on the src object to ignore the ESI tag and serve the page

timeout--Specifies the time, in seconds, for the fragment to be fetched. If the fragment has not been fetched within the time interval, then the fetch is aborted.

Note:

The ESI language release 1.0 specification provides support for an alt attribute, which specifies an alternative resource if the src is not found. Because Oracle9iAS Web Cache is near the application Web server, the alt tag cannot be processed in a useful manner. Therefore, Oracle9iAS Web Cache ignores the alt attribute.

Elements

request_body--Specifies the HTTP request body of the fragment
request_header--Specifies an HTTP request header field and value for Oracle9iAS Web Cache to use. You can specify multiple HTTP request headers. When this attribute is specified, all request headers from the parent fragment or template page are ignored.

Syntax Usage

<esi:include> supports up to three levels of nesting
<esi:include> does not support escaped double quotes (\"). For example, the following is not supported:
```
<esi:include src="file\"user.htm"/>
```
The attributes do not need to be in a particular order
The src support both HTTP and HTTPS. Oracle9iAS Web Cache permits the template and fragments to use different protocols. Take note of the following:
- If the src attribute specifies a fragment's relative path, such as src="/PersonalizedGreeting", then the template's protocol is used.
- If the protocol used in the src attribute does not match the protocol specified in the Site to Server Mapping page (General Configuration > Site to Server Mapping) of Oracle9iAS Web Cache Manager, then Oracle9iAS Web Cache uses the protocol configured for the origin server in the Site to Server Mapping page. Oracle9iAS Web Cache also reports the following warning message to the event log:
```
Date Warning: ESI Include protocol does not match Origin Server 
protocol: Origin Server Protocol=protocol URL=URL
```
  For example, if the template page is configured with <esi:include> src="https://www.company.com/gifs/frag1.gif"/> and the Site to Server mapping specifies HTTP for the origin server, then http://www.company.com/gifs/frag1.gif is used and the following message appears in the event log:
```
11/Jan/2002:19:25:59 +0000 Warning: ESI Include protocol does not match 
Origin Server protocol: Origin Server Protocol=http 
URL=https://www.company.com/gifs/frag1.gif
```
Do not specify more than one request_body element

You can have zero or more request_body elements

Use multiple request_header elements to specify multiple HTTP request header fields:

<esi:include src="URL_fragment" 

max-age="expiration_time [+ removal_time]"[method="GET|POST"]

onerror="continue" timeout="fetch_time">
  <esi:request_header name="request_header" value="value"/>
  <esi:request_header name="request_header" value="value"/>
</esi:include>

Usage

The <esi:include> tag instructs Oracle9iAS Web Cache to fetch the fragment specified by the src attribute. The attribute value must be a valid URL. Relative URLs will be resolved relative to the template page. The resulting object will replace the element in the markup served to the browser. The included fragment must reside on the same site. Therefore, it is not necessary to specify the host name in the URL.

If the include is successful, then the contents of the fetched src URL display. The included object is included exactly at the point of the include tag. For example, if the include tag is in a table cell, the fetched object is displayed in the table cell.

If Oracle9iAS Web Cache cannot fetch the src, then Oracle9iAS Web Cache tries to return an apology page error. If Oracle9iAS Web Cache cannot use the apology page and onerror="continue" is specified, then Oracle9iAS Web Cache ignores the <esi:include> tag. If onerror="continue" is not specified, then Oracle9iAS Web Cache looks for the try |attempt |except block. If the try |attempt |except block does not exist, then the exception handling is propagated to the parent or template page. The parent page will use the apology page, onerror attribute, or try |attempt |except block to handle the error. The template page will return an internal error.

If both the max-age control directive is set in the Surrogate-Control response-header field and the max-age attribute are set, then Oracle9iAS Web Cache uses the longest maximum age of the two. Oracle Corporation recommends setting the max-age attribute to a longer time than the max-age control directive. Use the max-age attribute to increase cache hits by serving fragments stale until the removal time. max-age=infinity specifies that the document never expires.

If method is not set, then GET is assumed. However, if the request_body element is set, then POST is assumed.

Oracle9iAS Web Cache generates the following HTTP request headers for all fragment requests:

Host:host:port
Content-Length:size (for HTTP POST body documents)
Surrogate-Capability:orcl="ORAESI/9.0.2 ESI/1.0"
Connection:Keep-Alive|Close

The request_header element enables you to control HTTP header other than these. Do not specify these HTTP request headers as request_header attributes, as a conflict can affect the operation of Oracle9iAS Web Cache.

If no request_header elements are specified, then Oracle9iAS Web Cache uses other request headers from the parent fragment or template page.

See Also:

"Fragmentation with the Inline and Include Tags" for a comparison of <esi:inline> and <esi:include> usage

Examples

The following ESI markup includes a file named frag1.htm. The fragment must be fetched within 60 seconds. If the fetch fails, then Oracle9iAS Web Cache ignores the includes and serves the page. If the fetch succeeds, then Oracle9iAS Web Cache includes the fragment. Oracle9iAS Web Cache expires the fragment after five minutes, and removes it after another eight minutes.

<esi:include src="/frag1.htm" timeout="60" maxage="300+480" onerror="continue"/>

The following ESI output includes the result of a dynamic query:

<esi:include src="/search?query=$QUERY_STRING(query)"/>

The following ESI output includes a personalized greeting, a Cookie HTTP request 
header, and a HTTP request body that includes the date:

<esi:include src="/PersonalGreeting" 
  <esi:request_header name="Cookie" value="pname=Scott Tiger"/>
  <esi:request_body value="day=05, month=10, year=2001"/>
</esi:include>

See Also:

"Example Portal Site Implementation" for an extended example of <esi:include> usage

ESI inline Tag

The <esi:inline> tag marks a fragment as a separately cacheable fragment, embedded in the HTTP response of another object. Oracle9iAS Web Cache stores and assembles these fragments independently as <esi:include> fragments.

See Also:

"Fragmentation with the Inline and Include Tags" for a comparison of <esi:inline> and <esi:include> usage

Syntax

<esi:inline name="URL" fetchable="yes|no" 

[max-age="expiration_time [+ removal_time]"] [timeout="fetch_time"]
Embedded HTML code
</esi:inline>

Attributes

name--Specifies a unique name for the fragment in URL format
fetchable--yes specifies that the URL can be used to independently fetch the fragment. no specifies that the fragment can only be generated as a response for another object.
max-age--Specifies the time, in seconds, to expire the fragment, and optionally, specifies the time, in seconds, to remove the fragment after the expiration time. Use this attribute if the template page has a higher tolerance for stale fragments than specified by the time-to-live parameters in fragment responses.
timeout--Specifies the time, in seconds, for the fragment to be fetched. If the fragment has not been fetched within the time interval, the fetch is aborted.

Usage

Some inline fragments are only delivered as part of an HTTP response for another object. These are not independently fetchable by Oracle9iAS Web Cache the way <esi:include> fragments are. When a non-fetchable fragment is needed by Oracle9iAS Web Cache, Oracle9iAS Web Cache must request the object from which the inline fragment was extracted.

When a non-fetchable <esi:inline> fragment is not found in the cache, Oracle9iAS Web Cache re-fetches the fragment's parent template. This behavior implies that the parent cannot be another non-fetchable <esi:inline> fragment. If the parent is an <esi:inline> non-fetchable fragment, then the response is returned to the browser is undefined.

See Also:

"Using Inline for Non-Fetchable Fragmentation"
"Using Inline for Fetchable Fragmentation"
"ESI include Tag" for usage notes on the maxage attribute

Example

The following ESI output embeds finance headlines:

<esi:inline name="/Top_News_Finance">
Latest News for finance
<TABLE>
  <TR>
   Blue-Chip Stocks Cut Losses; Nasdaq Up MO
    Stocks Fall at Opening After Plane Crash New York Times
    French rig factory with explosives New York Times
    Volkswagen faces Brazil strike CNN Europe
    Airbuss reliability record BBC
  </TR>
</TABLE>
</esi:inline>

See Also:

"Example Portal Site Implementation" for an extended example of <esi:inline> usage

ESI environment Tag

The <esi:environment> tag enables you to include custom environment variables from included fragments. Once included, these variables can then be used with the other ESI tags.

Syntax

<esi:environment src="environment_URL" name="environment_name" 

[max-age="expiration_time [+ removal_time]]" [method="GET|POST"] 
[onerror="continue"] [timeout="fetch_time"]/>

In this form, <esi:environment> does not have a closing </esi:environment>.


<esi:environment src="environment_URL" name="environment_name" 

[max-age="expiration_time [+ removal_time]"] [method="GET|POST"] 
[onerror="continue"] [timeout="fetch_time"]>
  [<esi:request_header name="request_header" name="request_header" 
value="value"/>]
  [<esi:request_body value="value"/>]
</esi:environment>

In this form with elements, <esi:environment> has a closing </esi:environment>.

Attributes

src--Specifies the URL from which to obtain environment variables and their values. The URL requires the following XML format:

<?xml version="1.0"?>
<esi-environment esiversion="ORAESI/9.0.2">
  <variable_name>variable_value</variable_name>
  <variable_name>variable_value</variable_name>
</esi-environment>

name--Specifies the name to use to refer to the environment variable
method--Specifies the HTTP request method of the documents to be invalidated. Valid values are GET or POST.
max-age--Specifies the time, in seconds, to expire the XML file, and optionally, specifies the time, in seconds, to remove the XML file after the expiration time
timeout--Specifies the time, in seconds, for the fragment to be fetched. If the fragment has not been fetched within the time interval, the fetch is aborted.
onerror--Specifies that if the fetch failed on the src object, to ignore the ESI tag and serve the page

Elements

request_body--Specifies the HTTP request body of the fragment
request_header--Specifies an HTTP request header field and value for Oracle9iAS Web Cache to use

Usage

To use the included custom variables with other ESI tags, specify the ESI environment tag before other tags. The usage of custom variables is the same as the ESI variables.

See Also:

"Variable Expressions" for usage instructions
"ESI include Tag" for a usage notes on maxage, method, onerror, request_body, and request_header

Example

The following ESI output specifies logindata to refer to the environment variables stored in catalog.xml. catalog.xml enables access to the value of the vendorID environment variable, which is used as a parameter in the included URL:

<esi:environment src="/catalog.xml" name="logindata"/>
<esi:include 
src="http://provider.com/intranetprovider?vendorID=$(logindata{vendorID})"/>

catalog.xml has the following content:

<?xml version=1.0?>
<esi-environment esiversion=""ORAESI/9.0.2"">
  <product_description>stereo</product_description>
  <vendorID>3278</vendorID>
  <partner1>E-Electronics</partner1>
  <partner2>E-City</partner2>
</esi-environment>

ESI choose | when | otherwise Tags

The <esi:choose>, <esi:when>, and <esi:otherwise> conditional tags provide the ability to perform logic based on boolean expressions.

Syntax

<esi:choose>
  <esi:when test="BOOLEAN_expression">
    Perform this action
  </esi:when>
  <esi:when test="BOOLEAN_expression">
    Perform this action
  </esi:when>
  <esi:otherwise>
    Perform this other action
  </esi:otherwise>
</esi:choose>

Attributes

test--Specifies the boolean operation

Usage

Each <esi:choose> tag must have a least one <esi:when> tag, and may optionally contain exactly one <esi:otherwise> tag.
Oracle9iAS Web Cache will execute the first <esi:when> tag whose test attribute evaluates truthfully, and then exit the <esi:choose> tag. If no <esi:when> tag evaluates to true and an <esi:otherwise> tag is present, then that element's content will be executed.
Other HTML or ESI element can be included inside <esi:when> or <esi:otherwise> elements

Boolean Expressions

The test attribute uses boolean expressions to determine how to evaluate true or false logic. ESI supports the following boolean operators:

== (equal to)

!= (not equal to)

> (greater than)

< (less than)

>= (greater than or equal to)

<= (less than or equal to)

& (and)

| (or)

! (not)

Note the following about the use of boolean expressions:

Operands associate from left to right

Sub-expressions can be grouped with parentheses in order to explicitly specify association
If both operands are numeric, then the expression is evaluated numerically
If either operand is non-numeric, then both operands are evaluated as strings

For example, 'a'==3 evaluates to 'a'=='3', where 3 is evaluated as a string.
The comparison of two boolean expressions results in an undefined operation
If an operand is empty or undefined, then the expression always evaluates to false
The logical operators (&, !, and|) are used to qualify expressions, but cannot be used to make comparisons
Use single quotes (') for constant strings

For example, the following string is a valid construction:
```
$(HTTP_COOKIE{name})==`typical'
```
Escaped single quotes (\') are not permitted. For example, the following is not supported:
```
$(HTTP_COOKIE{'user\'s name'})==`typical'
```
Arithmetic operations and assignments are not permitted
A null value evaluates whether or not a variable is empty

When a number is compared with null, that number is converted into an equivalent string and compared against an empty string. In the following ESI markup, $(logindata{name}) is a variable that provides access to the value of the name. If name is empty, then the expression evaluates to true; if name is not empty, then the expression evaluates to false.
```
<esi:choose>
  <esi:when test="$(logindata{name}) == null">
    <esi:include src=/login/$(logindata{name})"/>
 </esi:when>
 <esi:otherwise>
   <esi:include src=/login/guest.html"/>
 <esi:otherwise>
</esi:choose>  
```

The following expressions show correct usage of booleans:

!(1==1)
!('a'<='c')
(1==1)|('abc'=='def')
(4!=5)&(4==5)

The following expressions show incorrect usage of booleans:

(1 & 4)
("abc" | "edf")

Statements

Statements must be placed inside a <esi:when> or <esi:otherwise> subtag. Statements outside the subtags cannot be evaluated as conditions. Figure D-2 shows invalid placement of statements.

Figure D-2 Statement Placement

<esi:choose>
  HTML text. This is invalid because any characters other than whitespace 
  are not allowed in this area.
  <esi:when test="$(HTTP_HOST) == 'www.company.com'">
    <esi:include src="/company.html" />
  </esi:when>
     HTML text. This is invalid because any characters other than whitespace 
     are not allowed in this area.
  <esi:when test="$(HTTP_COOKIE{fragment) == 'First Fragment'">
    <img src="/img/TheImage.gif">
  </esi:when>
     HTML text. This is invalid because any characters other than whitespace 
     are not allowed in this area.
   <esi:otherwise>
     The default selection.
  </esi:otherwise>
   HTML text. This is invalid because any characters other than whitespace 
   are not allowed in this area.
</esi:choose>

Example

The following ESI markup includes advanced.html for requests that use the cookie Advanced and basic.html for requests that use the cookie Basic:

<esi:choose>
  <esi:when test="$(HTTP_COOKIE{group})=='Advanced'">
    <esi:include src="http://www.company.com/advanced.html"/>
  </esi:when>
  <esi:when test="$(HTTP_COOKIE{group})=='Basic User'">
    <esi:include src="http://www.company.com/basic.html"/>
  </esi:when>
  <esi:otherwise>
    <esi:include src="http://www.company.com/new_user.html"/>
  </esi:otherwise>
</esi:choose>

ESI try | attempt | except Tags

The <esi:try> tag provides for exception handling. <esi:try> must contain exactly one instance of both an <esi:attempt> and an <esi:except> tag:

Syntax

<esi:try>
  <esi:attempt>
    Try this...
  </esi:attempt>
  <esi:except>
    If the attempt fails, then perform this action...
  </esi:except>
</esi:try>

Usage

Oracle9iAS Web Cache first processes the contents of <esi:attempt>.

A failed <esi:attempt> triggers an error and causes Oracle9iAS Web Cache to process the contents of the <esi:except> tag.

Example

The following ESI markup attempts to fetch an advertisement. If the advertisement cannot be included, Oracle9iAS Web Cache includes a static link instead.

<esi:try>
  <esi:attempt>
    <esi:comment text="Include an ad"/>
    <esi:include src="http://www.company.com/ad1.htm"/>
  </esi:attempt>
  <esi:except>
    <esi:comment text="Just write some HTML instead"/>
    <a href=www.company.com>www.company.com</a>
  </esi:except>
</esi:try>

ESI comment Tag

The <esi:comment> tag enables you to comment ESI instructions, without making the comments available in the processor's output.

Syntax

<esi:comment text="text commentary"/>

<esi:comment> is an empty element, and does not have an end tag.

Usage

The <esi:comment> tag is not evaluated by Oracle9iAS Web Cache. If comments need to be visible in the HTML output, then use standard XML/HTML comment tags.

Example

The following ESI markup provides a comment for an included GIF file:

<esi:comment text="the following animation will have a 24 hour TTL"/>
<esi:include src="http://wwww.company.com/logo.gif" onerror="continue" />

ESI remove Tag

The <esi:remove> tag allows for specification of non-ESI markup output if ESI processing is not enabled with the Surrogate-Control header or there is not an ESI-enabled cache.

Syntax

<esi:remove>...HTML ouput</esi:remove>

Usage

Any HTML or ESI elements can be included within this tag, except other <esi:remove> tags. Note that nested ESI tags are not processed.

Example

The following ESI markup includes http://www.company.com if the <esi:include> content cannot be included.

<esi:include src="http://www.company.com/ad.html"/>
<esi:remove>
  <A HREF="http://www.company.com">www.company.com</A>
</esi:remove>

Normally, when Oracle9iAS Web Cache processes this example block, it fetches the ad.html file and includes it into the template page while silently discarding the <esi:remove> tag and its contents. If ESI processing is not enabled, all of the elements are passed through to browser, which ignores ESI markup. However, the browser displays the <A HREF=...> HTML link.

ESI Tag

The  tag enables HTML marked up with ESI tags to display to the browser without processing the ESI tags. When a page is processed with this tag, Oracle9iAS Web Cache removes the starting  elements, while still processing the contents of the page. When the markup cannot be processed, this tag assures that the ESI markup will not interfere with the final HTML output.

Syntax

<!--esi
 ESI elements
-->

Usage

Any ESI or HTML elements can be included within this tag, except other  tags.

Example

The following ESI markup hides the "Hello, Name" greeting if the ESI markup cannot be processed.

<!--esi  
 <p><esi:vars>Hello, $(HTTP_COOKIE{name})!</esi:vars></p>
-->

If the ESI markup can be processed, then  are removed in the final output. The output displays only <p><esi:vars>Hello, $(HTTP_COOKIE{name})!</esi:vars></p>.

ESI vars Tag

The <esi:vars> tag enables you to use an ESI or custom environment variable outside of an ESI tag.

Syntax

<esi:vars>$(environment_name{variable_name})</esi:vars>

Usage

See Also:

"Variable Expressions" and "ESI inline Tag" for variable usage of ESI and custom variables

Example

The following ESI markup includes the cookie type and its value as part of the included URL:

<esi:vars>
  <IMG SRC="http://www.example.com/$(HTTP_COOKIE{type})/hello.gif"/ >
</esi:vars>

The following ESI output refers to logindata as part of the <A HREF=...> link for the Welcome page. logindata refers to an XML file that contains custom environment variables. The output also includes the user's sessionID and category type cookie values as part of the other <A HREF=...> links.

<esi:vars>
  <A HREF="welcome.jsp?name=$(logindata{name})">
  <A HREF="/shopping.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_
STRING{type})">
  <IMG SRC="/img/shopping.gif">
  </A>
  <A HREF="/news.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_
STRING{type})">
  <IMG SRC="/img/news.gif">
  </A>
  <A HREF="/sports.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_
STRING{type})">
  <IMG SRC="/img/sports.gif">
  </A>
  <A HREF="/fun.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_
STRING{type})">
  <IMG SRC="/img/fun.gif">
  </A>
  <A HREF="/about.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_
STRING{type})">
  <IMG SRC="/img/about.gif">
  </A>
 </esi:vars>

D Edge Side Includes Language

Overview of ESI Tag Library

ESI Language Elements Supported

Table D-1 Language Elements Supported in ESI Release

Table D-2 Oracle Language Elements

Syntax Rules

Nesting Elements

Figure D-1 Nested ESI Elements

Variable Expressions

Table D-3 ESI-Supported Variables

Usage

Variable Substructure Access

Variable Default Values

Exceptions and Errors

Apology Page

ESI Language Control

Enabling ESI

ESI Tag Descriptions

ESI include Tag

Syntax

Attributes

Elements

Syntax Usage

Usage

Examples

ESI inline Tag

Syntax

Attributes

Usage

Example

ESI environment Tag

Syntax

Attributes

Elements

Usage

Example

ESI choose | when | otherwise Tags

Syntax

Attributes

Usage

Boolean Expressions

Statements

Figure D-2 Statement Placement

Example

ESI try | attempt | except Tags

Syntax

Usage

Example

ESI comment Tag

Syntax

Usage

Example

ESI remove Tag

Syntax

Usage

Example

ESI Tag

Syntax

Usage

Example

ESI vars Tag

Syntax

Usage

Example

D
Edge Side Includes Language