Applies To:

Show Versions Show Versions

Manual Chapter: Policy Management Guide for the BIG-IP WebAccelerator Module: D - Assembling Content with Edge Side Includes
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>


D

Assembling Content with Edge Side Includes


Using Edge Side Include (ESI)

Edge Side Includes (ESI) is a simple markup language that supports web surrogates, such as the WebAccelerator system, and is used to define web page components for dynamic assembly and delivery of web applications.

For page assembly, the WebAccelerator system uses ESI as an XML-based language to identify page fragments and other resources required during page assembly. The WebAccelerator system can also use ESI response headers to identify cache lifetime or no-cache conditions.

The ESI assembly model consists of a template that contains fragments. The template serves as a container for assembly and includes instructions for fragment retrieval. The template is the resource that is associated with the URL that the end user requests, and it includes language elements that instruct the WebAccelerator system to retrieve and include a specific URI for fragment.

Understanding ESI templates

HTML pages that use ESI markup are considered ESI templates. These templates use the same HTML, JavaScript, and other client-side markups as any traditional web page. However, sections of the final HTML do not appear in the markup produced by the origin servers. Instead, ESI tags are used to identify HTML fragments and other resources that the WebAccelerator system should place into a section of the page. The ESI tags can also identify the conditions under which WebAccelerator system should include the fragment or resource into the page.

When the WebAccelerator system locates ESI tags in an HTML page, it removes the ESI tags and replaces them with the appropriate fragment or resource.

Following is a sample template:

<html>
<head>
<title>A simple ESI Template</title>
</head>
<body>
<h1>A simple ESI Template</h1>
<esi:include src="http://www.somesite.com/fragments/fragment1.html"/>
</body>
</html>

For this example template, fragment1.html equates to the following:
<p>This is a sample fragment</p>

Upon receiving a request for the template, the WebAccelerator system responds with the following page:

<html>
<head>
<title>A simple ESI Template</title>
</head>
<body>
<h1>A simple ESI Template</h1>
<p>This is a sample fragment</p>
</body>
</html>

One of the best reasons to use ESI templates is to identify sections of a page that have different cached lifetime expectancies. Once the WebAccelerator system isolates these page sections into separate, unique chunks, it can manage them using content lifetime and cache invalidation mechanisms.

Note

For more information see esi:inline tags , Chapter 10, and Chapter 11, .

Understanding fragments

Each HTML block in a web page is called a fragment. An origin server can provide fragments individually, or embed fragments in a template using fragment tags. The WebAccelerator system replaces fragment tags with a specified value each time the page is requested. Since fragments can also contain ESI markup, a fragment can use esi:include tags or esi:inline tags to obtain other fragments.

The WebAccelerator system can cache the HTML fragments identified by the esi:include tags in accordance with the WebAccelerator system's caching behavior you specify, using the same content assembly mechanisms that you use for any web page. Because fragments are separate resources, you can assign each their own caching and handling information. For example, a cache time-to-live (TTL) of several days could be appropriate for the template, but a fragment that contains a selection that frequently changes, such as an advertisement, may require a much lower TTL. You can also mark some fragments as un-cacheable, if required.

For any given request, there is a limit to the number of esi:include tags and esi:inline tags that the WebAccelerator system processes. By default, the limit is 50 ESI tags. You should not change this default unless instructed to do so by an F5 Networks Technical Support representative.

Note

Normally, an HTML file is not cached if it does not have opening and closing HTML tags. Because ESI templates are generally valid HTML pages that do not contain matching <HTML></HTML> tags, you should disable matching HTML tags for response caching. See Caching responses, on page A-3 for more information.

Processing an ESI response

When the WebAccelerator system receives an HTTP request that it cannot service from its cache, it sends the request to the origin servers with an ESI Surrogate-Capabilities header in the HTTP request. This request header identifies the WebAccelerator system as being an ESI version 1.0 compliant device and identifies its device token, as follows:

Surrogate-Capabilities: wa="ESI/1.0"

When the origin servers respond to the WebAccelerator system's request, the response must contain an ESI Surrogate-Control response header and this header must identify ESI/1.0, using the content directive as follows:

Surrogate-Control: content="ESI/1.0"

If the WebAccelerator system does not see ESI/1.0 identified in the response header, it does not expect ESI markup included in the response and will ignore any existing ESI markup that appears in the response.

Note

In addition to the content directive, you can also choose to control the cached lifetime of this response by using the max-age or no-store directives. For more information about these directive, see Using ESI Surrogate-Control headers, on page B-4 .

Once the WebAccelerator system identifies the response as using ESI, it processes the ESI markup included in the response. When it locates the esi:include tags, the WebAccelerator system requests the HTML fragments identified by those tags. When the WebAccelerator system has received all of the HTML fragments required to service the response, it assembles the final page and uses it to respond to the original request.

Caching the response and fragments

When the WebAccelerator system has responded to the original HTTP request, it compiles the response that it received from the origin servers. This compiled response includes the HTML fragments and ESI tags, but does not include referred HTML fragments (using ESI tags) that the WebAccelerator system used when assembling the final page.

