FirstSpirit™ FormEdit

e-Spirit AG

2018-12-13
Table of Contents

1. Introduction

The FirstSpirit™ FormEdit module consists of an editorial component for the creation of web forms using the FirstSpirit SiteArchitect or ContentCreator and a web component in the form of a servlet, which accepts and processes data entered by the user.

1.1. Overview of the functions

The following forms of processing of form data are supported:

Save the data in a file in CSV format
This type of processing saves all values sent by the form within a freely definable file in CSV format.
Save the data in a JDBC-compatible database
By using this type of processing, it is possible to save the values within a database. The configuration setting can be used to define individual mapping for the form fields.
Dispatch the data as an e-mail
With this type of processing, any form data can be sent by e-mail. The e-mail layout can be individually designed by means of an e-mail template. Among other things, the e-mails can be sent with file attachments, and cc and bcc recipients are also possible.
Output of the data in the log file of the servlet engine
This function is used to output all values of the form within the log files of the servlet engine, in which the FormServlet is initialised.
Calling a URL with parameter passing
This function enables a URL with the defined parameters to be called, without the user seeing this page in the browser. (e.g. tracking)

Further, it is possible to evaluate the forms via your own implementations. The processing methods named above can also be combined with each other.

1.2. Layout and function

The following graphic shows the module’s layout and how it functions using the example of the live server. The web and application servers used in FirstSpirit are used for use of the module within the preview or staging.

Layout and function
Figure 1. Layout and function


1.3. Technical Requirements

The FormEdit module has the following technical requirements:

  • FormEdit module in the current version
  • FirstSpirit (Isolated- oder Legacy-Mode) 5.2.181007 or higher
  • a current Servlet Container

2. Installation and Configuration

FirstSpirit™ FormEdit is installed in three steps:

2.1. Module installation

Use the fsm file supplied to add the module on the FirstSpirit server. To install the module, open the ServerManager and select Server propertiesModules.

Module management in the server properties
Figure 2. Module management in the server properties


The main panel contains a list of modules installed on the FirstSpirit server. After clicking Install, select the fsm file supplied with the module and click Open to confirm your selection. After successful installation, the module is added to the list and must be given All permissions (see figure Module management in the server properties).

The project application FS FormEdit ProjectConfiguration, the web application FS FormEdit, and the library FS FormEdit Scripts are parts of the FirstSpirit™ FormEdit module.

The Project Application provides media, page, section, script and table templates which can be used to design forms. The component is Visible for the Project area. It is therefore a project locale component. This can be added following installation of the project component within the required projects.

The web application provides servlets, which can be used and called within the project. The component is Viewable for the ProjectWeb areas. It is therefore a web locale component. This can be added to the different web areas (preview, staging, live, ContentCreator) within the required projects following installation.

The library provides the classes that are used from within the provided scripts.

After any module installation or update, the FirstSpirit server needs to be restarted.

2.2. Installation and configuration of the project component

A project-specific configuration is required in order to use the FirstSpirit™ FormEdit module. It is set up using the project component, which must be added to the project being used. To add the project component, open the ServerManager and select Project propertiesProject components.

Project components in the project properties
Figure 3. Project components in the project properties


A list of all existing project components is displayed in the main panel. Click Add, then select the FS FormEdit ProjectConfiguration and click OK to confirm your selection. The project component is then added to the list in the main panel and will need to be configured (see figure Project components in the project properties). To configure the project component, select the entry in the list and click Configure to open the associated dialog (see figure Configuration dialog for the project component).

Configuration dialog for the project component
Figure 4. Configuration dialog for the project component


Select a database layer from the Schema combobox and click Import templates. The selection list contains all database layers approved for the project. If you have not used any layers to date, or if you want to use your own database for the module, select New layer. If this option is selected, a new layer is generated, which points to FirstSpirit’s internal Derby database.

For further information on database layers, please refer to the FirstSpirit Manual for Administrators.

After you have clicked the Import templates button and close the dialog, it is not possible to make any more changes to the configuration. Renewed importing is only possible by means of Delete and renewed Add of the project component.

2.3. Installation and configuration of the web component

A web component needs to be added in addition to the project component. To add a web component, open the ServerManager and select Project propertiesWeb components.

Web components in the project properties
Figure 5. Web components in the project properties


Inside the main panel, four tabs are visible. Each tab contains a list of the existing web components. For each tab, click Add, select FS FormEdit, and click OK to confirm. Then install and activate the web component on an active web server. The server can be selected using the selection box. The web component is then added to the list in the main panel for all four tab pages.

After adding them to a web area, it is possible to configure the components; either with the web.xml generated by the component or a generic GUI (see figure Configuring the web application).

Configuring the web application
Figure 6. Configuring the web application


