Submit Button Element
The Submit Button Element provides a pre-configured button which the user can click or tap when they have finished filling in your form.
Clicking or tapping the Submit Button will output the current values in all Elements which have an output data mapping configured to the Datasources specified in those output mapping. You will need to make sure that all Elements whose contents you want to save have been output mapped to a Datasource, e.g. by using the New Datasource from Form option.
If the user has created multiple records whilst using the form, submitting the form will save all records to the relevant databases.
In addition, if you have used the File Upload Element, any specified files will be uploaded when the form is submitted.
When you publish a form, as part of the publishing settings, you can specify that a PDF copy of the form should be automatically created when a user submits the form.
-
If an Imported or Digitise Forms Dataset has a Primary Key with a data type of int and its Identity property set to True or a data type of uniqueidentifier (GUID), Form Studio will automatically assign a value to the Primary Key field. For Primary Key(s) which have other data types, you will need to manually enter a suitable value into the Primary Key field(s), either within your custom JavaScript or via an output mapping from a suitable Element on the form, before you submit the form. When you publish your form, Digitise Forms will warn you if there are any Datasets which won't automatically have their Primary Keys generated.
Digitise Forms Datasources automatically have their Primary Key set to be a GUID, so this is generally only a potential issue with Imported Datasources. You can check a Primary Key's data type by opening the appropriate Dataset from the Datasources tab in the Project Explorer.
For Imported Stored Procedures which only include inserts or updates, and don't return a Result Set, you will need to provide the Primary Key value(s) if these are not accounted for in the Stored Procedure, Digitise Forms will not supply these as it does for Imported and Digitise Forms Datasources.
Imported Stored Procedures which return a Result Set do not use the Submit button to upload data and so this is not relevant in this situation.
-
Imported Stored Procedures which return a result set are not affected by this button - in order to execute them you need to use the LoadDatasource action in an Event (see Events tab under Properties below) or call loadDatasource within custom JavaScript. Imported Stored Procedures which only perform inserts and updates and those used with Digitise Forms Datasources will be executed by a call to submitForm providing you have output mapped Elements to them.
Once you have placed a Submit Button Element on a page, you can edit the Element's properties to configure the Element for your requirements. Select the Element on the page to display its properties in the Properties Pane.
The following properties are available:
Label
Allows you to specify the text you want to display on the face of the button. If you want to display an image on the button with no text, leave this property blank.
Visible and Disabled Properties
Image
Allows you to specify an image to be displayed on the button. If you specify a value in the Label property above, the position of the image in relation to the label is defined in the Image Position property on the Advanced tab, 
.
To browse for the picture, click on 
at the right-hand end of the property. A standard file browse dialog will be displayed allowing you to locate and select the required picture. If you want to re-use a picture that you have already used in this project, click on the down arrow symbol at the end of the edit box instead. This will display a list of images used in the project and you can select the one you want.
If you want to change the picture, simply select the new picture you want to use instead or to clear the selection, click on 
to the right of the button.
The Event properties allow you to provide customised actions to be performed when the submission is successful or when it fails. You can provide different actions for the two Events.
If the Success or Failure Events have an action or JavaScript function assigned, these will be actioned before the Success Page or Failure Page options found on the Advanced tab, .
Behaviour Category
Success Page
Allows you to specify a page to go to if the submission is successful. Leave blank if you do not want the form to display a specific page after a successful submission.
Note that if you are submitting multiple records, the success or failure pages, if specified, will be displayed, as appropriate, after all records have been submitted. The success page will only be displayed if all records are submitted successfully.
Failure Page
Allows you to specify a page to go to if the submission fails. Leave blank if you do not want the form to display a specific page after a failure. If you are displaying Datasource error messages (see Error Function and Error Message Text properties below), the page specified here will be displayed in addition to the error message.
Note that if you are submitting multiple records, the success or failure pages, if specified, will be displayed, as appropriate, after all records have been submitted. If at least one record fails, the failure page will be displayed.
Error Function
Allows you to specify a custom JavaScript function which will be called if the submit fails to output the data on the form due to a datasource error. By default the Submit Button includes built-in error handling, which will display the error message specified in the Error Message Text property below in the event that the button is unable to output the form data. The Error Function property allows more experienced developers to enhance this error handling by creating a JavaScript function to handle the errors instead.
If you want to create a custom error handler function, it must be based on the default error handler used with calls to the Digitise Forms intrinsic functions loadDataSource and updateDatasource. To create your own function, you will need to edit the custom JavaScript file and copy an existing error handling function, such as the default onDatasourceError function added to the custom Script file when data error messages are enabled. You can then rename and edit your new function as required, before entering the name of the function here in the Submit Button's Error Function property. For more information, including the format of an error handler function refer to the
If you leave this property blank, the standard error handling built into the Submit Button will be used instead and the error message supplied in the Error Message Text property below will be displayed if data cannot be submitted due to datasource errors.
- The error handling function will only be called if data error messages are enabled by selecting the Display Error Messages property in the form properties. If the error messages are disabled, and the submission fails, no message will be displayed and the submission will fail silently.
Error Message Text
Allows you to specify an error message to be displayed if the submit encounters a Datasource problem when attempting to output the form data. If a JavaScript function is specified in the Error Function property above, the error message specified here will be ignored.
- The error message entered here will only be displayed if data error messages are enabled by selecting the Display Error Messages property in the form properties. If the error messages are disabled, and the submission fails, no message will be displayed and the submission will fail silently.
Reset Form on Submit
If selected after submitting the form, the form will be cleared and should return to the same state it was in when first loaded.
Image Category
Image Position
Determines whether the image specified in the Image property above is displayed to the left or right of the button's label. If the Label property, above, is blank, this property is ignored.
Image Height
Specifies the height, in pixels, for the image. If you specify the height but not the width, the width will automatically be adjusted to maintain the original aspect ratio of the image. If you leave both the height and width blank the image will be displayed at its actual size.
Image Width
Specifies the width, in pixels, for the image. If you specify the width but not the height, the height will automatically be adjusted to maintain the original aspect ratio of the image. If you leave both the height and width blank the image will be displayed at its actual size.
Styles Category
Label Style
Allows you to assign a style to the Button's Label, e.g. to set the font type, size and colour.
Button Style
Allows you to assign a style to the body of the Button, e.g. to set the background colour.
If you have upgraded a project created using a version of Digitise Forms earlier than Digitise Forms - 2021 Spring Update, this property will automatically be set to the same value as the Label Style property above.
- If you are upgrading from Digitise Forms v1.4 or earlier, changes to the Submit Button error handling introduced in v1.4 could potentially result in error messages being displayed when a form is submitted which previously would have been handled silently. This only refers to error messages which were present before but were simply not displayed in earlier versions. As with any upgrade, we recommend you thoroughly test your forms after upgrading and republishing in the latest Form Studio before updating your live systems.
See also: