Form - Best Practices

Plan the overall form design and table structures prior to development

Description:

Plan the entity relationship (ERD) between form tables, outline the form layout, and analyze required fields upfront, prior to development.
This way, we can avoid common pitfalls on a best effort basis. This also ensures that form best practices are implemented in a preventative manner rather than "fixes" later on.

 Once an app has been deployed to PROD and has active usage, any modifications will have the added complexity to take into account of existing real-world user data.

Solution: 

• Good planning on form designs and table structures will ensure data consistency and constraints are in place, data is stored efficiently and optimized for reporting, prevent ambiguity of requirements, minimize technical debt on reworks, and many more benefits.

Don't add too many fields in a single form table

Description:

Most databases have a limit on the number of columns it can support in a table. Often, approx max of 200 VARCHAR columns.
Even if a form comes close to the limit, this may present maintenance challenges for the Joget app developer, and also increase complexity for any reporting purposes.

Solution: 

• Ideally, table normalization should be done prior to deploying to PROD.
  Once there is existing user data, this effort may be considerably complex as it now requires careful data migration and manipulation.
  Plan the table structure before beginning development work.

• If a form is becoming too large, consider splitting fields into several different form tables, and use Subform in order to create a parent-child table relationship.

Take caution on reusing same field IDs

Description:

Joget allows different form elements to reuse the same field IDs, in order to cater to special customization use cases.
However, issues can arise if multiple fields are unintendedly reusing the same exact field ID.
This rule applies to all form elements, including form sections and grid elements as well.

 In the "best" case, this will cause inconsistent record data being saved to DB due to data contention.
In the worst case, this can cripple form functionality altogether.
For example, if a form section ID is "documents" & another File Upload field ID is also "documents", depending on the ordering of the form structure, this can cause file uploads & retrievals to fail, since Joget is unable to differentiate which element is intended. 

Solution: 

• Avoid reusing same field IDs.

• If a form is becoming too large/complex and it becomes too difficult to recall which field IDs are already in use, this may be an indicator that the current form table is too large.
  Consider splitting into several different form tables, and use Subform in order to create a parent-child table relationship.

Naming convention for form-related identifiers

Description:

Use snake case for all form-related identifiers, such as for form field IDs and table names. This includes form section IDs and grid elements as well.
And as per expected practice for any identifiers, ensure all identifiers used are unique and do not reuse the same exact value unless intended.

The reason for this practice is, the forms and fields will dictate how Joget creates the underlying table structure in the database.

Since Joget officially supports MySQL, MSSQL, Oracle DB, Postgres, some DBs can be case-sensitive by default depending on the OS installed on and RDBMS you have. If this situation applies to your environment, this can cause confusion when app developers unintendedly use inconsistent letter capitalizations.

Solution: 

• Use snake case for all form-related IDs.
  Meaning, all spaces between words are replaced with underscore symbol "_", and no words are capitalized.
  Example: citizen_id, contacts_section, my_table_name

• If this convention is not followed, there would technically be no ill effects.
  Most importantly, simply keep a consistent naming convention to avoid app development and maintenance confusions.

Group-related fields

Description:

End users may face readability issues if all form inputs are arranged in a vertical manner without any thoughtful layoutting or categorizations. 

This forces end users to one-by-one understand the intent of field inputs, and can be prone to human errors, which may increase unnecessary need for additional input validations.

Solution: 

• Split input fields into distinct form sections with labels (e.g.: contact details, emergency contacts, shipping info, etc.), to avoid end user fatigue.

• Consider using Multi-Paged Form Element, to split into distinct sections & still allow for a 'compact'-like form.

Perform impact analysis before changing form design

Description:

Let's say in PROD, your app is already in-use for a while ; you already have several rows of real-world data in DB.
Example 1, let's say you want to change a date picker stored data format from mm/dd/yyyy to dd/mm/yyyy.
By doing this, new rows stored will use this new date format, however the old data is not accounted for, and end users using those old form data rows may experience issues with date format being incorrect, or worse case, not being able to parse at all.

As another example 2, you plan to make changes to forms that are actively used to represent activity(s) in your processes.
Joget has warning mechanisms to prevent accidental deletions of app components with active linkages to other components, however, the platform does not restrict modifications even if app components are published and in-use.
Carelessly modifying form design may unintentionally break functions (e.g.: values used for process routing).

Solution:

• In Advanced Tools, always check for form usages in the Usages tab, or check for ERD in the Table tab.

• Take into consideration of the old data before making changes to an existing form design.

• Take caution especially for these scenarios:

• Modifying/Deleting form components.
  Careless modifications or deletions may disrupt app stability due to missing linkages by other components or disconnected value retrievals for process flows.

• Deleting form fields.
  Joget will not delete the actual column on the database table for safety purposes, instead the 'deleted' field data will no longer be referencable on Joget platform.

