Create a new record using a simple form
This topic shows how to use the UiSdlForm component to build a basic form that collects user inputs, submits data, and creates a new WindTurbine entity.
The UiSdlForm component represents a structured, user-facing form. This component:
- Handles user input.
- Manages validation.
- Submits data to backend actions.
Each UiSdlForm instance uses two essential properties to function correctly: submitDataSpec and dataSpec.
JSON configuration for creating records
The form provides inputs for location, manufacturer, and manufacturing date. On submission, the form saves the data using the backend API.
The configuration below defines a complete form setup that creates a new WindTurbine record:
/* examplePackage/ui/c3/meta/examplePackage.SimpleForm.json */
{
"type": "UiSdlConnected<UiSdlForm>",
"component": {
"title": {
"title": "Wind Turbine"
},
"subtitle": {
"title": "Add new wind turbine"
},
"submitDataSpec": {
"dataType": "WindTurbine", // Target backend model to persist form data
"actionName": "merge", // Saves the data using 'merge' — inserts or updates based on existence
"submitArgument": "this" // Passes full form data object as the argument to the backend action
},
"clearOnCancel": true, // Resets form fields to initial state if cancel is clicked
"width": 20,
"dataSpec": {
"dataType": "Wind Turbine",
"fieldSets": {
"type": "[UiSdlFormFieldSet]", // Required type declaration for array of field sets
"value": [
{
"type": "UiSdlFormFieldSet", // Group of related input fields
"fields": [
{
"inputElement": {
"type": "UiSdlTextInput", // Text input for manufacturer name
"placeholder": "Enter a manufacturer"
},
"value": "manufacturer", // Default value for the input (optional)
"fieldName": "manufacturer", // Binds input to the 'manufacturer' property on the WindTurbine model
"label": "Manufacturer"
},
{
"inputElement": {
"type": "UiSdlTextInput", // Text input for location
"placeholder": "Enter a location"
},
"value": "location", // Default value (optional)
"fieldName": "location", // Binds to the 'location' field in the model
"label": "Location"
},
{
"inputElement": {
"type": "UiSdlDateTimeInput", // Date picker for manufacturing date
"allowKeyboardEdit": "true", // Allows manual entry of dates in addition to using the picker
"placeholder": "Enter manufactured date",
"dataSpec": {
// Configures dynamic behavior or restrictions for the input
"dataType": "WindTurbine",
"range": {
"rangeStart": {
"type": "UiSdlFieldBasedDataSpecSetting", // Binds rangeStart dynamically to a field value
"fieldName": "manufacturerDate" // Field used to calculate the allowed date range
}
}
}
},
"fieldName": "manufacturerDate", // Binds to 'manufacturerDate' on the data model
"label": "Manufactured date"
}
]
}
]
}
}
}
}How forms submits and loads data
The submitDataSpec block defines how the form sends collected data to the backend. This configuration connects the form to the server-side logic.
actionName sets the action that the platform executes when the form is submitted. In this example, it uses
"merge", which either inserts a new record or updates an existing one. Use"merge"when you want a flexible save operation that updates an existing record when the ID field is present and there is a record with the same ID persisted in the database, or creates a new record in the database if the id field is not present or is present but there is no existing record with that ID in the database.submitArgument specifies the argument that the backend action receives. The value
"this"means the full form data is sent as-is to the backend.
The dataSpec block describes the structure of the form. It defines the fields shown to the user, how they map to the data model, and any default behavior.
- fieldSets groups fields logically and defines how they appear in the form layout.
- Each field:
- Uses fieldName to bind the input to a specific property in the
WindTurbinemodel. - Defines an inputElement type such as UiSdlTextInput or UiSdlDateTimeInput to determine the user interface.
- Optionally includes
placeholder,label, and other properties to guide the user.
- Uses fieldName to bind the input to a specific property in the
This design pattern keeps the form dynamic, model-aware, and consistent with platform conventions.