Display, edit, and create a record in a data source.
If you add a Display form control, the user can display all fields of a record or only the fields that you specify. If you add an Edit form control, the user can edit those fields, create a record, and save those changes to a data source.
If you add a Gallery control, you can configure it to show a table in a data source and then configure a form to show whichever record the user selects in the gallery. You can also add one or more Button controls that the user can select to save edits, cancel edits, and create a record. By using controls together, you can create a complete solution.
For either type of form, you set its DataSource property to a table of records, and you set the form's Item property to show a specific record in that table. For example, you can set the Item property of a form to the SelectedItem property of a Gallery control. When the user selects a record in the gallery, the same record appears in the form, except that the form can show more fields. If the user returns to the gallery and selects a different record, the SelectedItem property of the gallery changes. This change updates the Item property of the form, which then shows the newly selected record.
Each form control contains one or more Card controls. By setting the DataField property of a card, you specify which field that card shows and other details.
When an Edit form control is in Edit mode, the user can update the record that's specified in the form's Item property. If inspected, the Mode property returns Edit.
When an Edit form control is in New mode, however, the Item property is ignored. The form doesn't show an existing record; instead, the values in each field match the default values of the data source with which you configured the form. The NewForm function causes a form to switch to this mode.
For example, you can set the Text property of a button to show New and its OnSelect property to a formula that includes the NewForm function. If the user selects that button, the form switches to New mode so that the user can create a record starting with known values.
If you create a Save changes button as the previous section describes, the user can create or update a record and then select that button to save those changes to the data source. You could, instead, configure an Image control or some other control to perform the same task, as long as you configure that control with the SubmitForm function. In any case, the Error, ErrorKind, OnSuccess, and OnFailure properties provide feedback on the outcome.
When the SubmitForm function runs, it first validates the data that user wants to submit. If a required field doesn't contain a value or another value doesn't conform to some other constraint, the ErrorKind properties are set, and the OnFailure formula runs. You can configure the Save changes button or other control so that the user can select it only if the data is valid (that is, if the Valid property of the form is true). Note that the user must not only correct the problem but also select the Save changes button again (or discard the changes by selecting a Cancel button, as described earlier) to reset the Error and ErrorKind properties.
If the data passes validation, SubmitForm sends it to the data source, which can take some time depending on network latency.
Some data sources can detect when two people try to update the same record at the same time In this case, ErrorKind is set to ErrorKind.Conflict, and the remedy is to refresh the data source with the other user's changes and reapply the change made by this user.
Tip: If you offer a Cancel button on your form so that the user can abandon changes in progress, add the ResetForm function to the button's OnSelect property even that property also contains a Navigate function to change screens. Otherwise, the form will retain the user's changes.
By default, cards are placed in a single column for phone apps and three columns for tablet apps. You can specify how many columns a form has and whether cards should snap to them as you configure the form. These settings aren't exposed as properties because they're used only to set the X, Y, and Width properties of the cards.
For more information, see Understand data form layout.
DataSource – The data source that contains the record that the user will show, edit, or create.
DefaultMode - The initial mode of the form control. See the description of Mode below for the acceptable values and their meanings.
DisplayMode - The mode to use for data cards and controls within the form control.
Derived from the Mode property based and cannot be set independently:
|FormMode.Edit||DisplayMode.Edit||Data cards and controls are editable, ready to accept changes to a record.|
|FormMode.New||DisplayMode.Edit||Data cards and controls are editable, ready to accept a new record.|
|FormMode.View||DisplayMode.View||Data cards and controls are not editable and optimized for viewing.|
Error – A user friendly error message to display for this form when the SubmitForm function fails.
ErrorKind – If an error occurs when SubmitForm runs, the kind of error that occurred.
|ErrorKind.Conflict||Another user changed the same record, resulting in a change conflict. Execute the Refresh function to reload the record, and try the change again.|
|ErrorKind.None||The error is of an unknown kind.|
|ErrorKind.Sync||The data source reported an error. Check the Error property for more information.|
|ErrorKind.Validation||A general validation issue was detected.|
Item – The record in the DataSource that the user will show or edit.
LastSubmit – The last successfully submitted record, including any server generated fields.
Mode – The control is in Edit or New mode.
|FormMode.Edit||The user can edit a record by using the form. The values in the form's cards are pre-populated with the existing record, for the user to change. If the SubmitForm function runs successfully, an existing record is modified.|
|FormMode.New||The user can create a record by using the form. The values in the form's controls are pre-popoulated with the defaults for a record of the data source. If the SubmitForm function runs successfully, an record is created.|
|FormMode.View||The user can view a record by using the form. The values in the form's controls are pre-popoulated with the defaults for a record of the data source.|
The form switches from New mode to Edit mode when any of these changes occurs: - The form is successfully submitted, and a record is created. If the gallery is set to automatically move selection to this new record, the form will be in Edit mode for the created record so that the user can make additional changes. - The EditForm function runs. - The ResetForm function runs. For example, the user might select a Cancel button that's been configured with this function.
OnFailure – How an app responds when a data operation has been unsuccessful.
OnReset – How an app responds when an Edit form control is reset.
OnSuccess – How an app responds when a data operation has been successful.
Unsaved – True if the Edit form control contains user changes that have not been saved.
Updates – The values to write back to the data source for a record loaded in a form control.
Valid – Whether a Card or Edit form control contains valid entries, ready to be submitted to the data source.
To enable a button to save changes only when the data in a form is valid but hasn't yet been submitted, set the button's Enabled to this formula:
SubmitButton.Enabled = IsBlank( Form.Error ) || Form.Valid
BorderColor – The color of a control's border.
BorderStyle – Whether a control's border is Solid, Dashed, Dotted, or None.
BorderThickness – The thickness of a control's border.
Fill – The background color of a control.
Height – The distance between a control's top and bottom edges.
Visible – Whether a control appears or is hidden.
Width – The distance between a control's left and right edges.
X – The distance between the left edge of a control and the left edge of its parent container (screen if no parent container).
Y – The distance between the top edge of a control and the top edge of the parent container (screen if no parent container).
For a comprehensive overview of how forms work, see Understand data forms.