Controlling what appears on forms and when

You can customize the citizen experience using things like Visibility.

On this page:

• Visibility basics
  • Read-only
• Scenario: Transitioning a fillable PDF form
  • A section from the PDF form
  • Analysing the logic
  • Your design options
  • Setting up the controls
  • Configuring your chosen option
    • Option 1: Visible when needed
    • Option 2: Hidden when not needed
    • Option 3: Disabled until need
    • Option 4: Disabled when not needed
• Other visibility options

Visibility basics

Visibility is the most common way to customize the form-filling experience for citizens. It allows you to simultaneously:

• Make form completion as quick and simple as possible, and
• Ensure that requested information is complete and correct

All controls are visible by default, but you can set their visibility to:

• "No" to hide the control everywhere except the Form Editor, such as a form control section
• "Formula" to specify one or more conditions under which it's made visible, such as when the value of another control matches a certain value
  • This is described in our scenario below
  • This is also used when working with a test layer

Visibility can be applied to:

• Sections, affecting everything within that section
• Grids, affecting everything within that grid
• Individual controls

Visibility settings are found in the control's settings in:

• The Formulas tab of most controls
• The Basic Settings tab of some controls

Finally, you can also apply visibility based on the 'media' of the form, such as making something visible only on the PDF. This is described in below in Other visibility options.

Read-only

A read-only control only displays information and doesn't collect it from the user, at least not directly. Read-only controls are most often used to display the results of calculations or other data in a form with a testing layer.

Since this works just like Visibility and is an alternative design option, it's included in our scenario below.

Scenario: Transitioning a fillable PDF form

If you've been tasked with modernizing your ministry's forms, you'll likely spend a lot of time transitioning paper and PDF forms to the web. The new web forms are rarely a direct copy of the original form.

• Content like instructions will be different
• You can automate things like calculations
• Some fields are only required under certain conditions

By necessity, paper and PDF forms had to be designed to accommodate all possible options for a process. Things like making sure the form was complete and correct was difficult or impossible to accomplish.

CMS Forms gives you the options and capability to improve on the experience and quality of submitted data.

A section from the PDF form

Here's a section of a business-related form that illustrates 4 questions, not all of which need to be answered in all cases.

The questions ask:

1. The kind of organization the request is for
   • There are 5 options
   • One of these is "Corporation", including a foreign entity
2. If the organization is a foreign entity
   • It's a simple "yes" or "no" question
   • It only applies to corporations
3. What jurisdiction the organization is registered in
   • It's a text box
   • It only applies to foreign entities
4. The nature of the business
   • It's a text box
   • It applies in all cases
   • We'll ignore this one for the examples

The design and text of this form suggests that there is intended logic.

Analysing the logic

There are implied conditions under which each question must be answered, and an order to those conditions. This is referred to as the "logic" of the form.

Looking at the original form, you can determine that question:

1. Needs to be answered for all applications
2. Needs to be answered only when the answer to question 1 is "Corporation"
3. Needs to be answered only when:
   • The answer to question 1 is "Corporation" and
   • The answer to question 2 is "Yes"

There are 2 conditions that apply to question 3 on jurisdiction. Depending on the design option you choose, you may have to account for one or both in creating your formulas.

Your design options

There are several design options to treat this logic in your form. For questions 2 and 3, you can:

1. Display the fields only when needed
2. Conceal the fields that are no longer needed
3. Disable the fields until they are needed
4. Disable the fields that are no longer needed

Option 1 is the most common and referred to as "progressive disclosure". New forms are shorter and extra questions only appear when needed. Forms appear less intimidating or complex to start, but if disclosure is excessive in a long form, it could be disappointing or frustrating to some users.

Option 2 is much less common and exposes all fields to the user to start, potentially setting a baseline for expectations. As they progress through the form, it becomes shorter and can inspire a feeling of rapid progression or acceleration. This is a good alternative to progressive dislosure for the long and complex forms that could annoy users.

Options 3 and 4 are rare, but can be a good option if you're setting up your form to autogenerate a PDF. This method allows you to create consistent form output without having to additionally set visibilty based on "mode".

To see what these different options look like, see:

• DEMO: Visibility options

Setting up the controls

Regardless of the option you choose, you'll need to set up your controls first.

