Usage Guide

The Form Builder

The form builder is a tool that allows you to create a form in a declarative way; it is a low-code solution that will enable you to create a form in a matter of minutes.

The form builder consists of 3 main parts:

1. The form structure. This is where you can select nodes and change their properties.
2. The form node (input) properties. All properties are described below.
3. The form preview. The rendering of how the published form will look.

When you finish building your form, you can go ahead and publish it; after publishing, you can send the page with the published form to your end users!

Display Condition Syntax

There are two distinctions you have to understand:

1. The node you want to hide is in the same group as the node you are checking the value of.
2. The node you want to hide is in another group as the node you are checking the value of.

This is better explained by example. Please look at the following form very carefully. The form is filled out on purpose so that you can see that the conditions are met:

Form Structure:

Form Render:

Nodes inside the same group

Display condition for the checkbox inside group 2: ff.NUM gt 5

Display condition for the select list inside group 2: ff.CHECKBOX is true

Display condition for the checkbox group inside group 3: ff.RADIO_GROUP is "X"

Display condition for the textarea inside group 3: ff.CHK2 in ["A","C"]

ff.: Starting point of the display condition

is: This keyword is to check for equality

is not: This keyword is to check for inequality

is gt/gte/lt/lte: This keyword is for numbers. You can use them to specify if a number should be greater than, greater than or equal, less than, or less than or equal

in []: This keyword is used when checking for multiple values, for checkbox groups, tag lists, and shuttles

"": Double quotes are used for text inputs, select lists, passwords, radio groups, autocomplete, and textareas

5: Numbers are used for number inputs

true/false: are used for checkbox inputs, switch

Node inside another group

Display condition for the number input inside group 2: ff.GROUP1.TEXT is "HI"

Display condition for the radio group input inside group 3: ff.GROUP2.SELECT is "C"

Advanced

In the advanced section, we'll explore the other keywords that allow for advanced display conditions. Here we see a few more advanced examples:

ff.GROUP2.NUM is gte 12 and ff.GROUP2.SELECT is not "A"

ff.RADIO_GROUP is "X" or (ff.RADIO_GROUP is "Z" and ff.CHK2 in ["A","C"])

apex.PX_SOME_ITEM is 5

ff.%P%REGISTRATION.%P%EMAIL is "test@test.com" and ff.%P%REGISTRATION.%P%PASSWORD is "password" ff.%A%REGISTRATION.%A%EMAIL is "test@test.com" and ff.%A%REGISTRATION.%A%PASSWORD is "password"

and: keyword to chain multiple conditions together. In this case, both need to be true

or: keyword to chain multiple conditions together. In this case, either condition needs to be true

(): You can use parenthesis to group more conditions together

apex.: This is used to check the value of an item on the page. This can be any item on the page.

%P%: This syntax is used to check the value of an item on the prepended form.

%A%: This syntax is used to check the value of an item on the appended form.

Default Value Syntax

NOTE: The Default Value Syntax is a way to conditionally set a default value to an input. If you want to set the default value to a static value, you can type it in instead of using the syntax.

The Default Value Syntax provides a default value to an input. This uses the same syntax as the Display Condition Syntax. But then, to assign a value to an input, you just use the keyword then, or if you want to use an if else statement, you can use the ternary operator ? "Value if true" : "Value if false".

Some examples:

ff.GROUP1.TEXT is "ABC" then "Default Value"

ff.NUM is 5 then 10

ff.GROUP2.NUM gte 5 ? 10 : 20

apex.PX_SOME_ITEM is 5 then 10

apex.PX_SOME_ITEM is 5 ? 10 : 20

apex.P7_FLOWFORM_ID is 1 ? apex.P7_FLOWFORM_ID : "2"

APEX Item Syntax

In both the display condition and default value syntax, you can use the APEX item syntax to get the value of an item on the page.

The syntax is as follows:

Display condition syntax

apex.PX_ITEM_NAME is "Value"

Default value syntax

apex.PX_ITEM_NAME is "Value" then 10

