Gentics CMS Documentation

Chapters

1. Configuration

   • General configuration

   • Internal and external forms

   • Available control types

   • Available block types

   • Control and block settings

   • Configurable Element Settings

   • Form flows

2. Implementation using Handlebars

3. Rendering and customizing with FormGen

4. E-mail template pages

5. Forms Frontend Rendering

   • Use pre-compiled Frontend FormGen

   • Download Sources & building

6. Redirect After Submission (successUrl)

   • Default Behavior

   • Behavior With Customized Flows

1 Configuration

In order to use the feature, it must be activated in the configuration:

feature:
	forms: true

Each form is based on a form type, which must also be configured. For each of these types, a list of available form fields and their properties must be created.

1.1 General configuration

1.2 Internal and external forms

Forms come in two kinds, internal and external, which are handled differently. Which kind a form is, is determined by its form type and configured per form type via the external flag (in combination with pluginName) in the General configuration above.

Internal forms are the forms managed by this feature: they are created and edited in the Editor and their submissions are processed by the configured Mesh plugin. This is the default, and all examples in this document are internal form types.

1.3 Available control types

1.4 Available block types

1.5 Control and block settings

1.6 Configurable Element Settings

This section describes what can be configured per element as defined in the formtype configuration (forms.yml).

1.6.1 Controls

1.6.1.1 number – Number Input Field

1.6.1.2 string – String Input Field

1.6.1.3 datetime – Datetime Input Field

1.6.1.4 time

Same as datetime but without the dateOnly setting:

1.6.1.5 boolean – Checkbox

1.6.1.6 catalog – Select

1.6.1.7 binary – File Upload

1.6.1.8 usermail – User EMail Field

Sends an email to the entered address after the form was submitted.

1.6.1.9 adminmail

Element to specify which admin mail addresses submission notifications should be sent to. If such an element is present in the form, the form’s email property is ignored, and the recipients are instead taken from the selected option keys (which are mapped to the configured mail addresses). When no adminmail element is present, mail sending falls back to the admin email configured on the form (email).

1.6.2 Blocks (structure / layout)

1.6.3 Other options (not per element – form-wide)

In addition, each form type defines options on the form level, e.g.:

• captchaOptions – selectable captcha variants offered when configuring the form’s spam protection (see the table below).

1.6.3.1 Captcha options (captchaOptions)

Each option is defined by a value (the identifier stored on the form) and a localized labelI18n.

1.7 Form flows

A form flow controls the sequence of screens a user is guided through when filling out a form — for example the form itself, an optional summary, and a final success screen. Each form type defines its flows in the flows list of the General configuration; the first entry is used as the default. A flow determines which screens are shown, which buttons appear on each screen, and which additional variables are passed to the screen components.

This allows the form process to be tailored to a project’s needs, for example:

• Show or hide individual buttons (such as a print button on the summary screen).
• Pass variables that enable additional behaviour in a screen (such as showing detailed information in the summary).
• Add or remove screens, for example by inserting a summary step before submission.

The example configuration below defines two flows for the generic type: a default flow leading straight from the form to the success screen, and a with_summary flow that inserts a summary screen in between.

A flow has the following top-level fields:

Each entry in steps describes a single screen:

Each entry in buttons describes a single footer button:

After this, the forms feature must be enabled for every node that should contain forms. Enable it per node in the Node Management tab of the administration interface, under the node’s Features.

Once the feature is enabled for a node, an additional Form Types tab appears for that node. Use it to assign the form types that should be available when creating forms in that node.

2 Implementation using Handlebars

For including forms into pages using Handlebars, a tagtype with two parts needs to be created:

The Handlebars Part should have the following template:

{{#gtx_form cms.tag.parts.form type="java"}}
    {{{this}}}
{{else}}
    {{gtx_i18n de="Kein Formular ausgewählt" en="No Form selected"}}
{{/gtx_form}}

For details on the gtx_form helper see Rendering with Handlebars

3 Rendering and customizing with FormGen

The forms configured above are rendered by FormGen. FormGen offers a wide range of configuration and customization options, such as custom form controls, lifecycle hooks, navigation buttons, overlays, screens and styling.

For all details on configuring and customizing the renderer, see the FormGen Customizing Guide

4 E-mail template pages

It is possible to create special pages in the CMS, which can be used as templates for mails, which are sent by forms (either admin mails or user mails).

The pages must be created from templates, which use the markup language Forms e-mail template and must render valid Handlebars code.

Those pages will be excluded from publishing, they will neither be written into the filesystem nor into a Content.Repository.

5 Forms Frontend Rendering

Forms are rendered on Client side with a provided React Component (=FormGen). The compiled JavaScript Application need to be part of your Portal so the Application can be included by the Forms-Directive. You have two Options:

• Download Pre-Compiled Ready to Use React-App and include in your portal
• Download Formgen Source Code and add it to your project for customization (build step required)

5.1 Use pre-compiled Frontend FormGen

You can download the builded Files from our Artifact-Server : https://repo.gentics.com/repository/maven-releases/com/gentics/cms/formgen/6.5.x/formgen-6.5.×.zip (use the correct CMS Version number) Or download it via maven dependency Plugin

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>3.6.1</version>
    <executions>
      <execution>
        <id>copy-formgen</id>
        <phase>prepare-package</phase>
        <goals>
          <goal>unpack</goal>
        </goals>
        <configuration>
          <artifactItems>
            <artifactItem>
              <groupId>com.gentics.cms</groupId>
              <artifactId>formgen</artifactId>
              <version>6.5.0</version>
              <type>zip</type>
              <outputDirectory>/formgen</outputDirectory>
            </artifactItem>
          </artifactItems>
        </configuration>
      </execution>
    </executions>
  </plugin>

Place the downloaded Files in /portal/public/cpa/formgen (portal-php) or /portal/data/static/cpa/formgen (portal-java)

5.2 Download Sources & building

You can download the source Files from our Artifact-Server : https://repo.gentics.com/repository/maven-releases/com/gentics/cms/formgen/6.5.x/formgen-6.5.x-src.zip (use the correct CMS Version number) Or also download it via maven dependeny Plugin (see step nefore), just add the src to the artifactItem

You can now customize FormGen (see the FormGen Customizing Guide).

5.2.1 Building

For Building you need node and npm. In the extracted source Folder run

npm ci
// and in apps/andp-ma-formgen
npm run build
//you get a dist/_expo/ containing the builded Formgen
//Place it in
//portal-java: /portal/data/static/cpa/formgen/_expo
//portal-php:  /portal/public/cpa/formgen/_expo

6 Redirect After Submission (successUrl)

A successUrl can be configured in the form properties to specify the page the user should be navigated to after successfully submitting a form.

6.1 Default Behavior

Because flows are individually configurable and an automatic redirect would restrict the flow execution, the navigation does not happen automatically. Instead, a button is displayed on the success screen whenever a successUrl is configured. The user must actively trigger the redirect by clicking the button.

This behavior is built into the default flow and requires no additional implementation.

6.2 Behavior With Customized Flows

If the flow is overridden or extended for a specific project, the default behavior no longer applies. In this case, the redirect logic must be implemented explicitly. Two options are available:

• Custom Elements: The logic for evaluating the successUrl and triggering the navigation is implemented directly within the custom element.
• Hook postSubmitForm: The redirect is handled via the postSubmitForm hook, which is called after the form has been submitted successfully.

In both cases, ensure that the successUrl is read from the form data and that the navigation is executed at the correct point in the flow.

.