grivero / lightning-apex-proxy

An Apex Proxy component for the Salesforce Lightning framework.

Lightning Apex Proxy

The Lightning Apex Proxy component makes calls to @AuraEnabled Apex methods easier by encapsulating the $A.enqueueAction cycle. It allows you to pass success and error callbacks as anonymous function and fire component-level and application-level events.

This repo is a Salesforce DX project. To get started, you'll need to spin up a scratch org, pull this repo and push the components into your scratch org.

Deploy to SFDX Scratch Org:

Deploy to Salesforce Org:

Usage

1. Make a Lightning Component that needs to call an Apex method.

2. Add Apex Proxy to the component. Remember to include the "aura:id" attribute.

   <c:ApexProxy aura:id="apexProxy" />
   

3. In your component's controller (or helper), find the Apex Proxy component by name and call it's "call" aura method.

   // locate the apex proxy component within this component
   var apexProxy = component.find('apexProxy');
   
   // the "action" is the apex @auraenabled method on this component's controller
   // in this case "ExampleApex.method1"
   var action = component.get('c.method1');
   
   // params to the method are pass as an object with property names matching
   var params = {
   	param1 : 'PARAM1'
   };
   
   // call the aura:method exposed on the ApexProxy component
   apexProxy.call(
   	action,
   	params,
       function(payload) {
   		// onSuccess function
   		// anonymous function retains references to component, event and helper
   		// ApexProxy component passes "payload", which is whatever the Apex method returns
   		// from here, you could make further calls to helper.whateverMethodToDoStuff();
   		component.set('v.method1Value', payload);
       },
   	function(payload) {
   		// onError function
   		// anonymous function retains references to component, event and helper
   		// ApexProxy component passes "payload", which is whatever the Apex method returns
   		// from here, you could make further calls to helper.whateverMethodToDoStuff();
   		console.log(payload)
       }
   );

   A consolidated example, passing callbacks (but no events):

   var apexProxy = component.find('apexProxy');
   var action = component.get('c.method1');
   var params = { param1 : 'PARAM1' };
   apexProxy.call(action, params,
   	function(payload) {
   		// success callback...
   	},
   	function(payload) {
   		// error callback...
   	}
   );

4. Rejoice in knowing you never have to write $A.enqueueAction code again.

Apex Proxy Events

Apex Proxy comes pre-packaged with a generic Application event (ApexProxyApplicationEvent) and Component event (ApexProxyComponentEvent). Each event has three attributes:

• title (String) - if the 'onSuccess' or 'onError' value provided is a string, the "title" attribute will be set with that value.
• data (Object) - the data returned from the Apex method.
• error (Object) - if the Apex method returns as an error, the getError() data will be populated here.

The last parameter of Apex Proxy's "call" method is "eventLevel". You can test it to:

• NONE (default) - no events are fired
• APPLICATION - the application-level event is fired
• COMPONENT - the component-level event is fired
• ALL - both the application and component-level events are fired

Application-Level Event Example

var apexProxy = component.find('apexProxy');
var action = component.get('c.method1');
var params = { param1 : 'PARAM1' };
apexProxy.call(action, params, 'doSuccessStuff', 'doErrorStuff', 'APPLICATION');

Any component handling ApexProxyApplicationEvent will receive the event with:

• title = 'doSuccessStuff' (or 'doErrorStuff')
• data = the response of the method
• error = getError() (if there is an error)

Component-Level Event Example

NOTE: you must update your reference to the Apex Proxy component to include an 'onComplete' attribute so the parent component can handle the event properly.

<c:ApexProxy aura:id="apexProxy" onComplete="{!c.doCompleteStuff}" />

Then, you can request the component-level event.

var apexProxy = component.find('apexProxy');
var action = component.get('c.method1');
var params = { param1 : 'PARAM1' };
apexProxy.call(action, params, 'doSuccessStuff', 'doErrorStuff', 'COMPONENT');

Any component handling ApexProxyComponentEvent will receive the event with:

• title = 'doSuccessStuff' (or 'doErrorStuff')
• data = the response of the method
• error = getError() (if there is an error)