Different parameters are available for configuring:

OK Redirect
Use this field to specify the path to the file displayed following successful sending of the form data. This value is used if a special page was not given in the form (see Chapter form-start). The forwarding behaviour can be influenced using the redirect: or forward: prefix. forward:ok.jsp, for example, would generate forwarding with all parameters to the page ok.jsp. If neither forward: nor redirect: is given, redirect always takes place.
Error Redirect
Use this field to specify the path to the file displayed following incorrect sending of the form data. This value is used if a special page was not given in the form (see Chapter form-start). The forwarding behaviour can be influenced using the redirect: or forward: prefix. forward:error.jsp, for example, would generate forwarding with all parameters to the page error.jsp. If neither forward: nor redirect: is given, redirect always takes place.
Form Encoding
Use this field to specify the encoding to be used for sending the form data. This is also a retrieval (fall-back)) value, if no encoding was given in the configuration of a processing component. Examples are UTF-8 or ISO-8859-1.

Always ensure that the encoding chosen matches the encoding used in the generated pages (MetaTags or encoding of the language in the ServerManager).

Path Prefix
Use this field to specify a prefix, which is placed in front of the path to the mail template, in order that it can be used. This prefix describes the partial path between the WebApp root and the folder created by FirstSpirit. For example, for the staging environment, this would be the schedule ID.
Loggers.ini Path

The path to the configuration file fs-formlogger.ini must be given in this field. If this field is empty, or if the file cannot be found, an empty configuration file is used.

Staging example

2708/de/conf/fs-formlogger.ini

The schedule ID – here 2708 – is placed in front of the path for the staging environment.

Live example

de/conf/fs-formlogger.ini

The path to be given here can also be given as an absolute value. This example searches for the file relative to the WebAppRoot.

Captcha Width
Use this field to determine the display width of the Captcha graphic in pixels. If this field is empty, an internal retrieval value of the servlet is used: 100.
Captcha Height
Use this field to determine the display height of the Captcha graphic in pixels. If this field is empty, an internal retrieval value of the servlet is used: 100.
Captcha Chars
Use this field to specify the number of characters displayed in the Captcha graphic. If this field is empty, an internal retrieval value of the servlet is used: 6.

2.4. Live-server side logging

For easier error analysis the FirstSpirit™ FormEdit module can log some information to an appropriate logfile. This logging uses the log4j2 framework. Therefore it is necessary to configure log4j2 for your webapplication accordingly, in case this wasn’t done before. Configuring log4j2 happens by putting the log4j2 configuration file log4j2.properties into the WEB-INFclasses directory. In case this directory doesn’t exist, it can be added manually.

An exemplary log4j2 configuration file could look in the following way:

status = error
dest = err
name = PropertiesConfig

property.filename = target/rolling/rollingtest.log

filter.threshold.type = ThresholdFilter
filter.threshold.level = debug

appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %m%n
appender.console.filter.threshold.type = ThresholdFilter
appender.console.filter.threshold.level = error

appender.rolling.type = RollingFile
appender.rolling.name = RollingFile
appender.rolling.fileName = ${filename}
appender.rolling.filePattern = target/rolling2/test1-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n
appender.rolling.policies.type = Policies
appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
appender.rolling.policies.time.interval = 2
appender.rolling.policies.time.modulate = true
appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
appender.rolling.policies.size.size=100MB
appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.max = 5

logger.rolling.name = de.espirit.firstspirit.opt.formedit
logger.rolling.level = debug
logger.rolling.additivity = false
logger.rolling.appenderRef.rolling.ref = RollingFile

rootLogger.level = info
rootLogger.appenderRef.stdout.ref = STDOUT

Please consider that depending on the configuration the logfile may also contain information from other modules.

3. Configuration of the FirstSpirit Project

For this section, it is assumed that the reader is familiar with handling FirstSpirit Data sources (content).

The various process options of the form data are configured in the project by so-called loggers. Each logger is assigned a specific processing type (e.g. MailLogger) and appropriate parameters. The various loggers are maintained as data sets (content store data) in a data source (content). The logger configuration file fs-formlogger.ini is generated on the basis of the logger configuration. The content schema and table templates necessary for this are generated on installation of the project component. To create loggers, it is now only necessary to create content for the table template form_edit.formLogger. For information on the logger types and their configuration options, please refer to Chapter Logger configuration of the processing.

Please ensure you set mapping for the missing languages within the table template form_edit.formLogger. (On delivery, only German is mapped.) Additional columns with _<language abbreviation> should be created for the language-dependent formLogger_description column.

3.1. Creating the logger

Open the project in SiteArchitect. There are now two options for creating or editing the logger:

  • directly via the content (content: FormLogger) in the Content Store