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.
- Creating a Form
- Edit, Share or Delete a Form
- Form Components
- Layout Components
- Conditional fields
- Styling your form
- Pre-filled values
- Update existing items
- Data Validation
- Disable or hide input fields
- Calculated fields
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.
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.
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.
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.
Once you have filled in the parameters, click Save to add the form component to the form.
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.
4. Layout Components
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.
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.
The Tab component allows adding tabs to the same page. You can add different form components to each tab.
The table component allows creating a table with columns and rows that allow adding additional components within it.
5. Conditional fields
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.
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"] == true
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".
show = data["category-field-2"] == true || data["category-field-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.
show = data["text-field-1"] == "yes" && data["category-field-1"] == 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.
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
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.
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.
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.
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.
To get the external_id of the field, go the Podio app and open the developer page.
Scroll down to find the external_id of the related Podio field.
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=true&external_id=true
8. Update existing items
To update an existing Podio item via a Form, use the following syntax:
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.
The pop-up will show you the item ID of the related item.
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.
- 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
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.
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
c) JSON Validation
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.
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.
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.