Forms and the HST ActionURL

Overview

Bloomreach Content supports the Post-Redirect-Get (PRG) pattern for handling form submissions in the delivery tier. The PRG pattern consists of three steps:

1. The form is submitted to an action URL using the POST method.
2. The form component's doAction method processes the submitted data.
3. The server responds to the POST request with a redirect to the original form URL using the GET method.

This page explains how to implement the PRG pattern in Bloomreach Content form components.

Form Submission

To implement the PRG pattern, submit the form using the POST method to an action URL generated by the hst:actionURL tag.

In a JSP template:

<hst:actionURL var="actionLink" />
<form action="${actionLink}" method="post">
  <!-- form fields here -->
</form>
copy

In a Freemarker template:

<@hst.actionURL var="actionLink"/>
<form action="${actionLink}" method="post">
  <!-- form fields here -->
</form>
copy

The action URL is unique to the component that renders the form. Submitting to this URL ensures that the doAction method of the correct component is invoked. An example action URL:

/news?_hn:type=action&_hn:ref=r34_r1_r1

This URL triggers an action request to the /news path and invokes the doAction method of the component with reference r34_r1_r1 on that page.

Required Method: POST

Always use the POST method when submitting a form to a generated action URL:

<form action="${actionLink}" method="post">

In brXM 14, submitting a GET request to an action URL incorrectly triggers the doAction method. To prevent this in version 14.1.0 and later, set the following property in your HST configuration:

container.actionValve.method.post.only = true

This configuration rejects GET requests to action URLs with HTTP status 405 "Method Not Allowed", which is the recommended behavior.

Starting with brXM 15.0, rejecting GET requests at action URLs is enabled by default.

Processing Form Data

To process form submissions, override BaseHstComponent#doAction(HstRequest request, HstResponse response) in the component that renders the form.

Form data is available in a org.hippoecm.hst.component.support.forms.FormMap object. You can use static methods from org.hippoecm.hst.component.support.forms.FormUtils to work with form data.

To access submitted form fields, create a FormMap and specify the field names:

FormMap map = new FormMap(request, new String[]{"inputFieldName"});
copy

A FormMap contains FormField objects, each holding a field value. You can add validation error messages to both the FormMap and its FormField objects.

To persist the form data and any messages across the redirect, use:

FormUtils.persistFormMap(request, response, map, null);
copy

Persist form data only within the doAction method.

After doAction completes, the request is redirected to the original page URL. The form component's doBeforeRender method is then invoked as with any standard GET request.

Rendering Persisted Form Data

To access persisted form data in the doBeforeRender method, use the following pattern:

FormMap map = new FormMap();
FormUtils.populate(request, map);
copy

You can then pass the form data and messages to the templating engine. This allows you to render error messages, prepopulate form fields, or display submitted values for confirmation.

Sealing Form Data

When the form data is no longer needed, seal the FormMap to prevent further access:

map.setSealed(true);
copy

Form Data Storage

Form data is stored in the content repository under /formdata. Data retention policies vary by implementation, so form data is not removed automatically. Each FormData entry includes a timestamp. To remove old form data, use the Form Data Cleanup Repository Job.