Install Enterprise Forms HST Components

This guide describes how to install and configure Enterprise Forms HST components in your Bloomreach Content project.

Add Dependencies to Your Site Webapp POM

Add the following dependencies to your site/webapp/pom.xml file:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-eforms-hst</artifactId>
</dependency>
<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-eforms-hcm-site</artifactId>
</dependency>

Set Up Email Session

To enable email functionality, configure a mail session as an environment variable. For Tomcat, add the following resource definition to your context.xml file:

<Resource name="mail/Session"
          auth="Container"
          type="javax.mail.Session"
          mail.smtp.host="your.smtp.host (e.g. localhost)"/>

Replace your.smtp.host with your SMTP server address.

Configure Annotated Beans

In your site's web.xml, locate the hst-beans-annotated-classes context parameter. Add the following value if it is not already present:

<context-param>
  <param-name>hst-beans-annotated-classes</param-name>
  <param-value>[existing-entries],
               classpath*:com/onehippo/**/*.class</param-value>
</context-param>

This configuration enables annotation scanning for the required classes.

Template Dependencies

The Enterprise Forms demo project includes example templates for rendering forms based on Enterprise Forms documents. Use these templates as a starting point for your own implementation.

The demo project is available as a .zip file in the Bloomreach Enterprise Maven repository. Access requires an Enterprise Maven Repository account. Download the demo project that matches your Enterprise Forms version from https://maven.bloomreach.com/service/rest/repository/browse/maven2-enterprise/com/onehippo/cms7/hippo-addon-eforms-demo/.

Select the relevant example templates based on your templating engine:

FreeMarker

site/src/main/webapp/WEB-INF/ftl/eforms/eforms-default.ftl
site/src/main/webapp/WEB-INF/ftl/eforms/eforms-validation-default.ftl
site/src/main/webapp/WEB-INF/ftl/lib/eforms-field-renderer.ftl

JSP

site/src/main/webapp/WEB-INF/jsp/eforms/eforms-default.jsp
site/src/main/webapp/WEB-INF/jsp/eforms/eforms-validation-default.jsp
site/src/main/webapp/WEB-INF/tags/eformsrenderfield.tag

These templates reference CSS and JavaScript resources located in:

site/src/main/webapp/css/
site/src/main/webapp/js/

Note: Starting with version 3.0.1, the Date form field supports specifying a time. The demo project uses jQuery's datetimepicker plugin. Minified JS and CSS for this plugin are included in the directories above.

HST Component Customization

If your content document links to a form document (for example, using hippo:mirror), implement a custom HstComponent. The following example demonstrates how to extend the default behavior:

public class MyEmailEformComponent extends EmailEformComponent {
    @Override
    public void doBeforeRender(final HstRequest request,
                               final HstResponse response)
                                         throws HstComponentException {
        super.doBeforeRender(request, response);
        // Custom logic
        request.setAttribute("document", getContentBean(request));
    }

    /**
     * Override this method to locate a linked form document using custom logic.
     */
    @Override
    public FormBean getFormBean(final HstRequest request) {
        final HippoBean bean = getContentBean(request);

        if (bean == null) {
            return null;
        }

        if (bean instanceof YourSpecialDocument) {
            final YourSpecialDocument document = (YourSpecialDocument) bean;
            return document.getFormBean();
        }

        log.warn("* Bean found is *not* a form document bean");

        return null;
    }
}

In this example, replace YourSpecialDocument with your specific document implementation (HippoDocument) that contains the link to the Enterprise Forms document. Override getFormBean() to return a valid FormBean as required by your use case.

Component Parameters

Enterprise Forms components provide default values for most parameters. You can override these by setting hst:parameternames and hst:parametervalues on your component. Common parameters include:

eforms-from-email (e.g., user@example.com)
eforms-from-name (e.g., Foo Bar)
eforms-to-name (comma-separated, e.g., some name, another name)
eforms-to-email (comma-separated, e.g., user1@example.com, user2@example.com)
eforms-subject (e.g., This is my form)
eforms-body-html (Freemarker or Velocity template containing dynamic HTML)
eforms-mailsession (e.g., myMailSessionName)
eforms-use-freemarker (e.g., true)

Custom Form or Field

You can customize form population or validation by implementing a custom Form or Field class.

To use a custom Form class, extend com.onehippo.cms7.eforms.hst.model.Form as shown below:

public class CustomForm extends Form {
    public CustomForm(FormBean bean, FormContext ctx) {
        super(bean, ctx);
    }

    @Override
    public List<ErrorMessage> validate(final boolean action,
                                       final FormMap formMap,
                                       final HstRequest request) {
        List<ErrorMessage> errorMessages = super.validate(action,
                                                          formMap,
                                                          request);

        FormField studentIdField = formMap.getField("student_id");

        if (studentIdField == null) {
            errorMessages.add(new ErrorMessage(
                              "formbuilder.validation.required",
                              "student_id",
                              "You can use '12345' or '67890' in this demo."));
        } else {
            if (!"12345".equals(studentIdField.getValue())
                && !"67890".equals(studentIdField.getValue())) {
                errorMessages.add(new ErrorMessage(
                            "formbuilder.validation.required",
                             "student_id",
                             "You can use '12345' or '67890' in this demo."));
            }
        }

        return errorMessages;
    }
}

This example extends the default Form class and overrides the validate() method to perform server-side validation.

To use a custom Field class, extend a default Field class such as com.onehippo.cms7.eforms.hst.model.DropDown:

public class CustomDropDown extends DropDown {

    public CustomDropDown(DropdownBean bean, Form form) {
        super(bean, form);

        // Retrieve dropdown options from an external source.
        List<String>[] valuesAndTexts = retrieveDropDownOptionsFromSomewhere();

        setValues(valuesAndTexts[0]);
        setDisplayValues(valuesAndTexts[1]);
    }

    @SuppressWarnings("unchecked")
    private List<String>[] retrieveDropDownOptionsFromSomewhere() {
        List<String> values = Arrays.asList("graduate", "teacher");
        List<String> displayValues = Arrays.asList("Graduate Certificate",
                                                   "Teacher Certificate");
        return new List[] { values, displayValues };
    }
}

In this example, the custom DropDown class retrieves dropdown option items from an external source and populates the field accordingly.