← Back to branch summary

~ubuntu-branches/debian/sid/varnish/sid

« back to all changes in this revision

Viewing changes to doc/sphinx/=build/html/_sources/tutorial/esi.txt

  • Committer: Package Import Robot
  • Author(s): Stig Sandbeck Mathisen
  • Date: 2011-10-29 15:23:24 UTC
  • mfrom: (0.1.15)
  • Revision ID: package-import@ubuntu.com-20111029152324-tdtlsurrv22ysknj
Tags: 3.0.2-1
* New upstream release
* Build from upstream tarball instead of git tag
* debian/watch: more specific regular expression

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/sphinx/=build/html/_sources/tutorial/esi.txt
 
1
.. _tutorial-esi:
 
2
 
 
3
Edge Side Includes
 
4
------------------
 
5
 
 
6
*Edge Side Includes* is a language to include *fragments* of web pages
 
7
in other web pages. Think of it as HTML include statement that works
 
8
over HTTP. 
 
9
 
 
10
On most web sites a lot of content is shared between
 
11
pages. Regenerating this content for every page view is wasteful and
 
12
ESI tries to address that letting you decide the cache policy for
 
13
each fragment individually.
 
14
 
 
15
In Varnish we've only implemented a small subset of ESI. As of 2.1 we
 
16
have three ESI statements:
 
17
 
 
18
 * esi:include 
 
19
 * esi:remove
 
20
 * <!--esi ...-->
 
21
 
 
22
Content substitution based on variables and cookies is not implemented
 
23
but is on the roadmap. 
 
24
 
 
25
Example: esi include
 
26
~~~~~~~~~~~~~~~~~~~~
 
27
 
 
28
Lets see an example how this could be used. This simple cgi script
 
29
outputs the date:::
 
30
 
 
31
     #!/bin/sh
 
32
     
 
33
     echo 'Content-type: text/html'
 
34
     echo ''
 
35
     date "+%Y-%m-%d %H:%M"
 
36
 
 
37
Now, lets have an HTML file that has an ESI include statement:::
 
38
 
 
39
     <HTML>
 
40
     <BODY>
 
41
     The time is: <esi:include src="/cgi-bin/date.cgi"/>
 
42
     at this very moment.
 
43
     </BODY>
 
44
     </HTML>
 
45
 
 
46
For ESI to work you need to activate ESI processing in VCL, like this:::
 
47
 
 
48
    sub vcl_fetch {
 
49
        if (req.url == "/test.html") {
 
50
           set beresp.do_esi = true; /* Do ESI processing               */
 
51
           set beresp.ttl = 24 h;    /* Sets the TTL on the HTML above  */
 
52
        } elseif (req.url == "/cgi-bin/date.cgi") {
 
53
           set beresp.ttl = 1m;      /* Sets a one minute TTL on        */
 
54
                                     /*  the included object            */
 
55
        }
 
56
    }
 
57
 
 
58
Example: esi remove
 
59
~~~~~~~~~~~~~~~~~~~
 
60
 
 
61
The *remove* keyword allows you to remove output. You can use this to make
 
62
a fall back of sorts, when ESI is not available, like this:::
 
63
 
 
64
  <esi:include src="http://www.example.com/ad.html"/> 
 
65
  <esi:remove> 
 
66
    <a href="http://www.example.com">www.example.com</a>
 
67
  </esi:remove>
 
68
 
 
69
Example: <!--esi ... -->
 
70
~~~~~~~~~~~~~~~~~~~~~~~~
 
71
 
 
72
 
 
73
This is a special construct to allow HTML marked up with ESI to render
 
74
without processing. ESI Processors will remove the start ("<!--esi")
 
75
and end ("-->") when the page is processed, while still processing the
 
76
contents. If the page is not processed, it will remain, becoming an
 
77
HTML/XML comment tag. For example::
 
78
 
 
79
  <!--esi  
 
80
  <p>Warning: ESI Disabled!</p>
 
81
  </p>  -->
 
82
 
 
83
This assures that the ESI markup will not interfere with the rendering
 
84
of the final HTML if not processed.
 
85
 
 
86