Serve a Dynamic Resource
Introduction
Goal
Implement the business logic to serve a resource dynamically.
Use Cases
Sometimes a page component needs to implement business logic to serve a resource. Common use cases are:
- Provide the content rendered by the page component in an alternative downloadable format such as PDF, CSV, image or iCalendar.
- Provide data (e.g. in JSON format) used by an AJAX script in the component template.
This page explains how to implement business logic to serve a resource using the first use case, by adding an iCalendar file download link to the Events feature included in the library.
The Basics
The basic elements of resource serving are:
-
In the component's template the hst:resourceURL tag is used to generate a resource URL at which the resource can be requested. The attribute resourceId will be accessible in the component class.
Freemarker:<@hst.resourceURL resourceId='foo'/>
JSP:
<hst:resourceURL resourceId="foo"/>
-
The component's class implements the doBeforeServeResource method which performs the business logic required to serve the resource.
public void doBeforeServeResource(HstRequest request, HstResponse response) throws HstComponentException { ... } -
The component's resource template (additional to its regular template) renders the resource. The resource template is configured through the hst:resourcetemplate property on the hst:component configuration node.
Example
In this example you will extend the Events feature (available in the library) by adding to the event detail page the option to download the event as an iCalendar file (*.ics) that can be imported in most calendar applications. You will implement the doBeforeServeResource method to generate the iCalendar file on-the-fly.
Set Up Project
Create a project using the Maven archetype using the default values for all parameters.
Build and run the project and add the Events feature from the library.
Rebuild and restart the project.
Browse to http://localhost:8080/site/events.
Browse to one of the listed events' detail page. This is where you will add the iCalendar download link.
Add a Download Link to the Template
Locate the template used to render the event details and add an iCalendar event download link using the hst:resourceURL tag and resourceId parameter value "ics":
Freemarker
repository-data/webfiles/src/main/resources/site/freemarker/myhippoproject/eventspage-main.ftl
<p> <a href="<@hst.resourceURL resourceId='ics'/>">Download iCalendar</a> </p>
JSP
site/src/main/webapp/WEB-INF/jsp/myhippoproject/eventspage-main.jsp
<p>
<hst:resourceURL var="resourceURL" resourceId="ics"/>
<a href="${resourceURL}">Download iCalendar</a>
</p>
Extend EssentialsContentComponent and Implement doBeforeServeResource
Look at the configuration of the event page's main content component: /hst:hst/hst:configurations/myhippoproject/hst:workspace/hst:containers/eventspage/main/content.
The component class configured for this component is the standard Content component: org.onehippo.cms7.essentials.components.EssentialsContentComponent.
In your project's site module create a new class org.example.ICalendarEvent that extends EssentialsContentComponent, and override the doBeforeServeResource method.
In your doBeforeServeResource implementation:
- Check that the resourceID is "ics". If not set the response status to 404.
- Retrieve the event content bean and check that it is not null and that it is indeed an event document. If not set the response status to 404.
- Build a String containing the event's title, start date and end date in iCalendar format.
- Set the response content type to text/calendar.
- Put the iCalendar String in a request attribute ics.
For example:
package org.example;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import org.example.beans.EventsDocument;
import org.hippoecm.hst.content.beans.standard.HippoBean;
import org.hippoecm.hst.core.component.HstComponentException;
import org.hippoecm.hst.core.component.HstRequest;
import org.hippoecm.hst.core.component.HstResponse;
import org.onehippo.cms7.essentials.components.EssentialsContentComponent;
public class ICalendarEvent extends EssentialsContentComponent {
@Override
public void doBeforeServeResource(HstRequest request, HstResponse response) throws HstComponentException {
String resourceID = request.getResourceID();
if ("ics".equals(resourceID)) {
HippoBean bean = request.getRequestContext().getContentBean();
if (bean != null && bean instanceof EventsDocument) {
EventsDocument eventDocument = (EventsDocument) bean;
DateFormat format = new SimpleDateFormat("yyyyMMdd'T'HHmmss");
StringBuilder iCalString = new StringBuilder();
iCalString.append("BEGIN:VCALENDAR\n");
iCalString.append("BEGIN:VEVENT\n");
iCalString.append("DTSTAMP:").append(format.format(eventDocument.getDate().getTime())).append("\n");
iCalString.append("DTSTART:").append(format.format(eventDocument.getDate().getTime())).append("\n");
iCalString.append("DTEND:").append(format.format(eventDocument.getEndDate().getTime())).append("\n");
iCalString.append("SUMMARY:").append(eventDocument.getTitle()).append("\n");
iCalString.append("UID:").append(eventDocument.getIdentifier()).append("\n");
iCalString.append("END:VEVENT\n");
iCalString.append("END:VCALENDAR\n");
response.setContentType("text/calendar");
request.setAttribute("ics", iCalString.toString());
} else {
response.setStatus(404);
}
} else {
response.setStatus(404);
}
}
}
Add a Resource Template
Create a new template that reads the ics request attribute and simply renders its String content (which is already in iCalendar format).
It's also nice to render a simple HTML error page in case there is no ics attribute (the status code is already set to 404 in this case).
Freemarker
repository-data/webfiles/src/main/resources/site/freemarker/myhippoproject/eventspage-main-download.ftl
<#if ics??>${ics}<#else><html><body><h1>404 Not Found</h1></body></html></#if>
JSP
site/src/main/webapp/WEB-INF/jsp/myhippoproject/eventspage-main-download.jsp
<%@ include file="/WEB-INF/jsp/include/imports.jsp" %>
<c:choose>
<c:when test="${not empty requestScope.ics}">
<c:out value="${requestScope.ics}"/>
</c:when>
<c:otherwise>
<html>
<body>
<h1>404 Not Found</h1>
</body>
</html>
</c:otherwise>
</c:choose>
Create a new template configuration node /hst:hst/hst:configurations/myhippoproject/hst:templates/eventspage-main-download.
Set the hst:renderpath property to your template's location:
- Freemarker: webfile:/freemarker/myhippoproject/eventspage-main-download.ftl
- JSP: jsp/myhippoproject/eventspage-main-download.jsp
Freemarker
/hst:hst/hst:configurations/myhippoproject/hst:templates:
/eventspage-main-download:
jcr:primaryType: hst:template
hst:renderpath: webfile:/freemarker/myhippoproject/eventspage-main-download.ftl
JSP
/hst:hst/hst:configurations/myhippoproject/hst:templates:
/eventspage-main-download:
jcr:primaryType: hst:template
hst:renderpath: jsp/myhippoproject/eventspage-main-download.jsp
Configure the Component Class and Resource Template
Finally, wire everything together in the component configuration at /hst:hst/hst:configurations/myhippoproject/hst:workspace/hst:containers/eventspage/main/content.
Set the hst:componentclass property to your custom class org.example.ICalendarEvent.
Add the hst:resourcetemplate property and set it to your template eventspage-main-download.
/hst:hst/hst:configurations/myhippoproject/hst:workspace/hst:containers/eventspage/main/content: hst:componentclass: org.example.ICalendarEvent hst:template: eventspage-main hst:resourcetemplate: eventspage-main-download hst:xtype: hst.item
Done!
Rebuild and restart your project, browse to an event and download the iCalendar file! You should be able to import it in most calendar applications.