In addition, the WebAccelerator system compiles each of the HTTP fragments into a compiled response and caches these compiled responses according to the caching rules to which they match. The WebAccelerator system uses any ESI or HTTP Cache-Control response headers, received with each fragment, to determine if the content is cacheable and what the cached lifetime is for the fragment, as described in Understanding lifetime mechanism precedence, on page 10-14 .

Note

To cache a fragment, the WebAccelerator system must consider the fragment complete. For more information, see Caching responses, on page A-3 .

The WebAccelerator system can obtain HTML fragments required by the page from a URL identified in the esi:include tag, or from the esi:inline tag embedded directly in the response. Regardless of the method that the WebAccelerator system uses to obtain the HTML fragments, it caches them separately from the template that referenced them.

Note

The template is the body of the document that was sent in the response. See Understanding ESI templates for more information.

Serving ESI content from cache

When the WebAccelerator system serves content from its cache, it assembles that content using instructions from the cached compiled responses. When ESI is in use, the WebAccelerator system performs the following assembly processes:

Managing cookies

The WebAccelerator system examines cookies presented in a request, as per the ESI specification. However, in the event that the WebAccelerator system needs to send the request to the origin servers for fresh content, and the origin server returns a response that includes Set-Cookie directive(s), the WebAccelerator system processes the original request as if the request presented the Set-Cookie directive(s).

Defining ESI language

The ESI language includes operators, variables, conditional statements, and several pre-defined tags to describe cacheable and non-cacheable content. ESI is a subset of XML and contains valid XML usage; however, ESI is more restrictive than XML and does not include all XML options. These restrictions simplifies both the language and the usage of ESI language.

ESI language is:

  • Case-sensitive
    ESI tags must be all lowercase, and ESI variables must be all uppercase. There are no exceptions.
  • Clear about closing tags
    Some ESI tags require closing tags, others do not. However, there are no situations when a closing tag is optional.

You can use conditional statements and comparison operators to instruct the WebAccelerator system to conditionally include fragments in an assembled page. You can configure the WebAccelerator system to switch these fragments for any given request based on conditions that exist in the requesting URL.

Understanding ESI expressions

Conditional elements use expressions in their test attributes to determine how to apply the contained elements. Expressions consist of operators, variables, and literals that evaluate to true or false. You use single quotes within an expression to delimit literals.

ESI allows complex expressions using Boolean operators. For example, the following expression evaluates to true if value1 is equal to value2 or if value3 is less than value4.

value1 == value2 | value3 < value4

ESI reads operands in an expression from left to right. You can use parentheses to explicitly identify associations within an expression. For example:

(value1 == value2) | (value3 < value4)

You can negate an expression by using the unary not (!) operator. For example:

!((value1 == value2) | (value3 < value4))

Defining ESI language elements

ESI supports the following language elements:

  • <esi:include> tag
  • <esi:inline> tag
  • <esi:choose> | <esi:when> | <esi:otherwise> tags
  • <esi:try> | <esi:attempt> | <esi:accept> tags
  • <esi:comment> tag
  • <esi:remove> tag
  • <esi:vars> tag
  • <!--esi...---> tag

When using ESI, the WebAccelerator system places esi:include or esi:inline tags in the HTML markup for the page to identify the source of HTML fragments. The WebAccelerator system can use these tags for retrieving and incorporating content into the pages that it serves.

Important

By default, the WebAccelerator system's limit is 50 ESI tags for a given client request. See Understanding fragments for more information.

The WebAccelerator system supports the entire ESI language specification, version 1.0 for content assembly activities. You can view the ESI version 1.0 specification at http://www.esi.org/.

esi:include tags

You can use the esi:include tag to identify a fragment that the WebAccelerator system should include in the final assembled page. This tag is an empty element and you must not provide a closing tag for it.

Following is an esi:include tag example:

<esi:include src="uri" [alt="uri"] [onerror="continue"]/>

The esi:include tag accepts arguments shown in Table D.14 .

Table D.14 esi:include tag arguments
Argument
Definition
src
Required argument that identifies the resource the WebAccelerator system is to include into the assembled page. You must provide a valid URI for this argument. If you provide a relative URI, then the WebAccelerator system resolves the URI relative to the requested template.
alt
Optional argument that identifies an alternative resource. This resource is used in the event that the resource identified by the src argument cannot be obtained. You must provide a valid URI for this argument. If you provide a relative URI, then the WebAccelerator system resolves the URI relative to the requested template.
onerror
Optional argument that forces the WebAccelerator system to silently continue processing in the event that it cannot obtain the resource identified by the src and alt arguments. If you do not provide this argument, then failure to obtain the identified resources results in the WebAccelerator system returning a 400-series status code and message. Note that if the esi:include tag is placed in an esi:try block (see the next section), then the esi:try block prevents the WebAccelerator system from returning the 400-series status codes to the client.

Following is an esi:include tag example with arguments:

<esi:include src="http://www.somesite.com/includes/frag1.html" />
<esi:include src="frag1.html" alt="http://web2.somesite.com/includes/frag1.html" />
<esi:include src="../images/sunset.jpg" onerror="continue" />

esi:inline tags

You use an esi:inline tag to demarcate a fragment that is referenced by an esi:include tag on the page.

Following is an esi:inline tag example:

<esi:inline name="uri" [fetchable="yes|no"] [src="uri"] [max-age=int]>
... html fragment ...
</esi:inline>

You can place as many esi:inline tags on the page as are required by the remainder of your ESI markup, however, the WebAccelerator system will only process a set number of ESI tags (the default is 50). If the fragment identified by the esi:inline tag is marked as non-fetchable (fetchable=no), then upon expiration the fragment is fetched by refreshing the page which contains the fragment. If the fragment is marked as fetchable, then a source URI for that fragment must be provided. In the event that the fragment expires, it can be refreshed from the source URI without refreshing the containing page.

The first time the WebAccelerator system access a page containing an esi:inline tag, it caches the fragment delimited by the esi:inline tag. The WebAccelerator system services subsequent requests for that fragment from its cache, even if that fragment is requested by some other page using either an esi:inline or esi:include tag.

esi:inline tags are important because they allow you to add ESI support to your site without re-architecting it to store and serve HTML fragments. Essentially, by marking up the appropriate sections of your site's pages with non-fetchable esi:inline tags, you can cache and re-use the HTML fragments needed by your site.

This tag accepts arguments shown in Table D.15 .

Table D.15 esi:inline tag arguments
Argument
Definition
name
Required argument that provides a URI which uniquely identifies the fragment. In the event that the fragment is fetchable, and if the fragment's expiration time is different from its template's expiration time, then this URI is used to fetch the fragment when it is refreshed.
fetchable
Required argument that identifies whether the fragment can be obtained from the URI identified by the name parameter. Valid values are either "yes" or "no".
Note that fetchable="yes" only has meaning if the fragment's cache expiration time is different than the template's expiration time. If the two expire at the same time, then the fragment is always refreshed when the template is refreshed.
If the fragment is fetchable and if the fragment's expiration time is different from the template's expiration time, then the WebAccelerator refreshes the fragment using the URI identified on the src parameter.
src
Required argument if fetchable="yes". If the fragment's expiration time is different from its template's expiration time, then this parameter is used to identify the URI where the fragment can be obtained. At a minimum, this argument should be set to the URI used to obtain the template.
If fetchable="no", then this argument is ignored and the URI provided on the name attribute is used. Note that this parameter is a F5 Networks extension to the ESI specification.
max-age
Optional argument that identifies a cache expiration time for the fragment. Units are in seconds. In order for this parameter to be obeyed, the WebAccelerator must have a lifetime policy set for the template such that ESI max age is obeyed. For more information on lifetime policies, see Chapter 10, .
Note that this parameter is an F5 Networks extension to the ESI specification.

Following is an esi:inline tag example with arguments:

<esi:inline name="http://www.somesite.com/includes/frag1.html"

fetchable="no" max-age=300>
<p>This is a sample HTML fragment that is included into
this page when the appropriate esi:include tag is evaluated.

</p>
</esi:inline>
<esi:include src="http://www.somesite.com/includes/frag1.html" />
<esi:inline name="http://www.somesite.com/includes/frag2.html"
fetchable="no" max-age=250>
<p>This is yet another sample HTML fragment that is
included into this page when an esi:include tag is evaluated.

</p>
</esi:inline>
<esi:include src="http://www.somesite.com/includes/frag2.html" />

esi:choose tags

You can use esi:choose tags for conditional processing of the ESI block. An <esi:choose> block has zero or more <esi:when> blocks, and zero or one <esi:otherwise> block.

Following is an esi:choose tag example:

<esi:choose>

<esi:when test="...">
...
</esi:when>
<esi:when test="...">
...
</esi:when>
<esi:otherwise>
...
</esi:otherwise>
</esi:choose>

The markup contained between the <esi:when></esi:when> tags is processed by the WebAccelerator system when the test argument evaluates to true. The WebAccelerator system processes the first <esi:when> block for which the test evaluates to true and then exits the <esi:choose> block. The WebAccelerator system replaces the entire <esi:choose> block with the results of processing that markup.

Note

The test provided for an <esi:when> block must be a valid ESI expression. See Defining ESI language for more information.

If none of the tests provided for the <esi:when> blocks evaluates to true, the WebAccelerator system processes the defined markup contained in the <esi:otherwise> block. The WebAccelerator system replaces the entire <esi:choose> block with the results of processing that markup.

If none of the tests provided for the <esi:when> blocks evaluates to true, and there is no <esi:otherwise> block defined for the <esi:choose> block, the WebAccelerator system removes the entire <esi:choose> block (replacing it with nothing) from the final assembled page.

