Dynamic Forms: Tutorial Guide

Dynamic Forms for Podio allows you to easily build complex forms with lots of complex logic. This tutorial page will guide you through the more advanced features.

 

Overview

1. Creating a Form

Forms can be created from the Overview page. Go to this page by clicking on Dynamic Forms in the navigation bar. Select your organization, workspace and app from the drop-down fields. You can choose whether you want to create a form (1 page form) or a wizard (form with multiple pages). Then click the Create new Form button to start building a form.

Important: It is possible to create multiple forms for the same Podio app.

Momentum

2. Edit, Share or Delete a Form

Once you have saved your form, it will become visible in the Overview page. In the section Your Dynamic Forms you will see your existing forms. There you have the option to edit, share, clone or delete your form.

Important: Deleting a form cannot be undone. Use caution.

Momentum

3. Form Components

A Form component collects user data and serves as the display or user interface within the system. Form components define the type of widget that users will enter their data and need to be linked to a Podio field of the related Podio app. To add a form component to a form, drag and drop the component from the left column into the desired location within the form.

Momentum

When you drop the form component, the settings form for the component will open. The settings for a form component are different for each component type, but the following parameters are usually present:

  • Label: The name or title for this component
  • Podio Field: Link it to a field of the related Podio app. In the Podio field drop-down you can only select the Podio fields that are relevant for the component type. Eg: The single text component cannot be linked to a number field in Podio.
  • Placeholder: The placeholder text that will appear when this field is empty. 
  • Tooltip
  • Description

Once you have filled in the parameters, click Save to add the form component to the form.

Momentum

To edit a form component on a form, hover over the component and click the  gear icon. You will then be presented with the settings form for the component.

Momentum

4. Layout Components

a) Section

A section may be added to a form to add extra text or instructions. 

  • Example 1: Add instructions at the top of a form that are for display only.
  • Example 2: Add section titles to structure your form.

There are no settings for a Content component and the value is not submitted back to the server. A WYSIWYG editor has been provided to help with formatting the content. If you use the HTML view of the editor, note that all unsafe HTML is stripped before rendering to prevent cross-site scripting exploits.

Momentum

b) Columns

The Column layout component can be used to split any area into two columns. Simply drag and drop the Column button onto the form and the area you drop it on will be split in two.

Momentum

c) Tabs

The Tab component allows adding tabs to the same page. You can add different form components to each tab. 

Momentum

d) Table

The table component allows creating a table with columns and rows that allow adding additional components within it.

Momentum

5. Conditional fields

a) Simple

Any form component can use conditional logic to determine when to hide or display itself. The settings for a conditional field, are configured on the component itself, and can be found by viewing the Conditional tab within the components settings.

The conditional logic is based on the following rules:

  • Each field can hide or display.
  • The visibility is dependent on another component defined within the form.
  • The logic is activated when the configured field contains the plaintext value defined in the settings.
Momentum

b) Advanced

In addition to Simple Conditional logic, you can also use Advanced Conditional logic, which uses actual JavaScript for any combination of conditions.

JavaScript conditional logic requires you to set the value of show to either true or false. Advanced Conditional logic will only work, if Simple Conditional logic isn’t already defined. Keep in mind that you need to refer to the External Field ID of a Podio field. 

Use the following syntax for text and number fields:

show = data["external-field-id"] == "value"

For category fields you  need to specify the label id (1, 2, ...) instead of the value itself. Use the following syntax for single category fields:

show = data["single-category"] == 1

Use the following syntax for multiple category fields:

show = data["multi-category"][1] == true  

Momentum

c) Examples

JavaScript also allows you add more complex conditional logic. Below are a few examples to make you familiar with the possibilities of advanced conditions.

Single condition

show = data["text-field"] == "hello"

The condition above will show the form component if the field with external ID "text-field" has input value "hello". 

OR condition

show = data["category-field-2"][1] == true || data["category-field-2"][2] == true

The condition above will show the form component if the 1st OR 2nd option of the category field with external ID "category-field-2" -field-1"  is selected.

AND condition

show = data["text-field-1"] == "yes" && data["category-field-1"][2] == true

The condition above will show the form component if the field with external ID "text-field-1" has input value "yes" AND if the 2nd option for field with external ID "category-field-1" is selected.

Exclude condition

show = data["single-category"] != 1

The condition above will show the form component if the field with external ID "single-category" has an input value different from the 1st label. 

6. Styling your form

a) Basic

Via the Customize tab of the form builder you have the option to change a few Basic styling parameters. Via the Preview button you can see how your changes impact the lay-out.

Momentum

b) CSS File

If you select the option CSS File, you can select a theme from bootswatch.com. Scroll down on this page and choose a theme that you like. Then click on Download, select the bootstrap.min.css option and copy the URL. 

Note: Selecting a theme will overwrite the basic styling parameters.

Momentum

c) Advanced

To add your own custom CSS code to your form,  click on the share option in the menu bar. A pop-up will be shown with the shareable link and the embed code. In this embed code you can add the custom CSS file.

Momentum

7. Pre-filled values

a) Text and number fields

To pre-fill the values for text and number fields, use the following syntax:

  • One value: forms.momentumtools.io/?form=form_id&external_id=value
  • Multiple values: forms.momentumtools.io/?form=form_id&external_id1=value1&external_id2=value2

To get the form_id click on Share in the menu bar. The form_id is the 12-character string at the end of the shareable link.

Momentum

To get the external_id of the field, go the Podio app and open the developer page.

Momentum

Scroll down to find the external_id of the related Podio field.

Momentum

b) Category fields

For category fields you need to use a different syntax to pre-fill the values. In this case you need to specify which label id (1, 2, ...) you would like to check. Use the following syntax:

  • Category Single : forms.momentumtools.io/?form=form_id&external_id=1
  • Category Multiple : forms.momentumtools.io/?form=form_id&external_id[1]=true&external_id[2]=true

8. Update existing items

To update an existing Podio item via a Form, use the following syntax:

forms.momentumtools.io/?form=form_id&item_id=item_id

Click here to learn how you can find the form_id.

To find the item_id, go the Podio app and open the Podio item. Click on Actions, then developer info.

Momentum

The pop-up will show you the item ID of the related item.

Momentum

9. Data Validation

Data validation can be applied to any form component. The data validation of a field, are configured on the component itself, and can be found by viewing the Validation tab within the components settings.

a) Basic

  • Required: If checked, the field will be required to have a value upon submission.
  • Minimum length: The minimum number of characters required to be entered for this field.
  • Regular Expression Pattern: The regular expression pattern test that the field value must pass before the form can be submitted. See regex101.com for help with writing regex expressions.

b) Custom Validation

You can use javascript to perform validation on a field. The way to respond is by setting the valid variable. If it is set to true then the validation passes. If you set it to a string, the validation fails and the validation message is set to whatever the valid variable is set to.

In addition, input variable is set to the value that has been entered in the field. The component variable is set to the definition of the field.

You can also reference other resources and properties for validation. For example, if there is a user resource with a password field, you can use its value with user.password

c) JSON Validation

Coming soon.

Momentum

10. Disable or Hide Input Fields

To disable or hide an input field, open the settings of the form component and check the disable or hide option.

  • Disable: Will disable the form input. 
  • Hide: A hidden field is still a part of the form, but it is hidden from view.  

These 2 options are, in combination with updating an existing item, very useful to address several use cases:

  • Disable: Show data from an existing Podio item to the end user, but prevent that the end user can edit the field.
  • Hide: "Secretly" update a Podio field when an end user submits a form. 
Momentum

11. Calculated Fields

Any form component can use logic to calculate its value. The calculation of a field, are configured on the component itself, and can be found by viewing the Calculation tab within the components settings.

Momentum

12. Translations

Via the Translations tab of the form builder, you can add multiple translations to the same form. In the field Default Locale you specify which language key you want to use. In the field Translations JSON you can list the different translation keys via JSON code. Depending on the selected langauge, the JSON code will find and replace every translation key in your form.

To get started you can copy the example code below and use the editor of jsoneditorlinline.org to update your code.

{"en":{"Yes":"Yes","Submit":"Submit"},
"sp":{"Yes":"Si","Submit":"Enviar"},
"de":{"Yes":"Ja","Submit":"Einsenden"}}

Momentum