forked from ezsystems/ezsi
/
documentation.html
778 lines (699 loc) · 29 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Documentation for the eZSI extension</title>
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
:Revision: $Revision: 4224 $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
tt.docutils {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="documentation-for-the-ezsi-extension">
<h1 class="title">Documentation for the eZSI extension</h1>
<!-- -*- coding: utf-8 -*- -->
<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#author" id="id1" name="id1">Author</a></li>
<li><a class="reference" href="#introduction" id="id2" name="id2">Introduction</a></li>
<li><a class="reference" href="#what-is-ezsi" id="id3" name="id3">What is eZSI ?</a></li>
<li><a class="reference" href="#how-does-this-extension-work" id="id4" name="id4">How does this extension work ?</a><ul>
<li><a class="reference" href="#use-case-1" id="id5" name="id5">Use case 1</a></li>
<li><a class="reference" href="#use-case-2" id="id6" name="id6">Use case 2</a></li>
<li><a class="reference" href="#use-case-3" id="id7" name="id7">Use case 3</a></li>
<li><a class="reference" href="#si-block-functionnal-specification" id="id8" name="id8">si-block functionnal specification</a></li>
<li><a class="reference" href="#esi-processing-part-1" id="id9" name="id9">ESI processing part 1</a></li>
<li><a class="reference" href="#esi-processing-part-2" id="id10" name="id10">ESI processing part 2</a></li>
<li><a class="reference" href="#cronjob-workflow" id="id11" name="id11">Cronjob workflow</a></li>
</ul>
</li>
<li><a class="reference" href="#installation" id="id12" name="id12">Installation</a><ul>
<li><a class="reference" href="#extracting-the-extension" id="id13" name="id13">Extracting the extension</a></li>
<li><a class="reference" href="#creating-the-new-table" id="id14" name="id14">Creating the new table</a></li>
<li><a class="reference" href="#declaring-the-extension" id="id15" name="id15">Declaring the extension</a></li>
<li><a class="reference" href="#setting-up-the-cronjob" id="id16" name="id16">Setting up the cronjob</a></li>
</ul>
</li>
<li><a class="reference" href="#removing-the-extension" id="id17" name="id17">Removing the extension</a><ul>
<li><a class="reference" href="#removing-all-si-blocks-calls" id="id18" name="id18">Removing all {si-blocks} calls</a></li>
<li><a class="reference" href="#removing-the-cronjob" id="id19" name="id19">Removing the cronjob</a></li>
<li><a class="reference" href="#removing-the-table" id="id20" name="id20">Removing the table</a></li>
<li><a class="reference" href="#deleting-si-blocks" id="id21" name="id21">Deleting si-blocks</a></li>
<li><a class="reference" href="#undeclaring-the-extension" id="id22" name="id22">Undeclaring the extension</a></li>
<li><a class="reference" href="#deleting-the-extension" id="id23" name="id23">Deleting the extension</a></li>
</ul>
</li>
<li><a class="reference" href="#configuring-the-extension" id="id24" name="id24">Configuring the extension</a><ul>
<li><a class="reference" href="#templatefunctionsettings" id="id25" name="id25">TemplateFunctionSettings</a></li>
<li><a class="reference" href="#siblocksettings" id="id26" name="id26">SIBlockSettings</a></li>
<li><a class="reference" href="#sifilessettings" id="id27" name="id27">SIFilesSettings</a></li>
<li><a class="reference" href="#ftpsettings" id="id28" name="id28">FTPSettings</a></li>
<li><a class="reference" href="#developmentsettings" id="id29" name="id29">DevelopmentSettings</a></li>
</ul>
</li>
<li><a class="reference" href="#template-function" id="id30" name="id30">Template function</a><ul>
<li><a class="reference" href="#si-block-function" id="id31" name="id31">{si-block} function</a></li>
<li><a class="reference" href="#key-generation" id="id32" name="id32">Key generation</a></li>
</ul>
</li>
<li><a class="reference" href="#important-notes" id="id33" name="id33">Important notes</a><ul>
<li><a class="reference" href="#si-block-vs-cache-block" id="id34" name="id34">{si-block} VS {cache-block}</a></li>
<li><a class="reference" href="#personnalized-pages" id="id35" name="id35">Personnalized pages</a></li>
</ul>
</li>
<li><a class="reference" href="#setting-up-apache-for-ssi" id="id36" name="id36">Setting up Apache for SSI</a><ul>
<li><a class="reference" href="#enabling-mod-filter" id="id37" name="id37">Enabling mod_filter</a></li>
<li><a class="reference" href="#enablig-mod-include" id="id38" name="id38">Enablig mod_include</a></li>
<li><a class="reference" href="#adding-mod-filter-rules" id="id39" name="id39">Adding mod_filter rules</a></li>
<li><a class="reference" href="#specific-rewrite-rule" id="id40" name="id40">Specific Rewrite Rule</a></li>
<li><a class="reference" href="#virtualhost-example" id="id41" name="id41">VirtualHost example</a></li>
</ul>
</li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id1" id="author" name="author">Author</a></h1>
<p>Jérôme Renard <<a class="reference" href="mailto:jr@ez.no">jr@ez.no</a>></p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">Introduction</a></h1>
<p>eZ Publish needed an extension that could be able to generate
ESI or SSI tags in order to cache the HTML page as much as possible.
This is what the eZSI extension has been designed for.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="what-is-ezsi" name="what-is-ezsi">What is eZSI ?</a></h1>
<p>eZSI makes it possible to generate either ESI or SSI tags in
the HTML page generated by eZ Publish.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id4" id="how-does-this-extension-work" name="how-does-this-extension-work">How does this extension work ?</a></h1>
<p>I hope the images below will be cleared enough to describe
how this extension work :</p>
<div class="section">
<h2><a class="toc-backref" href="#id5" id="use-case-1" name="use-case-1">Use case 1</a></h2>
<img alt="images/usecase1.png" src="images/usecase1.png" />
</div>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="use-case-2" name="use-case-2">Use case 2</a></h2>
<img alt="images/usecase2.png" src="images/usecase2.png" />
</div>
<div class="section">
<h2><a class="toc-backref" href="#id7" id="use-case-3" name="use-case-3">Use case 3</a></h2>
<img alt="images/usecase3.png" src="images/usecase3.png" />
</div>
<div class="section">
<h2><a class="toc-backref" href="#id8" id="si-block-functionnal-specification" name="si-block-functionnal-specification">si-block functionnal specification</a></h2>
<img alt="images/esiblock.png" src="images/esiblock.png" />
</div>
<div class="section">
<h2><a class="toc-backref" href="#id9" id="esi-processing-part-1" name="esi-processing-part-1">ESI processing part 1</a></h2>
<img alt="images/esipart1.png" src="images/esipart1.png" />
</div>
<div class="section">
<h2><a class="toc-backref" href="#id10" id="esi-processing-part-2" name="esi-processing-part-2">ESI processing part 2</a></h2>
<img alt="images/esipart2.png" src="images/esipart2.png" />
</div>
<div class="section">
<h2><a class="toc-backref" href="#id11" id="cronjob-workflow" name="cronjob-workflow">Cronjob workflow</a></h2>
<img alt="images/cronjobspecification.png" src="images/cronjobspecification.png" />
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id12" id="installation" name="installation">Installation</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id13" id="extracting-the-extension" name="extracting-the-extension">Extracting the extension</a></h2>
<p>Save the extension in your "extension" folder and extract it
with your favorite extracting tool. You can also run the
following command</p>
<pre class="literal-block">
tar zxvf ezsi.tar.gz
</pre>
<p>this will create a folder called "ezsi" under the "extension" folder</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id14" id="creating-the-new-table" name="creating-the-new-table">Creating the new table</a></h2>
<p>You have to create the new table needed by ezsi.
You can use the following command</p>
<pre class="literal-block">
mysql -u <user> -p<password> <ezpublishdatabase> < path/to/ezpublish/extension/ezsi/sql/mysql/schema.sql
</pre>
<p>This table must be stored in the same database as eZ Publish.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id15" id="declaring-the-extension" name="declaring-the-extension">Declaring the extension</a></h2>
<p>In order to have the extension working you have add the following
line</p>
<pre class="literal-block">
ActiveExtensions[]=ezsi
</pre>
<p>in</p>
<pre class="literal-block">
settings/override/site.ini.append.php
</pre>
<p>And update the autoload array</p>
<pre class="literal-block">
php bin/php/ezpgenerateautoloads.php -e
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id16" id="setting-up-the-cronjob" name="setting-up-the-cronjob">Setting up the cronjob</a></h2>
<p>In order to update SI blocks, ezsi is shipped with a cronjob which
calls all pages which contain SI blocks. It is up to you do decide
which frequency to use to launch the cronjob. The recommandation here
it to take all your ttl and caculate the average. After that you will
have enough informations to define a frequency. You can also add the
following line into your ezpublish.cron file since all the global
variables are already set:</p>
<pre class="literal-block">
0,15,30,45 * * * * cd $EZPUBLISHROOT && $PHP runcronjobs.php siblockupdate -q 2>&1
</pre>
<p>Remember that this is just an example. Here expired si-blocks will be
updated every 15 minutes. It is up to you to decide which frequency to use.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id17" id="removing-the-extension" name="removing-the-extension">Removing the extension</a></h1>
<p>If you plan to remove this extension then following
the process describe below is recommanded</p>
<div class="section">
<h2><a class="toc-backref" href="#id18" id="removing-all-si-blocks-calls" name="removing-all-si-blocks-calls">Removing all {si-blocks} calls</a></h2>
<p>You will have to remove all {si-block} calls in your templates.
The following command will help you to find them</p>
<pre class="literal-block">
grep -nR "{si-block" extension/ design/
</pre>
<p>If you are using SVN then you can use the following command
to avoid a lot of noise in the results of the above command</p>
<pre class="literal-block">
grep -nR "{si-block" extension/ design/ | grep -v svn
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id19" id="removing-the-cronjob" name="removing-the-cronjob">Removing the cronjob</a></h2>
<p>You also have to remove the cronjob described above from
your crontab. Run <tt class="docutils literal"><span class="pre">crontab</span> <span class="pre">-e</span></tt> and remove the according line.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id20" id="removing-the-table" name="removing-the-table">Removing the table</a></h2>
<p>You can now remove the ezsi_files table. To do this simply
run the following SQL query</p>
<pre class="literal-block">
DROP TABLE ezsi_file
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id21" id="deleting-si-blocks" name="deleting-si-blocks">Deleting si-blocks</a></h2>
<p>If the si-blocks have been stored on the local file system then
they are stored in <tt class="docutils literal"><span class="pre">var/si-blocks/*</span></tt>. You can simple run the following
command to remove them</p>
<pre class="literal-block">
rm -rf var/si-blocks/
</pre>
<p>If the SI blocks are stored in an external system, FTP for example
then the you simply have to remove the 'si-blocks' folder.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id22" id="undeclaring-the-extension" name="undeclaring-the-extension">Undeclaring the extension</a></h2>
<p>Remove the following line</p>
<pre class="literal-block">
ActiveExtensions[]=ezsi
</pre>
<p>in</p>
<pre class="literal-block">
settings/override/site.ini.append.php
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id23" id="deleting-the-extension" name="deleting-the-extension">Deleting the extension</a></h2>
<p>You can now remove the 'ezsi' folder which is located
in the "extension" folder.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id24" id="configuring-the-extension" name="configuring-the-extension">Configuring the extension</a></h1>
<p>All the useful configuration directives are located in
the following file</p>
<pre class="literal-block">
extension/ezsi/settings/ezsi.ini.append.php
</pre>
<div class="section">
<h2><a class="toc-backref" href="#id25" id="templatefunctionsettings" name="templatefunctionsettings">TemplateFunctionSettings</a></h2>
<p>Possible configuration</p>
<ul class="simple">
<li>ForceRegenerationString=<string></li>
<li>ForceRegenerationValue=<string></li>
</ul>
<p>It is possible to force the regeneration of a block by passing
<ForceRegenerationString>=<ForceRegenerationValue> in the URL.
<a class="reference" href="http://www.site.com/path/to/page">http://www.site.com/path/to/page</a>?<ForceRegenerationString>=<ForceRegenerationValue>
will force eZ Publish to regenerate the SI blocks defined in this page.</p>
<p>For example with the following configuration</p>
<pre class="literal-block">
ForceRegenerationString=force_siblocks_update
ForceRegenerationValue=yes
</pre>
<p>Will for the ezsi extension to update it SI blocks for
any page called with the following URL
<a class="reference" href="http://wwww.site.com/url/alias?force_siblocks_update=yes">http://wwww.site.com/url/alias?force_siblocks_update=yes</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id26" id="siblocksettings" name="siblocksettings">SIBlockSettings</a></h2>
<p>Possible configuration:</p>
<ul class="simple">
<li>BlockHandler=ESI</li>
<li>BlockHandler=SSI</li>
<li>BlockFilePathPrependString=<string></li>
</ul>
<p>If you choose</p>
<pre class="literal-block">
BlockHandler=ESI
</pre>
<p>Then you should be able to use Akamaï or Varnish or whatever HTTP proxy
which recognizes ESI markup. You will see the following markup
in your templates</p>
<pre class="literal-block">
<esi:include src="si-blocks/xxxxxxx.htm" ttl="yy"/>
</pre>
<p>If you choose</p>
<pre class="literal-block">
BlockHandler=SSI
</pre>
<p>Then you should be able to use Apache's mod_include.
Before using SSIs make sure your Apache server is ready to accept
SSI calls. Please refer to the following documention before using them:
<a class="reference" href="http://httpd.apache.org/docs/2.0/mod/mod_include.html">http://httpd.apache.org/docs/2.0/mod/mod_include.html</a>
You will see the following markup in your templates</p>
<pre class="literal-block">
<!--#include virtual="si-blocks/xxxxxx.htm" -->
</pre>
<p>Defining a value to BlockFilePathPrependString is useful when SI blocks
and HTTP are not on the same server. The extension will automatically
generate the string 'si-blocks/<cachefilename>.htm' but this is not
sufficient for remote file systems.
We need informations on how to acess the file.
This may be a hostname to access the file directly
like <a class="reference" href="http://siblocks.mysite.com/si-blocks">http://siblocks.mysite.com/si-blocks</a>/<cachefilename>.htm
If you plan to use a local storage then this directive
<em>MUST</em> be empty.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id27" id="sifilessettings" name="sifilessettings">SIFilesSettings</a></h2>
<p>two options are possible here:</p>
<ul class="simple">
<li>FS ( local File System )</li>
<li>FTP</li>
</ul>
<p>If you choose</p>
<pre class="literal-block">
FileHandler=FS
</pre>
<p>Then all SI blocks will be written on the local file system.
All the files will be stored in <tt class="docutils literal"><span class="pre">var/si-blocks/*</span></tt>.</p>
<p>If you choose</p>
<pre class="literal-block">
FileHandler=FTP
</pre>
<p>Then all SI bocks will be stored on a remote FTP. Its configuration
is described below. The blocks will be stored in <tt class="docutils literal"><span class="pre">si-blocks/*</span></tt>.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id28" id="ftpsettings" name="ftpsettings">FTPSettings</a></h2>
<p>These settings are only used for the FTP file handler.
If you choose</p>
<pre class="literal-block">
FileHandler=FS
</pre>
<p>They will not be used.
The configuration directives are:</p>
<ul class="simple">
<li>Host=<string></li>
<li>Port=<integer></li>
<li>Login=<string></li>
<li>Password=<string></li>
<li>Timeout=<integer></li>
<li>DestinationFolder=<string></li>
</ul>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id29" id="developmentsettings" name="developmentsettings">DevelopmentSettings</a></h2>
<p>ActivateSIMarkup=enabled|disabled
When set to disable the extension will not insert
the SI tags in the HTML page. Thism makes it possible
to plan the use of SI blocks without breaking the HTML
of the page. Useful for development and debugging :)</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id30" id="template-function" name="template-function">Template function</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id31" id="si-block-function" name="si-block-function">{si-block} function</a></h2>
<p>In order to have SI blocks generated in your HTML file you have
to call a new template function : si-block. The syntax is the following:</p>
<pre class="literal-block">
{si-block key=string $key [tll=integer $ttl]}
your template code here
{/si-block}
</pre>
<p>The <em>key</em> attribute is mandatory and can be a scalar or an array.
You can use a hash if you want but no key will be taken into account.
You can not use objects as keys.</p>
<p>The <em>ttl</em> is optionnal. However is you plan to use ESI and
Akamaï it is recommended to use it. You can choose between
4 units :</p>
<ul class="simple">
<li>h (hours)</li>
<li>m (minutes)</li>
<li>s (seconds)</li>
<li>d (days)</li>
</ul>
<p>Specify a floating point time is syntactically correct however
the extension will convert it into an int at runtime. This means
that for example setting ttl="9.5h" will not throw any syntax
error but the real TTL will be 9h.</p>
<p>You can put any template code between {si-block} instructions.
The template code inside these blocks will be interpreted and
stored into a static HTML file.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id32" id="key-generation" name="key-generation">Key generation</a></h2>
<p>At a lower level the key for each block is composed by the
following informations :</p>
<ul class="simple">
<li>value of the "key" attribute</li>
<li>location of the {si-block} call in the template</li>
<li>template name</li>
<li>siteaccess name</li>
<li>urlalias</li>
<li>view parameters</li>
</ul>
<p>This means that you do not have to think about unicity
in your keys everything is already done in the template
function. Although it is not recommended you can even use
the same key in the same template but at different locations
in this file. The final key will be different. This will make
the template more difficult to maintain though.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id33" id="important-notes" name="important-notes">Important notes</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id34" id="si-block-vs-cache-block" name="si-block-vs-cache-block">{si-block} VS {cache-block}</a></h2>
<p>SI blocks are not a replacement for cache-blocks since there is
neither subtree_expiry nor a a complex key system.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id35" id="personnalized-pages" name="personnalized-pages">Personnalized pages</a></h2>
<p>It is not possible to usr SI blocks for personnalized pages.
If you do this all user will see the same page.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id36" id="setting-up-apache-for-ssi" name="setting-up-apache-for-ssi">Setting up Apache for SSI</a></h1>
<p>This extension is able to generate SSI markup however
Apache must be configure as described below. In order
to be able to use SSIs with eZ Publish, you need Apache 2.2.</p>
<div class="section">
<h2><a class="toc-backref" href="#id37" id="enabling-mod-filter" name="enabling-mod-filter">Enabling mod_filter</a></h2>
<p>Apache needs a specific module to be able to parse SSI markup on the fly once the HTML
content is generated.This module is call mode_filter.
The documentation is available at this URL <a class="reference" href="http://httpd.apache.org/docs/2.2/mod/mod_filter.html">http://httpd.apache.org/docs/2.2/mod/mod_filter.html</a>
This module is generally available with the default apache2 setup.
The only this you have to do is to execute the following command</p>
<pre class="literal-block">
a2enmod filter
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id38" id="enablig-mod-include" name="enablig-mod-include">Enablig mod_include</a></h2>
<p>This module makes it possible to parse SSI markup and is called
by mod_filter. Documentation for this module is available at this
URL : <a class="reference" href="http://httpd.apache.org/docs/2.0/mod/mod_include.html">http://httpd.apache.org/docs/2.0/mod/mod_include.html</a>
This module is generally available with the default apache2 setup.
The only thing you have to do is to execute the following command</p>
<pre class="literal-block">
a2enmod include
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id39" id="adding-mod-filter-rules" name="adding-mod-filter-rules">Adding mod_filter rules</a></h2>
<p>In your site VirtualHost you can simply copy/paste the following
configuration directive</p>
<pre class="literal-block">
FilterDeclare SSI
FilterProvider SSI INCLUDES resp=Content-Type $text/html
FilterChain SSI
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id40" id="specific-rewrite-rule" name="specific-rewrite-rule">Specific Rewrite Rule</a></h2>
<p>In order to be able to find and execute SSI calls you must add
the following RewriteRules in you site VirtualHost. This directive
must be at the top of other directives</p>
<pre class="literal-block">
Rewriterule ^/var/si-blocks/.* - [L]
</pre>
<p>Do not forget to reload Apache configuration once you are done.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id41" id="virtualhost-example" name="virtualhost-example">VirtualHost example</a></h2>
<p>Here is a complete example of a working VirtualHost that contains
all the needed mod_filter configuration directives.</p>
<pre class="literal-block">
<VirtualHost *>
ServerName site.com
DocumentRoot /var/www/site.com
<Directory /var/www/site.com>
# The +Includes options is needed to accept SSI markup parsing
Options Indexes FollowSymLinks +Includes
AllowOverride None
</Directory>
DirectoryIndex index.php
<IfModule mod_rewrite.c>
RewriteEngine On
# Rewriterule needed by ezsi, make sure to place it among the first rules after statement above
Rewriterule ^/var/si-blocks/.* - [L]
# *Here the rest of your eZ Publish rewrite rules should be*
RewriteRule .* /index.php
</IfModule>
FilterDeclare SSI
FilterProvider SSI INCLUDES resp=Content-Type $text/html
FilterChain SSI
</VirtualHost>
</pre>
</div>
</div>
</div>
</body>
</html>