Gentics CMS Documentation

Chapters

1. Configuration

   • General configuration

   • Form-Type Configuration

   • Element Configuration

   • Element settings

   • Setting conditions

   • Aloha Configuration

   • Form flows

2. Translations

3. Implementation using Handlebars

4. Rendering and customizing with FormGen

5. E-mail template pages

6. Forms Frontend Rendering

   • Use pre-compiled Frontend FormGen

   • Download Sources & building

7. 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 elements and their settings must be created.

Elements in the context of forms are defined as things an editor can place into the form. These come in two types: Controls and Blocks.

Controls are Elements, the frontend user can interact with and which stores/handles form data. Blocks on the other hand are only for visual extras to the form, such as extra description texts or grouping of elements.

1.1 General configuration

The general configuration for the forms is defined the following way:

forms:
  formGenTranslations:
    form_loading:
      en: "Loading ..."
    custom_key:
      en: "Example"
  types:
    generic:
      nameI18n:
        en: Generic Type
      # See below for all options
    otherType:
      nameI18n:
        en: Another Type

1.2 Form-Type Configuration

1.2.1 FormGen settings

Settings under pluginConfiguration.formgenSettings are passed on to FormGen. Currently supported:

forms:
  types:
    generic:
      pluginConfiguration:
        formgenSettings:
          maxFileSizeToPreviewMB: 5

1.2.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.2.3 Captchas

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

1.3 Element Configuration

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

The following Properties are available for all settings:

1.3.1 Default Control-Types

The following controls are supported with the default FormGen app:

In the following sections, there’s an overview of the settings each control-type supports.

1.3.1.1 string control

The Validation object has the following properties

Example:

forms:
  types:
    example:
      controls:
        string:
          labelI18n:
            de: String Beispiel
            en: String example
          settings:
            - id: defaultValue
              type: string
              labelI18n:
                de: Standardbefüllung
                en: Default value
              backend: true
            - id: maxLength
              type: number
              labelI18n:
                de: Maximallänge
                en: Maximum Length
              backend: true
              propertyPath: validation.maxLength
            - id: validation
              type: select
              labelI18n:
                de: Validierung
                en: Validation
              backend: true
              propertyPath: validation.regexValidation
              options:
                - value:
                    key: "email"
                    regex: "^(([^<>()\\[\\]\\\\.,;:\\s@\"]+(\\.[^<>()\\[\\]\\\\.,;:\\\
                      s@\"]+)*)|(\".+\"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\\
                      .[0-9]{1,3}])|(([a-zA-Z\\-0-9]+\\.)+[a-zA-Z]{2,}))$"
                    errorMessage:
                      de: "Das soll ne eMail Adresse sein?"
                  labelI18n:
                    de: "E-Mail"
                    en: "Mail"

1.3.1.2 number control

Example:

forms:
  types:
    example:
      controls:
        number:
          labelI18n:
            de: Nummer Beispiel
            en: Number example
          settings:
            - id: defaultValue
              type: number
              labelI18n:
                de: Standardbefüllung
                en: Default value
              backend: true
            - id: minValue
              type: number
              labelI18n:
                de: Minimalwert
                en: Minimum value
              backend: true
              propertyPath: validation.minValue
            - id: maxValue
              type: number
              labelI18n:
                de: Maximalwert
                en: Maximum value
              backend: true
              propertyPath: validation.maxValue

1.3.1.3 datetime control

Example:

forms:
  types:
    example:
      controls:
        number:
          labelI18n:
            de: Nummer Beispiel
            en: Number example
          settings:
            - id: defaultValue
              type: date
              labelI18n:
                de: Standardbefüllung
                en: Default value
              backend: true
            - id: dateOnly
              type: boolean
              labelI18n:
                de: Nur datum
                en: Date only
              backend: true

1.3.1.4 time control

Same as datetime but without the dateOnly setting:

1.3.1.5 boolean control

1.3.1.6 catalog control

1.3.1.7 binary control

1.3.1.8 usermail control

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

1.3.1.9 adminmail control

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.3.1.10 aggregate control

An special element which creates a sub-form, where multiple entries can be created/submitted, aggregated under one common name.

An example would be, a list of attendees for an event, where each attendee has and input for firstName, lastName, and email. The aggregate would hold info for the three controls, but these can be entered n times, and the reports receives a single list value with all the attendees.

1.3.1.11 lazyCatalog control

Special catalog component, which primarily works the same. The main difference is where it loads the options from. This is mainly used for conditional options, where the evaluation for these options is handled in the backend, so no special configuration is required here. For all catalog settings, see the regular catalog control.

1.3.1.12 reference control

Special catalog component, which requires a search input, and the options are searched in the backend. Options are references to elements within Acta-Nova, the user has access to.

For all catalog settings, see the regular catalog control.

1.3.2 Default Block-elements

1.3.2.1 spacer block

Simply an empty block, used to create space between elements.

1.3.2.2 group block

A simple container element, which groups elements together. If the group has a display condition which isn’t met, all child-elements won’t be rendered either. This can be used to manage element conditions in a more central way, Instead of having to set the condition on each element individually.

1.3.2.3 text block

A simple block element which renders the text content which was entered.

1.3.2.4 conditionalcontainer block

Deprecated: The same as group, just here for compatibility reasons. Use group if possible.

1.3.2.5 sectionheadline block

Mainly the same as text, except that the text content is always escaped (i.E. no richContent), and put in a <h2> element.

Deprecated: Use the text block instead with custom formatting.

1.4 Element settings

A setting is simply a property of the element, which an editor can change. Settings are defined on each element configuration individually and can be configured to your projects needs.

The following setting types are available

Each setting has the following properties:

1.4.1 string setting

String settings have the following additional properties

1.4.2 translation setting

Shares the properties with string, except that there’s no multiple property.

1.4.3 date setting

Date settings have the following additional properties

1.4.4 select settings

Select settings have the following additional properties

1.4.5 options setting

Option settings have the following additional properties

1.4.6 user setting

User settings have the following additional properties

1.4.7 reference setting

1.5 Setting conditions

Settings may not always be relevant, and can be hidden with conditions. Only when a condition resolves to true, the setting may be displayed. Conditions are identified by their unique property key, to make writing/reading them as straight forward as possible.

Conditions are separated into two groups:

• Modifier Condition
• Source Condition

Modifier conditions are the three basic operations or, and, and not. Meanwhile, source conditions require a source element, from where the value is get and to match the actions against.

The list of source conditions and a description on how to use them:

1.5.1 Source Types

Sources are also defined by the unique key, and work the following way

1.5.2 Conditions Example

condition:
  and:
    - not:
        equals: true
        source:
          setting: foobar1
    - or:
      - empty: true
        source:
          control: otherSetting
      - biggerThan: 15
        source:
          control: attendeeCount

1.6 Aloha Configuration

Configuration for string or translation settings, which only works when the richContent (aka. AlohaEditor itself) is enabled for the setting. The Configuration is then applied to that single setting alone.

Example configuration:

text:
  labelI18n:
    de: "Text"
    en: "Text"
  settings:
  - type: "translation"
    id: "text"
    labelI18n:
      de: "Text"
      en: "Text"
    required: false
    backend: false
    richContent: true
    aloha:
      plugins:
        - "common/format"
        - "common/link"
        - "common/list"
      settings:
        plugins:
          format:
            config: ['b', 'i']

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:

1.7.1 Flow variable showProgress

The progress display shows the user which page of a multi-page form is currently open and allows navigating between the already visited pages. It is rendered above the form on the web platform and only if the form actually has pages.

Whether the progress display is shown can be controlled per flow step with the showProgress variable:

The value may be configured either as a real boolean (true / false) or as the string "true" / "false"; both are interpreted the same way. Any other value is treated as if the variable were not configured at all.

If showProgress is not configured, the screen type of the step decides:

If showProgress is configured, only the configured value counts — the screen type is then not taken into account.

The following example shows a success screen that — contrary to the default — also displays the progress:

- buttonLabelTranslationKey: form_flow_btn_success
  reactClass: SuccessScreen
  nameTranslationKey: form_flow_name_success
  descriptionTranslationKey: form_flow_desc_success
  buttons: []
  variables:
    - name: showProgress
      value: true

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 Translations

Translations can be managed in two ways: Globally or per Type. Usually all common translations are managed globally, and if a type has some additional translations, then these are added per type.

Configuration for these is quite simple: Create a property `formGenTranslations` under `forms` for a global configuration, and `formGenTranslations` under `forms.types.` for a type specific one.

Each key under the `formGenTranslations` property is then the translation key, and has a translation object as a default value. The translations themself are managed via a custom tool in the CMS.

Example:

forms:
  formGenTranslations:
    global_translation_key_1:
      de: Beispiel 1
      en: Example 1
    global_translation_key_2:
      de: Beispiel 2
      en: Example 2
  types:
    generic:
      formGenTranslations:
        generic_type_translation_key_1:
          de: Typen specifische übersetzung 1
          en: Type specific translation 1

3 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

4 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

5 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.

6 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)

6.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)

6.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).

6.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

7 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.

7.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.

7.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.

.