For this example, we'll set them up this way:

1. A radio button control named orgType
   • It's marked as required
   • The value for Corporation will be "corp"
2. A yes/no control named isForeign
   • It's marked as required
   • It provides the values "true" and "false"
3. A plain text control named juridiction
   • It's marked as required

For additional information, see:

• Requiring and validating data

Configuring your chosen option

Now that the fields are set up, you can apply the appropriate Visibility or Read-only settings based on your chosen design option.

• Formulas must resolve to 'true' for the setting to take effect
• Formulas can be phrased positively (X equals Y) or negatively (X does not equal Y)
• Formulas can be combined or compared using things like "and", "or" and brackets

The option settings below are based on the controls we set up earlier. You can follow the same format with your own control names.

Option 1: Visible when needed

This option is the most common and easiest to set up. Questions 2 and 3 will display in sequence, if needed. The formulas below are entered into the Visibility section.

For the isForeign control, enter the following formula:

string($orgType) = 'corp'

This tells Orbeon to display the control if the user selected "Corporation" for organization type.

For the jurisdiction control, enter the following formula:

string($isForeign) = 'true'

This tells Orbeon to display the control if the answer to the foreign entity question is "Yes".

Option 2: Hidden when not needed

This option will display questions 2 and 3, and then hide them if they're no longer needed. This is more complex because:

• Both have to be visible if question 1 is unanswered or "Corporation"
• Question 3 only remains visible if question 2 is answered "Yes"

The formulas below are entered into the Visibility section.

For the isForeign control, enter the following formula:

xxf:is-blank($orgType) or string($orgType) = 'corp'

This tells Orbeon to display the control:

• While the organization type is blank (unanswered), or
• When the organization type is "Corporation"

For the jurisdiction control, enter the following formula:

(xxf:is-blank($orgType) or string($orgType) = 'corp') and string($isForeign) != 'false'

This tells Orbeon to display the control:

• While the organization type is blank (unanswered), or
• When the organization type is "Corporation", and
• While the entity question has not been answered "No"

Option 3: Disabled until needed

This option locks the fields until they are needed. This works just like pregressive disclosure (option 1), but since 'true' activates read-only mode, we use the 'not' operator. The formulas below are entered into the Read-Only section.

For the isForeign control, enter the following formula:

string($orgType) != 'corp'

This tells Orbeon to keep the control locked unless the user selects "Corporation" as the organization type.

For the jurisdiction control, enter the following formula:

string($isForeign) != 'true'

This tells Orbeon to keep the control locked unless the answer to the foreign entity question is "Yes".

Option 4: Disabled when not needed

This option locks fields that are not needed, once that can be determined. Like option 2, this is more complex because:

• Both need to be locked if question 1 has been answered with something other than "Corporation"
• Question 3 also needs to lock if the answer to question 2 is "No"

The following formulas are entered into the Read-Only section.

For the isForeign control, enter the following formula:

xxf:non-blank($orgType) and string($orgType) != 'corp'

This tells Orbeon to keep the control open unless the user makes an organization type selection that is not "Corporation".

For the jurisdiction control, enter the following formula:

(xxf:non-blank($orgType) and string($orgType) != 'corp') or string($isForeign) = 'false'

This tells Orbeon to keep the control open until one of the following occurs:

• The user selects something other than "Corporation" for the organization type
• The user selected "Corporation" for the organization type, but answered "No" to the foreign entity question

If you don't add this extra condition, the control will remain open when the user selects something other than "Corporation" because the entity question will be locked and never answered.

Other visibility options

Sometimes you want something to appear on the web form but not on the PDF or in the email, or the other way around. You can use the fr:mode() function to accomplish this. It allows you to check the 'mode' the form is in.

Most of the options for this function are for parts of the application not available to you or citizens, but the two you can use are:

• pdf (applied to PDF output, whether autogenerated or templated)
• email (applied to the emails generated)

The PDF option is most common, so we'll use that one as an example.

• To make a field visible only on the PDF, use fr:mode() = 'pdf'
• To make a field visible only on the screen, use fr:mode() != 'pdf'

You can combine fr:mode() with any other conditions, like the ones used above.

For additional information, see:

• Setting up emails
• Designing your PDF
• Using PDF templates