Guest post: Peter Knolle is a Solutions Architect at Trifecta Technologies, Force.com MVP, and Salesforce Developer Group Organizer. He holds six Salesforce certifications, blogs regularly at peterknolle.com, and is active on Twitter @PeterKnolle.
The Lightning Component framework is powered by Apex on the server-side and by JavaScript on the client-side. The framework provides a rich JavaScript API to enable working with different features easier. This post details some of the objects and functions in the API that are more likely to be used in most components, along with some examples and useful information about each.
Before you can use the API you have to know what is available. The Lightning Components Developer’s Guide is a quite extensive and well organized guide that contains a lot of useful information. However, if you need to know more, you can access the JavaScript API documentation in the auradocs reference app which is available in your org at http://<yourInstance>.lightning.force.com/auradocs/reference.app or you can get to it from http://<yourInstance>.salesforce.com/auradocs.
The framework provides three parameters to component controller functions: component, event, and helper. For example, a controller function to handle a form submission could be the following.
handleFormSubmit : function(component, event, helper) { // handle it... }
It’s worth making it clear what is happening and how powerful it is. All that you have to do is define your controller function to accept the three parameters and you don’t have to worry about where they come from at all. You don’t have to configure anything else or program something to find the objects you need. The parameters are simply available to you to use in your controller function. The framework takes care of populating them with the correct values.
The helper is a place where you can define code to be shared within your component or sub components. In general, if you have any non-trivial logic you should move it to a helper and let the controller call the helper to execute it. For example, you might have some code that calls a server-side controller action to get a list of Opportunity records based on an event parameter. Instead of coding all of server communication directly in the controller, code it in the helper and leave the controller as very simple.
handleOpportunityStageChange : function(component, event, helper) { helper.loadOpportunities(component, event.getParam("stageName")); }
Now, if you have code elsewhere in your component that needs to load opportunities you can easily reuse it. For example, you might have code that loads based on an attribute value.
handleFormSubmit : function(component, event, helper) { // do some stuff... helper.loadOpportunities(component, component.get("v.stageName")); // do some other stuff... }
A Lightning Component is represented as a component object in the API. The methods on the component that you’ll use most often are as follows.
var myNum = cmp.get("v.myNum"); cmp.set("v.myNum", 256); var action = cmp.get("c.saveContact");
<input type="color" aura:id="colorPicker" class="cp"/> <ui:button label"submit" aura:id="submitButton" press="{!c.submit}"/> var picker = cmp.find("colorPicker"); var btn = cmp.find("submitButton");
var evt = cmp.getEvent("searchComplete");
A Lightning Event is represented as an Event object in the API. Just like the component, the event is provided by the framework to controller functions as a parameter. The methods on the event that you’ll find yourself using are as follows:
var recordId = event.getParam("recordId");
event.setParams({ stageName: "Closed/Won", amount: 10000 });
In addition to being able to call the methods individually, method chaining is supported for most objects in the API. For example, the following will get the event, set the parameters, and fire it.
cmp.getEvent("doSearch").setParams({ stageName: "Closed/Won", amount: 10000 }).fire();
The Action object isn’t a controller parameter, but is one that you will use when communicating with server-side controllers.
var contacts = action.getReturnValue();
if (action.getState() === "SUCCESS") { // success } else if (action.getState() === "ERROR") { // error }
if (action.getState() === "ERROR") { var errs = action.getErrors(); if (errs) { $A.log("Errors from action", errs); } }
action.setParameters({ stageName: "Closed/Won", type: "Existing Business" });
action.setCallback(this, function(a) { // handle it. };
In addition to the component and event objects, the API has some useful utility functions. Most can be accessed through the Aura object, which can be referred to as $A for convenience.
$A.enqueueAction(action);
$A.log("errors", a.getError());
var evt = $A.getEvt("c:searchCompleteEvent");
var attVal = cmp.get("v.myNum"); if ($A.util.isUndefinedOrNull(attVal)) { // do something... }
For more information on the JavasScript API in the Lightning Component Framework, refer to the Lightning Component Developer’s Guide. For a quick overview and introduction to Lightning Components, visit the Lightning Components page on Salesforce Developers. If you’re ready to learn hands-on while earning badges to demonstrate your skills, start the Lightning Components module in Trailhead.