The Form Generator plugin is not included with Gentics Mesh by default. In this article, you will learn how to configure this functionality.

Enable Forms plugin

The Forms feature is enabled by default in Gentics Portal | php, which proxies requests to the Mesh Forms Plugin. Public endpoints from http://<portal>/api/forms/(.*) will be passed to http://<mesh>/api/v1/<project-name>/plugins/forms/ and the portal’s route path will be removed from the request, also if a user is logged in the token will be passed with the request. Generally, these endpoints should be used from client-side scripts, so the Gentics Portal | php side configuration is automatically done this way.

Because the plugin is not included by default with Gentics Mesh, please contact our Team.

Render forms from views

The recommended way to render forms is to use the renderForm helper in a view. This helper will insert the necessary markup to load the FormGen React Native app (see FormGen Customizing for details) which in turn renders the form.

renderForm helper

@renderForm('<formUuid>')

To render an existing but not yet completely filled form you can pass the form cookie value as an option. The Form Generator feature loads the $COOKIE_NAME cookie (default: fg-data) into all views into the $fgCookie variable. This variable contains the cookie name ($fgCookie['key']) and the cookie value ($fgCookie['value']). The @renderForm helper supports passing options, like this cookie value:

With static variables:

@renderForm('<formUuid>', ['forms-data' => '<cookieValue>'])

With passed variables (assuming you have a formUuid field on your node):

@renderForm($node['fields']['formUuid'], [$fgCookie['key'] => $fgCookie['value']])

It is also possible to add the language for the form via the language variable: With static variables:

@renderForm('<formUuid>', ['forms-data' => '<cookieValue>', 'language' => 'de'])

Since Gentics CMP supports different types of forms, the parameters pluginName and externalId are used to specify the Mesh plugin that will handle requests for the form (with forms being the Mesh Forms plugin): With static variables:

@renderForm('<formUuid>', ['pluginName' => 'forms', 'externalId' => '<externalFormId>'])

New versions of the Mesh forms plugin support poll forms and adding a template context to customize rendering. The template context will be concatenated with the base template path configured in the plugin, and if a needed template is found in this path it is prioritized over generic templates. With static variables:

@renderForm('<formUuid>', ['templateContext' => 'customFormTheme'])

When rendering poll forms, the plugin will render the results, only if it determines that the user already participated in that poll. Rendering the results can also be forced by setting the showResults option:

Example:

@renderForm('<formUuid>', ['showResults' => true])

Disable caching for any page that uses renderForm (or fgRender) directive: Add 'renderForm' to portal.php config in cache.http.exceptions.

Example:

'cache' => [
        //[...]
        'http' => [
            //[...]
            'exceptions' => [
                'renderForm',
            ]
        ]
    ],

Rendering submitOnce results

Forms with the flag submitOnce set (which is for example used for poll forms, which a user can fill out once and then only sees the results of the poll) are rendered using a blade template that is configurable under forms.pollResultsTemplate in config/portal.php. The default path is forms/form, which means the blade template must be in the directory resources/views/forms and have the filename form.blade.php. A simple example for such a template, can be found in the Implementation guides.

FormGen app

The FormGen app must be built and placed in the directory configured under forms.staticFileDirectory in config/portal.php (which defaults to the path public/static/cpa/). For more information on the FormGen app see FormGen Customization. The app app is served under the path configured as forms.staticServePath which defaults to the path /static/cpa/.