Code Morphing to an Edit Form.

Lightning Record Edit Form

The Lightning Record Edit Form (lightning:recordEditForm) Base Lightning Component provides a way for developers to quickly create forms to create and edit records. It specifies event handler attributes (onload, onsubmit, onsuccess, onerror) and a method (submit) that allow developers to write customizations that hook into its standard functionality. This article explores what is available in each event’s context and some use cases for each one.

Example Component

This example is a simple component with a lightning:recordEditForm for a Contact. For the purposes of testing, a recordId attriburte and parentId can be supplied.

Onload

The onload event fires when the form is loaded. An instance of a Record UI is passed in as part of the event. This is part of the User Interface API (UI API). The way to get the instance is via the “recordUi” parameter of the event. Note that the documentation for RecordUI has a Map<String,Record> “records” property with the String being the record ID, but the object in the event has a “record” property that contains the Record which makes sense because there is only one.

Create

When creating a record, field values are not yet available; however the metadata about the fields is available. Here are some assertions that show where some of the values are located.

Edit

When editing a record, the field values are available as well as the metadata information. Note that some field values such as IDs for lookup fields appear in different places as illustrated in the assertions below.

Prepoulate a Field

A lightning:inputField can be prepopulated with a value by explicitly setting its value attribute. It might be tempting to mess around with the Record UI that is returned, but remember that when setting values for components, that needs to be done by using what is part of their specification, such as setting available attributes, which in this case is the “value” attribute.

We do have the ability to get field values via the Record UI during the onload and store them in component attributes for use in other events or to display them on the page. You may also use lightning:outputField within the lightning:recordEditForm and specify that its label should be hidden if you want to output just the value in a metadata aware way.

Onsubmit and Submit

The onsubmit event is fired automatically by the framework when the user clicks a button that has a type of “submit” that is within the form. A parameter named “fields” that contains the values of the fields submitted with the form is passed as part of the event. It is worth noting that compound fields such as Name, are passed in as their component parts. You can add your own values to fields in the component by simply overwriting whatever values is there, or to fields that exist on the object but are not in the component by adding them to the fields object. One use case for the latter, would be to add a parent ID field to a child record, when you do not want the user to be able to select the parent record. I first saw this use in Alba Rivas’s blog post.

Let’s say that the example component did not have the Account as an input field, but we wanted to set it behind the scenes in the onsubmit handler instead.

There is a method named “submit” on the lightning:recordEditForm component that takes the fields object as an argument. This is, obviously, what should be called to submit the form programmatically. The event.preventDefault() is called to prevent the form from submitting twice, since it is also being submitted by the framework in addition to the programmatic submit(fields).

The specification of the submit method:

To customize the behavior of your form when it loads or when data is submitted, use the onload and onsubmit attributes to specify event handlers. If you capture the submit event and submit the form programmatically, use event.preventDefault() to cancel the default behavior of the event. This prevents a duplicate form submission.

It is worth noting, that you do not have to cancel the default behavior and submit programatically. You can just set the fields and the deafult submit behavior will take care of the normal save.

The use case for calling submit programmatically is if you do not want to submit under certain conditions. This method would allow you to detect those conditions and then not submit.

Onsuccess

The onsuccess event is fired after the form is sucessfully saved. The object in the event is named “response” and is in the form of a Record from the User Interface API. It has:

  • apiName: The record’s API name, such as Contact.
  • childRelationships: The child relationship data for this record.
  • fields: The field data for this record, matching the requested layout.
  • id: The ID of this record.
  • recordTypeInfo: The record type info for this record, if any.

A common thing to do in this situation is to display some sort of confirmation message in the form of a toast. You can use the lightning:notificationsLibary component methods to achieve this.

Make sure that you include the lightning:notificationsLibrary component.

Onerror

The onerror event is fired when there is an error on form submission. Within the event handler you may want to take other actions such as making updates to other attributes of the component or fire some events. The object parameter in the event is named “error” which takes the form of a response defined in the UI API as an Error with Output with a nested Record Exceptions when there are failures on record create or update.

Consider a validation rule that requires the Department to be set when the Salultion is “Dr.” and that validation rule is set at the Department field level.

When the validation rule evaluates to true and the record fails to save, the field level message will automatically get displayed at the field level and the top level message will get displayed in the lightning:messages component.

The error object contains information about the error at the field level. The error object has a top level message in the message attribute and more detailed information about the exact field and message in the data object.

If that validation rule were to change to be at the Top level instead of the field level, the lightning:messages would contain the field level error message.

The contents of the error object would change slightly as well. Instead of the fieldErrors object containing the error, the non field specific output.errors array has the error.

Fields that are required are validated prior to the form submission with the HTML 5 required attribute. For required validations you’ll see an error like the following screen.

One thing I noticed was that in the onerror handler, component.find(“theAuraId”) did not seem to work. It always returned an empty object: “{}”. However, getting attribute values from the component (e.g., component.get(“v.recordId”) ) did work.

More

Visit the component library documentation on lightning:recordEditForm to see the official documentation on the Lightning Record Edit Form Base Lightning Component. There are also Trailhead units that feature lightning:recordEditForm and a module for the UI API. It is also worth checking on Known Issues related to lightning:recordEditForm. Closely related to lightning:recordEditForm is lightning:recordForm. It provides much of the same capabilities, but supports read-only and inline edit modes as well as edit mode.