There may be times you want users to create, edit or even delete rows on a data source. You can do this by setting up a form as described below.
Creating/editing rows in a data source
Let's assume you have a data source called 'Projects' and you want to use a form called 'Project Editor' to add/update rows in the projects data source.
- Open the form designer for your form. Make sure you have an editable Draft/Test version.
- Ensure you have a choices field on your form, which should be set to use the 'Projects' data source.
- Click 'Create/Update Row' property on that field. This instructs the form to create/edit the selected row from your choices field.
- Add a few more fields, one for each column that you're allowing to be edited on the projects data source.
On each of these fields make sure you set the 'Bind to Data Source Column' property to assign that field to be bound to the specified column. This binding means that the selected row's value for the given column will be set into the field, and also any edits in the field will be written back to that column.
- To enable the creation of a new row in the data source, you must have a 'dummy' row in your data source which has its first column value set to 0. This way the user can select this row from the list to add a new project.
The app is also coded to treat 0 value rows as being a new row, and it will auto-generate a 36 character unique key (a GUID) for the row to ensure uniqueness.
We recommend you also set the displayable title column of this dummy row to be something like 'Add new project'.
This will make the purpose of the dummy row clear to the user. If you want the dummy row to always be visible as an option on the choices field, set the default value property to 0 and tick on 'Always Show Default Option'.
Once you have implemented the above, test out your form to see the results. Try selecting an existing row and editing it. Also try creating a new row.
Once the form has been completed and uploaded, the projects data source will be automatically updated with the new/edited row, on both the device and then on the central data source on the web platform.
If the data source you are updating is supplied to the app via a Hosted GET, then read on to review the integration considerations involved.
Deleting rows from a data source
If you want to delete rows from a data source you will need to build a separate form that will perform deletes, even if you already have a form that does adds/edits.
This is an intentional platform approach, as it means the deletion operation is always silo'd to a dedicated dorm design. This helps to avoid situations where a user might delete a row when they thought they were inserting/updating it.
Once you have created your dedicated 'Delete' form follow these steps:
- Add a choices field that is linked to your target data source, e.g. if following the example above, this would be your 'Projects' Data Source.
- Click the 'Delete Row' property on your choices field.
This instructs the form to delete the selected row found in your choices field when the user uploads the form entry. Deletion is performed based on the value in the first column of the row - remember our system always treats the first column as the row unique identifier.
- You don't need any other fields besides the choices field above to perform the row deletion. You may want to add some read only fields that use the 'Bind to Data Source Column' option to display additional column information to the user. Allow them to confirm the correct row is selected for deletion.
Hosted GET considerations when creating new rows
Here's what happens when a new row is created on the app:
- A new record gets created with the form entry ID, as the row's identifier in the local app-side data source copy. This is done to give a consistent user experience, in that the user can see the new row they created in any data source listings immediately after completing their creation form entry.
- When a Hosted GET is involved, we expect your system to receive the new form entry (e.g. via a REST connector on the form), process it and check whether the choices/data source field value matches the form entry ID. If your service finds this, then your system knows that this entry created a new row and you can process accordingly, creating a matching new rows on your system with a new system assigned ID.
- A) If your Hosted GET does a full replace of rows on every call from the app, e.g. using the rows property on your responses, then you're done!
The next Hosted GET sync will clear all existing app rows, including the one stored locally with the form entry ID, and replace with your system's rows, including your new system assigned row.
3b. If you are making incremental updates on the Hosted GET, e.g. sending NewRows and DeletedRows back on your responses, you will still need to remove the local app created new row identified by the form entry ID, and adding your new system assigned row.
When receiving the form entry on your web service, you will need to track the user's device ID and form entry ID for use by your Hosted GET service, since you need to replace the app's local new row with your system assigned new row.
On next app sync from the user's device, identified by their device ID, your Hosted GET should send a DeletedRows value containing the stored form entry ID, along with a NewRows value containing the new system assigned row values. This will cause the app to delete the local entry ID based row, and add the new system assigned row.