Handling Events with Client-Side Controllers

Creating a Client-Side Controller

A client-side controller is part of the component bundle. It is auto-wired via the naming convention, <componentName>Controller.js.

To create a client-side controller using the Developer Console, click CONTROLLER in the sidebar of the component.

Calling Client-Side Controller Actions

Let's start by looking at events on different implementations of an HTML tag. The following example component creates three different buttons, of which only the last two work properly. Clicking on these buttons updates the text component attribute with the specified values. target.get("v.label") refers to the label attribute value on the button.

Component source

1swfobject.registerObject("clippy.codeblock-0", "9");<aura:component>
2    <aura:attribute name="text" type="String" default="Just a string.  Waiting for change."/>
3    <input type="button" value="Flawed HTML Button" onclick="alert('this will not work')"/>
4    <br/>
5    <input type="button" value="Hybrid HTML Button" onclick="{!c.handleClick}"/>
6    <br/>
7    <ui:button label="Framework Button" press="{!c.handleClick}"/>
8    <br/>
9    {!v.text}
10</aura:component>
11

Client-side controller source

1swfobject.registerObject("clippy.codeblock-1", "9");{
2    handleClick : function(component, event) {
3        var attributeValue = component.get("v.text");
4        aura.log("current text: " + attributeValue);
5
6        var target;
7        if (event.getSource) {
8            // handling a framework component event
9            target = event.getSource(); // this is a Component object
10            component.set("v.text", target.get("v.label"));
11        } else {
12            // handling a native browser event
13            target = event.target.value; // this is a DOM element
14            component.set("v.text", event.target.value);
15        }
16    }
17}
18

Any browser DOM element event starting with on, such as onclick or onkeypress, can be wired to a controller action. You can only wire browser events to controller actions. Arbitrary JavaScript in the component is ignored.

If you know some JavaScript, you might be tempted to write something like the first "Flawed" button because you know that HTML tags are first-class citizens in the framework. However, the "Flawed" button won't work as the framework has its own event system. DOM events are mapped to Lightning events, since HTML tags are mapped to Lightning components.

Handling Framework Events

Handle framework events using actions in client-side component controllers. Framework events for common mouse and keyboard interactions are available with out-of-the-box components.

Let's look at the onclick attribute in the "Hybrid" button, which invokes the handleClick action in the controller. The "Framework" button uses the same syntax with the press attribute in the <ui:button> component.

In this simple scenario, there is little functional difference between working with the "Framework" button or the "Hybrid" HTML button. However, components are designed with accessibility in mind so users with disabilities or those who use assistive technologies can also use your app. When you start building more complex components, the reusable out-of-the-box components can simplify your job by handling some of the plumbing that you would otherwise have to create yourself. Also, these components are secure and optimized for performance.

Accessing Component Attributes

In the handleClick function, notice that the first argument to every action is the component to which the controller belongs. One of the most common things you'll want to do with this component is look at and change its attribute values.

component.get("v.<attributeName>") returns the value of the <attributeName> attribute. The aura.log() utility function attempts to find a browser console and logs the attribute value to it.

Invoking Another Action in the Controller

To call an action method from another method, use a helper function and invoke it using helper.someFunction(component). A helper resource contains functions that can be reused by your JavaScript code in the component bundle.