apex.PX_ITEM_NAME is "Value" ? 10 : 20

Context Syntax

In both the display condition and default value syntax, you can use the context syntax to get the value of a context item. Context items are items that are set by the developer setting our gform_get_context function. In this function, the developer has to set a JSON object that consists of **_objects only.**. The context can be used to make the form aware of certain things, for example, the user that is logged in, the current page ID, the current language, etc.

The syntax is as follows:

Display condition syntax

ff.$.SOME_PATH is "Value"

ff.$.USER.ID is 1

Default value syntax

ff.$.SOME_PATH is "Value" then 10

ff.$.USER.ID is 1 ? "User" : "Admin"

General properties

All inputs have access to these properties

Node type code: This is the input type.

Label: This is the label you provide for your input. It can be written in multiple languages using the following button below. If no other languages are specified in this input, it will use the same input for all the languages.

Node Name: This is the name that identifies the input. This name must be unique inside the same group/container.

Field width: The form is split into 12 columns and you can decide how many columns you can let the input fill up using a number between 1-12.

Sort Index: The position of the input inside the group, providing a higher sort index than the previous input, will put the current input lower in the form than the previous.

Display Condition: This can be used to hide inputs based on a condition that you define.

Help Text: This is text you can provide for specific inputs to guide the end user with their answer. In this input, there can also be extra translations.

New Row: Puts the node on a new row in the form (default "ON"). When disabling this option, it will try to put the current node next to the previous one in the form.

Required: Makes an input required on submit.

Read Only: Makes an input read only.

Parent Node: The parent group/container of the input. All inputs should have this (except for the group/container).

Default Value: The default value of the node. This should be static.

Shared properties

Read carefully which inputs have access to these properties

Choices

This section applies to the following inputs: Checkbox Group, Radio Group, Select List, Shuttle, Textfield with Autocomplete, Taglist

Choices are defined lists of values that we can display in the input types above; you can make any list you want using different types.

Choices Type: You can provide the following types: Static, Reusable, Dynamic, Custom (will only show if you have a custom table/view defined).

Type 'Static':

• Choices Values: Multilingual comma separated input for the display values of the list.
• Choices Codes: Comma separated input for the return values of the list.

Type 'Reusable':

• Choices Reusable Code: The name of the list defined in our provided UC_FLOWFORMS_LOVS table
• Choices Add "Other": This will add another value to the list with the return value "OTHER".

Type 'Dynamic':

• Choices Dynamic Type: Define a custom JSON, SQL Query, or PL/SQL Function that returns a JSON in the following format: [{"label": "example", "value": "test"}]
• Choices Dynamic Query: The value of the JSON, SQL Query, or PLSQL function that returns a JSON.

Type 'Custom' (will only show if you have a custom table/view defined):

• Choices Reusable Code: The name of the list defined in your custom table/view. The table/view should have the following fields
  • LIST_NAME VARCHAR2(255)
  • RETURN_VALUE VARCHAR2(4000)
  • DISPLAY_VALUE VARCHAR2(4000)
  • DISPLAY_SEQUENCE NUMBER
  • PRIMARY KEY (LIST_NAME, RETURN_VALUE)

Repeat Row & Repeat Column

This section applies to the following inputs: Checkbox, Number Field, Password, Select List, Text Field

Repeat Row & Repeat Column are used to create a table-like structure of your input type. You can provide a list just like you would with 'Choices' above, and it will use that list to render the correct rows/columns.

The result will look something like this (example uses a text field as input):

{
    "data": [
        {
            "vertical": "BASIC_INSTALLATION",
            "horizontal": "<50",
            "value": ""
        },
        {
            "vertical": "BASIC_INSTALLATION_SOLAR",
            "horizontal": "<50",
            "value": ""
        },
        {
            "vertical": "BASIC_INSTALLATION_CHARGING",
            "horizontal": "<50",
            "value": ""
        },
        ...
        {
            "vertical": "BASIC_INSTALLATION_SONAR_CHARGING",
            "horizontal": ">100",
            "value": ""
        }
    ]
}

