Creating Advanced Forms

Liferay’s built-in Forms application supports your most basic form building needs (something like a one question survey), and your most advanced (like a mortgage application, or conference sign-up form). In a separate article, learn about the basics of form creation:

  • Navigating to the Forms application
  • Adding form fields, and supported field types
  • Configuring form fields
  • Viewing and Exporting form entries
  • Deleting form entries

This article covers more advanced use cases for forms, and a basic knowledge of the Forms application is assumed. Here’s a current list of the features you can use in your forms that are covered in this article:

  • Populating a Select field with a REST Data Provider
  • Making a field appear based on the value entered into another field
  • Add extra pages to the form
  • Providing a predefined value or a placeholder value
  • Validating fields using a number of different criteria
  • Configuring form permissions
  • Laying out the form

Aside from those features, which enhance the building of your forms, there are some settings and processing features to explore:

  • Enabling CAPTCHA for a form
  • Redirecting to a different URL after a successful form submission
  • Sending an email notification whenever a form entry is submitted

The Lunar Resort Employment Application Form

At The Lunar Resort, management is VERY particular in its hiring practices. Lots of people think they want to work on the moon full time, but it takes a special kind of person to really make it work. There’s so much that can go wrong:

  • Astrophobia: If a newly hired employee discovers they have an unshakable fear of space, it’s quite costly to send them back home.
  • Claustrophobia: The tiny sleeping capsules where employees rest is not compatible with a fear of small spaces.
  • Alienophobia: Some of The Lunar Resort guests are not from planet Earth. It’s important for employees to be comfortable and friendly with the more “exotic” guests, such as the Daleks.

There are more hiring pitfalls than the phobias listed above, but it’s time to start building the application form, starting with the creation of its pages.

Creating Form Pages

Liferay’s Forms application supports multi-page forms. To add one, click the Actions (Action) button at the top right hand corner of the form, and then click Add New Page.

Figure 1: You can add new pages or reset the current page from the Page Actions menu.

Figure 1: You can add new pages or reset the current page from the Page Actions menu.

You also have the option to Reset Page. If you click this, the title, description, and any fields you added to the page will be deleted. It gives you a blank slate.

The Lunar Resort employment form needs three pages with clear page descriptions:

  • Personal Details: This page requires you to give us some pretty personal information.
  • Very Personal Details: This page requires you to give us some very personal information.
  • Extremely Personal Details: This page requires you to give us some extremely personal information.

Once you create the form’s pages, you’ll see how navigating the pages is easy with the form page navigation wizard.

Figure 2: Multi-page forms have a default Wizard Mode that makes navigating the form easy for users.

Figure 2: Multi-page forms have a default *Wizard Mode* that makes navigating the form easy for users.

Once you have the form pages created, navigate back to the first page, Personal Details.

Adding Placeholder Text and Predefined Values

To populate the employment application form for The Lunar Resort, you should start by adding some of the usual fields, like a Full Name field:

  • Full Name: Add a required text field titled Full Name, with a description that reads Enter your full name, no matter how long. Under Show More Options, enter Placeholder Text: e.g., Maximillian Aurelius Piroux the 11th.

    Figure 3: The Full Name field in the employment form. It has a placeholder value to help users understand what you are looking for.

    Figure 3: The Full Name field in the employment form. It has a placeholder value to help users understand what you are looking for.

Remember that placeholder values will not be submitted if the field is left blank, so you don’t have to worry about getting a bunch of applications from Maximillian Aurelius Piroux the 11th.

Validating Text Fields

The HR department needs to weed prospective employees out if they’re not mature enough. If the user is under a certain age, make sure to ask them if they’ve ever been away for an extended period of time. This can be done using a text field that accepts only numbers (age), and then a field to probe whether the applicant can handle being away from home for a long period of time. In that field, you can use a Field Visibility Expression so it only appears if the user enters a number less than 30.

  • Age: Add a required text field called Age, with a description that says, Enter your age in years, and the placeholder text Numbers Only.

    Enable Validation and select Number, is greater than, and enter 0. You can enter an error message You must enter your age in years, and it must be greater than 0.

    Figure 4: The Age field in the employment form. It uses validation to ensure that a number greater than zero is entered.

    Figure 4: The Age field in the employment form. It uses validation to ensure that a number greater than zero is entered.

Make one more required field on the first page:

  • Email Address: A required text field that only accepts email address. Use the validation rule for TextEmail to make sure that a valid email address is entered.

Next create a field that will be displayed only if the user enters any number less than 30 in the Age field.

Using Field Visibility Expressions

Sometimes you only want a form field to appear if a certain value is entered in another field. In the Lunar Resort application for employment, you want to ask an additional questions to users who are less than 30 years old, to make sure they’re comfortable with being away from home for a long period of time.

  • Maximum Time Away From Home: This is a required select field with the description What’s the longest time, in consecutive months, that you’ve spent away from your permanent residence? Give it the following options: <1, 1-3, 4-12, >12.

    Enter a Predefined Value of <1.

    Now comes the interesting part. Under Field Visibility Expression, enter between(Age,0,29). This expression will cause the field to appear only if the Age field has a value between 0 and 29 entered. Another expression that will produce the same result is (Age>=0)&&(Age=<29). In this case, the expression is checking to make sure that the Age value is greater than or equal to zero and it’s checking to make sure that the entered Age value is less than or equal to