The markup contained by an <esi:when> or <esi:otherwise> block can be any valid markup used by your web pages. For example, if your site's pages are composed of HTML and JavaScript, then any valid combination of HTML, JavaScript, and ESI markup could appear there.

Following is an esi:choose tag example with a combination of HTML, JavaScript, and ESI markup:

<H1>Plan Options</H1>
<esi:choose>
<esi:when test="$(HTTP_COOKIE{membership}=='gold'>"
<p>Congratulations on your gold membership! Choose from one of the
following:</p>
<esi:include src="http://somesite.com/apps/planOptions.jsp?plan=1">

</esi:when>
<esi:when test="$(HTTP_COOKIE{membership}=='silver'>"
<p>Please choose from one of the following silver membership options:</p>
<esi:include src="http://somesite.com/apps/planOptions.jsp?plan=2">

</esi:when>
<esi:otherwise>
<p>You are not currently a member!</p>
<esi:include src="http://somesite.com/apps/planSignUp.jsp">
</esi:when>
</esi:choose>

esi:try tags

You can use esi:try tags to perform exception handling for <esi:include>. Each <esi:try> block must have exactly one <esi:attempt> block and exactly one <esi:except> block. Children of <esi:try> blocks are not allowed. You must terminate <esi:try>, <esi:attempt>, and <esi:except> blocks with their respective closing tags.

Following is an esi:try tag example:

<esi:try>

<esi:attempt>

...

</esi:attempt>

<esi:except>

...

</esi:except>

</esi:try>

When processing an <esi:try> block, the WebAccelerator system first attempts to process the markup contained in the <esi:attempt> block. If the <esi:include> found there triggers an error, then the WebAccelerator system processes the markup contained in the <esi:except> block.

Note

If <esi:include> is used with the onerror="continue" argument, the WebAccelerator system never processes the contents of the <esi:except> block. This is because the WebAccelerator system suppresses any error conditions that might arise when processing an <esi:include> if onerror="continue" is also used.

The WebAccelerator system replaces the entire <esi:try> block with the results of the markup that it processes, regardless as to whether that markup is found in the <esi:attempt> block or the <esi:except> block.

The markup contained by an <esi:attempt> or <esi:except> block can be any valid markup used by your web pages. For example, if your site's pages are composed of HTML and JavaScripttm, then any valid combination of HTML, JavaScript, and ESI markup can appear there. For example:

<esi:try>

<esi:attempt>
<p>On sale:</p>
<esi:include src="http://images.mysite.com/vase.html"
alt="http://images.mysite.com/overstock.html" />
</esi:attempt>
<esi:except>
<p>We're sorry! Our image server appears to be unreachable. Please
try again at some later date.</p>
</esi:except>
</esi:try>

esi:comment tags

You can use esi:comment tags to comment ESI instructions. The WebAccelerator system removes esi:comment tags from the final page that it assembles.

Following is an esi:comment tag example:

<esi:comment text="a comment string" />

This esi:comment tag is an empty element, therefore, you must not provide a closing tag for it.

esi:remove tags

You can use esi:remove tags to provide non-ESI markup, in the event that ESI processing is not enabled. The content within the esi:remove tags is standard HTML, which any browser can understand and render.

Following is an esi:remove tag example:

<esi:remove>

....

</esi:remove>

When the WebAccelerator system processes this block, it removes this markup. If ESI processing is not enabled, all of the elements are passed to the client, which ignores markup it does not understand. Therefore, the contents of the <esi:remove> block should consist of markup that the client understands, so the client can properly render it.

The WebAccelerator system does not process ESI markup on a page if the origin server does not send the appropriate ESI Surrogate-Control response header in the response. See Using Edge Side Include (ESI) for more information.

For example, for the following markup:

<p>This hour's hottest investment tip:</p>

<esi:include src="investTip.jsp" />

<esi:remove>

<p><em>Buy low and sell high.</em></p>

</esi:remove>

The browser will render:

Buy low and sell high.

esi:vars tags

You can use the esi:vars tag to include an ESI variable in markup outside an ESI block. For example:

<esi:vars>

<p>Currently logged in as $(HTTP_COOKIE{userID}|'anonymous')</p>

</esi:vars>

<!--esi ... --> tags

You can use the <!--esi ... --> construct to encapsulate ESI markup in the template. The WebAccelerator system removes the <!--esi and --> tags from the markup before sending the assembled page to the requesting client. The WebAccelerator system does not send any information between the tags to the client.

In addition, F5 Networks extends the ESI specification by adding the <--' .. `--> construct. The WebAccelerator system ignores any ESI tags that it finds within this construct.

Following is an <!--esi ... --> tag example:

<!--esi
...
-->
or
<--'
...
`-->

This construct is optional. Any client that does not understand ESI should ignore any ESI tags. You should primarily use this construct to guard against a client rendering valid HTML that may be incomplete if the corresponding ESI tags are not executed by the WebAccelerator system.

For example, the following statement:

<esi:vars>
<p>Currently logged in as $(HTTP_COOKIE{userID}|'anonymous')</p>
</esi:vars>

Might be better expressed as follows:
<!--esi
<esi:vars>
<p>Currently logged in as $(HTTP_COOKIE{userID}|'anonymous')</p>
</esi:vars>
-->

These rules represent the WebAccelerator system's interpretation of the ESI specification relative to comment handling, as follows. Before sending the page to the requesting client, the WebAccelerator system first processes:

  • Any ESI markup, most notably any ESI includes that are located inside the <!--esi ... -->.
  • Any ESI markup found inside normal HTML comments ( <!-- ... -->).

ESI operands

An ESI operand consists of a literal or a variable value.

Literal values

ESI can perform literal conditional processing using the esi:choose element (see esi:comment tags ). These elements make use of test attributes to drive the evaluation of the conditions. Test attributes make use of expressions: operand operator operand.

ESI literal values for conditional processing can be numeric or strings. You can optionally enclose string literals in quotes. You can use quotation marks ("double quotes"), or apostrophes (`single quotes'). Quotation marks are required if the string contains blank spaces, or if the string contains any characters not in the set [a-zA-Z0-9_.]. If quoted, a string literal cannot contain that same quote in the string. For example, if you want to use the following literal string:

Simon says, "duck"

You must quote the literal as follows:

`Simon says, "duck"'

ESI conditional processing interprets a non-quoted literal that is composed of only digits and (optionally) a single period (.) as a number, when this is most meaningful for the operator.

Variable values

ESI evaluates variables any time they appear between begin and end tags (such as when they appear inside an <esi:choose> block, or between beginning and ending <esi:vars> tags). In addition, some ESI tags permit variables in attribute values, but most do not. Notably, the SRC and ALT attributes for <esi:include> do permit variables.

The WebAccelerator system assembly engine literally emits ESI variables that appear in any other situation.

Note

The <esi:choose> block is described in esi:comment tags . The <esi:vars> tag is described in Using parameter value substitution with ESI . The <esi:include> tag is described in esi:include tags .

ESI supports the following read-only variables, which are used to obtain values that are presented on the HTTP request.

Table D.16 ESI supported read-only variables
Variable Type
Variable Name
Description
list
HTTP_ACCEPT_LANGUAGE
Contains a list of the values that appear on the HTTP Accept-Language request header.
dictionary
HTTP_COOKIE
Contains the cookies and cookie values presented on the HTTP request.
string
HTTP_HOST
Contains the value provided on the HTTP HOST request header.
string
HTTP_REFERER
Contains the value provided on the HTTP REFERER request header.
dictionary (special)
HTTP_USER_AGENT
Contains the value provided on the HTTP USER_AGENT request header
dictionary
QUERY_STRING
Contains the query parameters and their values that appeared on the request header.

You must put variable names in uppercase. To reference a variable's value, surround the variable parenthesis and precede it with a dollar sign ($). For example:

$(HTTP_COOKIE)

Lists variables

Variables that ESI identifies as lists return a particular response when a specified requested value is present. To specify the requested value, append the variable name with the value contained in braces ({}).

For example, ESI evaluates the following as true since en-gb appears as a value in the HTTP_ACCEPT_LANGUAGE header.

$(HTTP_ACCEPT_LANGUAGE{en-gb})

Note that the list variable value that you specify is case-sensitive.

Dictionaries variables

You can use ESI dictionaries variables to access a string that is identified by a key. You specify a key by appending the variable name with braces ({}) that contain the key. For example:

$(QUERY_STRING{action})

The HTTP request element uses the key as the variable name. For example, if you are using the QUERY_STRING variable, the key is a query parameter name. The QUERY_STRING variable returns the value presented for the requested HTTP request element. If the requested element does not appear on the URL, the QUERY_STRING variable returns an empty string.

For example. for the following URL:

http://www.somesite.com/srch.jsp?action=forward&sessionID=AAYu30Ws

The QUERY_STRING variable returns the following results.

Table D.17 QUERY_STRING variable example
Variable
Result
$(QUERY_STRING{action})
`forward'
$(QUERY_STRING{sessionID})
`AAYu30Ws'
any other key
`'

Note that the dictionary variable value that you specify is case-sensitive.

Default values

