Calling a Server-Side Action
A client-side controller is a JavaScript object in object-literal notation containing a map of name-value pairs.
Let’s say that you want to trigger a server-call from a component. The following component contains a button that’s wired to a client-side controller echo action. SimpleServerSideController contains a method that returns a string passed in from the client-side controller.
<aura:component controller="SimpleServerSideController">
<aura:attribute name="firstName" type="String" default="world"/>
<lightning:button label="Call server" onclick="{!c.echo}"/>
</aura:component>
This client-side controller includes an echo action that executes a serverEcho method on a server-side controller.
({
"echo" : function(cmp) {
// create a one-time use instance of the serverEcho action
// in the server-side controller
var action = cmp.get("c.serverEcho");
action.setParams({ firstName : cmp.get("v.firstName") });
// Create a callback that is executed after
// the server-side action returns
action.setCallback(this, function(response) {
var state = response.getState();
if (state === "SUCCESS") {
// Alert the user with the value returned
// from the server
alert("From server: " + response.getReturnValue());
// You would typically fire a event here to trigger
// client-side notification that the server-side
// action is complete
}
else if (state === "INCOMPLETE") {
// do something
}
else if (state === "ERROR") {
var errors = response.getError();
if (errors) {
if (errors[0] && errors[0].message) {
console.log("Error message: " +
errors[0].message);
}
} else {
console.log("Unknown error");
}
}
});
// optionally set storable, abortable, background flag here
// A client-side action could cause multiple events,
// which could trigger other events and
// other server-side action calls.
// $A.enqueueAction adds the server-side action to the queue.
$A.enqueueAction(action);
}
})
In the client-side controller, we use the value provider of c to invoke a server-side controller action. We also use the c syntax in markup to invoke a client-side controller action.
The cmp.get("c.serverEcho") call indicates that we’re calling the serverEcho method in the server-side controller. The method name in the server-side controller must match everything after the c. in the client-side call. In this case, that’s serverEcho.
The implementation of the serverEcho Apex method is shown in Apex Server-Side Controller Overview.
Use action.setParams() to set data to be passed to the server-side controller. The following call sets the value of the firstName argument on the server-side controller’s serverEcho method based on the firstName attribute value.
action.setParams({ firstName : cmp.get("v.firstName") });
action.setCallback() sets a callback action that is invoked after the server-side action returns.
action.setCallback(this, function(response) { ... });
The server-side action results are available in the response variable, which is the argument of the callback.
response.getState() gets the state of the action returned from the server.
response.getReturnValue() gets the value returned from the server. In this example, the callback function alerts the user with the value returned from the server.
$A.enqueueAction(action) adds the server-side controller action to the queue of actions to be executed. All actions that are enqueued will run at the end of the event loop. Rather than sending a separate request for each individual action, the framework processes the event chain and batches the actions in the queue into one request. The actions are asynchronous and have callbacks.
Client Payload Data Limit
Use action.setParams() to set data for an action to be passed to a server-side controller.
The framework batches the actions in the queue into one server request. The request payload includes all of the actions and their data serialized into JSON. The request payload limit is 4 MB.