Figure 7: You can make a field appear based on the value of another field in your form.

Figure 7: You can make a field appear based on the value of another field in your form.

Field Visibility Expressions are great for dynamically displaying a field based on another field’s entered data. Next, find out how to dynamically populate a select list from a Data Provider.

Populating Select Fields with REST Data Providers

On its final page (Extremely Personal Details) The Lunar Resort application form needs five select fields, all populated with the complete list of the countries of earth. Read the sidebar note below to find out why this field is needed (it’s just a fictional story, so skip if you don’t have time for some light entertainment).

Unless you have an intern, you don’t want to manually enter all the countries of earth into five different select fields. Instead, you want to populate the fields using a Data Provider.

Adding and Configuring a Data Provider

Before using a Data Provider in your select fields, you need to configure one that you can use in your forms. Navigate to the Forms application in Site AdministrationContent, and click the Options (Options) button.

Figure 10: Set up a data provider that can be reused in all your forms.

Figure 10: Set up a data provider that can be reused in all your forms.

If you click on Data Providers, the data providers window opens, and you can see any existing data providers or add a new one. Click the Add button (Add).

Fill out the Data Providers form, passing in the following values:

  • Name: Countries List
  • Description: A complete list of earth’s countries
  • URL: http://localhost:8080/api/jsonws/country/get-countries
  • Displayed JSON Attribute: nameCurrentValue
  • Stored JSON Attribute: name
  • User Name: test@example.com (or whatever your admin user name is)
  • Password: test (or whatever your admin password is)

You’re probably wondering what the URL, Displayed JSON Attribute, and Stored JSON Attribute fields are all about. First, it’s good to understand that what you’re doing when setting up a data provider is accessing a REST web service. You can use the JSON web services registered in Liferay, or any other REST web service you have access to. To find a list of the ready-to-use registered JSON web services in Liferay, navigate to http://localhost:8080/api/jsonws (assuming you’re running Liferay locally). If you do that, you’ll be able to browse the available Liferay services that you can use to populate your list. The services useful to you in the Forms application will get a list of something. The service you are calling in the data provider you set up above gets a list of countries. Find the get-countries JSON web service and click on it, then click Invoke. The Result tab will have a list of countries using JSON syntax, like this:

