This module is part of the Apache Sling project.
The purpose of the module presented here is to replace dynamic generated components (eg. current time or foreign exchange rates) with server-side include tag (eg. SSI or ESI). Therefore the dispatcher is able to cache the whole page but dynamic components are generated and included with every request. Components to include are chosen in filter configuration using resourceType
attribute.
When the filter intercepts request for a component with given resourceType
, it'll return a server-side include tag (eg. <!--#include virtual="/path/to/resource" -->
for Apache server). However the path is extended by new selector (nocache
by default). This is required because filter has to know when to return actual content.
Components don‘t have to be modified in order to use this module (or even aware of its existence). It’s servlet filter, installed as an OSGi bundle and it can be enabled, disabled or reconfigured without touching CQ installation.
Add following dependency to your project:
<dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.dynamic-include</artifactId> <version>3.1.2</version> </dependency>
Filter is delivered as a standard OSGi bundle. SDI is configured via the configuration factory called SDI Configuration. Following properties are available:
<!-- SDI include (path: %s, resourceType: %s) -->
to every replaced componentServer-Agent=Communique-Dispatcher
header, added by the AEM dispatcher. You may enter just the header name only or the name and the value split with =
.Filter is incompatible with following types of component:
requestType
of the synthetic resource).If component do not generate HTML but eg. JS or binary data then remember to turn off Comment option in configuration.
In order to enable SSI in Apache with dispatcher first enable Include
mod (on Debian: a2enmod include
). Then add Includes
option to the Options
directive in your virtual configuration host. After that find following lines in dispatcher.conf
file:
<IfModule dispatcher_module> SetHandler dispatcher-handler </IfModule>
and modify it:
<IfModule dispatcher_module> SetHandler dispatcher-handler </IfModule> SetOutputFilter INCLUDES
After setting output filter open virtualhost configuration and add Includes
option to Options
directive:
<Directory /> Options FollowSymLinks Includes AllowOverride None </Directory> <Directory /var/www/> Options Indexes FollowSymLinks Includes AllowOverride None Order allow,deny allow from all </Directory>
It's also a good idea to disable the caching for .nocache.html
files in dispatcher.any
config file. Just add:
/disable-nocache { /glob "*.nocache.html*" /type "deny" }
at the end of the /rules
section.
In order to enable TTL on Apache with dispatcher just add:
/enableTTL "1"
to your dispatcher configuration.
Just add following lines at the beginning of the vcl_fetch
section in /etc/varnish/default.vcl
file:
if(req.url ~ "\.nocache.html") { set beresp.ttl = 0s; } else if (req.url ~ "\.html") { set beresp.do_esi = true; }
It'll enable ESI includes in .html
files and disable caching of the .nocache.html
files.
Dynamic Include Filter can also replace dynamic components with AJAX tags, so they are loaded by the browser. It‘s called JSI. In the current version jQuery framework is used. More attention is required if included component has some Javascript code. Eg. Geometrixx Carousel component won’t work because it's initialization is done in page <head>
section while the component itself is still not loaded.
There are two cases: the first involves including a component which is available at some URL, eg.
/content/geometrixx/en/jcr:content/carousel.html
In this case, component is replaced with include tag, and nocache
selector is added
<!--#include virtual="/content/geometrixx/en/jcr:content/carousel.nocache.html" -->
If the filter gets request with selector it'll pass it (using doChain
) further without taking any action.
There are also components which are created from so-called synthetic resources. Synthetic resource have some resourceType and path, but they don't have any node is JCR repository. An example is
/content/geometrixx/en/jcr:content/userinfo
component with foundation/components/userinfo
resource type. These components return 404 error if you try to make a HTTP request. SDI recognizes these components and forms a different include URL for them in which resource type is added as a suffix, eg.:
/content/geometrixx/en/jcr:content/userinfo.nocache.html/foundation/components/userinfo
If filter got such request, it'll try to emulate <sling:include>
JSP tag and includes resource with given type and nocache
selector:
/content/geometrixx/en/jcr:content/userinfo.nocache.html
Selector is necessary, because otherwise filter would again replace component with a SSI tag.
Sling Dynamic Include donated to the Apache Sling project (SLING-5594), repackaged and released (SLING-6301)
#17 Support for time-based (TTL) caching, Dispatcher 4.1.11+ required