FirstSpirit™ FormEdit

The following forms of processing of form data are supported:

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

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.

Figure 1. Layout and function

The FormEdit module has the following technical requirements:

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

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 Project → Web 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.

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 properties → Project components.

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

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.

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

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

Figure 6. Configuring the web application

Different parameters are available for configuring:

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-INF → classes 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

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

Clicking the New Entry button in the content view or in the input component within the formstart section to open the following form:

Figure 9. Creating the logger

All logger-specific data is entered in this form:

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.

Configuring log file processing

Configuring CSV processing

Configuring database processing

Configuring e-mail processing

Configuring URL processing

This page template is a functional example template. It is also possible to check data against a database or similar.

This configuration file contains all the information of your forms or assignment to the processing configurations and these configurations themselves. The content of this file is generically generated by FirstSpirit during generation.

In order for this file to be correctly generated, a page based on the logger-ini-file template must be created in the Page Store, and the object ID of the form start template, or the templates generated by you which fulfil the function of the form start template, must be entered on this page. The ID is displayed with the keyboard shortcut ALT + P in the selected section template

Figure 20. fs-formlogger.ini page

When referencing in the structure, note that the file is filed in the place given when configuring the web component. Further, the file name of the page must be correctly set in the Site Store. The name fs-formlogger is used within this document:

Figure 21. File name of the configuration file

Furthermore the configurations of the FormEdit-Forms that were created in the project are store in the fs-formlogger.ini, so that they can be read from the webserver. This leads to the fact that the webapplication needs to be restarted, as soon as there are changes in the configuration of a form (form_start section) and the deployment was successful. The servlet will then be able to read the changed configuration.

The section template form-start introduces a new form. The basic configurations, which solely concern this form, can be made here.

Figure 23. form-start section

Any number of form elements can be created within a form-block element. The order of the components is irrelevant for the form’s ability to function. Each component can be individually configured. For example, stylesheet classes can be used and the display width and height of the form defined. For precise information and configuration examples, please refer to Chapter Available form elements.

Figure 24. form-block section

The form-divider element generates a graphic separation within the form and otherwise has no function.

The form-end section template defines the end of the form.

Figure 25. form-end section

The form editor enables the editor to use the complete set of HTML form elements. As already mentioned, before using the components it is advisable to make an adjustment to the HTML source code together with the stylesheet file. In this way, individual design templates can be adhered to and are available on the whole of the web page. However, the HTML tags of the form elements should not be affected by the changes, to ensure correct function of the JavaScript checks.

To add a new form element, select an already created section of the type form-block and add a new form element to the content area list:

Figure 26. Form elements

The following gives an overview of the available standard elements and their configuration options and functions.

4.5.1. Form component text

This component provides the user with a form text field. The component must be assigned a designator which is unique in this form (name attribute), so that the evaluation of the form and check of its content can work properly.

Labelling

Use this text field to enter the title of the form field.

Unique identifier (name attribute)

Use this text field to enter the unique identifier.

Default selection (value attribute)

Use this text field to enter text with which the form field is filled.

Allow editing (readonly attribute)

This radio button is used to control whether the user may edit the form field or not.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid data.

Number of characters (maxlength attribute)

This text field can be used to define the maximum number of characters that can be entered.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 27. Form component text

4.5.2. Form component textarea

The textarea form component provides a multi-line text input field for the user. The component must be assigned a designator which is unique in this form (name attribute), so that the evaluation of the form and check of its content can work properly.

Labelling

Use this text field to enter the title of the form field.

Unique identifier (name attribute)

Use this text field to enter the unique identifier.

Default selection (value attribute)

Use this text field to enter text with which the form field is filled.

Allow editing (readonly attribute)

This radio button is used to control whether the user may edit the form field or not.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid data.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 28. Form component textarea

4.5.3. Form component RadioButtons

This form component can be used to generate HTML radio buttons. On adding the radio buttons in the Options area, ensure that a meaningful default is given for each radio button. The radio buttons are shown with their corresponding designation (labelling), one after the other on the right-hand side of the component.

subcomponent RadioButtons

This component can be added within a form-block section. The values which are the same for all radio buttons are set in this section. The actual RadioButtons are added within a ContentAreaList in this section.

