Install Enterprise Forms HST Components

Add dependency to your site pom

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

Setup email session

If sending emails, you'll need to setup a mail session environmental variable. For Tomcat, add following lines to the context.xml file of your environment.

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

Configure annotated beans

In the site's web.xml, find the context-param hst-beans-annotated-classes and add the following value if it's not already there:

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

Template dependencies

The Enterprise Forms demo project contains examples for rendering a form based on an Enterprise Forms document. We recommend you copy them into your project and use them as a starting point for developing a template that meets the needs of your project. The demo project is deployed as a .zip file into Hippo's Maven repository. You can retrieve the demo project matching your project's version of Enterprise Forms from https://maven.onehippo.com/maven2-enterprise/com/onehippo/cms7/hippo-addon-eforms-demo/.

Depending on which templating engine your project uses, the following example templates are relevant:

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

Above templates depend on CSS and JS libraries found in

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

HST Component Customization

If you are linking to the form document (through hippo:mirror) from the mapped content document for instance, you'll need to create your own HstComponent like the following example:

public class MyEmailEformComponent extends EmailEformComponent {
    @Override
    public void doBeforeRender(final HstRequest request,
                               final HstResponse response)
                                         throws HstComponentException {
        super.doBeforeRender(request, response);
        // do your own stuff below....for example
        request.setAttribute("document", getContentBean(request));
    }

    /**
     * NOTE: you can override this method if you want to find a linked form
     * document in a custom way.
     */
    @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;
    }
}

NOTE: In this example, YourSpecialDocument is your specific document implementation (HippoDocument) which contains the link to Enterprise Forms document and #getFormBean() should be overriden to returns a valid FormBean in a custom way.

Custom Form or Field

You can use custom Form class or Field class to customize population or validation.

To use custom Form class, add your custom Form class by extending com.onehippo.cms7.eforms.hst.model.Form class like the following example:

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;
    }
}

In the example above, the custom form class just extends the default Form class and overrides #validate() method to validate the form in the server side.

Also, to use custom Field class, add your custom Field class by extending one of the default Field class such as com.onehippo.cms7.eforms.hst.model.DropDown class like the following example:

public class CustomDropDown extends DropDown {

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

        // Assume #retrieveDropDownOptionsFromSomewhere() method retrieves
        // data 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 the example above, the custom DropDown class just extends the default DropDown class and populate drop down option items by retrieving data from an external source.