Calling a Server-Side Action

A client-side controller is a JavaScript object in object-literal notation containing name-value pairs. Each name corresponds to a client-side action. Its value is the function code associated with the action.

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.

1<aura:component controller="SimpleServerSideController">
2    <aura:attribute name="firstName" type="String" default="world"/>
3    <ui:button label="Call server" press="{!c.echo}"/>
4</aura:component>

This client-side controller includes an echo action that executes a serverEcho method on a server-side controller.

1({
2    "echo" : function(cmp) {
3        // create a one-time use instance of the serverEcho action
4        // in the server-side controller
5        var action = cmp.get("c.serverEcho");
6        action.setParams({ firstName : cmp.get("v.firstName") });
7
8        // Create a callback that is executed after 
9        // the server-side action returns
10        action.setCallback(this, function(response) {
11            var state = response.getState();
12            // This callback doesn’t reference cmp. If it did,
13            // you should run an isValid() check
14            //if (cmp.isValid() && state === "SUCCESS") {
15            if (state === "SUCCESS") {
16                // Alert the user with the value returned 
17                // from the server
18                alert("From server: " + response.getReturnValue());
19
20                // You would typically fire a event here to trigger 
21                // client-side notification that the server-side 
22                // action is complete
23            }
24            //else if (cmp.isValid() && state === "INCOMPLETE") {
25            else if (state === "INCOMPLETE") {
26                // do something
27            }
28            //else if (cmp.isValid() && state === "ERROR") {
29            else if (state === "ERROR") {
30                var errors = response.getError();
31                if (errors) {
32                    if (errors[0] && errors[0].message) {
33                        console.log("Error message: " + 
34                                 errors[0].message);
35                    }
36                } else {
37                    console.log("Unknown error");
38                }
39            }
40        });
41
42        // optionally set storable, abortable, background flag here
43
44        // A client-side action could cause multiple events, 
45        // which could trigger other events and 
46        // other server-side action calls.
47        // $A.enqueueAction adds the server-side action to the queue.
48        $A.enqueueAction(action);
49    }
50})

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.

Use action.setParams() to set arguments 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.

1action.setParams({ firstName : cmp.get("v.firstName") });

action.setCallback() sets a callback action that is invoked after the server-side action returns.

1action.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.