Labelling

Use this text field to enter the title of the form field.

Group identifier (name attribute)

Use this text field to enter the unique identifier.

Content check (filled)

This radio button can be used to create a check which checks whether an entry has been selected.

Mandatory field note

A message which appears if the content check fails must be given for this type of form field.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 29. Form component radiobuttons

subcomponent RadioButton

This component can only be used within the form RadioButtons component. It is used to add the actual radio buttons within the component named above.

Labelling

Use this text field to enter the labelling of the option.

Value (value attribute)

Use this text field to enter the value for this option.

Preselection (checked attribute)

These radio buttons can be used to make a preselection, whether this form field should be selected or not.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 30. Form component radiobutton

4.5.4. Form component Checkboxes

This form component can be used to generate HTML checkboxes. When adding the checkboxes in the Options area it is necessary to ensure that a meaningful value is given for each checkbox. The checkboxes are shown with their corresponding designation (labelling), one after the other on the right-hand side of the component.

subcomponent Checkboxes

This component can be added within a form-block section. The values which are the same for all checkboxes are set in this section. The actual checkboxes are added within a ContentAreaList in this section.

Labelling

Use this text field to enter the title of the form field.

Group identifier (name attribute)

Use this text field to enter the unique identifier.

Content check (filled)

These radiobuttons can be used to create a check, which checks whether or not at least one checkbox in this group has been selected.

Mandatory field note

A message which appears if the content check fails must be given for this type of form field.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 31. Form component checkboxes

subcomponent Checkbox

This component can only be used within the form Checkboxes component. It is used to add the actual checkboxes within the component named above.

Labelling

Use this text field to enter the labelling of the option.

Value (value attribute)

Use this text field to enter the value for this option.

Preselection (checked attribute)

These radio buttons can be used to make a preselection, whether this checkbox should be selected or not.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 32. Form component checkbox

4.5.5. Form component Password

This component can be used to provide a password field for the user. Here too, the editor must assign a unique identifier for the component. Characters entered are shown in the component as asterisks (*).

Labelling

Use this text field to enter the title of the form field.

Unique identifier (name attribute)

Use this text field to enter the unique identifier.

Default selection (value attribute)

Use this text field to enter text with which the form field is filled.

Allow editing (readonly attribute)

This radio button is used to control whether the user may edit the form field or not.

Number of characters (maxlength attribute)

This text field can be used to define the maximum number of characters that can be entered.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 33. Form component password

4.5.6. Form component Hidden

This form component can be used to create fields which are not displayed in the browser, but can be evaluated in the servlet or PHP script, i.e. additional non-visible information. Here too, the editor must assign a unique identifier for the component.

Unique identifier (name attribute)

Use this text field to enter the unique identifier.

Default selection (value attribute)

Use this text field to enter text with which the form field is filled.

Figure 34. Form component hidden

4.5.7. Form component Autocompleter

This form component can be used to offer the user the convenience of having suggestions for completion of their input provided while they are typing. Here too, the editor must assign a unique identifier for the component.

Labelling

Use this text field to enter the title of the form field.

Unique identifier (name attribute)

Use this text field to enter the unique identifier.

Default selection (value attribute)

Use this text field to enter text with which the form field is filled.

Request file

This component can be used to select a page from the structure which accepts the input and returns the applicable values.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid data.

Number of characters (maxlength attribute)

This text field can be used to define the maximum number of characters that can be entered.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 35. Form component autocompleter

4.5.8. Form component Combobox Standard

The form combobox standard component provides the editor with a convenient way of making a selection list available to the form user. The contents of the list and the number and layout are freely formattable. Here the editor must give a unique group designator.

Labelling

Use this text field to enter the title of the form field.

Group identifier (name attribute)

Use this text field to enter the unique identifier.

Visible entries (size attribute)

Use this field to enter the number of visible entries as a number.

Multiselect (multiple attribute)

These radio buttons are used to control whether several entries in this form field can be selected or not.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid data.

Options

The contents/selection options of the form field can be entered in this list.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 36. Form component combobox standard

4.5.9. Form component Combobox Query