Row/Column Type: You can provide the following types: Static, Reusable, Dynamic, Custom (will only show if you have a custom table/view defined).

Type 'Static':

• Row/Column Values: Multilingual comma separated input for the display values of the list.
• Row/Column Codes: Comma separated input for the return values of the list.

Type 'Reusable':

• Row/Column Reusable Code: The name of the list defined in our provided UC_FLOWFORMS_LOVS table
• Row/Column Add "Other": This will add another value to the list with the return value "OTHER".

Type 'Dynamic':

• Row/Column Dynamic Type: Define a custom JSON, SQL Query, or PL/SQL Function that returns a JSON in the following format: [{"label": "example", "value": "test"}]
• Row/Column Dynamic Query: The value of the JSON, SQL Query, or PLSQL function that returns a JSON.

Type 'Custom' (will only show if you have a custom table/view defined):

• Row/Column Reusable Code: The name of the list defined in your custom table/view. The table/view should have the following fields

  • LIST_NAME VARCHAR2(255)
  • RETURN_VALUE VARCHAR2(4000)
  • DISPLAY_VALUE VARCHAR2(4000)
  • DISPLAY_SEQUENCE NUMBER
  • PRIMARY KEY (LIST_NAME, RETURN_VALUE)

Repeatable Rows/Columns: You can flick this switch on to let the end user provide extra columns or rows to the table. Row/Column Label: Label the column or row

Form input values & extra properties

This part will describe the resulting data value when the end user submits the form, any extra properties the input has, and an example picture.

If you ever need more information about an input, you can always reference the FormKit Documentation

Group

All inputs should always be inside a group. You can put groups into groups to create a nested structure. The group is used to group inputs together; it has no value but structures the form data. The structure of the JSON will look like the following using these groups:

{
  "GROUP_A": {
    "TEXT_FIELD": "Hello World",
    "GROUP_B": {
      "NUMBER_FIELD": "1"
    }
  },
  "GROUP_C_REPEATABLE": [
    // Notice the repeatable group makes the end data an array of objects
    {
      "TEXT_FIELD": "Hello World",
      "NUMBER_FIELD": "1"
    },
    {
      "TEXT_FIELD": "Hello World",
      "NUMBER_FIELD": "1"
    }
  ]
}

Extra properties:

• Collapsible: Collapsible make the group collapsible
• Repeatable: Turn the group into a repeatable group, making the end data an array of objects

Checkbox

Value: a boolean → true/false Extra properties: none

Checkbox Group

Value: An array of string values → ["A", "C"] Extra properties: Choices (as described above)

Color Picker

Value: An string starting with "#"→ "#ffffff"

Extra properties: None

Date Picker

Value: "2024-01-30T08:57:50.000Z"

Extra properties: None

Display Image:

Value: an image blob

Extra properties:

• Image: Choose an image to display
• Editiable Image: Let the end user edit the image

NOTE: When selecting an editable image like the image above, it will automatically get a field width of 12_**

File Browse

Value: File (will end up in the specified file DB)

Extra properties:

• File Accept: Set the mime-type of the file browse More info here
• File Capture: More info here
• File Multiple: Allow multiple files to be uploaded

Hidden

Value: Whatever you specify to be the extra value

Extra properties:

• Extra value: provide a value for the hidden input

Number Field

Value: "1" a string in representing a number

Extra properties:

• Node Length: The maximum number of characters allowed.
• Node Format: Regex expression for the input (https://www.regex101.com)
• Min Value: Minimum value of the number
• Max Value: Maximum value of the number
• Unique: Inside the same group repeatable group, have a unique value
• Repeat Row (as described above)
• Repeat Column (as described above)

Password

Value: "password" a string

Extra properties:

• Node Length: The maximum number of characters allowed.
• Node Format: Regex expression for the input ( regex101: build, test, and debug regex ![ref3])
• Unique: Inside the same group repeatable group, have a unique value
• Repeat Row (as described above)
• Repeat Column (as described above)

Radio Group

Value: "RADIO" a string value provided from the return value in the choices property

Extra properties:

• Choices (as described above)

Select List

Value: "select list" a string

Extra properties:

• Choices (as described above)
• Repeatable Row (as described above)
• Repeatable Column (as described above)

Shuttle

Value: ["X", "Z"] an array of strings

Extra properties:

• Choices (as described above)

Rating

Value: 1 a number

Extra properties:

• Rating Min: Minimum value of the rating

• Rating Max: Maximum value of the rating

• Rating Step: Step value of the rating

• Rating Off Color: Color the rating should have when off (please specify as a string preceded by a "#" ex. "#C748C7")

• Rating On Color: Color the rating should have when on (please specify as a string preceded by a "#" ex. "#C748C7")

• Rating Icon: Name of the Oracle APEX Icon to be used (ex. "heart")

• Rating Hover Highlight: Highlight the rating value on hover

Switch

Value: true/false a boolean

Extra properties:

• Switch On Value: The value when the toggle is checked.
• Switch Off Value: The value when the toggle is unchecked.
• Switch On Label: The text of the Value label when the toggle is checked.
• Switch Off Label: The text of the Value label when the toggle is unchecked.
• Switch Value Label Display: The on and off value labels will always default to being displayed outside and to the right of the toggle. Other accepted values include inner to set the value labels inside of the toggle and hidden, which hides the value labels.
• Switch Value Label Color On: Used to set the color of the value label when the toggle is checked.
• Switch Value Label Color Off: Used to set the color of the value label when the toggle is unchecked.
• Switch Thumb Icon: This prop is used to set the icon that will be placed inside the thumb section.
• Switch Thumb Icon Color On: Sets the background color of the thumb section when the toggle is checked. Switch Thumb Icon Color Off: Sets the background color of the thumb section when the toggle is unchecked. Switch Icon Color On: The color the icon should be set to when toggle-icon prop is set and the toggle is checked. Switch Icon Color Off: The color the icon should be set to when toggle-icon prop is set and the toggle is unchecked. Switch Track Color On: Sets the background color of the track section when toggle is checked. Switch Track Color Off: Sets the background color of the track section when the toggle is unchecked. Switch Alt Label Position: Moves the label above the toggle.

Text Field

Value: "Text Field" a string

Extra properties:

• Node Length: The maximum number of characters allowed.
• Node Format: Regex expression for the input regex101: build, test, and debug regex
• Unique: Inside the same group repeatable group, have a unique value
• Repeat Row (as described above)
• Repeat Column (as described above)

Text Field with Autocomplete

Value: "Text Field" a string

Extra properties:

• Choices (as described above)

Textarea

Value: "Multiline string" Extra properties: None

Mask

Value: "1-111-1111" a string masked the way you provide it in the mask input value

Extra properties:

• Mask Input: The mask to apply. This is a string composed of tokens (like "#") and literal string values.
• Mask Mode: Determines how the mask input operates. Options are shift, replace, and select.
• Mask Prefix: Characters that will always appear at the beginning of the input.
• Mask Suffix: Characters that will always appear at the end of the input.
• Mask Allow Incomplete: By default, the value of a mask input is empty until the pattern is complete. This prop allows the input to use incomplete values.
• Mask Reverse: Runs the mask in reverse — from right to left.
• Mask Show: Displays a live representation of the pattern's placeholder as the internal value of the input.
• Mask Unmask value: By default, the value of the input is the same as what is displayed (with formatting). The string literals will removed from the value if this prop is set to true.
• Mask tokens: Add new tokens or modify existing ones.

Taglist

Value: ["X", "Z"] array of strings

Extra properties:

• Choices (as described above)

Camera/File

Value: File (will end up in the specified file DB)

Extra properties: None

Number Field with a Unit of Measure

Value: "123L" string that consists of a number followed by the unit of measure

Extra properties:

• UOM lists (same as Choices described above)