ESI returns an empty string (`') if it does not find a value for a variable access. That is, ESI returns an empty string if one of the following occurs:

  • A dictionary key is undefined
  • The variable is empty.
  • The variable is non-existent.

You can use the logical or (|) operator to identify a default value for a variable, in the event that it returns an empty string as follows:

$(VARIABLE|default_value)

For example, the following returns either the value set for the userID cookie, or '0' if $(HTTP_COOKIE{userID}) evaluates to an empty string.:

$(HTTP_COOKIE{userID}|'0')

ESI operators

The following set of unary and binary logical operators are supported by ESI expressions, listed in order of decreasing precedence.

Table D.18 Supported ESI operators
Operator
Type
+
binary +
==, !=, <, >, <= , >=
comparison
!
unary negation
&
logical and
|
logical or

Binary

F5 Networks extends the ESI specification with the binary + operator, which can indicate an addition or a string concatenation. If the + operator is used with mixed data types, then the ESI performs string concatenation.

For example, ESI evaluates the following binary:

123 + `duck`

To:

123duck

Comparison

The comparison operators are shown in Table D.19 .

Table D.19 Comparison operators
Operator
Definition
==
equal
!=
not equal
<
less than
>
greater than
<=
less than or equal to
>=
greater than or equal to

If both operands are numeric, ESI performs the comparison numerically. If either operand is non-numeric, ESI evaluates both operands as strings. If an operand is empty or undefined, ESI evaluates the expression to false.

See the examples in Table D.20 .

Table D.20 Comparison operator string examples
Comparison
Explanation
1 == 1
Evaluates to true.
ESI performs this comparison numerically.
1=='1'
Evaluates to true.
ESI performs this comparison as if both operands are strings
(!(1 == 1) )== 1
Evaluates to false.
The left-hand operand is a boolean type, which is non-numeric. Essentially, this comparison is the same as the following:
`false' == `1'
1==
Evaluates to false.

Logical operators

Logical operators are listed in Table D.21 .

Table D.21 Logical operators
Operator
Definition
!
unary negation
&
logical and
|
logical or

F5 Networks extends the ESI specification to allow logical operators as comparators. When any Boolean value is required for an operator, and strings are provided for one or more operands, ESI considers empty as false and non-empty as true, as in the examples in Table D.22 .

Table D.22 Logical string examples
Comparison
Explanation
!(1 == 1)
Evaluates to false.
1=='1' & 4 < 3
Evaluates to false.
1=='1' | 4 < 3
Evaluates to true.
`duck' | `bar'
Evaluates to true.
`'&'bar'
Evaluate to false.
!`'
Evaluates to true.

Using parameter value substitution with ESI

Important

Before you read the following section, you must understand the concepts discussed in Defining ESI language .

The WebAccelerator system obtains both templates and fragments from the origin servers using HTTP requests, in much the same way that it obtains any content from your site. Depending on how you built your site and the matching policies that you defined for the WebAccelerator system, different caching policies can be in effect for the templates and fragments required to service any given request. This has important implications when it comes to parameter value substitutions.

The WebAccelerator system determines what portion of an HTML page/template/fragment is the target of a substitution when it compiles that object into a response. The WebAccelerator system then stores, the rule for how to perform that substitution with the compiled response.

The WebAccelerator system performs the actual substitution during request time (assembly time), based on the information that it finds in the HTTP request for the template. However, the parameter value substitution rules defined for the template are not necessarily relevant to the substitutions performed for the included fragments.

For example, suppose you have an application matching node that matches to ESI templates, and another that matches to HTML fragments included by the following templates:

  • Applications
  • Templates
  • Home
  • Quotes

This is a typical scenario because it allows you to have differing cache lifetimes for the two types of data.

For this example, the Applications node defines a parameter substitution rule that prompts substitution on query parameter IDENT and the source of the value for IDENT is the IDENT query parameter found on the HTTP request. The templates node, however, does not have this rule defined for it. Instead, it has a random number substitution rule defined for the IDENT query parameter.

For this example, the request for the template is:

http://www.somesite.com/apps/dosomething.jsp?IDENT=3798

In this case, any embedded URLs that originated in the template has IDENT query parameter set to 3798. Any embedded URLs that originated in the fragments that are included by the template have some random number (for example, 2290) set for the IDENT query parameter.

These mismatched values appear in the final page served by the WebAccelerator system. Depending on how your site is architected, and what the respective embedded URLs are actually used for, this may or may not be the desired behavior. For this reason, you must be aware of how your assembly policies are defined when you are interacting with ESI markup.

Parameter value substitution and ESI variables

The WebAccelerator system never performs parameter value substitution on HTML tags that use ESI variables or that exist inside an ESI tag.

For example, if you have a parameter value substitution rule that prompts the WebAccelerator system to replace the value of the URL query parameter with some value found on the request URL and you receive the following embedded URL:

<a href="http://www.somesite.com/dosomething.jsp?URL=$(HTTP _REFERER)">

The WebAccelerator system ignores the parameter value substitution, because this URL uses the $(HTTP_REFERER) ESI variable. Instead, the WebAccelerator system evaluates the ESI variable and uses its value for the URL query parameter.

If the same parameter value substitution is defined for a page in which the following include tag appears:

<esi:include src="http://www.somesite.com/fragments/firstBlock.jsp?
URL=http://www.somesite.com" />

The WebAccelerator system will again ignore the parameter value substitution, because the URL query parameter appears in an ESI tag.

For this situation, to have the WebAccelerator system substitute the value of the URL query parameter to a meaningful value at assembly time, you use an ESI variable as follows:

<esi:include src="http://www.somesite.com/fragments/firstBlock.jsp?
URL=$(QUERY_STRING{URL})" />

ESI implementation example

For this example, your site offers stock quote information from world-wide stock exchanges. When the stock exchange is active, your site updates stock quotes once every 15 minutes. When the stock exchange is inactive, your site begins updating stock quotes as soon as trading reopens and then, once every 15 minutes. This configuration ensures that the origin servers only receive requests for stock exchanges that are actively trading.

You provide stock quotes to customers in a series of tables that contain information for a given stock exchange. To manage the varying nature of the content requested by customers, your site generates a unique template for each user that is personalized based on specific cookies, as follows:

Table D.23 Cookies for personalizing template
Cookie name
Usage
familiarName
Used to identify and display user's first name.
surname
Used to identify and display user's last name.
display
Used to identify user preferences for displaying stock quotes, based on price or volume.
userid
Used to identify and display the stock exchange locations from which to get specific stocks quotes. These preferences are tracked as a database query keyed to the userid cookie.

Requests for stock quote information at your site appear in the following form:

http://stocks.somesite.com/quotes/quotes.jsp

Requests for a quote from a given exchange are expressed inside esi:include tags. The URLs used for these requests appear in the following form:

http://stocks.somesite.com/quotes/showQuotes?display=volume&
exchange=NASDAQ&user=820o8xdmp22

You can explicitly set a cache TTL for each fragment in the template, using the HTTP Expires response header. See max-age, on page 10-5 for more information.

If users change the information they want to see, you can invalidate the template from their cache. See Invalidating content manually, on page 11-9 for more information.

For this example site, you have two top-level nodes in the Request Type Hierarchy as follows.

  • Templates
    Specifies the rules related to ESI templates.
  • Quotes
    Specifies the caching and rules related to your quotes.

For this example, you configure the following matching rules on the Request Type Hierarchy tree.

Table D.24 ESI example matching rules
Node
Application matching parameter
Template
Create a rule based on the Path data type. Provide the following value for the Path parameter:
/quotes/quotes.jsp
Quotes
Create a rule based on the Path data type. Provide the following value for the Path parameter:
/quotes/showQuote.jsp

Note

See, Chapter 4, Introducing the Request Type Hierarchy Tree for specific instructions about how to create a Request Type Hierarchy tree.

Creating caching policies for the ESI example

For the Templates node, perform the following tasks:

  • Create a lifetime rule as follows:
    • Clear the Use HTTP lifetime headers if present check box to prevent users from forcing the WebAccelerator system to send requests to the origin servers, by using control-refresh (Internet Explorer) or shift-refresh (Netscape) in their browsers.
    • For the age settings, set a maximum lifetime of 12 hours.
    • For specific information about setting lifetime rules, see Chapter 10, .

  • Create a variation policy, adding familiarName, surname, display, and user cookies as parameters that are significant for content.
  • For specific information about creating variation rules, see Chapter 7, .

  • Create a proxy rule that indicates that the WebAccelerator system must send a request to the origin server if the userid cookie contains an empty value or is absent from the request.
  • For specific information about creating proxying rules, see Chapter 9, .

For the Quotes node, complete the following tasks:

  • Create a lifetime rule as follows:
    • Check the Use HTTP lifetime headers if present check box.
    • Clear the Ignore no-cache HTTP headers in the request check box to prevent users from forcing the WebAccelerator system to send requests to the origin servers, by using control-refresh (Internet Explorer) or shift-refresh (Netscape) in their browsers.
    • For the age settings, set a minimum lifetime of 15 minutes.
    • For specific information about setting lifetime rules, see Chapter 10, .

  • Create a proxy rule that indicates that the WebAccelerator system must send a request to the origin server if the user query parameter contains an empty value.
  • For specific information about creating proxying rules, see Chapter 9, .

Template example

The following is an example of a template that could be returned by the origin servers if users obtain stock quotes from the NASDAQ and from the London Stock Exchange. This template is based on a database query that runs when the origin servers receive a request for quotes from the user.

1: <html>
2: <head>
3: <title>
4: <!--esi
5: <esi:vars>
6: Stock quotes for $(HTTP_COOKIE{familiarName})
7: $(HTTP_COOKIE{surname})
8: </esi:vars>
9: -->
10: <esi:remove>
11: Stock quotes not processed
12: </esi:remove>
13: </title>
14: </head>
15: <body>
16: <!--esi
17: <esi:vars>
18: <h1>Stock quotes for $(HTTP_COOKIE{familiarName})
19: $(HTTP_COOKIE{surname})</h1>
20: </esi:vars>
21: <esi:comment text="get stock info for the NASDAQ" />
22: <esi:try>
23: <esi:attempt>
24: <esi:include src="http://stocks.somesite.com/quotes/
25: showQuotes.jsp?
26: display=$(HTTP_COOKIE{display})&exchange=NASDAQ&
27: user=$(HTTP_COOKIE{userid}) />
28: </esi:attempt>
29: <esi:except>
30: <h2>NASDAQ Quotes</h2>
31: <p>We're sorry, but the quotes you requested are not
32: available. Please wait a few minutes before trying again.</p>
33: </esi:except>
34: </esi:try>
35: <esi:comment text="get stock info for the London Stock Exchange" />
36: <esi:try>
37: <esi:attempt>
38: <esi:include src="http://stocks.somesite.com/quotes/
39: showQuotes.jsp?
40: display=$(HTTP_COOKIE{display})&exchange=LSE&
41: user=$(HTTP_COOKIE{userid}) />
42: </esi:attempt>
43: <esi:except>
44: <h2>London Stock Exchange Quotes</h2>
45: <p>We're sorry, but the quotes you requested are not
46: available. Please wait a few minutes before trying again.</p>
47: </esi:except>
48: </esi:try>
49: -->
50: <esi:remove>
51: <p>Due to an unknown error, your stock quotes could not be retrieved.
52: If the problem persists, <a href="mailto:planadmin@somesite.com">please
53: contact us.</a></p>
54: </esi:remove>
55: </body>
56: </html>

For this template example, lines 2 - 14 define the HTTP head section of the page that the WebAccelerator system returns to the client. If the WebAccelerator system processes the ESI markup in this section of the page, then it returns the following:

<head>
<title>
Stock quotes for Jen Babsen
</title>
</head>

Because you configured a proxy rule that indicates that the WebAccelerator system must send a request to the origin server if the userid cookie contains an empty value or is absent from the request, you can assume that the familiarName and surname cookies are set when the WebAccelerator system processes this ESI markup. As a result, you do not need to set a default name here.

If the WebAccelerator system does not process this ESI markup (because the client manages to request the page directly from the origin servers, or because the origin servers do not respond to the WebAccelerator system's request with an appropriate Surrogate-Control response header), then the ESI markup appears to be an HTML comment (or unknown tags in the case of the markup on lines 10 and 12) that the client ignores.

Similarly, lines 15 - 55 define the body section of the page. Again, if the WebAccelerator system does not process this ESI markup, the contents of the <esi:remove> block at lines 50 -54 are the only thing rendered by the client. So if the client somehow receives the unprocessed template, it renders the following:

<html>
<head>
<title>
Stock quotes not processed
</title>
</head>
<body>
<p>Due to an unknown error, your stock quotes could not be retrieved.
If the problem persists, <a href="mailto:planadmin@somesite.com">please
contact us.</a></p>
</body>
</html>

Lines 24 - 27 and lines 38 - 41 represent include attempts. If the esi:include from lines 24 - 27 fails, then the WebAccelerator system sends the HTML markup in lines 30 - 32 to the client for rendering. Similarly, if the esi:include from lines 38 - 41 fails, then the client receives the HTML markup shown in lines 44 - 46.

If the request identified by the esi:include in lines 24 - 27 succeeds, then the WebAccelerator system replaces lines 22 - 34 with the fragment that it receives from the origin servers (or from its own cache, if the fragment is available there). The same thing happens for the esi:include shown in lines 38 - 41.

When the origin servers respond to a request for this template, they do not explicitly set an expiration time for the template in cache, because you set a maximum TTL of 12 hours for the template. In addition, if the user updates his stock tracking preferences in such a way as to change the template (added or removed a stock exchange), the origin servers send the WebAccelerator system an invalidation request to force it to expire the template regardless of the template's current TTL in cache. For more information about content invalidation, see Chapter 11 .

Example of fragments in a template

The esi:include tags, shown in lines 24 - 27 and 38 - 41, in the preceding template example prompts the WebAccelerator system to retrieve a fragment. The WebAccelerator system replaces the esi:include tags (and the surround esi:try tags) with the fragment that it receives.

The actual fragment that the WebAccelerator system receives is determined by what the showQuotes application returns. This is gated by what the display and userid cookies settings. Assuming that display is set to price and userid is set to EV93jmCV00e4, the WebAccelerator system sends the following request:

http://stocks.somesite.com/quotes/showQuotes.jsp?display =price&
exchange=NASDAQ&user=EV93jmCV00e4

Upon receiving this request, the showQuotes application performs a database lookup to see what NASDAQ-listed stocks user EV93jmCV00e4 is tracking. Based on this lookup, the application might return a fragment that appears as follows:

<h2>NASDAQ Quotes</h2>
<table>
<tr><td>PHONY1</td><td>13.29</td><td>+0.03</td></tr>
<tr><td>PHONY2</td><td>2.09</td><td>-2.19</td></tr>
</table>

When the origin server responds to the WebAccelerator system with the fragment, it uses the HTTP Expires response header to indicate when the WebAccelerator system should refresh the fragment by sending the request to the origin server for new content. If the NASDAQ is in active trading, the expires time is set to 15 minutes in the future. If the NASDAQ is currently closed, the expires time is the day and time when the NASDAQ reopens for business.

If the user updates their list of NASDAQ-listed stocks, the origin servers send the WebAccelerator system an invalidation request to force it to expire this fragment regardless of the fragment's current TTL. For more information about content invalidation, see Chapter 11 . Content lifetime is described in Chapter 10 .




Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)