The form combobox query component provides the editor with a convenient way of making a selection list available to the form user. The contents of the list and the number and layout are freely formattable. This special SelectBox filters and outputs the selection options from the database via a Query. Here the editor must give a unique group designator.

Labelling

Use this text field to enter the title of the form field.

Group identifier (name attribute)

Use this text field to enter the unique identifier.

Visible entries (size attribute)

Use this field to enter the number of visible entries as a number.

Multiselect (multiple attribute)

These radio buttons are used to control whether several entries in this form field can be selected or not.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid data.

Database query

Use this text field to enter the name (UID) of a database query (Query) in the Template Store.

Column

Use this text field to enter the name of a database column or database field. The values of this column are available to choose from in this form field.

Selected value(s) (selected attribute)

Use this text field to specify one or several values which are preselected in the form field. If you specify several values, separate them with a comma (,).

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 37. Form component combobox query

4.5.10. Form component Combobox Date

The form combobox date component provides the editor with a convenient way of making a selection list available to the form user. The contents of the list, the number of entries and layout are freely formattable. Three boxes are automatically generated in this special SelectBox, which can be used to conveniently select a date. Here the editor must give a unique group designator.

To convert into a correct date format within the servlet, a toDate_ is placed in front of the unique identifier, in order to make the field identifiable for the servlet. If date was entered as the unique identifier, the field’s identifier is toDate_date and must therefore also be used in this form, e.g. in the mail template.

Labelling

Use this text field to enter the title of the form field.

Group identifier (name attribute)

Use this text field to enter the unique identifier.

Visible entries (size attribute)

Use this field to enter the number of visible entries as a number.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid data.

Start year

Use this text field to enter a date (year). Date selection is possible from this value up to the value of the End year field.

End year

Use this text field to enter a date (year). Date selection is possible from the value of the Start year field up to this value.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 38. Form component combobox date

4.5.11. Form component fileupload

This form component enables the user to send files via the form. In addition, it is possible to limit the file formats. Here too, the editor must assign a unique identifier for the component.

Labelling

Use this text field to enter the title of the form field.

Unique identifier (name attribute)

Use this text field to enter the unique identifier.

Content check (filled or valid value)

This radio button can be used to create a check which checks for content or valid file types.

Accepted file formats

Use this text field to enter a comma-separated list of file extensions. An evaluation only takes place if valid file type is activated for the content check. Several file extensions must be separated from each other by |.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 39. Form component fileupload

4.5.12. Form component Captcha

This form component is used to generate a captcha graphic, a link, which generates a new graphic, and a text field for entering the captcha code, in the form. This component should be used to refuse use of the form by non-human users.

Select the Captcha Validation checkbox in the form-start section so that the input is checked by the servlet.

Labelling

Use this text field to enter the title of the form field.

Number of characters (maxlength attribute)

This text field can be used to define the maximum number of characters that can be entered.

Display width

Use this field to specify the width of the form field in pixels.

Display height

Use this field to specify the height of the form field in pixels.

Stylesheet class (class attribute)

Use this text field to enter the name of a CSS class.

Figure 40. Form component captcha

Overlapping of the characters is affected by the height, width and number of characters to be rendered (see Chapter Installation and configuration of the web component). Always ensure that the characters are not too easy to read, as otherwise they can be read by spam robots. With the default configuration of 100 x 100 pixels with 6 characters, a captcha can look like this:

Figure 41. Form captcha graphic component

In real terms, the form Autocompleter component only provides a completely normal text input component. The logic which provides this component with the autocompletion function consists of two parts:

This concept is implemented in the templates supplied with the module on the basis of an example XML file. The logic is implemented on the jsp-side and also requires the Java jdom library.

Example

This example is based on the following XML file (xmlDataBase page template):

<?xml version="1.0" encoding="UTF-8"?>
<jobs>
   <job jobnr="Project Manager (jb-1742-a01)" jobdescription="Project Manager"/>
   <job jobnr="Apprentice (jb-1743-a02)" jobdescription="Apprentice"/>
   <job jobnr="Template Developer (jb-1744-a03)" jobdescription="Template Developer"/>
   <job jobnr="Product Development Manager (jb-1745-a04)" jobdescription="Product Development Manager"/>
</jobs>

