Forms Field Types Reference
The Liferay Forms application contains lots of field types and elements to add to your forms. To discover the available elements,
- Open the Product Menu (
) and click the compass icon (
) on the Site Administration menu. Select the Site where the form will be created. - Click Content & Data → Forms.
- Click the Add button (
). The form builder view appears. - Click the Add button () one more time to display the Add Elements sidebar (if it is not already opened).
Form Field Grouping and Repeatability: Form fields can be grouped for use across your forms (using Element Sets or can be made into Field Groups within the form. Create a Field group by dropping a field on top of another field. In addition, each field can be marked repeatable in its configuration, which allows the end user of the form to duplicate the field in the form.
Field Configuration Overview
The field configuration editor sidebar appears whenever you add a new field or click an existing one in the form builder. The available configuration options differ by field type.
All Form Fields have at least two configuration types: basic and advanced. Many forms can be created with just the basic configurations, which include things like
- label
- placeholder text
- required (and what the required message says)
- help text
There are additional field-specific basic configurations as well.
Advanced configurations include
- predefined values
- search configurations
- whether the field is repeatable
- the system/programmatic field reference
- field confirmation
- whether the field is hidden
There are additional field-specific advanced configurations as well.
Hiding Fields
Sometimes it’s useful to pass information from an external source (like a REST Data Provider) into a form field that’s only to be used for triggering a form rule. In this case, use the Hide Field configuration (new in Liferay 7.4).
Field Confirmation
Field confirmation is supported in Liferay Forms as of version 7.4. Rather than a field in the Form Builder that you add directly to the form body, the confirmation field only appears in the form when you configure a single-line Text or Numeric field to Require Confirmation (using the field’s Advanced configuration section). This field ensures that fields with important data are entered correctly (for example, email address fields).
New configuration options appear when you enable the confirmation field:
Direction: Choose Vertical (the default) or Horizontal to determine whether the confirmation field appears below or alongside the original field.
Label: Choose the prefix for the original field label. The default value is Confirm, so a field named Email Address has a confirmation field label of Confirm Email Address.
Error Message: Depending on the field you’re confirming, you can provide a more specific error message.
See Validating Text and Numeric Field Entries for information on ensuring the user enters information in a valid format.
Field Name, Field ID, and Field Reference
In the first release of Liferay 7.3, the editable configuration Field Name was removed, and a read-only Field ID was included in each field’s Advanced tab. However, an editable replacement, Field Reference, is now available in Liferay 7.3+. Use the Field Name value in 7.2, and the Field Reference in 7.3+, when referencing the field programmatically.
Form Fields and Elements
Paragraph
The paragraph field displays static text on the form, as entered by the form creator. Users do not enter data into paragraph fields. This is useful for longer instructions.
Paragraph fields can be much more than plain text. Create rich content using the embedded content editor.
Text Field
Users enter free-form text into these fields. For example, a Full Name field is a text field. By default, a text field keeps all input on a single line of text. To accommodate longer responses, choose the multi-line setting when configuring the text field as in this example. You can put limits on the text users can enter (e.g., numbers from 1-10, email addresses, etc.) by using the text field’s validation options.
Select from List
Users select one option (or more, if configured to allow it) from a list of choices. Choices are entered manually or automatically populated by a data provider. For example, a Country of Residence field can be selected from list field populated by a Countries of the World data provider.
Single Selection
Using a radio button, users select one option from a list of options displayed on the form.
Boolean
Users enable or disable a checkbox or switch, logging a true or false response to the displayed text.
Date
Users select a date using a date picker.
As of Liferay 7.4, the Advanced configuration of the Date Field includes Validation. You can put limits on the dates users can enter (e.g., numbers from 1-10, email addresses, etc.) by using the validation options in the field’s Advanced configuration.
Date and Time
Added in Liferay 7.4, Users fill in both the date and a time of day in one field.
The Date and Time field accepts input following the format DD/MM/YYYY HH:MM [AM/PM]. For example, 01/06/1981 12:15 PM is January 6, 1981 at fifteen minutes past midday. A date and time picker can be used, or the User can enter the date directly into the field.
Multiple Selection
Users select one or more options from check boxes (or toggles, if configured).
Grid
Using radio buttons, users select from options laid out in rows and columns. One selection can be made per row. This is useful when the same response metric is needed for multiple questions.
Numeric
Users enter numeric data (integers or decimals) into numeric fields. Non-numeric input is not accepted.
There are some interesting advanced field settings for numeric fields:
- Require Confirmation ensures the user enters data correctly.
- Validation constrains the user input to your pre-configured requirements.
- An Input Mask allows you to display the correct format as the user enters numeric data.
Upload
Upload fields let users upload a file from the local file system. Logged in Users can choose from files they have previously uploaded or upload a new one.
In 7.2 logged in Users can select an existing file from the Documents and Media library or choose to upload a file from their local file systems.
Beginning with Liferay 7.3 (DXP FP1+ and CE GA7+), you can allow unauthenticated Guest Users to upload files. Enable Guest uploads within the Form Field’s configuration:
Uploaded documents are stored in a hidden folder in the Documents and Media repository. To display them in the Documents and Media application, set the following portal property in a portal-ext.properties file:
dl.show.hidden.mount.folders=true
Configure the Guest upload behavior in the Control Panel: System Settings → Forms (Content and Data) → Forms, or by creating a configuration file named com.liferay.dynamic.data.mapping.form.web.internal.configuration.DDMFormWebConfiguration.config.
To configure the Forms application at the instance scope, use the Forms entry in Instance Settings.
Guest Upload File Extensions (guestUploadFileExtensions): Enter the comma-separated list of accepted file extensions. By default the following list is supported: doc, docx, jpeg, jpg, pdf, png, ppt, pptx, tiff, txt, xls, and xlsx.
Guest Upload Maximum file Size (guestUploadMaximumFileSize): Set the maximum file size Guest User can upload via the Upload field. This is configured for authenticated Users in the Documents and Media application’s configuration, and system-wide limits are defined in the Upload Servlet Request System Settings entry, in the field named Overall Maximum Upload Request Size. By default the limit is 25 MB.
Maximum Repetitions for Upload Fields (maximumRepetitionsForUploadFields): If the field is configured as repeatable, set maximum number of times the field can be added to the form by the User (applies equally to Guest Users and logged in Users). By default the limit is 5.
Maximum Submissions for Guest Upload Fields (maximumSubmissionsForGuestUploadFields): Set the maximum number of times a Guest User can submit a form that includes a Guest-enabled Upload field. The Guest User’s IP address is used to keep track of submissions. By default the limit is 5.
Image
Users can select an image file (.gif, .jpeg, .jpg, or .png) from Web Content Images, the Documents and Media library, or upload an image file from their local file systems.
Guest Users cannot access or upload images. Avoid using this field unless only authenticated Users can access the form.
After adding the image, the user can fill out an additional field for the image, Description. When the image field is optional, the usage is straightforward: neither the image or its description is required. However, like all forms fields, the image field can be marked required. When the image field is required, the form builder can choose whether the description is required or optional:
Color
Users can enter the hex code of a color by selecting it from the color picker or entering the code directly.
Rich Text
Users can enter Rich Text content (including formatted text, embedded images, attachments, etc.) into a form field.
Search Location
Use the Search Location field(s) in Liferay 7.4+ to collect valid addresses conveniently from form users.
See Using the Search Location Field for more information.