[
  {
    "a2": "AF",
    "a3": "AFG",
    "countryId": "20",
    "idd": "093",
    "mvccVersion": "0",
    "name": "afghanistan",
    "nameCurrentValue": "Afghanistan",
    "number": "4"
  },
    ...

That’s the record for the country Afghanistan. As you can see in the URL tab, the URL you entered into the data provider form is the same as the one generated for accessing the get-countries JSON web service. You can find the URL for any registered JSON web service using this same procedure.

The Displayed JSON Attribute field is where you specify which field you want to use to populate your select list. In this case, nameCurrentValue provides the full, properly capitalized country name, and that’s what you want users of the form to see.

The Stored JSON Attribute field is where you set which field will be stored in the database for the form entry. The name field was selected in this example.

Once you set up the data provider, click Save. Now you can set up five select fields that list all the countries of earth in no time.

Using a Data Provider in a Select Field

Back in the application form, go to the third page, Extremely Personal Details. Add a select field.

  • Relocation Country: First Choice: Make the select field required, and enter If relocation becomes necessary, to which country on earth would you most like to go? as Help Text. Select the radio button to Create List From Data Provider, and choose Countries List. Click Save.

If you’re building the example application form, do the same thing four more times, using field labels to reflect the choice number. For example, you’d call the second select field Relocation Country: Second Choice, and so on until you have five of them. You can decide what help text to provide, if any.

Figure 11: You can configure a data provider and use it to populate a select field.

Figure 11: You can configure a data provider and use it to populate a select field.

Your Data Provider is now being used to populate your select fields. However, this form is going to be submitted by Guest users, who don’t currently have permission to see the list of results from the data provider.

Granting Data Provider Permissions

To configure the data provider’s permissions, navigate to the Forms application (Site AdministrationContentForms). Open the Options menu (Options) and select Data Providers. For the data provider you want to configure, click the Actions button (Actions), then Permissions.

For the employment application form in The Lunar Resort, Guest users need the View permission, or else they won’t be able to see the options provided by the data provider in the select fields. Once you grant the permission, click Save.

That concludes the actual development of the form (adding pages and form fields). The rest of the article covers features of the Forms application that you’ll use during or after form entry submission.

Enabling CAPTCHA on Form Submissions

You’re probably familiar with CAPTCHA, the program used to prevent a bot from submitting forms. It’s often used in Login applications, but you can use it in the Forms application, too.

Figure 12: You can enable CAPTCHA for your form in the Form Settings window.

Figure 12: You can enable CAPTCHA for your form in the Form Settings window.

To enable CAPTCHA, click the form’s Options (Options) button, then Settings. Enable the Require CAPTCHA setting, click Done, save the form, and that’s all there is to it!

Figure 13: Once you enable CAPTCHA, your form has protection against bot submissions.

Figure 13: Once you enable CAPTCHA, your form has protection against bot submissions.

Now, you’re much more likely to receive form submissions from humans!

Setting Up Form Notifications

It’s possible to have a notification email sent each time a form entry is successfully submitted. Open the form’s Form Settings section (click the Options (Options) button → Settings). Click the Email Notifications tab, enable the option to Send an email notification for each entry, and fill out the fields:

  • From Name: The name of the sender. This could be the site name, the form, name, or anything else that will be informative to the recipient.
  • From Address: You can use something like noreply@example.com, so that recipients of the notification don’t try to reply.
  • To Address: This should be the email address of the notification recipient (for example, test@example.com).
  • Subject: An informative subject line tells the recipient what happened. An application for employment was submitted in The Lunar Resort might be appropriate for the form developed in this article.

If you enabled workflow for the form, and there’s already a notification going to the people who need to process the form entry, you might not need to generate any notification from the Forms application itself.

Redirecting Users after Form Submission

You can send users to any URL you want upon form submission. You might have a particular Thanks for your submission! type page with a link to the home page, or you might want to direct a user somewhere specific based on the form they just submitted.

Whatever your use case is, you can set up a redirect URL by opening the form’s Form Settings section (click the Options (Options) button → Settings). In the Redirect URL just type the URL. That’s it.

So, your form is all set up ready to be filled out by users. However, you haven’t configured the permissions yet, so the only user with permission to add records is you, the owner! There’s a good chance you’ll want to customize the form’s permissions.

Configuring Form Permissions

By default, you can grant the following permissions for a form:

  • Delete: Permission to delete the form.
  • Permissions: This gives any role with the permission the ability to configure the form’s permissions.
  • Add Record: Permission to submit form entries.
  • Update: Permission to update form entries.
  • View: All the other permissions you can configure for the form depend on this one. Think about it: if you can’t see the form, how can you add a record?

Figure 14: You can configure the permissions for a form.

Figure 14: You can configure the permissions for a form.

If you want to allow unauthenticated visitors to your site to view and fill out forms, give the Guest role the View and Add Record permissions.

Navigate to the Forms application (Site AdministrationContentForms). Click the application employment form’s Actions button (Actions), and select Permissions. Give the Guest role the View and Add permissions, then click Save.

Form Layouts

Sometimes, it doesn’t make sense to have a single column, vertically oriented form, which is what you get by default when you just keep clicking the large Add Field button on the form as you build the form.

Instead, you might use more than one column in your form.

Figure 15: An example of a multiple column form layout.

Figure 15: An example of a multiple column form layout.

As you can see, the multi-column approach saves a lot of space in the pictured form. You can also use a mixed approach, with each row broken into a different number of columns.

Figure 16: There are many ways to lay out your Liferay forms.

Figure 16: There are many ways to lay out your Liferay forms.

If you’re going to lay out your forms, you’ll be working with two entities in the form builder interface: Rows and Field Slots. You’ve already added and configured fields. All you’re doing here is learning to resize them and move them around. Rows are just that, the rows of the form.

If you’ve added a field to the form, you’ve also added a row. By default, clicking the large Add Field button on the form will add a field that occupies the entire row.

Figure 17: By default, fields in your form will occupy an entire row.

Figure 17: By default, fields in your form will occupy an entire row.

If you’d like, you can design your forms before you add the fields. Just start resizing the row using the form layout functionality (drag the chevrons to resize the field slots, or columns, in a row). As you make a field slot smaller, the new space is taken up by another field slot. You’ll end by having divided the row into two columns. Resizing again will make three columns. Once you have the row situated how you’d like, start adding the form fields.

Figure 18: Its easy to resize form rows and make new form slots.

Figure 18: It's easy to resize form rows and make new form slots.

You can also cut entire rows from the form and paste them elsewhere. Any fields you added and configured will be pasted with the field. Once you click the cut icon (the scissors), you’ll be alerted to the available positions where you can paste the row and its fields.

Figure 19: Cut and past an entire row, including its fields, in your form layout.

Figure 19: Cut and past an entire row, including its fields, in your form layout.

Did you notice the delete icon (Trash)? Clicking it deletes the entire row, with all its fields.

Just like you can cut and paste an entire row, you can move an individual field to any unoccupied field slot, in any row. Just open the field’s actions menu by clicking the Actions button (Actions), which will appear when you hover your mouse over the field in the layout.

Figure 20: Move an individual field in your form layout.

Figure 20: Move an individual field in your form layout.

In addition to moving the field, you can edit the field or delete it.

Now it’s done. Your users, including Guest users, can submit applications to The Lunar Resort. The form is multi-page, full of features, and there’s even some processing that’s done on form submission. As you can see, there’s a lot of flexibility built in to Liferay’s Forms application.

« Basic FormsSending Form Entries through a Workflow »
Este artigo foi útil?
Utilizadores que acharam útil: 0 de 2