On using the form Autocompleter field, after entering, e.g. 3 characters, a request is sent to the page referenced in the form component. This page is based on the autocompleterequest page template. Logic is implemented in this page template, which accepts this request and the transferred character chain.

incomingValue = (String) request.getParameter("q");

Within the referenced XML source, the comparator attribute is searched for occurrence of the requested character string.

for (Element child : children) {
   if (incomingValue == null ||
   child.getAttribute(compareAttr).getValue().toLowerCase().contains(incomingValue.toLowerCase())) {
      buffer.append(child.getAttribute(resultAttr).getValue() + "\n");
   }
}

If an applicable entry is found, a response is sent to the form input component:

Project Manager
Product Development Manager

The data found is now shown to the form user, e.g. here the value of the jobdescription attribute (return text). If the user now selects an option, it is saved as the value of the form field.

This example describes all actions to be performed by the editor, which are necessary to create a form with which a user can register for a competition.

The data entered by the user is to be used on the one hand for a personalised participation confirmation and on the other is to be stored in a database containing all participants.

To carry out this example, the FirstSpirit™ FormEdit module must be installed for a FirstSpirit project, as described in Chapter Installation and Configuration. Furthermore, a database and an available e-mail server are required.

4.8.1. Creating the form

Create a new page in the Page Store and choose the form template. Add the form start, form block_and _form end sections, one after the other in a section area of the page:

Figure 42. Create page with form sections

Now enter a heading and form name in the form start section. Choose Post as the send method and enable client-side content checking. If you already have a confirmation page and an error page in your structure, you can reference them here.

Now switch to the form block section and create a text field for each of the following: Name, first name, street, house number, post code, town/city and e-mail address. Use the content check Field filled on each. To enable easy filing of the data in the database, it is advisable to choose the column name in the database as the unique identifier. For this example we use name, firstname, street, housenumber, zip, city and email as unique identifiers:

Figure 43. Form elements

All the necessary fields in the form end section are already completed, but you can now adjust them to your wishes.

4.8.2. Creating the mail template

Create a new page in the Page Store on the basis of the mailtemplate template. We use the field from the form as the recipient, as the e-mail is to be sent to the form user. I.e., in this example, %e-mail%.

You can also define the term yourself, just like the message text and the sender’s address. You can use %uniqueIdentifier% in the message text to access all form fields:

Figure 44. Mail template

Now use Drag&Drop to drag the mail template you have created into the Site Store or reference it via the context menu from the Site Store.

4.8.3. Creating the logger configuration (e-mail)

Now switch back to your form start section and add a new data record in the Processing component.

Figure 45. Add data record

In the following dialog, enter a name for the e-mail processing and choose MailLogger as the LoggerType. You can add an optional description.

Now add a new data record to the Logger Parameter component by clicking Add Section and select the logger-text-value entry and click OK. In the following dialog, enter smtpHost as the parameter name and the address of your outgoing mail server as the parameter value, e.g. smtp.ANOther.de. Repeat this for the encoding parameter, using the name of the encoding you require (here: UTF-8).

Now create a new section; however, this time using the logger-template-ref template. Now enter mailTemplatePath as the parameter name and choose the mail template created by you in the Mailtemplate component. Further parameters are explained in Chapter Autocomplete request.

Figure 46. MailLogger parameter

Finally, select Activated status in the component (see Chapter Creating the logger) and click the save symbol in the top left-hand corner. The logger created by you is now automatically listed in the Processing component, in your form start section.

4.8.4. Creating the logger configuration (database)

The second configuration is created in exactly the same way as described in Chapter Creating the logger configuration (e-mail). However, here you select JdbcLogger as the logger type and create all parameters on the basis of the logger-text-value template. Please create the driver parameter first with the name of your database driver, e.g. com.mysql.jdbc.Driver for a MySQL database.

Please ensure that the database driver has already been added to the FirstSpirit server.

Use the url parameter to pass the address to your database, e.g. jdbc:mysql://muster:3306/formlogger and the table parameter to pass the name of your table (here: demo).

Now create the user and password parameters and fill these with the login data for the database, which is usually made available to you by your database administrator.

Figure 47. JdbcLogger parameter

Further parameters are explained in paragraph Configuring database processing.