• Changing the field ID of a field.
  This is the equivalent of adding a new column into the database table & orphaning the older field ID column. Joget will not automatically rename columns within the database table.

• Changing the table name of a form.
  This is the equivalent of creating a new database table & orphaning the older table name. Joget will not automatically rename database tables.

• Assess any other means of fulfilling requirements without the need to alter existing data.
  If a change is deemed necessary, then consider remediation efforts to maintain data consistency.

• Using the above example 1 of changing date picker stored data format, it may not be necessary to change the date data format, but instead we could simply change the date display format to achieve the intended result without needing any manual database alterations.

Pay attention to form load & save times

Description:

Long form load/save times impact end user experience, or in worse severity it can cause misunderstanding that server has failed to operate.
Standalone forms without any integrations should load fairly fast (unless the amount of data is extremely huge).

However, performance issues commonly arise when executing complex custom bean shell scripts, or external integrations such as external DB queries or JSON API calls are used in a form.
Since custom scripts and external resources are out of Joget's control, any slow performance incurred by these will force the Joget server to wait for them to finish execution.

Solution: 

• For multi-row elements (e.g.: select box, grid elements), be aware of the amount of data to be loaded.
  Example: It is highly unlikely that an end user needs to scroll through 10000 options in a select box. It also impacts performance on the server & end user browser performance to process lots of data. Consider using AJAX Select Box or Autocomplete Text Field, that also allows searching.

• If there are multiple select boxes that have dependencies on other form field values in order to load selections, consider using AJAX Dynamic Cascade Drop-downs.

• For any external DB queries or JSON APIs executed, do be aware of performance of external resources.
  Example: If a form executes an API call for Post Form Submission Processing, if this API call responds slowly, server is forced to wait for API call to finish. This also forces the end user to wait for form save to complete.

Enforce form validation

Description:

Form Validator plugins in Joget will be processed in the backend, to ensure expected values are entered for user input.

Optionally, you can also customize your forms with custom frontend validation logic, to better assist your end users to fill in correct data & further minimize backend calls to Joget server to check validation.

Do not rely solely on frontend validation, as this can be easily bypassed by savvy users via browser developer tool manipulations.

Solution:

• You can configure Form Validator for form elements, to ensure expected values are entered for user input.
• To avoid potentially "reinventing the wheel" for your validator requirements, you can search for Form Validator plugins in the Joget Marketplace.

Use placeholder value or tooltips where it helps

Description:

There may be cases where some fields may be unfamiliar to an end user (e.g.: public citizen filling up forms for government related operations).
Although field validation is important, it is also equally important for input fields to be as helpful where possible.

 Over-reliance on form validation without intuitive visual or informational cues may cause form submissions to be frequently bounced back with validation errors, and result in a frustrating end user experience.

Solution: 

• For text fields, where relevant, configure "placeholder" to add helpful descriptions or sample values for end users to better understand the expected input values.
• In the Form Builder, under "Advanced Tools", use the "Tooltips" feature to add helpful hoverable-popups with descriptions for end users to better understand the expected input values.

Enforce file/image upload size limit & file format

Description:

If no file size limit is enforced on File/Image Upload field, end users can upload a huge file that may incur unnecessary storage on the server.
If file format is not enforced, any file of any file extension type can be uploaded without restriction.
And depending if there are customizations to process such files in real-time, it may incur unexpected behaviours or performance penalty.

In most cases, the intent of a file upload field is already known upfront to the developer.
For example, if a file upload field is only expected to accept PDF files within the max expected range of 5MB per file, it would be wise to limit file size to max 5MB & only accept file .pdf file extension.

Solution: 

• For all File/Image Upload fields, ensure the maximum file size & file type is configured.

Remove unnecessary form permissions

Description:

Although permission control can be applied in many different components of a Joget app, it is not necessary to apply again in a duplicate manner.

For example, if the related UI is already configured for Logged In Users only, it is not needed to reapply this same permission on the form layer, as this adds unnecessary processing overhead & is prone to configuration error.

Solution: 

• If the "outer layers" already have adequate permissions, it is not required to add permission on the form layer. Remove redundant permission rules.
• Apply permission rules conservatively. Only if the UI is unable to granularly control permission to your requirement, only then apply permission rules on the form layer.

Control form element visibility via "Visibility - Advanced Tools"

Description:

A new feature in Joget DX 9.1 onwards, the previous "Form Section Visibility" feature has been upgraded to its own "Visibility" tab, under "Advanced Tools".

For this upgrade, you can now easily configure as many conditions as you need, and control visibility in a granular manner even on individual form elements.

Hence, it is no longer necessary to create "dummy" form sections in order to show/hide form components.

Solution: 

• If you are currently using older versions of Joget, it is highly recommended to update/upgrade to the latest version of Joget in order to enjoy new features or refinements for better app design.