Creating a Record

To create a record using Lightning Data Service, declare force:recordData without assigning a recordId. Next, load a record template by calling the getNewRecord function on force:recordData. Finally, apply values to the new record, and save the record by calling the saveRecord function on force:recordData.

Call getNewRecord to create an empty record from a record template. You can use this record as the backing store for a form or otherwise have its values set to data intended to be saved.
Call saveRecord to commit the record. This is described in Saving a Record.

Create an Empty Record from a Record Template

To create an empty record from a record template, you can’t set a recordId on the force:recordData tag. Without a recordId, Lightning Data Service doesn’t load an existing record.

In your component’s init or another handler, call the getNewRecord on force:recordData. getNewRecord takes the following arguments.

Attribute Name	Type	Description
`entityApiName`	String	The entity API name for the sObject of the record to be created.
`recordTypeId`	String	The 18 character ID of the record type for the new record. If not specified, the default record type for the object is used, as defined in the user’s profile.
`skipCache`	Boolean	Whether to load the record template from the server instead of the client-side Lightning Data Service cache. Defaults to `false`.
`callback`	Function	A function invoked after the empty record is created. This function receives no arguments.

getNewRecord doesn’t return a result. It simply prepares an empty record and assigns it to the targetRecord attribute.

Creating a Record

The following example illustrates the essentials of creating a record using Lightning Data Service. This example is intended to be added to an account record Lightning page.

ldsCreate.cmp

1<aura:component implements="flexipage:availableForRecordHome, force:hasRecordId">
2
3    <aura:attribute name="newContact" type="Object"/>
4    <aura:attribute name="simpleNewContact" type="Object"/>
5    <aura:attribute name="newContactError" type="String"/>
6   
7    <aura:handler name="init" value="{!this}" action="{!c.doInit}"/>
8
9    <force:recordData aura:id="contactRecordCreator" 
10                      layoutType="FULL"
11                      targetRecord="{!v.newContact}"
12                      targetFields="{!v.simpleNewContact}"
13                      targetError="{!v.newContactError}" />
14                      
15    <div class="slds-page-header" role="banner">
16        <p class="slds-text-heading--label">Create Contact</p>
17    </div>
18
19    <!-- Display Lightning Data Service errors -->
20    <aura:if isTrue="{!not(empty(v.newContactError))}">
21        <div class="recordError">
22            <ui:message title="Error" severity="error" closable="true">
23                {!v.newContactError}
24            </ui:message>
25        </div>
26    </aura:if>
27
28    <!-- Display the new contact form -->
29    <div class="slds-form--stacked">
30        <lightning:input aura:id="contactField" name="firstName" label="First Name"
31                         value="{!v.simpleNewContact.FirstName}" required="true"/>
32      
33        <lightning:input aura:id="contactField" name="lastname" label="Last Name"
34                      value="{!v.simpleNewContact.LastName}" required="true"/>
35                
36        <lightning:input aura:id="contactField" name="title" label="Title"
37                      value="{!v.simpleNewContact.Title}" />
38                      
39        <lightning:button label="Save contact" onclick="{!c.handleSaveContact}"
40                   variant="brand" class="slds-m-top--medium"/>
41   </div>
42
43</aura:component>

This component doesn’t set the recordId attribute of force:recordData. This tells Lightning Data Service to expect a new record. Here, that’s created in the component’s init handler.

ldsCreateController.js

1({
2    doInit: function(component, event, helper) {
3        // Prepare a new record from template
4        component.find("contactRecordCreator").getNewRecord(
5            "Contact", // sObject type (entityApiName)
6            null,      // recordTypeId
7            false,     // skip cache?
8            $A.getCallback(function() {
9                var rec = component.get("v.newContact");
10                var error = component.get("v.newContactError");
11                if(error || (rec === null)) {
12                    console.log("Error initializing record template: " + error);
13                    return;
14                }
15                console.log("Record template initialized: " + rec.sobjectType);
16            })
17        );
18    },
19
20    handleSaveContact: function(component, event, helper) {
21        if(helper.validateContactForm(component)) {
22            component.set("v.simpleNewContact.AccountId", component.get("v.recordId"));
23            component.find("contactRecordCreator").saveRecord(function(saveResult) {
24                if (saveResult.state === "SUCCESS" || saveResult.state === "DRAFT") {
25                    // record is saved successfully
26                    var resultsToast = $A.get("e.force:showToast");
27                    resultsToast.setParams({
28                        "title": "Saved",
29                        "message": "The record was saved."
30                    });
31                    resultsToast.fire();
32
33                } else if (saveResult.state === "INCOMPLETE") {
34                    // handle the incomplete state
35                    console.log("User is offline, device doesn't support drafts.");
36                } else if (saveResult.state === "ERROR") {
37                    // handle the error state
38                    console.log('Problem saving contact, error: ' + JSON.stringify(saveResult.error));
39                } else {
40                    console.log('Unknown problem, state: ' + saveResult.state + ', error: ' + JSON.stringify(saveResult.error));
41                }
42            });
43        }
44    }
45})

The doInit init handler calls getNewRecord() on the force:recordData component, passing in a simple callback handler. This call creates a new, empty contact record, which is used by the contact form in the component’s markup.

The callback passed to getNewRecord() must be wrapped in $A.getCallback() to ensure correct access context when the callback is invoked. If the callback is passed in without being wrapped in $A.getCallback(), any attempt to access private attributes of your component results in access check failures.

Even if you’re not accessing private attributes, it’s a best practice to always wrap the callback function for getNewRecord() in $A.getCallback(). Never mix (contexts), never worry.

Note

The handleSaveContact handler is called when the Save Contact button is clicked. It’s a straightforward application of saving the contact, as described in Saving a Record, and then updating the user interface.

The helper function, validateContactForm, isn’t shown. It simply validates the form values. For an example of this validation, see Lightning Data Service Example.

Note

Lightning Components Developer Guide

Creating a Record

Create an Empty Record from a Record Template

Creating a Record

See Also: