D
Edge Side Includes Language

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

This appendix contains these topics:

• Overview of ESI Tag Library

• ESI Tag Descriptions

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 Oracle 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 Oracle 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 Cacheability Attributes in Response Headers" http://www.edge-delivery.org for additional information about the ESI language

The following topics provide an overview of ESI usage:

• Syntax Rules

• Nesting Elements

• Variable Expressions

• Exceptions and Errors

• Syntax Rules

Syntax Rules

ESI elements and attributes adhere to XML syntax but can be embedded in other documents such as HTML or XML documents. When Oracle 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 must be lowercase

• Supported CGI environment variables require 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-1 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 POST body or the URL. Variables are only interpreted when enclosed within ESI tags.

Table D-1 ESI-Supported Variables

Variable Name	HTTP Request-Header Field	Substructure Type	Description	Example
HTTP_ACCEPT_LANGUAGE	Accept-Language	List	Specifies in a comma-separated list the set of languages that are preferred as a response	da,en-gb,en
HTTP_COOKIE	Cookie	Dictionary	Specifies in a semi-colon-separated list the cookie name and value pairs	id=571; visits=42
HTTP_HOST	Host	Not Applicable	Specifies the host name and port number of the resource. Port 80 is the default port number.	http://www.company.com
HTTP_REFERER	Referer	Not Applicable	Specifies the URL of the reference resource	http://www.company.com
HTTP_USER_AGENT	User-Agent	Dictionary	Specifies the Web browser type, browser version, or operating system that initiated the request.	Mozilla, MSIE 5.5
QUERY_STRING	Not Applicable	Dictionary	Ampersand-separated list of string and value pairs	first=Jane&last=Doe

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-1 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.

Variables identified with a substructure type of Dictionary in Table D-1 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-1 return a boolean value depending on whether the requested value is present.

Table D-2 lists examples of substructure access, with specific values based on the examples in Table D-1.

Note: HTTP_USER_AGENT can use one of three keys: browser for browser type, version for browser version, and os for operating system.

Table D-2 Dictionary and List Examples

Variable Name and Key	Example Variable Setting	Returned Value
$(HTTP_ACCEPT_LANGUAGE{language})	$(HTTP_LANGUAGE{en-gb})	If the Accept_Language header uses en-gb, then returns a value of true.
$(HTTP_COOKIE{cookie_name})	$(HTTP_COOKIE{visits})	If the Cookie header contains the string visits=42, then returns a value of 42.
$(HTTP_USER_AGENT{browser,version,os})	$(HTTP_USER_AGENT{browser})	Enables Oracle Web Cache to determine the User-Agent's browser. Returns values of Mozilla, MSIE, or Other.
$(HTTP_USER_AGENT{browser,version,os})	$(HTTP_USER_AGENT{version})	Enables Oracle Web Cache to determine the User-Agent's version. Returns the version number of the browser.
$(HTTP_USER_AGENT{browser,version,os})	$(HTTP_USER_AGENT{os})	Enables Oracle Web Cache to determine the User-Agent's operating system. Returns a value of WIN, MAC, UNIX, or Other.
$(QUERY_STRING{string})	$(QUERY_STRING{last})	Returns a value of Doe

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 Oracle 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:

• ESI Language Control

• Apology Page

Apology Page

The first mechanism is to use an apology page.

Set the apology page in the Administering Web Sites > Apology Page of Oracle Web Cache Manager.

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

See Also: "ESI include Tag" "ESI try | attempt | except Tags"

Enabling ESI

To enable Oracle 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

• ESI choose | when | otherwise Tags

• ESI try | attempt | except Tags

• ESI comment Tag

• ESI remove Tag

• ESI <!--esi-->Tag

• ESI vars Tag

ESI include Tag

The <esi:include> tag provides syntax for including fragments. It specifies the object to include and allows for two additional, optional settings.

Syntax

<esi:include src="URL_fragment" onerror="continue"/>

Note that <esi:include> does not have a closing </esi:include>.

Attributes

• src--Specifies the HTML fragment to fetch. The fragment can be a file referenced by a URL or it can include variables.

• onerror--Optional. Specifies that if the fetch failed on the src object, to ignore the ESI tag and serve the page.

  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 Oracle Web Cache is near the application Web server, the alt tag cannot be processed in a useful manner. Therefore, Oracle Web Cache ignores the alt attribute.

Syntax Usage

• <esi:include> supports up to three levels of recursion.

• <esi:include> does not support escaped double quotes (\"). For example, the following is not supported:

  <esi:include src="file\"user.htm"/>
  
  

• src and onerror attributes do not need to be in a particular order

Usage

The <esi:include> tag tells Oracle 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, 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 Oracle Web Cache cannot fetch the src, it returns an HTTP status code greater than 400 with an error message, unless the onerror attribute is present. If onerror="continue" is specified, then Oracle Web Cache ignores the <esi:include> tag.

Examples

The following ESI markup includes a file named frag1.htm:

<esi:include src="/frag1.htm" onerror="continue"/>

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

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

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.

• Oracle 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.

The following expressions show correct usage:

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

The following expressions show incorrect usage:

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

Statements

Statements must be placed inside an <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

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

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

Example

The following ESI markup attempts to fetch an ad. If the ad cannot be included, Oracle 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 Oracle Web Cache. If comments need to be visible in the HTML output, 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 Oracle 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 <!--esi-->Tag

The <!--esi...--> 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, Oracle Web Cache removes the starting<!--esi and ending end --> 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 <!--esi...--> 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 <!--esi and --> 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 environment variable outside of an ESI tag.

Syntax

<esi:vars>ESI Variable</esi:vars>

Usage

See Also: "Variable Expressions"

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 markup includes the user's sessionID and category type cookie values as part of the <A HREF=...> links.

<esi:vars>
  <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>