Lightning Components Developer Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 506

DownloadLightning Components Developer Guide
Open PDF In BrowserView PDF
Lightning Components
Developer Guide
Version 39.0, Spring ’17

@salesforcedocs
Last updated: April 15, 2017

© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,

as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS
Chapter 1: What is the Lightning Component Framework? . . . . . . . . . . . . . . . . . . . . . . 1
What is Salesforce Lightning? . . . . . . . . . . . . .
Why Use the Lightning Component Framework?
Open Source Aura Framework . . . . . . . . . . . .
Components . . . . . . . . . . . . . . . . . . . . . . . .
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Developer Console . . . . . . . . . . . . .
Online Content . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

2
2
3
3
3
4
5

Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Create a Standalone Lightning App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Optional: Install the Expense Tracker App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Create an Expense Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Step 1: Create A Static Mockup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Step 2: Create A Component for User Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Step 3: Load the Expense Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Step 4: Create a Nested Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Step 5: Enable Input for New Expenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Step 6: Make the App Interactive With Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Create a Component for Salesforce1 and Lightning Experience . . . . . . . . . . . . . . . . . . . . . . 30
Load the Contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Fire the Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 3: Creating Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Create Lightning Components in the Developer Console . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Lightning Bundle Configurations Available in the Developer Console . . . . . . . . . . . . . . . 39
Component Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Component Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Using the Default Namespace in Organizations with No Namespace Set . . . . . . . . . . . . 42
Using Your Organization’s Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Using a Namespace in or from a Managed Package . . . . . . . . . . . . . . . . . . . . . . . . . 42
Creating a Namespace in Your Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Namespace Usage Examples and Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Component Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Component IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
HTML in Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
CSS in Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Contents

Component Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Component Composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Component Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Component Facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Best Practices for Conditional Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Component Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Using Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Dynamic Output in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Data Binding Between Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Value Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Expression Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Expression Operators Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Expression Functions Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Using Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Using Custom Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Input Component Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Dynamically Populating Label Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Getting Labels in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Setting Label Values via a Parent Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Providing Component Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Working with Base Lightning Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Base Lightning Components Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Event Handling in Base Lightning Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Working with UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Event Handling in UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Using the UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Supporting Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Button Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Audio Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Forms, Fields, and Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 4: Using Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Use Lightning Components in Lightning Experience and Salesforce1 . . . . . . . . . . . . . . . . . . . 98
Configure Components for Custom Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Add Lightning Components as Custom Tabs in Lightning Experience . . . . . . . . . . . . . . . 99
Add Lightning Components as Custom Tabs in Salesforce1 . . . . . . . . . . . . . . . . . . . . 100
Configure Components for Custom Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Configure Components for Record-Specific Actions . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Lightning Component Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Get Your Lightning Components Ready to Use on Lightning Pages . . . . . . . . . . . . . . . . . . . 108

Contents

Configure Components for Lightning Pages and the Lightning App Builder . . . . . . . . . . 109
Lightning Component Bundle Design Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Configure Components for Lightning Experience Record Pages . . . . . . . . . . . . . . . . . . 111
Create Components for Lightning for Outlook and Lightning for Gmail (Beta) . . . . . . . . . 113
Create Dynamic Picklists for Your Custom Components . . . . . . . . . . . . . . . . . . . . . . . 117
Tips and Considerations for Configuring Components for Lightning Pages and the Lightning
App Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Use Lightning Components in Community Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Configure Components for Communities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Create Custom Theme Layout Components for Communities . . . . . . . . . . . . . . . . . . . . 121
Create Custom Search and Profile Menu Components for Communities . . . . . . . . . . . . 123
Create Custom Content Layout Components for Communities . . . . . . . . . . . . . . . . . . . 124
Add Components to Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Use Lightning Components in Visualforce Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Add Lightning Components to Any App with Lightning Out (Beta) . . . . . . . . . . . . . . . . . . . . 128
Lightning Out Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Lightning Out Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Lightning Out Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Authentication from Lightning Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Share Lightning Out Apps with Non-Authenticated Users . . . . . . . . . . . . . . . . . . . . . . 133
Lightning Out Considerations and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Chapter 5: Communicating with Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Actions and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Handling Events with Client-Side Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Component Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Component Event Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Create Custom Component Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Fire Component Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Handling Component Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Component Event Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Application Event Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Create Custom Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Fire Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Handling Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Application Event Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Event Handling Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Advanced Events Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Firing Lightning Events from Non-Lightning Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Events Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Events Anti-Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Events Fired During the Rendering Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Events Handled In Salesforce1 and Lightning Experience . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Contents

System Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Chapter 6: Creating Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
App Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Designing App UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Creating App Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Developing Secure Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Content Security Policy Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
What is LockerService? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Writing Secure Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Salesforce Lightning CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Styling Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Using the Salesforce Lightning Design System in Apps . . . . . . . . . . . . . . . . . . . . . . . . 191
Using External CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
More Readable Styling Markup with the join Expression . . . . . . . . . . . . . . . . . . . . . . . 193
Tips for CSS in Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Vendor Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Styling with Design Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Using External JavaScript Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Working with Attribute Values in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Working with a Component Body in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Working with Events in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Sharing JavaScript Code in a Component Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Modifying the DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Client-Side Rendering to the DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Invoking Actions on Component Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Modifying Components Outside the Framework Lifecycle . . . . . . . . . . . . . . . . . . . . . . 230
Validating Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Throwing and Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Calling Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Using JavaScript Promises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Making API Calls from Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Create CSP Trusted Sites to Access Third-Party APIs . . . . . . . . . . . . . . . . . . . . . . . . . 238
JavaScript Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Dynamically Creating Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Detecting Data Changes with Change Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Finding Components by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Dynamically Adding Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Dynamically Showing or Hiding Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Adding and Removing Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Which Button Was Pressed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Using Apex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Creating Server-Side Logic with Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Contents

Creating Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Working with Salesforce Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Testing Your Apex Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Making API Calls from Apex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Lightning Data Service (Developer Preview) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Loading a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Saving a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Creating a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Deleting a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Record Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Considerations and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Lightning Data Service Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
SaveRecordResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Lightning Container (Developer Preview) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Using a Third-Party Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Sending Messages to and from the App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Handling Errors in Your Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Lightning Container Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Implement an Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Controlling Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Application Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Interface Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Component Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Attribute Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Event Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Using Object-Oriented Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
What is Inherited? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Inherited Component Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Abstract Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Inheritance Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Using the AppCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Distributing Applications and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Chapter 7: Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Enable Debug Mode for Lightning Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Salesforce Lightning Inspector Chrome Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Install Salesforce Lightning Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Salesforce Lightning Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Log Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Chapter 8: Fixing Performance Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
—Clean Unrendered Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Contents

—Multiple Items Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Chapter 9: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Reference Doc App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Supported aura:attribute Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Basic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Standard and Custom Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Collection Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Custom Apex Class Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Framework-Specific Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
aura:application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
aura:component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
aura:dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
aura:event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
aura:interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
aura:method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
aura:set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Setting Attributes Inherited from a Super Component . . . . . . . . . . . . . . . . . . . . . . . . 337
Setting Attributes on a Component Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Setting Attributes Inherited from an Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Component Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
aura:expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
aura:html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
aura:if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
aura:iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
aura:renderIf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
aura:template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
aura:text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
aura:unescapedHtml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
auraStorage:init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
force:canvasApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
force:inputField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
force:outputField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
force:recordEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
force:recordPreview (Developer Preview) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
force:recordView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
forceChatter:feed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
forceChatter:fullFeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
forceChatter:publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
forceCommunity:navigationMenuBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
forceCommunity:routeLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
lightning:avatar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
lightning:badge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Contents

lightning:button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
lightning:buttonGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
lightning:buttonIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
lightning:buttonMenu (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
lightning:card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
lightning:container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
lightning:formattedDateTime (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
lightning:formattedNumber (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
lightning:icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
lightning:input (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
lightning:inputRichText (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
lightning:layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
lightning:layoutItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
lightning:menuItem (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
lightning:select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
lightning:spinner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
lightning:tab (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
lightning:tabset (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
lightning:textarea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
ltng:require . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
ui:actionMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
ui:button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
ui:checkboxMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
ui:inputCheckbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
ui:inputCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
ui:inputDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
ui:inputDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
ui:inputDefaultError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
ui:inputEmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
ui:inputNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
ui:inputPhone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
ui:inputRadio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
ui:inputRichText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
ui:inputSecret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
ui:inputSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
ui:inputSelectOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
ui:inputText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
ui:inputTextArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
ui:inputURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
ui:menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
ui:menuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
ui:menuItemSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
ui:menuList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
ui:menuTrigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

Contents

ui:menuTriggerLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
ui:message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
ui:outputCheckbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
ui:outputCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
ui:outputDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
ui:outputDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
ui:outputEmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
ui:outputNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
ui:outputPhone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
ui:outputRichText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
ui:outputText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
ui:outputTextArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
ui:outputURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
ui:radioMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
ui:scrollerWrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
ui:spinner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Interface Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Event Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
force:closeQuickAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
force:createRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
force:editRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
force:navigateToComponent (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
force:navigateToList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
force:navigateToObjectHome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
force:navigateToRelatedList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
force:navigateToSObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
force:navigateToURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
force:recordSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
force:recordSaveSuccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
force:refreshView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
force:showToast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
forceCommunity:analyticsInteraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
forceCommunity:routeChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
lightning:openFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
ltng:selectSObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
ltng:sendMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
ui:clearErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
ui:collapse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
ui:expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
ui:menuFocusChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
ui:menuSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
ui:menuTriggerPress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
ui:validationError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
System Event Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

Contents

aura:doneRendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
aura:doneWaiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
aura:locationChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
aura:systemError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
aura:valueChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
aura:valueDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
aura:valueInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
aura:waiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Supported HTML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

INDEX

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

CHAPTER 1
In this chapter ...
•

What is Salesforce
Lightning?

•

Why Use the
Lightning Component
Framework?

•

Open Source Aura
Framework

•

Components

•

Events

•

Using the Developer
Console

•

Online Content

What is the Lightning Component Framework?
The Lightning Component framework is a UI framework for developing dynamic web apps for mobile
and desktop devices. It’s a modern framework for building single-page applications engineered for
growth.
The framework supports partitioned multi-tier component development that bridges the client and
server. It uses JavaScript on the client side and Apex on the server side.

1

What is the Lightning Component Framework?

What is Salesforce Lightning?

What is Salesforce Lightning?
Lightning includes the Lightning Component Framework and some exciting tools for developers. Lightning makes it easier to build
responsive applications for any device.
Lightning includes these technologies:
• Lightning components give you a client-server framework that accelerates development, as well as app performance, and is ideal
for use with the Salesforce1 mobile app and Salesforce Lightning Experience.
• The Lightning App Builder empowers you to build apps visually, without code, quicker than ever before using off-the-shelf and
custom-built Lightning components. You can make your Lightning components available in the Lightning App Builder so administrators
can build custom user interfaces without code.
Using these technologies, you can seamlessly customize and easily deploy new apps to mobile devices running Salesforce1. In fact, the
Salesforce1 mobile app and Salesforce Lightning Experience are built with Lightning components.
This guide provides you with an in-depth resource to help you create your own standalone Lightning apps, as well as custom Lightning
components that can be used in the Salesforce1 mobile app. You will also learn how to package applications and components and
distribute them in the AppExchange.

Why Use the Lightning Component Framework?
The benefits include an out-of-the-box set of components, event-driven architecture, and a framework optimized for performance.
Out-of-the-Box Component Set
Comes with an out-of-the-box set of components to kick start building apps. You don't have to spend your time optimizing your
apps for different devices as the components take care of that for you.
Rich component ecosystem
Create business-ready components and make them available in Salesforce1, Lightning Experience, and Communities. Salesforce1
users access your components via the navigation menu. Customize Lightning Experience or Communities using drag-and-drop
components on a Lightning Page in the Lightning App Builder or using Community Builder. Additional components are available
for your org in the AppExchange. Similarly, you can publish your components and share them with other users.
Performance
Uses a stateful client and stateless server architecture that relies on JavaScript on the client side to manage UI component metadata
and application data. The client calls the server only when absolutely necessary; for example to get more metadata or data. The
server only sends data that is needed by the user to maximize efficiency. The framework uses JSON to exchange data between the
server and the client. It intelligently utilizes your server, browser, devices, and network so you can focus on the logic and interactions
of your apps.
Event-driven architecture
Uses an event-driven architecture for better decoupling between components. Any component can subscribe to an application
event, or to a component event they can see.
Faster development
Empowers teams to work faster with out-of-the-box components that function seamlessly with desktop and mobile devices. Building
an app with components facilitates parallel design, improving overall development efficiency.
Components are encapsulated and their internals stay private, while their public shape is visible to consumers of the component.
This strong separation gives component authors freedom to change the internal implementation details and insulates component
consumers from those changes.

2

What is the Lightning Component Framework?

Open Source Aura Framework

Device-aware and cross browser compatibility
Apps use responsive design and provide an enjoyable user experience. The Lightning Component framework supports the latest in
browser technology such as HTML5, CSS3, and touch events.

Open Source Aura Framework
The Lightning Component framework is built on the open source Aura framework. The Aura framework enables you to build apps
completely independent of your data in Salesforce.
The Aura framework is available at https://github.com/forcedotcom/aura. Note that the open source Aura framework
has features and components that are not currently available in the Lightning Component framework. We are working to surface more
of these features and components for Salesforce developers.
The sample code in this guide uses out-of-the-box components from the Aura framework, such as aura:iteration and
ui:button. The aura namespace contains components to simplify your app logic, and the ui namespace contains components
for user interface elements like buttons and input fields. The force namespace contains components specific to Salesforce.

Components
Components are the self-contained and reusable units of an app. They represent a reusable section of the UI, and can range in granularity
from a single line of text to an entire app.
The framework includes a set of prebuilt components. You can assemble and configure components to form new components in an
app. Components are rendered to produce HTML DOM elements within the browser.
A component can contain other components, as well as HTML, CSS, JavaScript, or any other Web-enabled code. This enables you to
build apps with sophisticated UIs.
The details of a component's implementation are encapsulated. This allows the consumer of a component to focus on building their
app, while the component author can innovate and make changes without breaking consumers. You configure components by setting
the named attributes that they expose in their definition. Components interact with their environment by listening to or publishing
events.
SEE ALSO:
Creating Components

Events
Event-driven programming is used in many languages and frameworks, such as JavaScript and Java Swing. The idea is that you write
handlers that respond to interface events as they occur.
A component registers that it may fire an event in its markup. Events are fired from JavaScript controller actions that are typically triggered
by a user interacting with the user interface.
There are two types of events in the framework:
• Component events are handled by the component itself or a component that instantiates or contains the component.
• Application events are handled by all components that are listening to the event. These events are essentially a traditional
publish-subscribe model.

3

What is the Lightning Component Framework?

Using the Developer Console

You write the handlers in JavaScript controller actions.
SEE ALSO:
Communicating with Events
Handling Events with Client-Side Controllers

Using the Developer Console
The Developer Console provides tools for developing your components and applications.

The Developer Console enables you to perform these functions.
• Use the menu bar (1) to create or open these Lightning resources.
– Application
– Component
– Interface
– Event
– Tokens
• Use the workspace (2) to work on your Lightning resources.
• Use the sidebar (3) to create or open client-side resources that are part of a specific component bundle.
– Controller
– Helper
– Style
– Documentation
– Renderer
– Design
– SVG

4

What is the Lightning Component Framework?

Online Content

For more information on the Developer Console, see The Developer Console User Interface.
SEE ALSO:
Salesforce Help: Open the Developer Console
Create Lightning Components in the Developer Console
Component Bundles

Online Content
This guide is available online. To view the latest version, go to:
https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/

Go beyond this guide with exciting Trailhead content. To explore more of what you can do with Lightning Components, go to:
Trailhead Module: Lightning Components Basics
Link: https://trailhead.salesforce.com/module/lex_dev_lc_basics
Learn with a series of hands-on challenges on how to use Lightning Components to build modern web apps.
Quick Start: Lightning Components
Link: https://trailhead.salesforce.com/project/quickstart-lightning-components
Create your first component that renders a list of Contacts from your org.
Project: Build an Account Geolocation App
Link: https://trailhead.salesforce.com/project/account-geolocation-app
Build an app that maps your Accounts using Lightning Components.
Project: Build a Restaurant-Locator Lightning Component
Link: https://trailhead.salesforce.com/project/workshop-lightning-restaurant-locator
Build a Lightning component with Yelp’s Search API that displays a list of businesses near a certain location.
Project: Build a Lightning App with the Lightning Design System
Link: https://trailhead.salesforce.com/project/slds-lightning-components-workshop
Design a Lightning component that displays an Account list.

5

CHAPTER 2
In this chapter ...
•

Before You Begin

•

Create a Standalone
Lightning App

•

Create a Component
for Salesforce1 and
Lightning Experience

Quick Start
The quick start steps you through building and running two simple apps: a standalone Lightning app
for tracking expenses and a Lightning component to manage selected contacts in Salesforce1. You’ll
create all components from the Developer Console. A standalone app is directly accessible by going to
the URL:
https://.lightning.force.com//.app,
where  is the name of your custom Salesforce domain

The standalone app you’re creating accesses a custom object and displays its records. It enables you to
edit a field on the records, capturing changes in a client-side controller and passing that information
using a component event to an Apex controller, which then persists the data.
The Lightning component you’re creating accesses the contact object and displays its records in
Salesforce1. You’ll use built-in Salesforce1 events to create or edit contact records, and view related
cases.

6

Quick Start

Before You Begin

Before You Begin
To work with Lightning apps and components , follow these prerequisites.
1. Create a Developer Edition organization
2. Define a Custom Salesforce Domain Name
Note: For this quick start tutorial, you don’t need to create a Developer Edition organization or register a namespace prefix. But
you want to do so if you’re planning to offer managed packages. You can create Lightning components using the UI in Enterprise,
Performance, Unlimited, Developer Editions or a sandbox. If you don’t plan to use a Developer Edition organization, you can
go directly to Define a Custom Salesforce Domain Name.

Create a Developer Edition Organization
You need an org to do this quick start tutorial, and we recommend you don’t use your production org. You only need to create a Developer
Edition org if you don’t already have one.
1. In your browser, go to https://developer.salesforce.com/signup?d=70130000000td6N.
2. Fill in the fields about you and your company.
3. In the Email field, make sure to use a public address you can easily check from a Web browser.
4. Type a unique Username. Note that this field is also in the form of an email address, but it does not have to be the same as your
email address, and in fact, it’s usually better if they aren’t the same. Your username is your login and your identity on
developer.salesforce.com, so you’re often better served by choosing a username such as
firstname@lastname.com.
5. Read and then select the checkbox for the Master Subscription Agreement and then click Submit Registration.
6. In a moment you’ll receive an email with a login link. Click the link and change your password.

Define a Custom Salesforce Domain Name
A custom domain name helps you enhance access security and better manage login and authentication for your organization. If your
custom domain is universalcontainers, then your login URL would be
https://universalcontainers.lightning.force.com. For more information, see My Domain in the Salesforce Help.

Create a Standalone Lightning App
This tutorial walks you through creating a simple expense tracker app using the Developer Console.
The goal of the app is to take advantage of many of the out-of-the-box Lightning components, and to demonstrate the client and server
interactions using JavaScript and Apex. As you build the app, you’ll learn how to use expressions to interact with data dynamically and
use events to communicate data between components.
Make sure you’ve created the expense custom object shown in Create an Expense Object on page 10. Using a custom object to store
your expense data, you’ll learn how an app interacts with records, how to handle user interactions using client-side controller actions,
and how to persist data updates using an Apex controller.
After you create a component, you can include it in Salesforce1 by following the steps in Add Lightning Components as Custom Tabs
in Salesforce1 on page 100. For packaging and distributing your components and apps on AppExchange, see Distributing Applications
and Components on page 302.

7

Quick Start

Create a Standalone Lightning App

Note: Lightning components can be added to the Salesforce1 navigation menu, the App Launcher in Lightning Experience, as
well as a standalone app. To create components that utilize Salesforce1-specific components and events that can be used only in
Salesforce1 and Lightning Experience, see Create a Component for Salesforce1 and Lightning Experience on page 30.
The following image shows the expense tracker as a standalone app.

1. The form contains Lightning input components (1) that update the view and expense records when the Submit button is pressed.
2. Counters are initialized (2) with total amount of expenses and number of expenses, and updated on record creation or deletion. The
counter turns red when the sum exceeds $100.
3. Display of expense list (3) uses Lightning output components and are updated as more expenses are added.
4. User interaction on the expense list (4) triggers an update event that saves the record changes.
These are the resources you are creating for the expense tracker app.
Resources

Description

expenseTracker Bundle
expenseTracker.app

The top-level component that contains all other components

Form Bundle
form.cmp

A collection of Lightning input components to collect user input

formController.js

A client-side controller containing actions to handle user interactions on the form

formHelper.js

A client-side helper functions called by the controller actions

form.css

The styles for the form component

8

Quick Start

Optional: Install the Expense Tracker App

Resources

Description

expenseList Bundle
expenseList.cmp

A collection of Lightning output components to display data from expense records

expenseListController.js

A client-side controller containing actions to handle user interactions on the display
of the expense list

Apex Class
ExpenseController.apxc

Apex controller that loads data, inserts, or updates an expense record

Event
updateExpenseItem.evt

The event fired when an expense item is updated from the display of the expense list

Optional: Install the Expense Tracker App
If you want to skip over the quick start tutorial, you can install the Expense Tracker app as an unmanaged package. Make sure that you
have a custom domain enabled in your organization.
A package is a bundle of components that you can install in your org. This packaged app is useful if you want to learn about the Lightning
app without going through the quick start tutorial. If you’re new to Lightning components, we recommend that you go through the
quick start tutorial. This package can be installed in an org without a namespace prefix. If your org has a registered namespace, follow
the inline comments in the code to customize the app with your namespace.
Note: Make sure that you have a custom domain enabled. Install the package in an org that doesn’t have any of the objects with
the same API name as the quick start objects.
To install the Expense Tracker app:
1. Click the installation URL link: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t1a000000EbZp
2. Log in to your organization by entering your username and password.
3. On the Package Installation Details page, click Continue.
4. Click Next, and on the Security Level page click Next.
5. Click Install.
6. Click Deploy Now and then Deploy.
When the installation completes, you can select the Expenses tab on the user interface to add new expense records.

The Expenses menu item on the Salesforce1 navigation menu. If you don’t see the menu item in Salesforce1, you must create a Lightning
Components tab for expenses and include it in the Salesforce1 navigation menu. See Add Lightning Components as Custom Tabs in
Salesforce1 for more information.

9

Quick Start

Create an Expense Object

Note: The Lightning component tab isn’t available if you don’t have a custom domain enabled in your org. Verify that you have
a custom domain and that the Expenses tab is available in the Lightning Components Tabs section of the Tabs page.
Salesforce1 Navigation.

For Lightning Experience, the Expenses tab is available via the App Launcher in the custom app titled “Lightning”.

Next, you can modify the code in the Developer Console or explore the standalone app at
https://.lightning.force.com//expenseTracker.app, where 

is the name of your custom Salesforce domain.
Note: To delete the package, from Setup, enter Installed Package in the Quick Find box, select Installed Package,
and then delete the package.

Create an Expense Object
Create an expense object to store your expense records and data for the app.
You’ll need to create this object if you’re following the tutorial at Create a Standalone Lightning App on page 7.
1. From your management settings for custom objects, if you’re using Salesforce Classic, click New Custom Object, or if you’re using
Lightning Experience, select Create > Custom Object.
2. Define the custom object.
• For the Label, enter Expense.
• For the Plural Label, enter Expenses.

10

Quick Start

Create an Expense Object

3. Click Save to finish creating your new object. The Expense detail page is displayed.
Note: If you’re using a namespace prefix, you might see namespace__Expense__c instead of Expense__c.
4. On the Expense detail page, add the following custom fields.
Field Type

Field Label

Number(16, 2)

Amount

Text (20)

Client

Date/Time

Date

Checkbox

Reimbursed?

When you finish creating the custom object, your Expense definition detail page should look similar to this.

5. Create a custom object tab to display your expense records.
a. From Setup, enter Tabs in the Quick Find box, then select Tabs.

11

Quick Start

Step 1: Create A Static Mockup

b. In the Custom Object Tabs related list, click New to launch the New Custom Tab wizard.
• For the Object, select Expense.
• For the Tab Style, click the lookup icon and select the Credit Card icon.
c. Accept the remaining defaults and click Next.
d. Click Next and Save to finish creating the tab.
In Salesforce Classic, you should now see a tab for your Expenses at the top of the screen. In Lightning Experience, click the App
Launcher icon ( ) and then the Other Items icon. You should see Expenses in the Items list.
6. Create a few expense records.
a. Click the Expenses tab and click New.
b. Enter the values for these fields and repeat for the second record.
Expense Name

Amount

Lunch

21

Dinner

70

Client

ABC Co.

Date

Reimbursed?

4/1/2015 12:00 PM

Unchecked

3/30/2015 7:00 PM

Checked

Step 1: Create A Static Mockup
Create a static mockup in a.app file, which is the entry point for your app. It can contain other components and HTML markup.
The following flowchart summarizes the data flow in the app. The app retrieves data from the records through a combination of client-side
controller and helper functions, and an Apex controller, which you’ll create later in this quick start.

12

Quick Start

Step 1: Create A Static Mockup

This tutorial uses Lightning Design System styling, which provides a look and feel that’s consistent with Lightning Experience.
1. Open the Developer Console.
a. In Salesforce Classic, click Your Name > Developer Console.
b.

In Lightning Experience, click the quick access menu (

), and then Developer Console.

2. Create a new Lightning app. In the Developer Console, click File > New > Lightning Application.
3. Enter expenseTracker for the Name field in the New Lightning Bundle popup window. This creates a new app,
expenseTracker.app.

13

Quick Start

Step 2: Create A Component for User Input

4. In the source code editor, enter this code.










Expenses






My Expenses















An application is a top-level component and the main entry point to your components. It can include components and HTML markup,
such as 
 and 
 tags. Your app automatically gets Lightning Design System styles if it extends force:slds.
5. Save your changes and click Preview in the sidebar to preview your app. Alternatively, navigate to
https://.lightning.force.com//expenseTracker.app, where 

is the name of your custom Salesforce domain. If you’re not using a namespace, your app is available at
/c/expenseTracker.app.
You should see the header My Expenses.
SEE ALSO:
Salesforce Help: Open the Developer Console
aura:application
Using the Salesforce Lightning Design System in Apps

Step 2: Create A Component for User Input
Components are the building blocks of an app. They can be wired up to an Apex controller class to load your data. The component you
create in this step provides a form that takes in user input about an expense, such as expense amount and date.
1. Click File > New > Lightning Component.
2. Enter form for the Name field in the New Lightning Bundle popup window. This creates a new component, form.cmp.
3. In the source code editor, enter this code.
Note: The following code creates an input form that takes in user input to create an expense, which works in both a standalone
app, and in Salesforce1 and Lightning Experience. For apps specific to Salesforce1 and Lightning Experience, you can use
force:createRecord to open the create record page.








































15

Quick Start

Step 2: Create A Component for User Input

































Total Expenses

$









No. of Expenses


















16

Quick Start

Step 2: Create A Component for User Input


{!expense.Name}, {!expense.Client__c},
{!expense.Amount__c}, {!expense.Date__c},
{!expense.Reimbursed__c}








Components provide a rich set of attributes and browser event support. Attributes are typed fields that are set on a specific instance
of a component, and can be referenced using an expression syntax. All aura:attribute tags have name and type values. For
more information, see Supported aura:attribute Types on page 325.
The attributes and expressions here will become clearer as you build the app. {!v.exp} evaluates the number of expenses records
and {!v.total} evaluates the total amount. {!c.createExpense} represents the client-side controller action that runs
when the Submit button (1) is clicked, which creates a new expense. The press event in ui:button enables you to wire up
the action when the button is pressed.

The expression {!v.expenses} wires up the component to the expenses object. var="expense" denotes the name of
the variable to use for each item inside the iteration. {!expense.Client__c} represents data binding to the client field in
the expense object.
Note: The default value for newExpense of type Expense__c must be initialized with the correct fields, including
sobjectType. Initializing the default value ensures that the expense is saved in the correct format.
4. Click STYLE in the sidebar to create a new resource named form.css. Enter these CSS rule sets.
.THIS .uiInputDateTime .datePicker-openIcon {
position: absolute;
left: 45%;
top: 45%;
}
.THIS .uiInputDateTime .timePicker-openIcon {
position: absolute;
left: 95%;

17

Quick Start

Step 2: Create A Component for User Input

top: 70%;
}
.THIS .uiInputDefaultError li {
list-style: none;
}

Note: THIS is a keyword that adds namespacing to CSS to prevent any conflicts with another component’s styling. The
.uiInputDefaultError selector styles the default error component when you add field validation in Step 5: Enable
Input for New Expenses on page 23.
5. Add the component to the app. In expenseTracker.app, add the new component to the markup.
This step adds  to the markup. If you’re using a namespace, you can use  instead. If
you haven’t set a namespace prefix for your organization, use the default namespace c when referencing components that you’ve
created.










Expenses






My Expenses




















6. Save your changes and click Update Preview in the sidebar to preview your app. Alternatively, reload your browser.
Note: In this step, the component you created doesn’t display any data since you haven’t created the Apex controller class
yet.
Good job! You created a component that provides an input form and view of your expenses. Next, you’ll create the logic to display your
expenses.
SEE ALSO:
Component Markup
Component Body

18

Quick Start

Step 3: Load the Expense Data

Step 3: Load the Expense Data
Load expense data using an Apex controller class. Display this data via component attributes and update the counters dynamically.
Create the expense controller class.
1. Click File > New > Apex Class and enter ExpenseController in the New Class window. This creates a new Apex class,
ExpenseController.apxc.
2. Enter this code.
public with sharing class ExpenseController {
@AuraEnabled
public static List getExpenses() {
// Perform isAccessible() check here
return [SELECT Id, Name, Amount__c, Client__c, Date__c,
Reimbursed__c, CreatedDate FROM Expense__c];
}
}

The getExpenses() method contains a SOQL query to return all expense records. Recall the syntax {!v.expenses} in
form.cmp, which displays the result of the getExpenses() method in the component markup.
Note: For more information on using SOQL, see the Force.com SOQL and SOSL Reference.
@AuraEnabled enables client- and server-side access to the controller method. Server-side controllers must be static and all

instances of a given component share one static controller. They can return or take in any types, such as a List or Map.
Note: For more information on server-side controllers, see Apex Server-Side Controller Overview on page 248.
3. In form.cmp, update the aura:component tag to include the controller attribute.


Note: If your org has a namespace, use controller="myNamespace.ExpenseController" instead.
4. Add an init handler to load your data on component initialization.






On initialization, this event handler runs the doInit action that you’re creating next. This init event is fired before component
rendering.
5. Add the client-side controller action for the init handler. In the sidebar, click CONTROLLER to create a new resource,
formController.js. Enter this code.
({
doInit : function(component, event, helper) {
//Update expense counters
helper.getExpenses(component);
},//Delimiter for future code
})

19

Quick Start

Step 3: Load the Expense Data

During component initialization, the expense counters should reflect the latest sum and total number of expenses, which you’re
adding next using a helper function, getExpenses(component).
Note: A client-side controller handles events within a component and can take in three parameters: the component to which
the controller belongs, the event that the action is handling, and the helper if it’s used. A helper is a resource for storing code
that you want to reuse in your component bundle, providing better code reusability and specialization. For more information
about using client-side controllers and helpers, see Handling Events with Client-Side Controllers on page 138 and Sharing
JavaScript Code in a Component Bundle on page 223.
6. Create the helper function to display the expense records and dynamically update the counters. Click HELPER to create a new
resource, formHelper.js and enter this code.
({
getExpenses: function(component) {
var action = component.get("c.getExpenses");
action.setCallback(this, function(response) {
var state = response.getState();
if (component.isValid() && state === "SUCCESS") {
component.set("v.expenses", response.getReturnValue());
this.updateTotal(component);
}
});
$A.enqueueAction(action);
},
updateTotal : function(component) {
var expenses = component.get("v.expenses");
var total = 0;
for(var i=0; i New > Lightning Component.
2. Enter expenseList in the New Lightning Bundle window. This creates a new component, expenseList.cmp.
3. In expenseList.cmp, enter this code.
Note: Use the API name of the fields to bind the field values. For example, if you’re using a namespace, you must use
{!v.expense.myNamespace__Amount__c} instead of {!v.expense.Amount__c}.












{!v.expense.Name}










Amount:




Client:

21

Quick Start

Step 4: Create a Nested Component





Date:




Reimbursed?













Instead of using {!expense.Amount__c}, you’re now using {!v.expense.Amount__c}. This expression accesses the
expense object and the amount values on it.
Additionally, href="{!'/' + v.expense.Id}" uses the expense ID to set the link to the detail page of each expense
record.
4. In form.cmp, update the aura:iteration tag to use the new nested component, expenseList. Locate the existing
aura:iteration tag.


{!expense.Name}, {!expense.Client__c}, {!expense.Amount__c}, {!expense.Date__c},
{!expense.Reimbursed__c}



Replace it with an aura:iteration tag that uses the expenseList component.





Notice how the markup is simpler as you’re just passing each expense record to the expenseList component, which handles
the display of the expense details.
5. Save your changes and reload your browser.
You created a nested component and passed its attributes to a parent component. Next, you’ll learn how to process user input and
update the expense object.
Beyond the Basics
When you create a component, you are providing the definition of that component. When you put the component in another
component, you are create a reference to that component. This means that you can add multiple instances of the same component
with different attributes. For more information about component attributes, see Component Composition on page 51.
SEE ALSO:
Component Attributes

22

Quick Start

Step 5: Enable Input for New Expenses

Step 5: Enable Input for New Expenses
When you enter text into the form and press Submit, you want to insert a new expense record. This action is wired up to the button
component via the press attribute.
The following flowchart shows the flow of data in your app when you create a new expense. The data is captured when you click the
Submit button in the component form.cmp, processed by your JavaScript code and sent to the server-side controller to be saved
as a record. Data from the records is displayed in the nested component you created in the previous step.

First, update the Apex controller with a new method that inserts or updates the records.

23

Quick Start

Step 5: Enable Input for New Expenses

1. In the ExpenseController class, enter this code below the getExpenses() method.
@AuraEnabled
public static Expense__c saveExpense(Expense__c expense) {
// Perform isUpdateable() check here
upsert expense;
return expense;
}

The saveExpense() method enables you to insert or update an expense record using the upsert operation.
Note: Fore more information about the upsert operation, see the Apex Developer Guide.
2. Create the client-side controller action to create a new expense record when the Submit button is pressed. In
formController.js, add this code after the doInit action.
createExpense : function(component, event, helper) {
var amtField = component.find("amount");
var amt = amtField.get("v.value");
if (isNaN(amt)||amt==''){
amtField.set("v.errors", [{message:"Enter an expense amount."}]);
}
else {
amtField.set("v.errors", null);
var newExpense = component.get("v.newExpense");
helper.createExpense(component, newExpense);
}
},//Delimiter for future code

createExpense validates the amount field using the default error handling of input components. If the validation fails, we set
an error message in the errors attribute of the input component. For more information on field validation, see Validating Fields

on page 230.
Notice that you’re passing in the arguments to a helper function helper.createExpense(), which then triggers the Apex
class saveExpense.
Note: Recall that you specified the aura:id attributes in Step 2: Create A Component for User Input on page 14. aura:id
enables you to find the component by name using the syntax component.find("amount") within the scope of this
component and its controller.
3. Create the helper function to handle the record creation. In formHelper.js, add these helper functions after the updateTotal
function.
createExpense: function(component, expense) {
this.upsertExpense(component, expense, function(a) {
var expenses = component.get("v.expenses");
expenses.push(a.getReturnValue());
component.set("v.expenses", expenses);
this.updateTotal(component);
});
},
upsertExpense : function(component, expense, callback) {
var action = component.get("c.saveExpense");
action.setParams({
"expense": expense

24

Quick Start

Step 6: Make the App Interactive With Events

});
if (callback) {
action.setCallback(this, callback);
}
$A.enqueueAction(action);
}

createExpense calls upsertExpense, which defines an instance of the saveExpense server-side action and sets the
expense object as a parameter. The callback is executed after the server-side action returns, which updates the records, view,
and counters. $A.enqueueAction(action) adds the server-side action to the queue of actions to be executed.

Note: Different possible action states are available and you can customize their behaviors in your callback. For more information
on action callbacks, see Calling a Server-Side Action.
4. Save your changes and reload your browser.
5. Test your app by entering a new expense record with field values: Breakfast, 10, ABC Co., Apr 30, 2014
9:00:00 AM. For the date field, you can also use the date picker to set a date and time value. Click the Submit button. The record
is added to both your component view and records, and the counters are updated.
Note: To debug your Apex code, use the Logs tab in the Developer Console. For example, if you don’t have input validation
for the date time field and entered an invalid date time format, you might get an INVALID_TYPE_ON_FIELD_IN_RECORD
exception, which is listed both on the Logs tab in the Developer Console and in the response header on your browser. Otherwise,
you might see an Apex error displayed in your browser. For more information on debugging your JavaScript code, see Enable
Debug Mode for Lightning Components on page 304.
Congratulations! You have successfully created a simple expense tracker app that includes several components, client- and server-side
controllers, and helper functions. Your app now accepts user input, which updates the view and database. The counters are also
dynamically updated as you enter new user input. The next step shows you how to add a layer of interactivity using events.
SEE ALSO:
Handling Events with Client-Side Controllers
Calling a Server-Side Action
CRUD and Field-Level Security (FLS)

Step 6: Make the App Interactive With Events
Events add an interactive layer to your app by enabling you to share data between components. When the checkbox is checked or
unchecked in the expense list view, you want to fire an event that updates both the view and records based on the relevant component
data.
This flowchart shows the data flow in the app when a data change is captured by the selecting and deselecting of a checkbox on the
expenseList component. When the Reimbursed? checkbox is selected or deselected, this browser click event fires the component
event you’re creating here. This event communicates the expense object to the handler component, and its controller calls the Apex
controller method to update the relevant expense record, after which the response is ignored by the client since we won’t be handling
this server response here.

25

Quick Start

Step 6: Make the App Interactive With Events

Let’s start by creating the event and its handler before firing it and handling the event in the parent component.
1. Click File > New > Lightning Event.
2. Enter updateExpenseItem in the New Event window. This creates a new event, updateExpenseItem.evt.
3. In updateExpenseItem.evt, enter this code.
The attribute you’re defining in the event is passed from the firing component to the handlers.



26

Quick Start

Step 6: Make the App Interactive With Events




The framework has two types of events: component events and application events.
Note: Always try to use a component event instead of an application event, if possible. Component events can only be
handled by components above them in the containment hierarchy so their usage is more localized to the components that
need to know about them. Application events are best used for something that should be handled at the application level,
such as navigating to a specific record. Application events allow communication between components that are in separate
parts of the application and have no direct containment relationship.
We’ll use a component event. Recall that expenseList.cmp contains the Reimbursed? checkbox.
4. Update expenseList.cmp to register that it fires the event. Add this tag after the  tag.


The Reimbursed? checkbox is wired up to a client-side controller action, denoted by change="{!c.update}". You’ll set up
the update action next.
5. In the expenseList sidebar, click CONTROLLER. This creates a new resource, expenseListController.js. Enter this
code.
({
update: function(component, evt, helper) {
var expense = component.get("v.expense");
// Note that updateExpense matches the name attribute in 
var updateEvent = component.getEvent("updateExpense");
updateEvent.setParams({ "expense": expense }).fire();
}
})

When the checkbox is checked or unchecked, the update action runs, setting the reimbursed parameter value to true or
false. The updateExpenseItem.evt event is fired with the updated expense object .
6. In the handler component, form.cmp, add this handler code before the  tags.


This event handler runs the updateEvent action when the component event you created is fired. The 
tag uses the same value of the name attribute, updateExpense, from the  tag in
c:expenseList

7. Wire up the updateEvent action to handle the event. In formController.js, enter this code after the createExpense
controller action.
updateEvent : function(component, event, helper) {
helper.upsertExpense(component, event.getParam("expense"));
}

This action calls a helper function and passes in event.getParam("expense"), which contains the expense object with its
parameters and values in this format: { Name : "Lunch" , Client__c : "ABC Co." , Reimbursed__c :
true , CreatedDate : "2014-08-12T20:53:09.000Z" , Amount__c : 20}.
8. Save your changes and reload your browser.

27

Quick Start

Summary

9. Click the Reimbursed? checkbox for one of the records.
Note that the background color for the record changes. When you change the reimbursed status on the view, the update event
is fired, handled by the parent component, which then updates the expense record by running the server-side controller action
saveExpense.
That’s it! You have successfully added a layer of interaction in your expense tracker app using a component event.
The app you just created is currently accessible as a standalone app by accessing
https://.lightning.force.com//expenseTracker.app, where 
is the name of your custom Salesforce domain. To make it accessible in Salesforce1, see Add Lightning Components as Custom Tabs in
Salesforce1 on page 100. To package and distribute your app on AppExchange, see Distributing Applications and Components on page
302.

SEE ALSO:
Component Events
Event Handling Lifecycle

Summary
You created several components with controllers and events that interact with your expense records. The expense tracker app performs
three distinct tasks: load the expense data and counters on app initialization, take in user input to create a new record and update the
view, and handle user interactions by communicating relevant component data via events.

28

Quick Start

Summary

When form.cmp is initialized, the init handler triggers the doInit client-side controller, which calls the getExpenses
helper function. getExpenses calls the getExpenses server-side controller to load the expenses. The callback sets the expenses
data on the v.expenses attribute and calls updateTotal to update the counters.
Clicking the Submit button triggers the createExpense client-side controller. After field validation, the createExpense helper
function is run, in which the upsertExpense helper function calls the saveExpense server-side controller to save the record.
The callback pushes the new expense to the list of expenses and updates the attribute v.expenses in form.cmp, which in turn
updates the expenses in expenseList.cmp. Finally, the helper calls updateTotal to update the counters represented by the
v.total and v.exp attributes.
expenseList.cmp displays the list of expenses. When the Reimbursed? checkbox is selected or deselected, the click event
triggers the update client-side controller. The updateExpenseItem event is fired with the relevant expense passed in as a

29

Quick Start

Create a Component for Salesforce1 and Lightning Experience

parameter. form.cmp handles the event, triggering the updateEvent client-side controller. This controller action then calls the
upsertExpense helper function, which calls the saveExpense server-side controller to save the relevant record.

Create a Component for Salesforce1 and Lightning Experience
Create a component that loads contacts data and interacts with Salesforce1 and Lightning Experience. Some of the events that are used
in this tutorial are not supported for standalone apps.

The component has these features.
• Displays a toast message (1) when all contacts are loaded successfully
• Use a nested component that displays all contacts or displays all primary contacts that are colored green when the input select value
(2) is changed

30

Quick Start

Load the Contacts

• Opens the create record page to create a new contact when the New Contact button (3) is clicked
• Opens the edit record page to update the selected contact when the Edit button (4) is clicked
• Navigates to the record when the contact (5) is clicked
• Navigates to related cases when the View Cases button (6) is clicked
You’ll create the following resources.
Resource

Description

Contacts Bundle
contacts.cmp

The component that loads contact data

contactsController.js The client-side controller actions that loads contact data, handles input select change event, and opens

the create record page
contactsHelper.js

The helper function that retrieves contact data and display toast messages based on the loading status

contactList Bundle
contactList.cmp

The contact list component

contactListController.js The client-side controller actions that opens the edit record page, and navigates to a contact record,

related cases, and map of contact address
contactList.css

The styles for the component

Apex Controller
ContactController.apxc The Apex controller that queries the contact records

Load the Contacts
Create an Apex controller and load your contacts.
Your organization must have existing contact records for this tutorial. This tutorial uses a custom picklist field, Level, which is represented
by the API name Level__c. This field contains three picklist values: Primary, Secondary, and Tertiary.
1. Click File > New > Apex Class, and then enter ContactController in the New Class window. This creates a new Apex
class, ContactController.apxc. Enter this code and then save.
If you’re using a namespace in your organization, replace Level__c with myNamespace__Level__c.
public with sharing class ContactController {
@AuraEnabled
public static List getContacts() {
List contacts =
[SELECT Id, Name, MailingStreet, Phone, Email, Level__c FROM Contact];
//Add isAccessible() check
return contacts;
}
@AuraEnabled
// Retrieve all primary contacts
public static List getPrimary() {

31

Quick Start

Load the Contacts

List primaryContacts =
[SELECT Id, Name, MailingStreet, Phone, Email, Level__c FROM Contact WHERE
Level__c = 'Primary'];
//Add isAccessible() check
return primaryContacts;
}
}

getPrimary() returns all contacts whose Level__c field is set to Primary.

2. Click File > New > Lightning Component, and then enter contactList for the Name field in the New Lightning Bundle
popup window. This creates a new component, contactList.cmp. Enter this code and then save.


















3. In the contactList sidebar, click STYLE to create a new resource named contactList.css. Replace the placeholder code with
the following code and then save.
.THIS.primary{
background: #4ECDC4
}

!important;

.THIS.row {
background: #fff;
max-width:90%;
border-bottom: 2px solid #f0f1f2;
padding: 10px;
margin-left: 2%;
margin-bottom: 10px;
min-height: 70px;
border-radius: 4px;
}

32

Quick Start

Load the Contacts

4. Click File > New > Lightning Component, and then enter contacts for the Name field in the New Lightning Bundle popup
window. This creates a new component, contacts.cmp. Enter this code and then save. If you’re using a namespace in your
organization, replace ContactController with myNamespace.ContactController.



















5. In the contacts sidebar, click CONTROLLER to create a new resource named contactsController.js. Replace the
placeholder code with the following code and then save.
({
doInit : function(component, event, helper) {
// Retrieve contacts during component initialization
helper.getContacts(component);
},//Delimiter for future code
})

6. In the contacts sidebar, click HELPER to create a new resource named contactsHelper.js. Replace the placeholder code
with the following code and then save.
({
getContacts : function(cmp) {
// Load all contact data
var action = cmp.get("c.getContacts");
action.setCallback(this, function(response) {
var state = response.getState();
if (cmp.isValid() && state === "SUCCESS") {
cmp.set("v.contacts", response.getReturnValue());
}
// Display toast message to indicate load status
var toastEvent = $A.get("e.force:showToast");
if (state === 'SUCCESS'){
toastEvent.setParams({
"title": "Success!",

33

Quick Start

Fire the Events

"message": " Your contacts have been loaded successfully."
});
}
else {
toastEvent.setParams({
"title": "Error!",
"message": " Something has gone wrong."
});
}
toastEvent.fire();
});
$A.enqueueAction(action);
}
})

7. Create a new Lightning Component tab by following the steps on Add Lightning Components as Custom Tabs in Salesforce1 on
page 100. Make sure you include the component in the Salesforce1 navigation menu.
Finally, you can go to the Salesforce1 mobile browser app to check your output. When your component is loaded, you should see a toast
message that indicates your contacts are loaded successfully.
Next, we’ll wire up the other events so that your input select displays either all contacts or only primary contacts that are colored green.
We’ll also wire up events for opening the create record and edit record pages, and events for navigating to a record and a URL.

Fire the Events
Fire the events in your client-side controller or helper functions. The force events are handled by Salesforce1.
This demo builds on the contacts component you created in Load the Contacts on page 31.
1. In the contactList sidebar, click CONTROLLER to create a new resource named contactListController.js. Replace the
placeholder code with the following code and then save.
({
gotoRecord : function(component, event, helper) {
// Fire the event to navigate to the contact record
var sObjectEvent = $A.get("e.force:navigateToSObject");
sObjectEvent.setParams({
"recordId": component.get("v.contact.Id"),
"slideDevName": 'related'
})
sObjectEvent.fire();
},
editRecord : function(component, event, helper) {
// Fire the event to navigate to the edit contact page
var editRecordEvent = $A.get("e.force:editRecord");
editRecordEvent.setParams({
"recordId": component.get("v.contact.Id")
});
editRecordEvent.fire();
},
relatedList : function (component, event, helper) {
// Navigate to the related cases

34

Quick Start

Fire the Events

var relatedListEvent = $A.get("e.force:navigateToRelatedList");
relatedListEvent.setParams({
"relatedListId": "Cases",
"parentRecordId": component.get("v.contact.Id")
});
relatedListEvent.fire();
}
})

2. Refresh the Salesforce1 mobile browser app, and click these elements to test the events.
• Contact: force:navigateToSObject is fired, which updates the view with the contact record page. The contact name
corresponds to the following component.






• Edit Contact button: force:editRecord is fired, which opens the edit record page. The Edit Contact icon corresponds to
the following component.


3. Open contactsController.js. After the doInit controller, enter this code and then save.
createRecord : function (component, event, helper) {
// Open the create record page
var createRecordEvent = $A.get("e.force:createRecord");
createRecordEvent.setParams({
"entityApiName": "Contact"
});
createRecordEvent.fire();
},
select : function(component, event, helper){
// Get the selected value of the ui:inputSelect component
var selectCmp = component.find("selection");
var selectVal = selectCmp.get("v.value");
// Display all primary contacts or all contacts
if (selectVal==="All Primary"){
var action = component.get("c.getPrimary");
action.setCallback(this, function(response){
var state = response.getState();
if (component.isValid() && state === "SUCCESS") {
component.set("v.contacts", response.getReturnValue());
}
});
$A.enqueueAction(action);
}
else {
// Return all contacts
helper.getContacts(component);
}
}

35

Quick Start

Fire the Events

Notice that if you pull down the page and release it, the page refreshes all data in the view. Now you can test your components by
clicking on the areas highlighted in Create a Component for Salesforce1 and Lightning Experience on page 30.
For an example on creating a standalone app that can be used independent of Salesforce1, see Create a Standalone Lightning App on
page 7.

36

CHAPTER 3

Creating Components

In this chapter ...

Components are the functional units of the Lightning Component framework.

•

Create Lightning
Components in the
Developer Console

A component encapsulates a modular and potentially reusable section of UI, and can range in granularity
from a single line of text to an entire application.

•

Component Markup

•

Component
Namespace

•

Component Bundles

•

Component IDs

•

HTML in Components

•

CSS in Components

•

Component
Attributes

•

Component
Composition

•

Component Body

•

Component Facets

•

Best Practices for
Conditional Markup

•

Component
Versioning

•

Using Expressions

•

Using Labels

•

Localization

•

Providing
Component
Documentation

•

Working with Base
Lightning
Components

•

Working with UI
Components

•

Supporting
Accessibility

37

Creating Components

Create Lightning Components in the Developer Console

Create Lightning Components in the Developer Console
The Developer Console is a convenient, built-in tool you can use to create new and edit existing Lightning components and other
bundles.
1. Open the Developer Console.
Select Developer Console from the Your Name or the quick access menu (

).

2. Open the New Lightning Bundle panel for a Lightning component.
Select File > New > Lightning Component.
3. Name the component.
For example, enter helloWorld in the Name field.
4. Optional: Describe the component.
Use the Description field to add details about the component.
5. Optional: Add component configurations to the new component.
You can select as many options in the Component Configuration section as you wish, or select no configuration at all.
6. Click Submit to create the component.
Or, to cancel creating the component, click the panel’s close box in the top right corner.
Example:

38

Creating Components

Lightning Bundle Configurations Available in the Developer
Console

IN THIS SECTION:
Lightning Bundle Configurations Available in the Developer Console
Configurations make it easier to create a component or application for a specific purpose, like a Lightning Page or Lightning
Communities Page, or a quick action or navigation item in Lightning Experience or Salesforce1. The New Lightning Bundle panel in
the Developer Console offers a choice of component configurations when you create a Lightning component or application bundle.
SEE ALSO:
Using the Developer Console
Lightning Bundle Configurations Available in the Developer Console

Lightning Bundle Configurations Available in the Developer Console
Configurations make it easier to create a component or application for a specific purpose, like a Lightning Page or Lightning Communities
Page, or a quick action or navigation item in Lightning Experience or Salesforce1. The New Lightning Bundle panel in the Developer
Console offers a choice of component configurations when you create a Lightning component or application bundle.
Configurations add the interfaces required to support using the component in the desired context. For example, when you choose the
Lightning Tab configuration, your new component includes implements="force:appHostable" in the
 tag.

Using configurations is optional. You can use them in any combination, including all or none.
The following configurations are available in the New Lightning Bundle panel.
Configuration

Markup

Description

Lightning component bundle
Lightning Tab

implements="force:appHostable"

39

Creates a component for use as a
navigation element in Lightning
Experience or Salesforce1.

Creating Components

Component Markup

Configuration

Markup

Description

Lightning Page

implements="flexipage:availableForAllPageTypes" Creates a component for use in
Lightning Pages or the Lightning App
and access="global"

Builder.
Lightning Record Page

implements="flexipage:availableForRecordHome, Creates a component for use on a
record home page in Lightning
force:hasRecordId" and access="global"

Experience.
Lightning Communities implements="forceCommunity:availableForAllPageTypes" Creates a component that’s available
Page
for drag and drop in the Community
and access="global"
Builder.
Lightning Quick Action

implements="force:lightningQuickAction"

Creates a component that can be
used with a Lightning quick action.

Lightning application bundle
Lightning Out
Dependency App

Creates an empty Lightning Out
dependency app.

extends="ltng:outApp"

Note: For details of the markup added by each configuration, see the respective documentation for those features.

SEE ALSO:
Create Lightning Components in the Developer Console
Interface Reference
Configure Components for Custom Tabs
Configure Components for Custom Actions
Configure Components for Lightning Pages and the Lightning App Builder
Configure Components for Lightning Experience Record Pages
Configure Components for Communities

Component Markup
Component resources contain markup and have a .cmp suffix. The markup can contain text or references to other components, and
also declares metadata about the component.
Let's start with a simple "Hello, world!" example in a helloWorld.cmp component.

Hello, world!


This is about as simple as a component can get. The "Hello, world!" text is wrapped in the  tags, which appear
at the beginning and end of every component definition.

40

Creating Components

Component Namespace

Components can contain most HTML tags so you can use markup, such as 
 and . HTML5 tags are also supported.








Note: Case sensitivity should be respected as your markup interacts with JavaScript, CSS, and Apex.
Use the Developer Console to create components.

Component Naming Rules
A component name must follow these naming rules:
• Must begin with a letter
• Must contain only alphanumeric or underscore characters
• Must be unique in the namespace
• Can’t include whitespace
• Can’t end with an underscore
• Can’t contain two consecutive underscores
SEE ALSO:
aura:component
Using the Developer Console
Component Access Control
Client-Side Rendering to the DOM
Dynamically Creating Components

Component Namespace
Every component is part of a namespace, which is used to group related components together. If your organization has a namespace
prefix set, use that namespace to access your components. Otherwise, use the default namespace to access your components.
Another component or application can reference a component by adding  in its markup. For
example, the helloWorld component is in the docsample namespace. Another component can reference it by adding
 in its markup.
Lightning components that Salesforce provides are grouped into several namespaces, such as aura, ui, and force. Components
from third-party managed packages have namespaces from the providing organizations.
In your organization, you can choose to set a namespace prefix. If you do, that namespace is used for all of your Lightning components.
A namespace prefix is required if you plan to offer managed packages on the AppExchange.
If you haven’t set a namespace prefix for your organization, use the default namespace c when referencing components that you’ve
created.

41

Creating Components

Using the Default Namespace in Organizations with No
Namespace Set

Namespaces in Code Samples
The code samples throughout this guide use the default c namespace. Replace c with your namespace if you’ve set a namespace
prefix.

Using the Default Namespace in Organizations with No Namespace Set
If your organization hasn’t set a namespace prefix, use the default namespace c when referencing Lightning components that you’ve
created.
The following items must use the c namespace when your organization doesn’t have a namespace prefix set.
• References to components that you’ve created
• References to events that you’ve defined
The following items use an implicit namespace for your organization and don’t require you to specify a namespace.
• References to custom objects
• References to custom fields on standard and custom objects
• References to Apex controllers
See Namespace Usage Examples and Reference on page 43 for examples of all of the preceding items.

Using Your Organization’s Namespace
If your organization has set a namespace prefix, use that namespace to reference Lightning components, events, custom objects and
fields, and other items in your Lightning markup.
The following items use your organization’s namespace when your organization has a namespace prefix set.
• References to components that you’ve created
• References to events that you’ve defined
• References to custom objects
• References to custom fields on standard and custom objects
• References to Apex controllers
• References to static resources
Note: Support for the c namespace in organizations that have set a namespace prefix is incomplete. The following items can
use the c namespace if you prefer to use the shortcut, but it’s not currently a recommended practice.
• References to components that you’ve created when used in Lightning markup, but not in expressions or JavaScript
• References to events that you’ve defined when used in Lightning markup, but not in expressions or JavaScript
• References to custom objects when used in component and event type and default system attributes, but not in
expressions or JavaScript
See Namespace Usage Examples and Reference on page 43 for examples of the preceding items.

Using a Namespace in or from a Managed Package
Always use the complete namespace when referencing items from a managed package, or when creating code that you intend to
distribute in your own managed packages.

42

Creating Components

Creating a Namespace in Your Organization

Creating a Namespace in Your Organization
Create a namespace for your organization by registering a namespace prefix.
If you’re not creating managed packages for distribution then registering a namespace prefix isn’t required, but it’s a best practice for
all but the smallest organizations.
Your namespace prefix must:
• Begin with a letter
• Contain one to 15 alphanumeric characters
• Not contain two consecutive underscores
For example, myNp123 and my_np are valid namespaces, but 123Company and my__np aren’t.
To register a namespace prefix:
1. From Setup, enter Packages in the Quick Find box. Under Create, select Packages.
Note: This item is only available in Salesforce Classic.
2. In the Developer Settings panel, click Edit.
Note: This button doesn’t appear if you’ve already configured your developer settings.
3. Review the selections that are required for configuring developer settings, and then click Continue.
4. Enter the namespace prefix you want to register.
5. Click Check Availability to determine if the namespace prefix is already in use.
6. If the namespace prefix that you entered isn’t available, repeat the previous two steps.
7. Click Review My Selections.
8. Click Save.

Namespace Usage Examples and Reference
This topic provides examples of referencing components, objects, fields, and so on in Lightning components code.
Examples are provided for the following.
• Components, events, and interfaces in your organization
• Custom objects in your organization
• Custom fields on standard and custom objects in your organization
• Server-side Apex controllers in your organization
• Dynamic creation of components in JavaScript
• Static resources in your organization

Organizations with No Namespace Prefix Set
The following illustrates references to elements in your organization when your organization doesn’t have a namespace prefix set.
References use the default namespace, c, where necessary.

43

Creating Components

Namespace Usage Examples and Reference

Referenced Item

Example

Component used in markup



Component used in a system
attribute




Apex controller



Custom object in attribute data type 





value="{!v.newExpense.Amount__c}" label=…

updateTotal: function(component) {
…
for(var i = 0 ; i < expenses.length ; i++){
var exp = expenses[i];
total += exp.Amount__c;
}
…
}

var myCmp = $A.createComponent("c:myComponent", {},
function(myCmp) { }
);

Interface comparison in a JavaScript aCmp.isInstanceOf("c:myInterface")
function
Event registration



Application event in a JavaScript
function

var updateEvent = $A.get("e.c:updateExpenseItem");

Static resources



44

type="c:updateExpenseItem" name=… />
action=… />

Creating Components

Namespace Usage Examples and Reference

Organizations with a Namespace Prefix
The following illustrates references to elements in your organization when your organization has set a namespace prefix. References use
an example namespace yournamespace.
Referenced Item

Example

Component used in markup



Component used in a system
attribute



extends="yournamespace:myComponent">



Custom object in attribute data type 

Custom object or custom field in
attribute defaults

Custom field in an expression
Custom field in a JavaScript function

Component created dynamically in
a JavaScript function




updateTotal: function(component) {
…
for(var i = 0 ; i < expenses.length ; i++){
var exp = expenses[i];
total += exp.yournamespace__Amount__c;
}
…
}

var myCmp = $A.createComponent("yournamespace:myComponent",
{},
function(myCmp) { }
);

Interface comparison in a JavaScript aCmp.isInstanceOf("yournamespace:myInterface")
function
Event registration



Event handler



type="yournamespace:updateExpenseItem"

event="yournamespace:updateExpenseItem"

45

Creating Components

Component Bundles

Referenced Item

Example

Explicit dependency



Application event in a JavaScript
function

var updateEvent = $A.get("e.yournamespace:updateExpenseItem");

Static resources



Component Bundles
A component bundle contains a component or an app and all its related resources.
Resource

Resource Name

Usage

Component or Application

sample.cmp or
sample.app

The only required resource in a Creating Components on page
bundle. Contains markup for the 37
component or app. Each bundle aura:application on page 331
contains only one component
or app resource.

CSS Styles

sample.css

Contains styles for the
component.

Controller

sampleController.js

Contains client-side controller Handling Events with Client-Side
methods to handle events in the Controllers on page 138
component.

Design

sample.design

File required for components
Configure Components for
used in Lightning App Builder, Lightning Pages and the
Lightning Pages, or Community Lightning App Builder
Builder.

Documentation

sample.auradoc

A description, sample code, and Providing Component
one or multiple references to
Documentation on page 82
example components

Renderer

sampleRenderer.js

Client-side renderer to override Client-Side Rendering to the
default rendering for a
DOM on page 226
component.

Helper

sampleHelper.js

JavaScript functions that can be Sharing JavaScript Code in a
called from any JavaScript code Component Bundle on page 223
in a component’s bundle

SVG File

sample.svg

Custom icon resource for
components used in the
Lightning App Builder or
Community Builder.

46

See Also

CSS in Components on page 48

Configure Components for
Lightning Pages and the
Lightning App Builder on page
109

Creating Components

Component IDs

All resources in the component bundle follow the naming convention and are auto-wired. For example, a controller
Controller.js is auto-wired to its component, which means that you can use the controller within the
scope of that component.

Component IDs
A component has two types of IDs: a local ID and a global ID. You can retrieve a component using its local ID in your JavaScript code. A
global ID can be useful to differentiate between multiple instances of a component or for debugging purposes.

Local IDs
A local ID is an ID that is only scoped to the component. A local ID is often unique but it’s not required to be unique.
Create a local ID by using the aura:id attribute. For example:


Note: aura:id doesn't support expressions. You can only assign literal string values to aura:id.
Find the button component by calling cmp.find("button1") in your client-side controller, where cmp is a reference to the
component containing the button.
find() returns different types depending on the result.

• If the local ID is unique, find() returns the component.
• If there are multiple components with the same local ID, find() returns an array of the components.
• If there is no matching local ID, find() returns undefined.
To find the local ID for a component in JavaScript, use cmp.getLocalId().

Global IDs
Every component has a unique globalId, which is the generated runtime-unique ID of the component instance. A global ID (1) is
not guaranteed to be the same beyond the lifetime of a component, so it should never be relied on. A global ID can be useful to
differentiate between multiple instances of a component or for debugging purposes.

To create a unique ID for an HTML element, you can use the globalId as a prefix or suffix for your element. For example:



In your browser’s developer console, retrieve the element using document.getElementById("_footer"),
where  is the generated runtime-unique ID.

47

Creating Components

HTML in Components

To retrieve a component’s global ID in JavaScript, use the getGlobalId() function.
var globalId = cmp.getGlobalId();

SEE ALSO:
Finding Components by ID
Which Button Was Pressed?

HTML in Components
An HTML tag is treated as a first-class component by the framework. Each HTML tag is translated into an  component,
allowing it to enjoy the same rights and privileges as any other component.
For example, the framework automatically converts a standard HTML 
 tag to this component:


You can add HTML markup in components. Note that you must use strict XHTML. For example, use 
 instead of 
. You can
also use HTML attributes and DOM events, such as onclick.
Warning: Some tags, like  and , aren’t supported. For a full list of unsupported tags, see Supported HTML
Tags on page 486.

Unescaping HTML
To output pre-formatted HTML, use aura:unescapedHTML. For example, this is useful if you want to display HTML that is generated
on the server and add it to the DOM. You must escape any HTML if necessary or your app might be exposed to security vulnerabilities.
You can pass in values from an expression, such as in .
{!expression} is the framework's expression syntax. For more information, see Using Expressions on page 57.

SEE ALSO:
Supported HTML Tags
CSS in Components

CSS in Components
Style your components with CSS.
Add CSS to a component bundle by clicking the STYLE button in the Developer Console sidebar.
For external CSS resources, see Styling Apps on page 190.
All top-level elements in a component have a special THIS CSS class added to them. This, effectively, adds namespacing to CSS and
helps prevent one component's CSS from blowing away another component's styling. The framework throws an error if a CSS file doesn't
follow this convention.
Let's look at a sample helloHTML.cmp component. The CSS is in helloHTML.css.

48

Creating Components

CSS in Components

Component source



Hello, HTML!



Check out the style in this list.


    

  • I'm red.
    • 

  • I'm blue.
    • 

  • I'm green.
    • 




CSS source
.THIS {
background-color: grey;
}
.THIS.white {
background-color: white;
}
.THIS .red {
background-color: red;
}
.THIS .blue {
background-color: blue;
}
.THIS .green {
background-color: green;
}

Output

The top-level elements, h2 and ul, match the THIS class and render with a grey background. Top-level elements are tags wrapped
by the HTML body tag and not by any other tags. In this example, the li tags are not top-level because they are nested in a ul tag.
The 
 element matches the .THIS.white selector and renders with a white background. Note that
there is no space in the selector as this rule is for top-level elements.

49

Creating Components

Component Attributes

The 
  •  element matches the .THIS .red selector and renders with a red background. Note that this is a
descendant selector and it contains a space as the 
  •  element is not a top-level element.
SEE ALSO:
Adding and Removing Styles
HTML in Components

Component Attributes
Component attributes are like member variables on a class in Apex. They are typed fields that are set on a specific instance of a component,
and can be referenced from within the component's markup using an expression syntax. Attributes enable you to make components
more dynamic.
Use the  tag to add an attribute to the component or app. Let’s look at the following sample,
helloAttributes.app:


Hello {!v.whom}!


All attributes have a name and a type. Attributes may be marked as required by specifying required="true", and may also specify
a default value.
In this case we've got an attribute named whom of type String. If no value is specified, it defaults to "world".
Though not a strict requirement,  tags are usually the first things listed in a component’s markup, as it provides
an easy way to read the component's shape at a glance.

Attribute Naming Rules
An attribute name must follow these naming rules:
• Must begin with a letter or an underscore
• Must contain only alphanumeric or underscore characters

Expressions
helloAttributes.app contains an expression, {!v.whom}, which is responsible for the component's dynamic output.
{!expression} is the framework's expression syntax. In this case, the expression we are evaluating is v.whom. The name of the
attribute we defined is whom, while v is the value provider for a component's attribute set, which represents the view.

Note: Expressions are case sensitive. For example, if you have a custom field myNamespace__Amount__c, you must refer
to it as {!v.myObject.myNamespace__Amount__c}.
SEE ALSO:
Supported aura:attribute Types
Using Expressions

50

Creating Components

Component Composition

Component Composition
Composing fine-grained components in a larger component enables you to build more interesting components and applications.
Let's see how we can fit components together. We will first create a few simple components: c:helloHTML and
c:helloAttributes. Then, we’ll create a wrapper component, c:nestedComponents, that contains the simple components.
Here is the source for helloHTML.cmp.



    
Hello, HTML!

    

    Check out the style in this list.
    

      

    • I'm red.
      • 

    • I'm blue.
      • 

    • I'm green.
      • 

    
    

CSS source
.THIS {
background-color: grey;
}
.THIS.white {
background-color: white;
}
.THIS .red {
background-color: red;
}
.THIS .blue {
background-color: blue;
}
.THIS .green {
background-color: green;
}

Output

Here is the source for helloAttributes.cmp.



51

Creating Components

Component Composition


Hello {!v.whom}!


nestedComponents.cmp uses composition to include other components in its markup.


Observe! Components within components!




Output

Including an existing component is similar to including an HTML tag. Reference the component by its "descriptor", which is of the form
namespace:component. nestedComponents.cmp references the helloHTML.cmp component, which lives in the c
namespace. Hence, its descriptor is c:helloHTML.
Note how nestedComponents.cmp also references c:helloAttributes. Just like adding attributes to an HTML tag, you
can set attribute values in a component as part of the component tag. nestedComponents.cmp sets the whom attribute of
helloAttributes.cmp to "component composition".

Attribute Passing
You can also pass attributes to nested components. nestedComponents2.cmp is similar to nestedComponents.cmp,
except that it includes an extra passthrough attribute. This value is passed through as the attribute value for c:helloAttributes.



Observe! Components within components!




Output

helloAttributes is now using the passed through attribute value.

52

Creating Components

Component Body

Note: {#v.passthrough} is an unbound expression. This means that any change to the value of the whom attribute in
c:helloAttributes doesn’t propagate back to affect the value of the passthrough attribute in
c:nestedComponents2. For more information, see Data Binding Between Components on page 59.

Definitions versus Instances
In object-oriented programming, there’s a difference between a class and an instance of that class. Components have a similar concept.
When you create a .cmp resource, you are providing the definition (class) of that component. When you put a component tag in a
.cmp , you are creating a reference to (instance of) that component.
It shouldn't be surprising that we can add multiple instances of the same component with different attributes.
nestedComponents3.cmp adds another instance of c:helloAttributes with a different attribute value. The two instances
of the c:helloAttributes component have different values for their whom attribute .



Observe! Components within components!





Output

Component Body
The root-level tag of every component is . Every component inherits the body attribute from
.
The  tag can contain tags, such as , ,
, , and so on. Any free markup that is not enclosed in one of the tags allowed in a component is
assumed to be part of the body and is set in the body attribute.
The body attribute has type Aura.Component[]. It can be an array of one component, or an empty array, but it's always an array.
In a component, use “v” to access the collection of attributes. For example, {!v.body} outputs the body of the component.

Setting the Body Content
To set the body attribute in a component, add free markup within the  tag. For example:



53

Creating Components

Component Facets


    Body part
    


    

To set the value of an inherited attribute, use the  tag. Setting the body content is equivalent to wrapping that free
markup inside . Since the body attribute has this special behavior, you can omit .
The previous sample is a shortcut for this markup. We recommend the less verbose syntax in the previous sample.




    Body part
    

Hello World!
    


Accessing the Component Body
To access a component body in JavaScript, use component.get("v.body").
SEE ALSO:
aura:set
Working with a Component Body in JavaScript

Component Facets
A facet is any attribute of type Aura.Component[]. The body attribute is an example of a facet.
To define your own facet, add an aura:attribute tag of type Aura.Component[] to your component. For example, let's
create a new component called facetHeader.cmp.




54

Creating Components

Best Practices for Conditional Markup


    
{!v.header}
    
{!v.body}

    
    

This component has a header facet. Note how we position the output of the header using the v.header expression.
The component doesn't have any output when you access it directly as the header and body attributes aren't set. Let’s create another
component, helloFacets.cmp, that sets these attributes.


See how we set the header facet.
    

Nice body!

Hello Header!


    

Note that aura:set sets the value of the header attribute of facetHeader.cmp, but you don’t need to use aura:set if
you’re setting the body attribute.
SEE ALSO:
Component Body

Best Practices for Conditional Markup
Use the  tag to conditionally display markup. Alternatively, you can conditionally set markup in JavaScript logic. Consider
the performance cost as well as code maintainability when you design components. The best design choice depends on your use case.

Consider Alternatives to Conditional Markup
Here are some use cases where you should consider alternatives to .
You want to toggle visibility
Don’t use  to toggle markup visibility. Use CSS instead. See Dynamically Showing or Hiding Markup on page 244.
You need to nest conditional logic or use conditional logic in an iteration
Using  can hurt performance by creating a large number of components. Excessive use of conditional logic in markup
can also lead to cluttered markup that is harder to maintain.

55

Creating Components

Component Versioning

Consider alternatives, such as using JavaScript logic in an init event handler instead. See Invoking Actions on Component
Initialization on page 229.
SEE ALSO:
aura:if
Conditional Expressions

Component Versioning
Component versioning enables you to declare dependencies against specific revisions of an installed managed package.
By assigning a version to your component, you have granular control over how the component functions when new versions of a
managed package are released. For example, imagine that a :button is pinned to version 2.0 of a package.
Upon installing version 3.0, the button retains its version 2.0 functionality.
Note: The package developer is responsible for inserting versioning logic into the markup when updating a component. If the
component wasn’t changed in the update or if the markup doesn’t account for version, the component behaves in the context
of the most recent version.
Versions are assigned declaratively in the Developer Console. When you’re working on a component, click Bundle Version Settings
in the right panel to define the version. You can only version a component if you’ve installed a package, and the valid versions for the
component are the available versions of that package. Versions are in the format .. So if you assign a component
version 1.4, its behavior depends on the first major release and fourth minor release of the associated package.

When working with components, you can version:
• Apex controllers
• JavaScript controllers
• JavaScript helpers
• JavaScript renderers
• Bundle markup
– Applications (.app)
– Components (.cmp)
– Interfaces (.intf)
– Events (.evt)

56

Creating Components

Using Expressions

You can’t version any other types of resources in bundles. Unsupported types include:
• Styles (.css)
• Documentation (.doc)
• Design (.design)
• SVG (.svg)
Once you’ve assigned versions to components, or if you’re developing components for a package, you can retrieve the version in several
contexts.
Resource

Return Type

Expression

Apex

Version

System.requestVersion()

JavaScript

String

cmp.getVersion()

Lightning component markup

String

{!Version}

You can use the retrieved version to add logic to your code or markup to assign different functionality to different versions. Here’s an
example of using versioning in an  statement.





...


Using Expressions
Expressions allow you to make calculations and access property values and other data within component markup. Use expressions for
dynamic output or passing values into components by assigning them to attributes.
An expression is any set of literal values, variables, sub-expressions, or operators that can be resolved to a single value. Method calls are
not allowed in expressions.
The expression syntax is: {!expression}
expression is a placeholder for the expression.

Anything inside the {! } delimiters is evaluated and dynamically replaced when the component is rendered or when the value is
used by the component. Whitespace is ignored.
The resulting value can be a primitive, such as an integer, string, or boolean. It can also be a JavaScript object, a component or collection,
a controller method such as an action method, and other useful results.
Note: If you're familiar with other languages, you may be tempted to read the ! as the "bang" operator, which negates boolean
values in many programming languages. In the Lightning Component framework, {! is simply the delimiter used to begin an
expression.
If you're familiar with Visualforce, this syntax will look familiar.

57

Creating Components

Dynamic Output in Expressions

There is a second expression syntax: {#expression}. For more details on the difference between the two forms of expression
syntax, see Data Binding Between Components.
Identifiers in an expression, such as attribute names accessed through the view, controller values, or labels, must start with a letter or
underscore. They can also contain numbers or hyphens after the first character. For example, {!v.2count} is not valid, but
{!v.count} is.
Important: Only use the {! } syntax in markup in .app or .cmp files. In JavaScript, use string syntax to evaluate an expression.
For example:
var theLabel = cmp.get("v.label");

If you want to escape {!, use this syntax:


This renders {! in plain text because the aura:text component never interprets {! as the start of an expression.
IN THIS SECTION:
Dynamic Output in Expressions
The simplest way to use expressions is to output dynamic values.
Conditional Expressions
Here are examples of conditional expressions using the ternary operator and the  tag.
Data Binding Between Components
When you add a component in markup, you can use an expression to initialize attribute values in the component based on attribute
values of the container component. There are two forms of expression syntax, which exhibit different behaviors for data binding
between the components.
Value Providers
Value providers are a way to access data. Value providers encapsulate related values together, similar to how an object encapsulates
properties and methods.
Expression Evaluation
Expressions are evaluated much the same way that expressions in JavaScript or other programming languages are evaluated.
Expression Operators Reference
The expression language supports operators to enable you to create more complex expressions.
Expression Functions Reference
The expression language contains math, string, array, comparison, boolean, and conditional functions. All functions are case-sensitive.

Dynamic Output in Expressions
The simplest way to use expressions is to output dynamic values.
Values used in the expression can be from component attributes, literal values, booleans, and so on. For example:
{!v.desc}

In this expression, v represents the view, which is the set of component attributes, and desc is an attribute of the component. The
expression is simply outputting the desc attribute value for the component that contains this markup.
If you're including literal values in expressions, enclose text values within single quotes, such as {!'Some text'}.

58

Creating Components

Conditional Expressions

Include numbers without quotes, for example, {!123}.
For booleans, use {!true} for true and {!false} for false.
SEE ALSO:
Component Attributes
Value Providers

Conditional Expressions
Here are examples of conditional expressions using the ternary operator and the  tag.

Ternary Operator
This expression uses the ternary operator to conditionally output one of two values dependent on a condition.
Active

The {!v.location == '/active' ? 'selected' : ''} expression conditionally sets the class attribute of an HTML
 tag, by checking whether the location attribute is set to /active. If true, the expression sets class to selected.

Using  for Conditional Markup
This snippet of markup uses the  tag to conditionally display an edit button.




You can’t edit this.



If the edit attribute is set to true, a ui:button displays. Otherwise, the text in the else attribute displays.
SEE ALSO:
Best Practices for Conditional Markup

Data Binding Between Components
When you add a component in markup, you can use an expression to initialize attribute values in the component based on attribute
values of the container component. There are two forms of expression syntax, which exhibit different behaviors for data binding between
the components.
This concept is a little tricky, but it will make more sense when we look at an example. Consider a c:parent component that has a
parentAttr attribute. c:parent contains a c:child component with a childAttr attribute that’s initialized to the value
of the parentAttr attribute. We’re passing the parentAttr attribute value from c:parent into the c:child component,
which results in a data binding, also known as a value binding, between the two components.



59

Creating Components

Data Binding Between Components






{!v.parentAttr} is a bound expression. Any change to the value of the childAttr attribute in c:child also affects the
parentAttr attribute in c:parent and vice versa.

Now, let's change the markup from:


to:


{#v.parentAttr} is an unbound expression. Any change to the value of the childAttr attribute in c:child doesn’t affect
the parentAttr attribute in c:parent and vice versa.

Here’s a summary of the differences between the forms of expression syntax.
{#expression} (Unbound Expressions)

Data updates behave as you would expect in JavaScript. Primitives, such as String, are passed by value, and data updates for the
expression in the parent and child are decoupled.
Objects, such as Array or Map, are passed by reference, so changes to the data in the child propagate to the parent. However,
change handlers in the parent aren’t notified. The same behavior applies for changes in the parent propagating to the child.
{!expression} (Bound Expressions)

Data updates in either component are reflected through bidirectional data binding in both components. Similarly, change handlers
are triggered in both the parent and child components.
Tip: Bi-directional data binding is expensive for performance and it can create hard-to-debug errors due to the propagation
of data changes through nested components. We recommend using the {#expression} syntax instead when you pass
an expression from a parent component to a child component unless you require bi-directional data binding.

Unbound Expressions
Let’s look at another example of a c:parentExpr component that contains another component, c:childExpr.
Here is the markup for c:childExpr.




    childExpr childAttr: {!v.childAttr}
    

    
    

Here is the markup for c:parentExpr.




60

Creating Components

Data Binding Between Components




    parentExpr parentAttr: {!v.parentAttr}
    

    
    

The c:parentExpr component uses an unbound expression to set an attribute in the c:childExpr component.


When we instantiate childExpr, we set the childAttr attribute to the value of the parentAttr attribute in c:parentExpr.
Since the {#v.parentAttr} syntax is used, the v.parentAttr expression is not bound to the value of the childAttr
attribute.
The c:exprApp application is a wrapper around c:parentExpr.





In the Developer Console, click Preview in the sidebar for c:exprApp to view the app in your browser.
Both parentAttr and childAttr are set to “parent attribute”, which is the default value of parentAttr.
Now, let’s create a client-side controller for c:childExpr so that we can dynamically update the component. Here is the source for
childExprController.js.
/* childExprController.js */
({
updateChildAttr: function(cmp) {
cmp.set("v.childAttr", "updated child attribute");
}
})

In the Developer Console, click Update Preview for c:exprApp.
Press the Update childAttr button. This updates childAttr to “updated child attribute”. The value of parentAttr is unchanged
since we used an unbound expression.


Let’s add a client-side controller for c:parentExpr. Here is the source for parentExprController.js.
/* parentExprController.js */
({
updateParentAttr: function(cmp) {
cmp.set("v.parentAttr", "updated parent attribute");
}
})

In the Developer Console, click Update Preview for c:exprApp.
Press the Update parentAttr button. This time, parentAttr is set to “updated parent attribute” while childAttr is unchanged
due to the unbound expression.

61

Creating Components

Data Binding Between Components

Warning: Don’t use a component’s init event and client-side controller to initialize an attribute that is used in an unbound
expression. The attribute will not be initialized. Use a bound expression instead. For more information on a component’s init
event, see Invoking Actions on Component Initialization on page 229.
Alternatively, you can wrap the component in another component. When you instantiate the wrapped component in the wrapper
component, initialize the attribute value instead of initializing the attribute in the wrapped component’s client-side controller.

Bound Expressions
Now, let’s update the code to use a bound expression instead. Change this line in c:parentExpr:


to:


In the Developer Console, click Update Preview for c:exprApp.
Press the Update childAttr button. This updates both childAttr and parentAttr to “updated child attribute” even though
we only set v.childAttr in the client-side controller of childExpr. Both attributes were updated since we used a bound
expression to set the childAttr attribute.

Change Handlers and Data Binding
You can configure a component to automatically invoke a change handler, which is a client-side controller action, when a value in one
of the component's attributes changes.
When you use a bound expression, a change in the attribute in the parent or child component triggers the change handler in both
components. When you use an unbound expression, the change is not propagated between components so the change handler is only
triggered in the component that contains the changed attribute.
Let’s add change handlers to our earlier example to see how they are affected by bound versus unbound expressions.
Here is the updated markup for c:childExpr.





    childExpr childAttr: {!v.childAttr}
    

    
    

Notice the  tag with name="change", which signifies a change handler. value="{!v.childAttr}"
tells the change handler to track the childAttr attribute. When childAttr changes, the onChildAttrChange client-side
controller action is invoked.
Here is the client-side controller for c:childExpr.
/* childExprController.js */
({
updateChildAttr: function(cmp) {

62

Creating Components

Data Binding Between Components

cmp.set("v.childAttr", "updated child attribute");
},
onChildAttrChange: function(cmp, evt) {
console.log("childAttr has changed");
console.log("old value: " + evt.getParam("oldValue"));
console.log("current value: " + evt.getParam("value"));
}
})

Here is the updated markup for c:parentExpr with a change handler.








    parentExpr parentAttr: {!v.parentAttr}
    

    
    

Here is the client-side controller for c:parentExpr.
/* parentExprController.js */
({
updateParentAttr: function(cmp) {
cmp.set("v.parentAttr", "updated parent attribute");
},
onParentAttrChange: function(cmp, evt) {
console.log("parentAttr has changed");
console.log("old value: " + evt.getParam("oldValue"));
console.log("current value: " + evt.getParam("value"));
}
})

In the Developer Console, click Update Preview for c:exprApp.
Open your browser’s console (More tools > Developer tools in Chrome).
Press the Update parentAttr button. The change handlers for c:parentExpr and c:childExpr are both triggered as we’re
using a bound expression.


Change c:parentExpr to use an unbound expression instead.


In the Developer Console, click Update Preview for c:exprApp.

63

Creating Components

Value Providers

Press the Update childAttr button. This time, only the change handler for c:childExpr is triggered as we’re using an unbound
expression.
SEE ALSO:
Detecting Data Changes with Change Handlers
Dynamic Output in Expressions
Component Composition

Value Providers
Value providers are a way to access data. Value providers encapsulate related values together, similar to how an object encapsulates
properties and methods.
The value providers for a component are v (view) and c (controller).
Value Provider

Description

See Also

v

A component’s attribute set. This value provider enables Component Attributes
you to access the value of a component’s attribute in the
component’s markup.

c

A component’s controller, which enables you to wire up Handling Events with Client-Side Controllers
event handlers and actions for the component

All components have a v value provider, but aren't required to have a controller. Both value providers are created automatically when
defined for a component.
Note: Expressions are bound to the specific component that contains them. That component is also known as the attribute value
provider, and is used to resolve any expressions that are passed to attributes of its contained components.

Global Value Providers
Global value providers are global values and methods that a component can use in expressions.
Global Value
Provider

Description

See Also

globalID

The globalId global value provider returns the global Component IDs
ID for a component. Every component has a unique
globalId, which is the generated runtime-unique ID
of the component instance.

$Browser

The $Browser global value provider returns
information about the hardware and operating system
of the browser accessing the application.

$Label

The $Label global value provider enables you to access Using Custom Labels
labels stored outside your code.

64

$Browser

Creating Components

Value Providers

Global Value
Provider

Description

See Also

$Locale

The $Locale global value provider returns information $Locale
about the current user’s preferred locale.

$Resource

The $Resource global value provider lets you
$Resource
reference images, style sheets, and JavaScript code you’ve
uploaded in static resources.

Accessing Fields and Related Objects
Values in a value provider are accessed as named properties. To use a value, separate the value provider and the property name with a
dot (period). For example, v.body. You can access value providers in markup or in JavaScript code.
When an attribute of a component is an object or other structured data (not a primitive value), access the values on that attribute using
the same dot notation.
For example, {!v.accounts.id} accesses the id field in the accounts record.
For deeply nested objects and attributes, continue adding dots to traverse the structure and access the nested values.
SEE ALSO:
Dynamic Output in Expressions

$Browser
The $Browser global value provider returns information about the hardware and operating system of the browser accessing the
application.
Attribute

Description

formFactor

Returns a FormFactor enum value based on the type of hardware the browser is running on.
• DESKTOP for a desktop client
• PHONE for a phone including a mobile phone with a browser and a smartphone
• TABLET for a tablet client (for which isTablet returns true)

isAndroid

Indicates whether the browser is running on an Android device (true) or not (false).

isIOS

Not available in all implementations. Indicates whether the browser is running on an iOS device (true)
or not (false).

isIPad

Not available in all implementations. Indicates whether the browser is running on an iPad (true) or not
(false).

isIPhone

Not available in all implementations. Indicates whether the browser is running on an iPhone (true) or
not (false).

isPhone

Indicates whether the browser is running on a phone including a mobile phone with a browser and a
smartphone (true), or not (false).

65

Creating Components

Value Providers

Attribute

Description

isTablet

Indicates whether the browser is running on an iPad or a tablet with Android 2.2 or later (true) or not
(false).

isWindowsPhone

Indicates whether the browser is running on a Windows phone (true) or not (false). Note that this
only detects Windows phones and does not detect tablets or other touch-enabled Windows 8 devices.

Example: This example shows usage of the $Browser global value provider.

{!$Browser.isTablet}
{!$Browser.isPhone}
{!$Browser.isAndroid}
{!$Browser.formFactor}


Similarly, you can check browser information in a client-side controller using $A.get().
({
checkBrowser: function(component) {
var device = $A.get("$Browser.formFactor");
alert("You are using a " + device);
}
})

$Locale
The $Locale global value provider returns information about the current user’s preferred locale.
These attributes are based on Java’s Calendar, Locale and TimeZone classes.
Attribute

Description

Sample Value

country

The ISO 3166 representation of the country code
based on the language locale.

"US", "DE", "GB"

currency

The currency symbol.

"$"

currencyCode

The ISO 4217 representation of the currency code. "USD"

decimal

The decimal separator.

"."

firstDayOfWeek

The first day of the week, where 1 is Sunday.

1

grouping

The grouping separator.

","

isEasternNameStyle Specifies if a name is based on eastern style, for
example, last name first name
[middle] [suffix].

false

labelForToday

The label for the Today link on the date picker.

“Today”

language

The language code based on the language locale.

"en", "de", "zh"

66

Creating Components

Value Providers

Attribute

Description

Sample Value

langLocale

The locale ID.

“en_US”, “en_GB”

nameOfMonths

The full and short names of the calendar months

{ fullName: “January”, shortName: “Jan” }

nameOfWeekdays

The full and short names of the calendar weeks

{ fullName: “Sunday”, shortName: “SUN” }

timezone

The time zone ID.

"America/Los_Angeles"

userLocaleCountry The country based on the current user’s locale

“US”

userLocaleLang

The language based on the current user’s locale

“en”

variant

The vendor and browser-specific code.

"WIN", "MAC", "POSIX"

Number and Date Formatting
The framework’s number and date formatting are based on Java’s DecimalFormat and DateFormat classes.
Attribute

Description

Sample Value

currencyformat

The currency format.

"¤#,##0.00;(¤#,##0.00)"
¤ represents the currency sign, which is replaced
by the currency symbol.

dateFormat

The date format.

"MMM d, yyyy"

datetimeFormat

The date time format.

"MMM d, yyyy h:mm:ss a"

numberformat

The number format.

"#,##0.###"
# represents a digit, the comma is a placeholder for
the grouping separator, and the period is a
placeholder for the decimal separator. Zero (0)
replaces # to represent trailing zeros.

percentformat

The percentage format.

"#,##0%"

timeFormat

The time format.

"h:mm:ss a"

zero

The character for the zero digit.

“0”

Example: This example shows how to retrieve different $Locale attributes.
Component source

{!$Locale.language}
{!$Locale.timezone}
{!$Locale.numberFormat}
{!$Locale.currencyFormat}


67

Creating Components

Value Providers

Similarly, you can check locale information in a client-side controller using $A.get().
({
checkDevice: function(component) {
var locale = $A.get("$Locale.language");
alert("You are using " + locale);
}
})

SEE ALSO:
Localization

$Resource
The $Resource global value provider lets you reference images, style sheets, and JavaScript code you’ve uploaded in static resources.
Using $Resource lets you reference assets by name, without worrying about the gory details of URLs or file paths. You can use
$Resource in Lightning components markup and within JavaScript controller and helper code.

Using $Resource in Component Markup
To reference a specific resource in component markup, use $Resource.resourceName within an expression. resourceName
is the Name of the static resource. In a managed packaged, the resource name must include the package namespace prefix, such as
$Resource.yourNamespace__resourceName. For a stand-alone static resource, such as an individual graphic or script,
that’s all you need. To reference an item within an archive static resource, add the rest of the path to the item using string concatenation.
Here are a few examples.









Include CSS style sheets or JavaScript libraries into a component using the  tag. For example:




Note: Due to a quirk in the way $Resource is parsed in expressions, use the join operator to include multiple $Resource
references in a single attribute. For example, if you have more than one JavaScript library to include into a component the scripts
attribute should be something like the following.
scripts="{!join(',',
$Resource.jsLibraries + '/jsLibOne.js',
$Resource.jsLibraries + '/jsLibTwo.js')}"

68

Creating Components

Expression Evaluation

Using $Resource in JavaScript
To obtain a reference to a static resource in JavaScript code, use $A.get('$Resource.resourceName').
resourceName is the Name of the static resource. In a managed packaged, the resource name must include the package namespace
prefix, such as $Resource.yourNamespace__resourceName. For a stand-alone static resource, such as an individual graphic

or script, that’s all you need. To reference an item within an archive static resource, add the rest of the path to the item using string
concatenation. For example:
({
profileUrl: function(component) {
var profUrl = $A.get('$Resource.SLDSv2') + '/assets/images/avatar1.jpg';
alert("Profile URL: " + profUrl);
}
})

Note: Static resources referenced in JavaScript aren’t automatically added to packages. If your JavaScript depends on a resource
that isn’t referenced in component markup, add it manually to any packages the JavaScript code is included in.

$Resource Considerations
Global value providers in the Lightning Component framework are, behind the scenes, implemented quite differently from global
variables in Salesforce. Although $Resource looks like the global variable with the same name available in Visualforce, formula fields,
and elsewhere, there are important differences. Don’t use other documentation as a guideline for its use or behavior.
Here are two specific things to keep in mind about $Resource in the Lightning Component framework.
First, $Resource isn’t available until the Lightning Component framework is loaded on the client. Some very simple components
that are composed of only markup can be rendered server-side, where $Resource isn’t available. To avoid this, when you create a
new app, stub out a client-side controller to force components to be rendered on the client.
Second, if you’ve worked with the $Resource global variable, in Visualforce or elsewhere, you’ve also used the URLFOR() formula
function to construct complete URLs to specific resources. There’s nothing similar to URLFOR() in the Lightning Component framework.
Instead, use simple string concatenation, as illustrated in the preceding examples.
SEE ALSO:
Salesforce Help: Static Resources

Expression Evaluation
Expressions are evaluated much the same way that expressions in JavaScript or other programming languages are evaluated.
Operators are a subset of those available in JavaScript, and evaluation order and precedence are generally the same as JavaScript.
Parentheses enable you to ensure a specific evaluation order. What you may find surprising about expressions is how often they are
evaluated. The framework notices when things change, and trigger re-rendering of any components that are affected. Dependencies
are handled automatically. This is one of the fundamental benefits of the framework. It knows when to re-render something on the page.
When a component is re-rendered, any expressions it uses will be re-evaluated.

Action Methods
Expressions are also used to provide action methods for user interface events: onclick, onhover, and any other component
attributes beginning with "on". Some components simplify assigning actions to user interface events using other attributes, such as the
press attribute on .

69

Creating Components

Expression Operators Reference

Action methods must be assigned to attributes using an expression, for example {!c.theAction}. This assigns an Aura.Action,
which is a reference to the controller function that handles the action.
Assigning action methods via expressions allows you to assign them conditionally, based on the state of the application or user interface.
For more information, see Conditional Expressions on page 59.


This button will show "Like It" for items that have not yet been liked, and clicking it will call the likeIt action method. Then the
component will re-render, and the opposite user interface display and method assignment will be in place. Clicking a second time will
unlike the item, and so on.

Expression Operators Reference
The expression language supports operators to enable you to create more complex expressions.

Arithmetic Operators
Expressions based on arithmetic operators result in numerical values.
Operator

Usage

Description

+

1 + 1

Add two numbers.

-

2 - 1

Subtract one number from the other.

*

2 * 2

Multiply two numbers.

/

4 / 2

Divide one number by the other.

%

5 % 2

Return the integer remainder of dividing the first number by the
second.

-

-v.exp

Unary operator. Reverses the sign of the succeeding number. For
example if the value of expenses is 100, then -expenses
is -100.

Numeric Literals
Literal

Usage

Description

Integer

2

Integers are numbers without a decimal point or exponent.

Float

3.14

Numbers with a decimal point, or numbers with an exponent.

-1.1e10

Null

A literal null number. Matches the explicit null value and numbers
with an undefined value.

null

70

Creating Components

Expression Operators Reference

String Operators
Expressions based on string operators result in string values.
Operator

Usage

Description

+

'Title: ' + v.note.title

Concatenates two strings together.

String Literals
String literals must be enclosed in single quotation marks 'like this'.
Literal

Usage

Description

string

'hello world'

Literal strings must be enclosed in single quotation marks. Double quotation marks
are reserved for enclosing attribute values, and must be escaped in strings.

\

'\n'

Whitespace characters:
• \t (tab)
• \n (newline)
• \r (carriage return)
Escaped characters:
• \" (literal ")
• \' (literal ')
• \\ (literal \)

Unicode

'\u####'

A Unicode code point. The # symbols are hexadecimal digits. A Unicode literal
requires four digits.

null

null

A literal null string. Matches the explicit null value and strings with an undefined
value.

Comparison Operators
Expressions based on comparison operators result in a true or false value. For comparison purposes, numbers are treated as the
same type. In all other cases, comparisons check both value and type.
Operator

Alternative

Usage

Description

==

eq

1 == 1

Returns true if the operands are equal. This
comparison is valid for all data types.

1 == 1.0
1 eq 1

Note:
undefined==null
evaluates to true.

71

Warning: Don’t use the == operator for
objects, as opposed to basic types, such as
Integer or String. For example,
object1==object2 evaluates
inconsistently on the client versus the server
and isn’t reliable.

Creating Components

Expression Operators Reference

Operator

Alternative

Usage

Description

!=

ne

1 != 2

Returns true if the operands are not equal. This
comparison is valid for all data types.

1 != true
1 != '1'
null != false
1 ne 2
<

lt

Returns true if the first operand is numerically
less than the second. You must escape the <
operator to < to use it in component markup.
Alternatively, you can use the lt operator.

1 < 2
1 lt 2

>

gt

Returns true if the first operand is numerically
greater than the second.

42 > 2
42 gt 2

<=

le

Returns true if the first operand is numerically
less than or equal to the second. You must escape
the <= operator to <= to use it in component
markup. Alternatively, you can use the le operator.

2 <= 42
2 le 42

>=

ge

Returns true if the first operand is numerically
greater than or equal to the second.

42 >= 42
42 ge 42

Logical Operators
Expressions based on logical operators result in a true or false value.
Operator

Usage

Description

&&

isEnabled &&
hasPermission

Returns true if both operands are individually true. You must escape the && operator to
&& to use it in component markup. Alternatively, you can use the and()
function and pass it two arguments. For example, and(isEnabled, hasPermission).

||

hasPermission
|| isRequired

Returns true if either operand is individually true.

!

!isRequired

Unary operator. Returns true if the operand is false. This operator should not be confused
with the ! delimiter used to start an expression in {!. You can combine the expression
delimiter with this negation operator to return the logical negation of a value, for example,
{!!true} returns false.

Logical Literals
Logical values are never equivalent to non-logical values. That is, only true == true, and only false == false; 1 !=
true, and 0 != false, and null != false.

72

Creating Components

Expression Functions Reference

Literal

Usage

Description

true

true

A boolean true value.

false

false

A boolean false value.

Conditional Operator
There is only one conditional operator, the traditional ternary operator.
Operator

Usage

Description

? :

(1 != 2) ? "Obviously" : "Black
is White"

The operand before the ? operator is evaluated as
a boolean. If true, the second operand is returned. If
false, the third operand is returned.

SEE ALSO:
Expression Functions Reference

Expression Functions Reference
The expression language contains math, string, array, comparison, boolean, and conditional functions. All functions are case-sensitive.

Math Functions
The math functions perform math operations on numbers. They take numerical arguments. The Corresponding Operator column lists
equivalent operators, if any.
Function

Alternative

Usage

Description

Corresponding
Operator

add

concat

add(1,2)

Adds the first argument
to the second.

+

sub

subtract

sub(10,2)

Subtracts the second
argument from the first.

-

mult

multiply

mult(2,10)

Multiplies the first
*
argument by the second.

div

divide

div(4,2)

Divides the first argument /
by the second.

mod

modulus

mod(5,2)

Returns the integer
%
remainder resulting from
dividing the first
argument by the second.

abs(-5)

Returns the absolute
value of the argument:

abs

73

None

Creating Components

Function

Expression Functions Reference

Alternative

Usage

Description

Corresponding
Operator

the same number if the
argument is positive, and
the number without its
negative sign if the
number is negative. For
example, abs(-5) is
5.
neg

negate

neg(100)

Reverses the sign of the
argument. For example,

- (unary)

neg(100) is -100.

String Functions
Function

Alternative

Usage

Description

Corresponding
Operator

concat

add

concat('Hello ',
'world')

Concatenates the two +
arguments.

add('Walk ', 'the dog')
format

format($Label.ns.labelName, Replaces any
parameter
v.myVal)

Note: This function works for
arguments of type String,
Decimal, Double,
Integer, Long, Array,
String[], List, and Set.
join

placeholders with
comma-separated
attribute values.

join(separator, subStr1, Joins the substrings
adding the separator
subStr2, subStrN)
join(' ','class1',
'class2', v.class)

String (first argument)
between each
subsequent argument.

Label Functions
Function

Usage

Description

format

format($Label.np.labelName,
v.attribute1 , v.attribute2)

Outputs a label and updates it.
Replaces any parameter
placeholders with
comma-separated attribute values.

format($Label.np.hello, v.name)

74

Creating Components

Expression Functions Reference

Function

Usage

Description
Supports ternary operators in
labels and attributes.

Informational Functions
Function

Usage

Description

length

myArray.length

Returns the length of an array or a string.

empty

empty(v.attributeName)

Returns true if the argument is empty. An empty
argument is undefined, null, an empty array, or an
empty string. An object with no properties is not considered
empty.

Note: This function works for arguments
of type String, Array, Object,
List, Map, or Set.

Tip: {! !empty(v.myArray)} evaluates
faster than {!v.myArray &&
v.myArray.length > 0} so we recommend
empty() to improve performance.
The $A.util.isEmpty() method in JavaScript is
equivalent to the empty() expression in markup.

Comparison Functions
Comparison functions take two number arguments and return true or false depending on the comparison result. The eq and
ne functions can also take other data types for their arguments, such as strings.
Function

Usage

Description

equals

equals(1,1)

Returns true if the specified arguments == or eq
are equal. The arguments can be any data
type.

notequals

notequals(1,2)

Returns true if the specified arguments != or ne
are not equal. The arguments can be any
data type.

lessthan

lessthan(1,5)

Returns true if the first argument is
numerically less than the second
argument.

< or lt

greaterthan

greaterthan(5,1)

Returns true if the first argument is
numerically greater than the second
argument.

> or gt

lessthanorequal

lessthanorequal(1,2) Returns true if the first argument is

numerically less than or equal to the
second argument.

75

Corresponding
Operator

<= or le

Creating Components

Using Labels

Function

Usage

Description

Corresponding
Operator

greaterthanorequal

greaterthanorequal(2,1) Returns true if the first argument is

>= or ge

numerically greather than or equal to the
second argument.

Boolean Functions
Boolean functions operate on Boolean arguments. They are equivalent to logical operators.
Function

Usage

Description

Corresponding Operator

and

and(isEnabled,
hasPermission)

Returns true if both
arguments are true.

&&

or

or(hasPermission,
hasVIPPass)

Returns true if either one of
the arguments is true.

||

not

not(isNew)

Returns true if the argument !
is false.

Function

Usage

Description

Corresponding Operator

if

if(isEnabled,
'Enabled', 'Not
enabled')

Evaluates the first argument as
a boolean. If true, returns the
second argument. Otherwise,
returns the third argument.

?: (ternary)

Conditional Function

Using Labels
Labels are text that presents information about the user interface, such as in the header (1), input fields (2), or buttons (3). While you can
specify labels by providing text values in component markup, you can also access labels stored outside your code using the $Label
global value provider in expression syntax.

76

Creating Components

Using Custom Labels

This section discusses how to use the $Label global value provider in these contexts:
• The label attribute in input components
• The format() expression function for dynamically populating placeholder values in labels
IN THIS SECTION:
Using Custom Labels
Custom labels are custom text values that can be translated into any language that Salesforce supports. To access custom labels in
Lightning components, use the $Label global value provider.
Input Component Labels
A label describes the purpose of an input component. To set a label on an input component, use the label attribute.
Dynamically Populating Label Parameters
Output and update labels using the format() expression function.
Getting Labels in JavaScript
You can retrieve labels in JavaScript code. Your code performs optimally if the labels are statically defined and sent to the client
when the component is loaded.
Setting Label Values via a Parent Attribute
Setting label values via a parent attribute is useful if you want control over labels in child components.

Using Custom Labels
Custom labels are custom text values that can be translated into any language that Salesforce supports. To access custom labels in
Lightning components, use the $Label global value provider.
Custom labels enable developers to create multilingual applications by automatically presenting information (for example, help text or
error messages) in a user's native language.
To create custom labels, from Setup, enter Custom Labels in the Quick Find box, then select Custom Labels.
Use this syntax to access custom labels in Lightning components:

77

Creating Components

Input Component Labels

• $Label.c.labelName for the default namespace
• $Label.namespace.labelName if your org has a namespace, or to access a label in a managed package
Here are some examples.
Label in a markup expression using the default namespace
{!$Label.c.labelName}

Label in JavaScript code if your org has a namespace
$A.get("$Label.namespace.labelName")

SEE ALSO:
Value Providers

Input Component Labels
A label describes the purpose of an input component. To set a label on an input component, use the label attribute.
This example shows how to use labels using the label attribute on an input component.


The label is placed on the left of the input field and can be hidden by setting labelClass="assistiveText". assistiveText
is a global style class used to support accessibility.

Using $Label
Use the $Label global value provider to access labels stored in an external source. For example:


To output a label and dynamically update it, use the format() expression function. For example, if you have np.labelName set
to Hello {0}, the following expression returns Hello World if v.name is set to World.
{!format($Label.np.labelName, v.name)}

SEE ALSO:
Supporting Accessibility

Dynamically Populating Label Parameters
Output and update labels using the format() expression function.
You can provide a string with placeholders, which are replaced by the substitution values at runtime.
Add as many parameters as you need. The parameters are numbered and are zero-based. For example, if you have three parameters,
they will be named {0}, {1}, and {2}, and they will be substituted in the order they're specified.
Let's look at a custom label, $Label.mySection.myLabel, with a value of Hello {0} and {1}, where $Label is the
global value provider that accesses your labels.
This expression dynamically populates the placeholder parameters with the values of the supplied attributes.
{!format($Label.mySection.myLabel, v.attribute1, v.attribute2)}

78

Creating Components

Getting Labels in JavaScript

The label is automatically refreshed if one of the attribute values changes.
Note: Always use the $Label global value provider to reference a label with placeholder parameters. You can't set a string
with placeholder parameters as the first argument for format(). For example, this syntax doesn't work:
{!format('Hello {0}', v.name)}

Use this expression instead.
{!format($Label.mySection.salutation, v.name)}

where $Label.mySection.salutation is set to Hello {0}.

Getting Labels in JavaScript
You can retrieve labels in JavaScript code. Your code performs optimally if the labels are statically defined and sent to the client when
the component is loaded.

Static Labels
Static labels are defined in one string, such as "$Label.c.task_mode_today". The framework parses static labels in markup
or JavaScript code and sends the labels to the client when the component is loaded. A server trip isn’t required to resolve the label. Use
$A.get() to retrieve static labels in JavaScript code. For example:
var staticLabel = $A.get("$Label.c.task_mode_today");

Dynamic Labels
You can dynamically create labels in JavaScript code. This technique can be useful when you need to use a label that isn’t known until
runtime when it’s dynamically generated.
// Assume the day variable is dynamically generated
// earlier in the code
// THIS CODE WON’T WORK
var dynamicLabel = $A.get("$Label.c." + day);

If the label is already known on the client, $A.get() displays the label. If the value is not known, an empty string is displayed in
production mode, or a placeholder value showing the label key is displayed in debug mode.
Since the label, "$Label.c." + day", is dynamically generated, the framework can’t parse it and send it to the client when the
component is requested. dynamicLabel is an empty string, which isn’t what you want!
There are a few alternative approaches to using $A.get() so that you can work with dynamically generated labels.
If your component uses a known set of dynamically constructed labels, you can avoid a server roundtrip for the labels by adding a
reference to the labels in a JavaScript resource. The framework sends these labels to the client when the component is requested. For
example, if your component dynamically generates $Label.c.task_mode_today and $Label.c.task_mode_tomorrow
label keys, you can add references to the labels in a comment in a JavaScript resource, such as a client-side controller or helper.
// hints to ensure labels are preloaded
// $Label.Related_Lists.task_mode_today
// $Label.Related_Lists.task_mode_tomorrow

If your code dynamically generates many labels, this approach doesn’t scale well.

79

Creating Components

Setting Label Values via a Parent Attribute

If you don’t want to add comment hints for all the potential labels, the alternative is to use $A.getReference(). This approach
comes with the added cost of a server trip to retrieve the label value.
This example dynamically constructs the label value by calling $A.getReference() and updates a tempLabelAttr component
attribute with the retrieved label.
var labelSubStr = "task_mode_today";
var labelReference = $A.getReference("$Label.c." + labelSubStr);
cmp.set("v.tempLabelAttr", labelReference);
var dynamicLabel = cmp.get("v.tempLabelAttr");

$A.getReference() returns a reference to the label. This isn’t a string, and you shouldn’t treat it like one. You never get a string
label directly back from $A.getReference().

Instead, use the returned reference to set a component’s attribute value. Our code does this in cmp.set("v.tempLabelAttr",
labelReference);.
When the label value is asynchronously returned from the server, the attribute value is automatically updated as it’s a reference. The
component is rerendered and the label value displays.
Note: Our code sets dynamicLabel = cmp.get("v.tempLabelAttr") immediately after getting the reference.
This code displays an empty string until the label value is returned from the server. If you don’t want that behavior, use a comment
hint to ensure that the label is sent to the client without requiring a later server trip.
SEE ALSO:
Using JavaScript
Input Component Labels
Dynamically Populating Label Parameters

Setting Label Values via a Parent Attribute
Setting label values via a parent attribute is useful if you want control over labels in child components.
Let’s say that you have a container component, which contains another component, inner.cmp. You want to set a label value in
inner.cmp via an attribute on the container component. This can be done by specifying the attribute type and default value. You
must set a default value in the parent attribute if you are setting a label on an inner component, as shown in the following example.
This is the container component, which contains a default value My Label for the _label attribute .






This inner component contains a text area component and a label attribute that’s set by the container component.





80

Creating Components

Localization

This client-side controller action updates the label value.
({
setLabel:function(cmp) {
cmp.set("v._label", 'new label');
}
})

When the component is initialized, you’ll see a button and a text area with the label My Label. When the button in the container
component is clicked, the setLabel action updates the label value in the inner component. This action finds the label attribute
and sets its value to new label.
SEE ALSO:
Input Component Labels
Component Attributes

Localization
The framework provides client-side localization support on input and output components.
The following example shows how you can override the default langLocale and timezone attributes. The output displays the
time in the format hh:mm by default.
Note: For more information on supported attributes, see the Reference Doc App.
Component source




timezone="Europe/Berlin"

The component renders as Okt. 7, 2015 2:17:08 AM.
Additionally, you can use the global value provider, $Locale, to obtain the locale information. The locale settings in your organization
overrides the browser’s locale information.

Working with Locale Information
In a single currency organization, Salesforce administrators set the currency locale, default language, default locale, and default time
zone for their organizations. Users can set their individual language, locale, and time zone on their personal settings pages.
Note: Single language organizations cannot change their language, although they can change their locale.
For example, setting the time zone on the Language & Time Zone page to (GMT+02:00) returns 28.09.2015 09:00:00
when you run the following code.


Running $A.get("$Locale.timezone") returns the time zone name, for example, Europe/Paris. For more information,
see "Supported Time Zones" in the Salesforce Help.

81

Creating Components

Providing Component Documentation

Setting the currency locale on the Company Information page to Japanese (Japan) - JPY returns ¥100,000 when you
run the following code.


Similarly, running $A.get("$Locale.currency") returns "¥" when your org’s currency locale is set to Japanese
(Japan) - JPY. For more information, see "Supported Currencies" in the Salesforce Help.

Using the Localization Service
The framework’s localization service enables you to manage the localization of date, time, numbers, and currencies. These methods are
available in the AuraLocalizationService JavaScript API.
This example sets the formatted date time using $Locale and the localization service.
var dateFormat = $A.get("$Locale.dateFormat");
var dateString = $A.localizationService.formatDateTime(new Date(), dateFormat);

If you’re not retrieving the browser’s date information, you can specify the date format on your own. This example specifies the date
format and uses the browser’s language locale information.
var dateFormat = "MMMM d, yyyy h:mm a";
var userLocaleLang = $A.get("$Locale.langLocale");
return $A.localizationService.formatDate(date, dateFormat, userLocaleLang);

The AuraLocalizationService JavaScript API provides methods for working with localization. For example, you can compare
two dates to check that one is later than the other.
var startDateTime = new Date();
//return the date time at end of the day
var endDateTime = $A.localizationService.endOf(d, 'day');
if( $A.localizationService.isAfter(startDateTime,endDateTime)) {
//throw an error if startDateTime is after endDateTime
}

Note: For more information on the localization service, see the JavaScript API in the Reference Doc App.

SEE ALSO:
Value Providers

Providing Component Documentation
Component documentation helps others understand and use your components.
You can provide two types of component reference documentation:
• Documentation definition (DocDef): Full documentation on a component, including a description, sample code, and a reference to
an example. DocDef supports extensive HTML markup and is useful for describing what a component is and what it does.
• Inline descriptions: Text-only descriptions, typically one or two sentences, set via the description attribute in a tag.
To provide a DocDef, click DOCUMENTATION in the component sidebar of the Developer Console. The following example shows the
DocDef for np:myComponent.

82

Creating Components

Providing Component Documentation

Note: DocDef is currently supported for components and applications. Events and interfaces support inline descriptions only.



    An np:myComponent component represents an element that executes
an action defined by a controller.
    

    


    This example shows a simple setup of myComponent.
    
    


    This example shows how you can customize myComponent.
    
    
    

A documentation definition contains these tags.
Tag

Description



The top-level definition of the DocDef



Describes the component using extensive HTML markup. To include code samples in the
description, use the 
     tag, which renders as a code block. Code entered in the 
     tag
must be escaped. For example, escape  by entering
<aura:component>.



References an example that demonstrates how the component is used. Supports extensive HTML
markup, which displays as text preceding the visual output and example component source. The
example is displayed as interactive output. Multiple examples are supported and should be wrapped
in individual  tags.
• name: The API name of the example
• ref: The reference to the example component in the format


• label: The label of the title

Providing an Example Component
Recall that the DocDef includes a reference to an example component. The example component is rendered as an interactive demo in
the component reference documentation when it’s wired up using aura:example.


The following is an example component that demonstrates how np:myComponent can be used.




83

Creating Components

Working with Base Lightning Components

This sets the attribute on the np:myComponent
component.




Providing Inline Descriptions
Inline descriptions provide a brief overview of what an element is about. HTML markup is not supported in inline descriptions. These
tags support inline descriptions via the description attribute.
Tag

Example





















Viewing the Documentation
The documentation you create will be available at
https://.lightning.force.com/auradocs/reference.app, where  is the name of

your custom Salesforce domain.
SEE ALSO:
Reference

Working with Base Lightning Components
Base Lightning components are the building blocks that make up the modern Lightning Experience, Salesforce1, and Lightning
Communities user interfaces.
Base Lightning components incorporate Lightning Design System markup and classes, providing improved performance and accessibility
with a minimum footprint.
These base components handle the details of HTML and CSS for you. Each component provides simple attributes that enable variations
in style. This means that you typically don’t need to use CSS at all. The simplicity of the base Lightning component attributes and their
clean and consistent definitions make them easy to use, enabling you to focus on your business logic.
You can find base Lightning components in the lightning namespace to complement the existing ui namespace components.
In instances where there are matching ui and lightning namespace components, we recommend that you use the lightning

84

Creating Components

Working with Base Lightning Components

namespace component. The lightning namespace components are optimized for common use cases. Beyond being equipped
with the Lightning Design System styling, they handle accessibility, real-time interaction, and enhanced error messages.
In subsequent releases, we intend to provide additional base Lightning components. We expect that in time the lightning namespace
will have parity with the ui namespace and go beyond it.
In addition, the base Lightning components will evolve with the Lightning Design System over time. This ensures that your customizations
continue to match Lightning Experience and Salesforce1.
For all the components available, see the component reference at
https://.lightning.force.com/auradocs/reference.app, where  is the name of

your custom Salesforce domain or see the Component Reference section.

Input Control Components
The following components are interactive, for example, like buttons and tabs.
Type

Key Components

Description

Lightning Design System

Button

lightning:button

Represents a button element.

Buttons

Button Icon

lightning:buttonIcon An icon-only HTML button.

Button Icons

Button
Group

lightning:buttonGroup Represents a group of buttons.

Button Groups

Button Menu lightning:buttonMenu A dropdown menu with a list of actions or functions. Menus
lightning:menuItem

A list item in lightning:buttonMenu.

Select

lightning:select

Creates an HTML select element.

Select

Tabs

lightning:tab

A single tab that is nested in a
lightning:tabset component.

Tabs

lightning:tabset

Represents a list of tabs.

Visual Components
The following components provide informative cues, for example, like icons and loading spinners.
Type

Key Components

Description

Avatar

lightning:avatar

A visual representation of a person.

Badge

lightning:badge

A label that holds a small amount of information. Badges

Card

lightning:card

Applies a container around a related grouping of Cards
information.

Icon

lightning:icon

A visual element that provides context.

Layout

lightning:layout

Responsive grid system for arranging containers Grid
on a page.

85

Lightning Design System

Icons

Creating Components

Type

Spinner

Base Lightning Components Considerations

Key Components

Description

Lightning Design System

lightning:layoutItem

A container within a lightning:layout
component.

lightning:spinner

Displays an animated spinner.

Spinners

Field Components
The following components enable you to enter or display values.
Type

Key Components

Description

Lightning Design System

Input

lighting:input

Represents interactive controls that accept Forms
user input depending on the type
attribute.

Internationalization lighting:formattedDateTime Displays formatted date and time.

N/A

lightning:formattedNumber Displays formatted numbers.

Rich Text Area

lightning:inputRichText A WYSIWYG editor with a customizable

Rich Text Editor

toolbar for entering rich text
Text Area

lightning:textArea A multiline text input.

Textarea

Base Lightning Components Considerations
Learn about the guidelines on using the base Lightning components.
We recommend that you don't depend on the markup of a Lightning component as its internals can change in the future. For example,
using cmp.get("v.body") and examining the DOM elements can cause issues in your code if the component markup change
down the road. With LockerService enforced, you can’t traverse the DOM for components you don't own. Instead of accessing the DOM
tree, take advantage of value binding with component attributes and use component methods that are available to you. For example,
to get an attribute on a component, use cmp.find("myInput").get("v.name") instead of
cmp.find("myInput").getElement().name. The latter doesn’t work if you don’t have access to the component, such as
a component in another namespace.
Many of the base Lightning components are still evolving and the following considerations can help you while you’re building your
apps.
lightning:buttonMenu (Beta)
This component contains menu items that are created only if the button is triggered. You can’t reference the menu items during
initialization or if the button isn’t triggered yet.
lightning:formattedDateTime (Beta)
This component provides fallback behavior in Apple Safari 10 and below. The following formatting options have exceptions when
using the fallback behavior in older browsers.
• era is not supported.
• timeZoneName appends GMT for short format, GMT-h:mm or GMT+h:mm for long format.
• timeZone supports UTC. If another timezone value is used, lightning:formattedDateTime uses the browser
timezone.

86

Creating Components

Base Lightning Components Considerations

lightning:formattedNumber (Beta)
This component provides the following fallback behavior in Apple Safari 10 and below.
• If style is set to currency, providing a currencyCode value that’s different from the locale displays the currency code
instead of the symbol. The following example displays EUR12.34 in fallback mode and €12.34 otherwise.


• currencyDisplayAs supports symbol only. The following example displays $12.34 in fallback mode only if the
currencyCode matches the user’s locale currency and USD12.34 otherwise.


lightning:input (Beta)
Date pickers are available in the following components but they don’t inherit the Lightning Design System styling.
• 
• 
Fields for percentage and currency input must specify a step increment of 0.01 as required by the native implementation.



When working with checkboxes, radio buttons, and toggle switches, use aura:id to group and traverse the array of components.
Grouping them enables you to use get("v.checked") to determine which elements are checked or unchecked without
reaching into the DOM. You can also use the name and value attributes to identify each component during the iteration. The
following example groups three checkboxes together using aura:id.


    

    
Select your favorite color:




    



    

In your client-side controller, you can retrieve the array using cmp.find("colors") and inspect the checked values.
When working with type="file", you must provide your own server-side logic for uploading files to Salesforce. Read the file
using the FileReader HTML object, and then encode the file contents before sending them to your Apex controller. In your Apex
controller, you can use the EncodingUtil methods to decode the file data. For example, you can use the Attachment object
to upload files to a parent object. In this case, you pass in the base64 encoded file to the Body field to save the file as an attachment
in your Apex controller.

87

Creating Components

Event Handling in Base Lightning Components

Uploading files using this component is subject to regular Apex controller limits, which is 1 MB. To accommodate file size increase
due to base64 encoding, we recommend that you set the maximum file size to 750 KB. You must implement chunking for file size
larger than 1 MB. Files uploaded via chunking are subject to a size limit of 4 MB. For more information, see the Apex Developer Guide.
lightning:tab (Beta)
This component creates its body during runtime. You can’t reference the component during initialization. Referencing the component
using aura:id can return unexpected results, such as the component returning an undefined value when implementing
cmp.find("myComponent").
lightning:tabset (Beta)
When you load more tabs than can fit the width of the viewport, the tabset provides navigation buttons that scrolls horizontally to
display the overflow tabs.

Event Handling in Base Lightning Components
Base components are lightweight and closely resemble HTML markup. They follow standard HTML practices by providing event handlers
as attributes, such as onfocus, instead of registering and firing Lightning component events, like components in the ui namespace.
Because of their markup, you might expect to access DOM elements via event.target or event.currentTarget. However,
this type of access breaks encapsulation because it provides access to another component’s DOM elements, which are subject to change.
LockerService, which will be enabled for all orgs in Summer ’17, enforces encapsulation. Use the methods described here to make your
code compliant with LockerService.
To retrieve the component that fired the event, use event.getSource().



({
doSomething: function(cmp, event, helper) {
var button = event.getSource();
//The following patterns are not supported
//when you’re trying to access another component’s
//DOM elements.
var el = event.target;
var currentEl = event.currentTarget;
}
})

Retrieve a component attribute that’s passed to the event by using this syntax.
event.getSource().get("v.name")

Reusing Event Handlers
event.getSource() helps you determine which component fired an event. Let’s say you have several buttons that reuse the
same onclick handler. To retrieve the name of the button that fired the event, use event.getSource().get("v.name").




88

Creating Components

Event Handling in Base Lightning Components



({
handleClick: function(cmp, event, helper) {
//returns "new", "edit", or "delete"
var buttonName = event.getSource().get("v.name");
}
})

Retrieving the Active Component Using the onactive Handler
Components, such as lightning:tab and lightning:menuItem, support the onactive handler so that you can obtain
a reference to the target component when it becomes active. Clicking the component multiple times invokes the handler once only.
For example, you can toggle a check mark on a menu item in a lightning:buttonMenu component when it’s clicked.







({
handleActive: function (cmp, event) {
var menuItem = event.getSource();
menuItem.set("v.checked", !menuItem.get("v.checked"));
}
})

Note: If you only need the ID or value of the tab and you don’t need a reference to the target component, use the onselect
event handler.

Retrieving the ID and Value Using the onselect Handler
Some components provide event handlers to pass in events to child components, such as the onselect event handler on the
following components.
• lightning:buttonMenu
• lightning:tabset
Although the event.detail syntax continues to be supported, we recommend that you update your JavaScript code to use the
following patterns for the onselect handler as we plan to deprecate event.detail in a future release.
• event.getParam("id")
• event.getParam("value")

89

Creating Components

Working with UI Components

For example, you want to retrieve the value of a selected menu item in a lightning:buttonMenu component from a client-side
controller.
//Before
var menuItem = event.detail.menuItem;
var itemValue = menuItem.get("v.value");
//After
var itemValue = event.getParam("value");

Similarly, to retrieve the ID of a selected tab in a lightning:tabset component:
//Before
var tab = event.detail.selectedTab;
var tabId = tab.get("v.id");
//After
var tabId = event.getParam("id");

Note: If you need a reference to the target component, use the onactive event handler instead.

Working with UI Components
The framework provides common user interface components in the ui namespace. All of these components extend either
aura:component or a child component of aura:component. aura:component is an abstract component that provides
a default rendering implementation. User interface components such as ui:input and ui:output provide easy handling of
common user interface events like keyboard and mouse interactions. Each component can be styled and extended accordingly.
Note: If you are looking for components that apply the Lightning Design System styling, consider using the base lightning
components instead.
For all the components available, see the component reference at
https://.lightning.force.com/auradocs/reference.app, where  is the name of

your custom Salesforce domain.

Complex, Interactive Components
The following components contain one or more sub-components and are interactive.
Type

Key Components

Description

Message

ui:message

A message notification of varying severity levels

Menu

ui:menu

A drop-down list with a trigger that controls its visibility

ui:menuList

A list of menu items

ui:actionMenuItem

A menu item that triggers an action

ui:checkboxMenuItem

A menu item that supports multiple selection and can be used to
trigger an action

ui:radioMenuItem

A menu item that supports single selection and can be used to
trigger an action

ui:menuItemSeparator

A visual separator for menu items

90

Creating Components

Type

Working with UI Components

Key Components

Description

ui:menuItem

An abstract and extensible component for menu items in a
ui:menuList component

ui:menuTrigger

A trigger that expands and collapses a menu

ui:menuTriggerLink

A link that triggers a dropdown menu. This component extends
ui:menuTrigger

Input Control Components
The following components are interactive, for example, like buttons and checkboxes.
Type

Key Components

Description

Button

ui:button

An actionable button that can be pressed or clicked

Checkbox

ui:inputCheckbox

A selectable option that supports multiple selections

ui:outputCheckbox

Displays a read-only value of the checkbox

Radio button

ui:inputRadio

A selectable option that supports only a single selection

Drop-down List

ui:inputSelect

A drop-down list with options

ui:inputSelectOption

An option in a ui:inputSelect component

Visual Components
The following components provides informative cues, for example, like error messages and loading spinners.
Type

Key Components

Description

Field-level error

ui:inputDefaultError

An error message that is displayed when an error occurs

Spinner

ui:spinner

A loading spinner

Field Components
The following components enables you to enter or display values.
Type

Key Components

Description

Currency

ui:inputCurrency

An input field for entering currency

ui:outputCurrency

Displays currency in a default or specified format

ui:inputEmail

An input field for entering an email address

ui:outputEmail

Displays a clickable email address

ui:inputDate

An input field for entering a date

Email

Date and time

91

Creating Components

Type

Event Handling in UI Components

Key Components

Description

ui:inputDateTime

An input field for entering a date and time

ui:outputDate

Displays a date in the default or specified format

ui:outputDateTime

Displays a date and time in the default or specified format

Password

ui:inputSecret

An input field for entering secret text

Phone Number

ui:inputPhone

An input field for entering a telephone number

ui:outputPhone

Displays a phone number

ui:inputNumber

An input field for entering a numerical value

ui:outputNumber

Displays a number

Range

ui:inputRange

An input field for entering a value within a range

Rich Text

ui:inputRichText

An input field for entering rich text

ui:outputRichText

Displays rich text

ui:inputText

An input field for entering a single line of text

ui:outputText

Displays text

ui:inputTextArea

An input field for entering multiple lines of text

ui:outputTextArea

Displays a read-only text area

ui:inputURL

An input field for entering a URL

ui:outputURL

Displays a clickable URL

Number

Text

Text Area

URL

SEE ALSO:
Using the UI Components
Creating Components
Component Bundles

Event Handling in UI Components
UI components provide easy handling of user interface events such as keyboard and mouse interactions. By listening to these events,
you can also bind values on UI input components using the updateon attribute, such that the values update when those events are
fired.
Capture a UI event by defining its handler on the component. For example, you want to listen to the HTML DOM event, onblur, on a
ui:inputTextArea component.


92

Creating Components

Using the UI Components

The blur="{!c.handleBlur}" listens to the onblur event and wires it to your client-side controller. When you trigger the
event, the following client-side controller handles the event.
handleBlur : function(cmp, event, helper){
var elem = cmp.find("textarea").getElement();
//do something else
}

For all available events on all components, see the Component Reference on page 339.

Value Binding for Browser Events
Any changes to the UI are reflected in the component attribute, and any change in that attribute is propagated to the UI. When you
load the component, the value of the input elements are initialized to those of the component attributes. Any changes to the user input
causes the value of the component variable to be updated. For example, a ui:inputText component can contain a value that’s
bound to a component attribute, and the ui:outputText component is bound to the same component attribute. The
ui:inputText component listens to the onkeyup browser event and updates the corresponding component attribute values.







The next example takes in numerical inputs and returns the sum of those numbers. The ui:inputNumber component listens to
the onkeyup browser event. When the value in this component changes on the keyup event, the value in the ui:outputNumber
component is updated as well, and returns the sum of the two values.







Note: The input fields return a string value and must be properly handled to accommodate numerical values. In this example,
both values are multiplied by 1 to obtain their numerical equivalents.

Using the UI Components
Users interact with your app through input elements to select or enter values. Components such as ui:inputText and
ui:inputCheckbox correspond to common input elements. These components simplify event handling for user interface events.
Note: For all available component attributes and events, see the component reference at
https://.lightning.force.com/auradocs/reference.app, where  is the

name of your custom Salesforce domain .

93

Creating Components

Supporting Accessibility

To use input components in your own custom component, add them to your .cmp or .app resource. This example is a basic set up
of a text field and button. The aura:id attribute defines a unique ID that enables you to reference the component from your JavaScript
code using cmp.find("myID");.




Note: All text fields must specify the label attribute to provide a textual label of the field. If you must hide the label from view,
set labelClass="assistiveText" to make the label available to assistive technologies.
The ui:outputText component acts as a placeholder for the output value of its corresponding ui:inputText component.
The value in the ui:outputText component can be set with the following client-side controller action.
getInput : function(cmp, event) {
var fullName = cmp.find("name").get("v.value");
var outName = cmp.find("nameOutput");
outName.set("v.value", fullName);
}

The following example is similar to the previous, but uses value binding without a client-side controller. The ui:outputText
component reflects the latest value on the ui:inputText component when the onkeyup browser event is fired.







Tip: To create and edit records in Salesforce1, use the force:createRecord and force:recordEdit events to utilize
the built-in record create and edit pages.

Supporting Accessibility
When customizing components, be careful in preserving code that ensures accessibility, such as the aria attributes.
Accessible software and assistive technology enable users with disabilities to use and interact with the products you build. Aura
components are created according to W3C specifications so that they work with common assistive technologies. While we always
recommend that you follow the WCAG Guidelines for accessibility when developing with the Lightning Component framework, this
guide explains the accessibility features that you can leverage when using components in the ui namespace.
IN THIS SECTION:
Button Labels
Audio Messages
Forms, Fields, and Labels
Events
Menus

94

Creating Components

Button Labels

Button Labels
Buttons may be designed to appear with just text, an image and text, or an image without text. To create an accessible button, use
ui:button and set a textual label using the label attribute.


To create an accessible button with Lightning Design System styling, use lightning:button instead.


When using ui:button, assign a non-empty string to label attribute. These examples show how a ui:button should render:





Audio Messages
To convey audio notifications, use the ui:message component, which has role="alert" set on the component by default.
The "alert" aria role will take any text inside the div and read it out loud to screen readers without any additional action by the
user.

This is an error message.


Forms, Fields, and Labels
Input components are designed to make it easy to assign labels to form fields. Labels build a programmatic relationship between a form
field and its textual label. When using a placeholder in an input component, set the label attribute for accessibility.
Use the input components that extend ui:input, except when type="file". For example, use ui:inputTextarea in
preference to the 

    • 

This example retrieves the value of a ui:inputTextArea component and displays it using ui:outputTextArea.





    
You entered: 

    
    

({
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");

429

Reference

ui:inputTextArea

$A.util.removeClass(cmpMsg, 'hide');
var comments = component.find("comments").get("v.value");
var oTextarea = component.find("oTextarea");
oTextarea.set("v.value", comments);
}
})

Attributes
Attribute Name

Attribute Type

Description

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

cols

Integer

The width of the text area, which is defined by the number of characters
to display in a single row at a time. Default value is “20”.

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

errors

List

The list of errors to be displayed.

label

String

The text of the label component

labelClass

String

The CSS class of the label component

maxlength

Integer

The maximum number of characters that can be typed into the input
field. Corresponds to the maxlength attribute of the rendered HTML
textarea element.

placeholder

String

The text that is displayed by default.

readonly

Boolean

Specifies whether the text area should be rendered as read-only. Default
value is “false”.

required

Boolean

Specifies whether the input is required. Default value is "false".

requiredIndicatorClass String

Required?

The CSS class of the required indicator component

resizable

Boolean

Specifies whether or not the textarea should be resizable. Defaults to
true.

rows

Integer

The height of the text area, which is defined by the number of rows to
display at a time. Default value is “2”.

updateOn

String

Updates the component's value binding if the updateOn attribute is set
to the handled event. Default value is "change".

value

String

The value currently in the input field.

430

Reference

ui:inputURL

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

select

COMPONENT

The event fired when the user selects some text.

blur

COMPONENT

The event fired when the user moves off from the component.

focus

COMPONENT

The event fired when the user focuses on the component.

keypress

COMPONENT

The event fired when the user presses or holds down a keyboard key on the
component.

keyup

COMPONENT

The event fired when the user releases a keyboard key on the component.

keydown

COMPONENT

The event fired when the user presses a keyboard key on the component.

cut

COMPONENT

The event fired when the user cuts content to the clipboard.

onError

COMPONENT

The event fired when there are any validation errors on the component.

onClearErrors

COMPONENT

The event fired when any validation errors should be cleared.

change

COMPONENT

The event fired when the user changes the content of the input.

copy

COMPONENT

The event fired when the user copies content to the clipboard.

paste

COMPONENT

The event fired when the user pastes content from the clipboard.

ui:inputURL
An input field for entering a URL.
A ui:inputURL component represents an input field for a URL, which is rendered as an HTML input tag of type url. To render
the output from a ui:inputURL component, use the ui:outputURL component.
This is a basic set up of a ui:inputURL component.


431

Reference

ui:inputURL

This example results in the following HTML.

    



    

This example retrieves the value of a ui:inputURL component and displays it using ui:outputURL.




    
You entered: 

    
    

({
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var url = component.find("url").get("v.value");
var oURL = component.find("oURL");
oURL.set("v.value", url);
oURL.set("v.label", url);
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

errors

List

The list of errors to be displayed.

label

String

The text of the label component

labelClass

String

The CSS class of the label component

432

Reference

ui:inputURL

Attribute Name

Attribute Type

Description

maxlength

Integer

The maximum number of characters that can be typed into the input
field. Corresponds to the maxlength attribute of the rendered HTML input
element.

placeholder

String

Text that is displayed when the field is empty, to prompt the user for a
valid entry.

required

Boolean

Specifies whether the input is required. Default value is "false".

requiredIndicatorClass String

Required?

The CSS class of the required indicator component

size

Integer

The width of the input field, in characters. Corresponds to the size
attribute of the rendered HTML input element.

updateOn

String

Updates the component's value binding if the updateOn attribute is set
to the handled event. Default value is "change".

value

String

The value currently in the input field.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

select

COMPONENT

The event fired when the user selects some text.

blur

COMPONENT

The event fired when the user moves off from the component.

focus

COMPONENT

The event fired when the user focuses on the component.

keypress

COMPONENT

The event fired when the user presses or holds down a keyboard key on the
component.

keyup

COMPONENT

The event fired when the user releases a keyboard key on the component.

keydown

COMPONENT

The event fired when the user presses a keyboard key on the component.

cut

COMPONENT

The event fired when the user cuts content to the clipboard.

onError

COMPONENT

The event fired when there are any validation errors on the component.

433

Reference

ui:menu

Event Name

Event Type

Description

onClearErrors

COMPONENT

The event fired when any validation errors should be cleared.

change

COMPONENT

The event fired when the user changes the content of the input.

copy

COMPONENT

The event fired when the user copies content to the clipboard.

paste

COMPONENT

The event fired when the user pastes content from the clipboard.

ui:menu
A dropdown menu list with a trigger that controls its visibility. To create a clickable link and a list of menu items, use ui:menuTriggerLink
and ui:menuList.
A ui:menu component contains a trigger and list items. You can wire up list items to actions in a client-side controller so that selection
of the item triggers an action. This example shows a menu with list items, which when pressed updates the label on the trigger.










This client-side controller updates the trigger label when a menu item is clicked.
({
updateTriggerLabel: function(cmp, event) {
var triggerCmp = cmp.find("trigger");
if (triggerCmp) {
var source = event.getSource();
var label = source.get("v.label");
triggerCmp.set("v.label", label);
}
}
})

The dropdown menu and its menu items are hidden by default. You can change this by setting the visible attribute on the
ui:menuList component to true. The menu items are shown only when you click the ui:menuTriggerLink component.
To use a trigger, which opens the menu, nest the ui:menuTriggerLink component in ui:menu. For list items, use the
ui:menuList component, and include any of these list item components that can trigger a client-side controller action:
• ui:actionMenuItem - A menu item
• ui:checkboxMenuItem - A checkbox that supports multiple selections
• ui:radioMenuItem - A radio item that supports single selection
To include a separator for these menu items, use ui:menuItemSeparator.

434

Reference

ui:menu

This example shows several ways to create a menu.











    









    

    

    









    

     
    

    

    

    
Combination menu items








435

Reference

ui:menu














    

    
    

({
updateTriggerLabel: function(cmp, event) {
var triggerCmp = cmp.find("trigger");
if (triggerCmp) {
var source = event.getSource();
var label = source.get("v.label");
triggerCmp.set("v.label", label);
}
},
updateLabel: function(cmp, event) {
var triggerCmp = cmp.find("mytrigger");
if (triggerCmp) {
var source = event.getSource();
var label = source.get("v.label");
triggerCmp.set("v.label", label);
}
},
getMenuSelected: function(cmp) {
var menuItems = cmp.find("checkbox");
var values = [];
for (var i = 0; i < menuItems.length; i++) {
var c = menuItems[i];
if (c.get("v.selected") === true) {
values.push(c.get("v.label"));
}
}
var resultCmp = cmp.find("result");
resultCmp.set("v.value", values.join(","));
},
getRadioMenuSelected: function(cmp) {
var menuItems = cmp.find("radio");
var values = [];
for (var i = 0; i < menuItems.length; i++) {
var c = menuItems[i];
if (c.get("v.selected") === true) {
values.push(c.get("v.label"));
}

436

Reference

ui:menuItem

}
var resultCmp = cmp.find("radioResult");
resultCmp.set("v.value", values.join(","));
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:menuItem
A UI menu item in a ui:menuList component.

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

437

Reference

ui:menuItemSeparator

Attribute Name

Attribute Type

Description

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

hideMenuAfterSelected Boolean

Required?

Set to true to hide menu after the menu item is selected.

label

String

The text displayed on the component.

selected

Boolean

The status of the menu item. True means this menu item is selected;
False is not selected.

type

String

The concrete type of the menu item. Accepted values are 'action',
'checkbox', 'radio', 'separator' or any namespaced component descriptor,
e.g. ns:xxxxmenuItem.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

select

COMPONENT

The event fired when the user selects some text.

blur

COMPONENT

The event fired when the user moves off from the component.

focus

COMPONENT

The event fired when the user focuses on the component.

keypress

COMPONENT

The event fired when the user presses or holds down a keyboard key on the
component.

keyup

COMPONENT

The event fired when the user releases a keyboard key on the component.

keydown

COMPONENT

The event fired when the user presses a keyboard key on the component.

ui:menuItemSeparator
A menu separator to divide menu items, such as ui:radioMenuItem, and used in a ui:menuList component.

438

Reference

ui:menuList

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:menuList
A menu component that contains menu items.
This component is nested in a ui:menu component and can be used together with a ui:menuTriggerLink component.
Clicking the menu trigger displays the container with menu items.





to display menu items"/>
click="{!c.doSomething}"/>
click="{!c.doSomething}"/>
click="{!c.doSomething}"/>
click="{!c.doSomething}"/>

ui:menuList can contain these components, which runs a client-side controller when clicked:

• ui:actionMenuItem
• ui:checkboxMenuItem
• ui:radioMenuItem
• ui:menuItemSeparator

439

Reference

ui:menuList

See ui:menu for more information.

Attributes
Attribute Name

Attribute Type

Description

autoPosition

Boolean

Move the popup target up when there is not enough space at the bottom
to display. Note: even if autoPosition is set to false, popup will still position
the menu relative to the trigger. To override default positioning, use
manualPosition attribute.

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

closeOnClickOutside Boolean

Required?

Close target when user clicks or taps outside of the target

closeOnTabKey

Boolean

Indicates whether to close the target list on tab key or not.

curtain

Boolean

Whether or not to apply an overlay under the target.

menuItems

List

A list of menu items set explicitly using instances of the Java class: aura.
components.ui.MenuItem.

visible

Boolean

Controls the visibility of the menu. The default is false, which hides the
menu.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

menuExpand

COMPONENT

The event fired when the menu list displays.

menuSelect

COMPONENT

The event fired when the user select a menu item.

menuCollapse

COMPONENT

The event fired when the menu list collapses.

440

Reference

ui:menuTrigger

Event Name

Event Type

Description

menuFocusChange

COMPONENT

The event fired when the menu list focus changed from one menuItem to another
menuItem.

ui:menuTrigger
A clickable link that expands and collapses a menu. To create a link for ui:menu, use ui:menuTriggerLink instead.

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

label

String

The text displayed on the component.

title

String

The text to display as a tooltip when the mouse pointer hovers over this
component.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

select

COMPONENT

The event fired when the user selects some text.

blur

COMPONENT

The event fired when the user moves off from the component.

focus

COMPONENT

The event fired when the user focuses on the component.

441

Reference

ui:menuTriggerLink

Event Name

Event Type

Description

keypress

COMPONENT

The event fired when the user presses or holds down a keyboard key on the
component.

keyup

COMPONENT

The event fired when the user releases a keyboard key on the component.

keydown

COMPONENT

The event fired when the user presses a keyboard key on the component.

menuTriggerPress COMPONENT

The event that is fired when the trigger is clicked.

ui:menuTriggerLink
A link that triggers a dropdown menu used in ui:menu

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

label

String

The text displayed on the component.

title

String

The text to display as a tooltip when the mouse pointer hovers over this
component.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

select

COMPONENT

The event fired when the user selects some text.

442

Reference

ui:message

Event Name

Event Type

Description

blur

COMPONENT

The event fired when the user moves off from the trigger.

focus

COMPONENT

The event fired when the user focuses on the trigger.

keypress

COMPONENT

The event fired when the user presses or holds down a keyboard key on the
component.

keyup

COMPONENT

The event fired when the user releases a keyboard key on the component.

keydown

COMPONENT

The event fired when the user presses a keyboard key on the component.

menuTriggerPress COMPONENT

The event that is fired when the trigger is clicked.

ui:message
Represents a message of varying severity levels
The severity attribute indicates a message's severity level and determines the style to use when displaying the message. If the
closable attribute is set to true, the message can be dismissed by pressing the × symbol.
This example shows a confirmation message that can be dismissed.

This is a confirmation message.


This example shows messages in varying severity levels.


This is a confirmation message.


This is a message.


This is a warning.


This is an error message.



Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

443

Reference

ui:outputCheckbox

Attribute Name

Attribute Type

Description

Required?

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

closable

Boolean

Specifies whether to display an 'x' that will close the alert when clicked.
Default value is 'false'.

severity

String

The severity of the message. Possible values: message (default), confirm,
info, warning, error

title

String

The title text for the message.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputCheckbox
Displays a checkbox in a checked or unchecked state.
A ui:outputCheckbox component represents a checkbox that is rendered as an HTML img tag. This component can be used
with ui:inputCheckbox, which enables users to select or deselect the checkbox. To select or deselect the checkbox, set the
value attribute to true or false. To display a checkbox, you can use an attribute value and bind it to the ui:outputCheckbox
component.



The previous example renders the following HTML.
checkbox checked

This example shows how you can use the ui:inputCheckbox component.




444

Reference

ui:outputCheckbox


    Selected:
    

    

    The following checkbox uses a component attribute to bind its value.
    

    

({
onCheck: function(cmp, evt) {
var checkCmp = cmp.find("checkbox");
resultCmp = cmp.find("checkResult");
resultCmp.set("v.value", ""+checkCmp.get("v.value"));
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

altChecked

String

The alternate text description when the checkbox is checked. Default
value is “True”.

altUnchecked

String

The alternate text description when the checkbox is unchecked. Default
value is “False”.

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

value

Boolean

Specifies whether the checkbox is checked.

Yes

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

445

Reference

ui:outputCurrency

ui:outputCurrency
Displays the currency in the default or specified format, such as with specific currency code or decimal places.
A ui:outputCurrency component represents a number as a currency that is wrapped in an HTML span tag. This component
can be used with ui:inputCurrency, which takes in a number as a currency. To display a currency, you can use an attribute value
and bind it to the ui:outputCurrency component.



The previous example renders the following HTML.
$50,000.00

To override the browser's locale, use the currencySymbol attribute.


You can also override it by specifying the format.
var curr = cmp.find("curr");
curr.set("v.format", '£#,###.00');

This example shows how you can bind data from a ui:inputCurrency component.



You entered: 


Attributes
Attribute Name

Attribute Type

Description

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

currencyCode

String

The ISO 4217 currency code specified as a String, e.g. “USD”.

currencySymbol String

Required?

The currency symbol specified as a String.

format

String

The format of the number. For example, format=“.00” displays the number
followed by two decimal places. If not specified, the default format based
on the browser's locale will be used.

value

Decimal

The output value of the currency, which is defined as type Decimal.

446

Yes

Reference

ui:outputDate

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputDate
Displays a date in the default or specified format based on the user's locale.
A ui:outputDate component represents a date output in the YYYY-MM-DD format and is wrapped in an HTML span tag. This
component can be used with ui:inputDate, which takes in a date input. ui:outputDate retrieves the browser's locale
information and displays the date accordingly. To display a date, you can use an attribute value and bind it to the ui:outputDate
component.



The previous example renders the following HTML.
Sep 29, 2014

This example shows how you can bind data from the ui:inputDate component.






    
You entered: 

    
    

({
doInit : function(component, event, helper) {
var today = new Date();

447

Reference

ui:outputDate

component.set('v.today', today.getFullYear() + "-" + (today.getMonth() + 1) + "-"
+ today.getDate());
},
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var expdate = component.find("expdate").get("v.value");
var oDate = component.find("oDate");
oDate.set("v.value", expdate);
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

format

String

A string (pattern letters are defined in java.text.SimpleDateFormat) used
to format the date and time of the value attribute.

langLocale

String

The language locale used to format date value.

value

String

The output value of the date. It should be a date string in ISO-8601 format Yes
(YYYY-MM-DD).

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

448

Reference

ui:outputDateTime

ui:outputDateTime
Displays a date, time in a specified or default format based on the user's locale.
A ui:outputDateTime component represents a date and time output that is wrapped in an HTML span tag. This component
can be used with ui:inputDateTime, which takes in a date input. ui:outputDateTime retrieves the browser's locale
information and displays the date accordingly. To display a date and time, you can use an attribute value and bind it to the
ui:outputDateTime component.



The previous example renders the following HTML.
Sep 29, 2014 12:17:08 AM

This example shows how you can bind data from a ui:inputDateTime component.






    
You entered: 


/>

({
doInit : function(component, event, helper) {
var today = new Date();
component.set('v.today', today.getFullYear() + "-" + (today.getMonth() + 1) + "-"
+ today.getDate());
},
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var todayVal = component.find("today").get("v.value");
var oDateTime = component.find("oDateTime");
oDateTime.set("v.value", todayVal);
}
})

449

Reference

ui:outputEmail

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

format

String

A string (pattern letters are defined in java.text.SimpleDateFormat) used
to format the date and time of the value attribute.

langLocale

String

The language locale used to format date value.

timezone

String

The timezone ID, for example, America/Los_Angeles.

value

String

An ISO8601-formatted string representing a date time.

Yes

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputEmail
Displays an email address in an HTML anchor () element. The leading and trailing space are trimmed.
A ui:outputEmail component represents an email output that is wrapped in an HTML span tag. This component can be used
with ui:inputEmail, which takes in an email input. The email output is wrapped in an HTML anchor element and mailto is
automatically appended to it. This is a simple set up of a ui:outputEmail component.


The previous example renders the following HTML.
abc@email.com

450

Reference

ui:outputEmail

This example shows how you can bind data from a ui:inputEmail component.




    
You entered: 

    
    

({
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var email = component.find("email").get("v.value");
var oEmail = component.find("oEmail");
oEmail.set("v.value", email);
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

value

String

The output value of the email

Yes

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

451

Reference

ui:outputNumber

Event Name

Event Type

Description

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputNumber
Displays the number in the default or specified format. Supports up to 18 digits before the decimal place.
A ui:outputNumber component represents a number output that is rendered as an HTML span tag. This component can be
used with ui:inputNumber, which takes in a number input. ui:outputNumber retrieves the locale information and displays
the number in the given decimal format. To display a number, you can use an attribute value and bind it to the ui:outputNumber
component.



The previous example renders the following HTML.
10.10

This example retrieves the value of a ui:intputNumber component, validates the input, and displays it using ui:outputNumber.


 
    

    

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

format

String

The format of the number. For example, format=“.00” displays the number
followed by two decimal places. If not specified, the Locale default format
will be used.

value

Decimal

The number displayed when this component is rendered.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

452

Yes

Reference

ui:outputPhone

Event Name

Event Type

Description

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputPhone
Displays the phone number in a URL link format.
A ui:outputPhone component represents a phone number output that is wrapped in an HTML span tag. This component can
be used with ui:inputPhone, which takes in a phone number input. The following example is a simple set up of a
ui:outputPhone component.


The previous example renders the following HTML.
415-123-4567

When viewed on a mobile device, the example renders as an actionable link.

415-123-4567


This example shows how you can bind data from a ui:inputPhone component.




    
You entered: 

    
    

({
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var phone = component.find("phone").get("v.value");

453

Reference

ui:outputRichText

var oPhone = component.find("oPhone");
oPhone.set("v.value", phone);
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

value

String

The phone number displayed when this component is rendered.

Yes

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputRichText
Displays richly-formatted text including tags such as paragraph, image, and hyperlink, as specified in the value attribute.
A ui:outputRichText component represents rich text and can be used to display input from a ui:inputRichText
component. This component displays URLs and email addresses within rich text fields as hyperlinks.
For example, you can enter bold or colored text via a ui:inputRichText component and bind its value to a
ui:outputRichText component, which results in the following HTML.

    
Aura, input rich text demo

    

This component supports the following HTML tags: a, b, br, big, blockquote, caption, cite, code, col, colgroup,
del, div, em, h1, h2, h3, hr, i, img, ins, kbd, li, ol, p, param, pre, q, s, samp, small, span, strong, sub, sup,
table, tbody, td, tfoot, th, thead, tr, tt, u, ul, var, strike.

454

Reference

ui:outputText

Supported HTML attributes include: accept, action, align, alt, autocomplete, background, bgcolor, border,
cellpadding, cellspacing, checked, cite, class, clear, color, cols, colspan, coords, datetime,
default, dir, disabled, download, enctype, face, for, headers, height, hidden, high, href, hreflang,
id, ismap, label, lang, list, loop, low, max, maxlength, media, method, min, multiple, name, noshade,
novalidate, nowrap, open, optimum, pattern, placeholder, poster, preload, pubdate, radiogroup,
readonly, rel, required, rev, reversed, rows, rowspan, spellcheck, scope, selected, shape, size,
span, srclang, start, src, step, style, summary, tabindex, target, title, type, usemap, valign, value,
width, xmlns.

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

linkify

Boolean

Indicates if the URLs in the text are set to render as hyperlinks.

value

String

The richly-formatted text used for output.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputText
Displays text as specified by the value attribute.
A ui:outputText component represents text output that is wrapped in an HTML span tag. This component can be used with
ui:inputText, which takes in a text input. To display text, you can use an attribute value and bind it to the ui:outputText
component.



455

Reference

ui:outputTextArea

The previous example renders the following HTML.

some string


This example shows how you can bind data from an ui:inputText component.



You entered: 


Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

title

String

Displays extra information as hover text.

value

String

The text displayed when this component is rendered.

Yes

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputTextArea
Displays the text area as specified by the value attribute.

456

Reference

ui:outputTextArea

A ui:outputTextArea component represents text output that is wrapped in an HTML span tag. This component can be used
with ui:inputTextArea, which takes in a multiline text input. To display text, you can use an attribute value and bind it to the
ui:outputTextArea component. A ui:outputTextArea component displays URLs and email addresses as hyperlinks.



The previous example renders the following HTML.
some string

This example shows how you can bind data from the ui:inputTextArea component.





    
You entered: 

    
    

({
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var comments = component.find("comments").get("v.value");
var oTextarea = component.find("oTextarea");
oTextarea.set("v.value", comments);
}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

linkify

Boolean

Indicates if the URLs in the text are set to render as hyperlinks.

value

String

The text to display.

457

Yes

Reference

ui:outputURL

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:outputURL
Displays a link to a URL as specified by the value attribute, rendered on a given text (label attribute) and image, if any.
A ui:outputURL component represents a URL that is wrapped in an HTML a tag. This component can be used with ui:inputURL,
which takes in a URL input. To display a URL, you can use an attribute value and bind it to the ui:outputURL component.



The previous example renders the following HTML.
http://www.google.com

This example shows how you can bind data from a ui:inputURL component.




    
You entered: 

    
    

({
setOutput : function(component, event, helper) {
var cmpMsg = component.find("msg");
$A.util.removeClass(cmpMsg, 'hide');
var url = component.find("url").get("v.value");
var oURL = component.find("oURL");
oURL.set("v.value", url);
oURL.set("v.label", url);

458

Reference

ui:radioMenuItem

}
})

Attributes
Attribute Name

Attribute Type

Description

Required?

alt

String

The alternate text description for image (used when there is no label)

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

iconClass

String

The CSS style used to display the icon or image.

label

String

The text displayed on the component.

target

String

The target destination where this rendered component is displayed.
Possible values: _blank, _parent, _self, _top

title

String

The text to display as a tooltip when the mouse pointer hovers over this
component.

value

String

The text displayed when this component is rendered.

Yes

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

ui:radioMenuItem
A menu item with a radio button that indicates a mutually exclusive selection and can be used to invoke an action. This component is
nested in a ui:menu component.

459

Reference

ui:radioMenuItem

A ui:radioMenuItem component represents a menu list item for single selection. Use aura:iteration to iterate over a list
of values and display the menu items. A ui:menuTriggerLink component displays and hides your menu items.










Attributes
Attribute Name

Attribute Type

Description

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

disabled

Boolean

Specifies whether the component should be displayed in a disabled state.
Default value is "false".

hideMenuAfterSelected Boolean

Required?

Set to true to hide menu after the menu item is selected.

label

String

The text displayed on the component.

selected

Boolean

The status of the menu item. True means this menu item is selected;
False is not selected.

type

String

The concrete type of the menu item. Accepted values are 'action',
'checkbox', 'radio', 'separator' or any namespaced component descriptor,
e.g. ns:xxxxmenuItem.

Events
Event Name

Event Type

Description

dblclick

COMPONENT

The event fired when the user double-clicks the component.

mouseover

COMPONENT

The event fired when the user moves the mouse pointer over the component.

mouseout

COMPONENT

The event fired when the user moves the mouse pointer away from the
component.

mouseup

COMPONENT

The event fired when the user releases the mouse button over the component.

mousemove

COMPONENT

The event fired when the user moves the mouse pointer over the component.

click

COMPONENT

The event fired when the user clicks on the component.

460

Reference

ui:scrollerWrapper

Event Name

Event Type

Description

mousedown

COMPONENT

The event fired when the user clicks a mouse button over the component.

select

COMPONENT

The event fired when the user selects some text.

blur

COMPONENT

The event fired when the user moves off from the component.

focus

COMPONENT

The event fired when the user focuses on the component.

keypress

COMPONENT

The event fired when the user presses or holds down a keyboard key on the
component.

keyup

COMPONENT

The event fired when the user releases a keyboard key on the component.

keydown

COMPONENT

The event fired when the user presses a keyboard key on the component.

ui:scrollerWrapper
Creates a container that enables native scrolling in Salesforce1.
A ui:scrollerWrapper creates a container that enables native scrolling in Salesforce1. This component enables you to nest
more than one scroller inside the container. Use the class attribute to define the height and width of the container. To enable scrolling,
specify a height that's smaller than its content.
This example creates a scrollable area with a height of 300px.





/** CSS **/
.THIS.scrollerSize {
height: 300px;
}

The Lightning Design System scrollable class isn't compatible with native scrolling on mobile devices. Use
ui:scrollerWrapper if you want to enable scrolling in Salesforce1.
Usage Considerations
In Google Chrome on mobile devices, nested ui:scrollerWrapper components are not scrollable when the border-radius
CSS property is set to a non-zero value. To enable scrolling in this case, set border-radius to a non-zero value on the outer
ui:scrollerWrapper component.
Here is an example.









461

Reference

ui:spinner


/** CSS **/
.THIS.outerScroller {
/* fix scrolling in innerScroller */
border-radius: 1px;
}
.THIS.innerScroller {
/* make innerScroller rounded */
border-radius: 10px;
}

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS class applied to the outer element. This style is in addition to base
classes output by the component.

ui:spinner
A loading spinner to be used while the real component body is being loaded
To toggle the spinner, use get("e.toggle"), set the isVisible parameter to true or false, and then fire the event.
This example shows a spinner that can be toggled.





({
toggleSpinner: function(cmp) {
var spinner = cmp.find('spinner');
var evt = spinner.get("e.toggle");
if(!$A.util.hasClass(spinner, 'hideEl')){
evt.setParams({ isVisible : false });
}
else {
evt.setParams({ isVisible : true });
}
evt.fire();
}
})

462

Reference

Interface Reference

Attributes
Attribute Name

Attribute Type

Description

Required?

body

Component[]

The body of the component. In markup, this is everything in the body of
the tag.

class

String

A CSS style to be attached to the component. This style is added in
addition to base styles output by the component.

isVisible

Boolean

Specifies whether or not this spinner should be visible. Defaults to true.

Events
Event Name

Event Type

Description

toggle

COMPONENT

The event fired when the spinner is toggled.

Interface Reference
Implement these platform interfaces to allow a component to be used in different contexts, or to enable your component to receive
extra context data. A component can implement multiple interfaces. Some interfaces are intended to be implemented together, while
others are mutually exclusive. Some interfaces have an effect only in Lightning Experience and Salesforce1.
clients:hasEventContext

Enables a component to be assigned to an event’s date or location attributes in Lightning for Outlook and Lightning for Gmail. For
more information, see Create Components for Lightning for Outlook and Lightning for Gmail (Beta).
clients:hasItemContext

Enables a component to be assigned to an email’s or a calendar event’s item attributes in Lightning for Outlook and Lightning for
Gmail. For more information, see Create Components for Lightning for Outlook and Lightning for Gmail (Beta).
flexipage:availableForAllPageTypes

To appear in the Lightning App Builder or a Lightning Page, a component must implement the
flexipage:availableForAllPageTypes interface. For more information, see Configure Components for Lightning
Pages and the Lightning App Builder.
flexipage:availableForRecordHome

If your component is designed just for record pages, implement the flexipage:availableForRecordHome interface
instead of flexipage:availableForAllPageTypes. For more information, see Configure Components for Lightning
Experience Record Pages.
forceCommunity:availableForAllPageTypes

To appear in Community Builder, a component must implement the forceCommunity:availableForAllPageTypes
interface. For more information, see Configure Components for Communities.
force:appHostable

Allows a component to be used as a custom tab in Lightning Experience or Salesforce1. For more information, see Add Lightning
Components as Custom Tabs in Lightning Experience.

463

Reference

Event Reference

force:hasRecordId

Enables a component to be assigned the ID of the currently displaying record. Useful for components invoked in a context associated
with a specific record, such as record page components or custom object actions. This interface has no effect except when used
within Lightning Experience, Salesforce1, and template-based communities. For more information, see Configure Components for
Lightning Experience Record Pages.
force:hasSObjectName

Enables a component to access the API name of the object of the currently displaying record. Useful for record page components.
This interface has no effect except when used within Lightning Experience, Salesforce1, and template-based communities. For more
information, see Configure Components for Lightning Experience Record Pages.
force:lightningQuickAction

Allows a component to display in a panel with standard action controls, such as a Cancel button. These components can also display
and implement their own controls, but should handle events from the standard controls. If you implement
force:lightningQuickAction, you can’t implement force:lightningQuickActionWithoutHeader within
the same component. For more information, see Configure Components for Custom Actions.
force:lightningQuickActionWithoutHeader

Allows a component to display in a panel without additional controls. The component should provide a complete user interface for
the action. If you implement force:lightningQuickActionWithoutHeader, you can’t implement
force:lightningQuickAction within the same component. For more information, see Configure Components for Custom
Actions.
ltng:allowGuestAccess
Add the ltng:allowGuestAccess interface to your Lightning Out dependency app to make it available to users without

requiring them to authenticate with Salesforce. This interface lets you build your app with Lightning components, and deploy it
anywhere and to anyone. For more information, see Share Lightning Out Apps with Non-Authenticated Users.

Event Reference
Use out-of-the-box events to enable component interaction within Lightning Experience or Salesforce1, or within your Lightning
components. For example, these events enable your components to open a record create or edit page, or navigate to a record.
If you fire one of these events in your Lightning apps or components outside of Salesforce1 or Lightning Experience:
• You must handle the event by using the  tag in the handling component.
• Use the  or  tags to ensure that the event is sent to the client, when
needed.
SEE ALSO:
aura:dependency
Fire Component Events
Fire Application Events

force:closeQuickAction
Closes a quick action panel. Only one quick action panel can be open in the app at a time.
To close a quick action panel, usually in response to completing or canceling the action, run
$A.get("e.force:closeQuickAction").fire();.

464

Reference

force:createRecord

This example closes the quick action panel after processing the input from the panel’s user interface and displaying a “toast” message
with the processing results. While the processing and the toast are unrelated to closing the quick action, the sequence is important.
Firing force:closeQuickAction should be the last thing your quick action handler does.
/*quickAddController.js*/
({
clickAdd: function(component, event, helper) {
// Get the values from the form
var n1 = component.find("num1").get("v.value");
var n2 = component.find("num2").get("v.value");
// Display the total in a "toast" status message
var resultsToast = $A.get("e.force:showToast");
resultsToast.setParams({
"title": "Quick Add: " + n1 + " + " + n2,
"message": "The total is: " + (n1 + n2) + "."
});
resultsToast.fire();
// Close the action panel
var dismissActionPanel = $A.get("e.force:closeQuickAction");
dismissActionPanel.fire();
}
})

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.

force:createRecord
Opens a page to create a record for the specified entityApiName, for example, “Account” or “myNamespace__MyObject__c”.
To display the record create page for an object, set the object name on the entityApiName parameter and fire the event.
recordTypeId is optional and, if provided, specifies the record type for the created object. This example displays the record create
panel for contacts.
createRecord : function (component, event, helper) {
var createRecordEvent = $A.get("e.force:createRecord");
createRecordEvent.setParams({
"entityApiName": "Contact"
});
createRecordEvent.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only. This event
presents a standard page to create a record. That is, it doesn’t respect overrides on the object’s create action.
Attribute Name

Type

Description

entityApiName

String

Required. The API name of the custom or standard object, such as “Account”, “Case”,
“Contact”, “Lead”, “Opportunity”, or “namespace__objectName__c”.

recordTypeId

String

The ID of the record type, if record types are available for the object.

465

Reference

force:editRecord

force:editRecord
Opens the page to edit the record specified by recordId.
To display the record edit page for an object, set the object name on the recordId attribute and fire the event. This example displays
the record edit page for a contact that’s specified by recordId.
editRecord : function(component, event, helper) {
var editRecordEvent = $A.get("e.force:editRecord");
editRecordEvent.setParams({
"recordId": component.get("v.contact.Id")
});
editRecordEvent.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

recordId

String

Required. The record ID associated with the record to be edited.

force:navigateToComponent (Beta)
Navigates from a Lightning component to another.
Note: This release contains a beta version of force:navigateToComponent with known limitations.
To navigate from a Lightning component to another, specify the component name using componentDef. This example navigates
to a component c:myComponent and sets a value on the contactName attribute.
navigateToMyComponent : function(component, event, helper) {
var evt = $A.get("e.force:navigateToComponent");
evt.setParams({
componentDef : "c:myComponent",
componentAttributes: {
contactName : component.get("v.contact.Name")
}
});
evt.fire();
}

You can navigate only to a component that’s marked access="global" or a component within the current namespace.
Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

componentDef

String

The component to navigate to, for example, c:myComponent

componentAttributes Object
isredirect

Boolean

The attributes for the component
Specifies whether the navigation is a redirect. If true, the browser replaces the current
URL with the new one in the navigation history. This value defaults to false.

466

Reference

force:navigateToList

force:navigateToList
Navigates to the list view specified by listViewId.
To navigate to a list view, set the list view ID on the listViewId attribute and fire the event. This example displays the list views for
contacts.
gotoList : function (component, event, helper) {
var action = component.get("c.getListViews");
action.setCallback(this, function(response){
var state = response.getState();
if (state === "SUCCESS") {
var listviews = response.getReturnValue();
var navEvent = $A.get("e.force:navigateToList");
navEvent.setParams({
"listViewId": listviews.Id,
"listViewName": null,
"scope": "Contact"
});
navEvent.fire();
}
});
$A.enqueueAction(action);
}

This Apex controller returns all list views for the contact object.
@AuraEnabled
public static List getListViews() {
List listviews =
[SELECT Id, Name FROM ListView WHERE SobjectType = 'Contact'];
// Perform isAccessible() check here
return listviews;
}

You can also provide a single list view ID by providing the list view name you want to navigate to in the SOQL query.
SELECT Id, Name FROM ListView WHERE SobjectType = 'Contact' and Name='All Contacts'

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

listViewId

String

Required. The ID of the list view to be displayed.

listViewName

String

Specifies the name for the list view and doesn’t need to match the actual name. To use
the actual name that’s saved for the list view, set listViewName to null.

scope

String

The name of the sObject in the view, for example, “Account” or
“namespace__MyObject__c”.

SEE ALSO:
CRUD and Field-Level Security (FLS)

467

Reference

force:navigateToObjectHome

force:navigateToObjectHome
Navigates to the object home specified by the scope attribute.
To navigate to an object home, set the object name on the scope attribute and fire the event. This example displays the home page
for a custom object.
navHome : function (component, event, helper) {
var homeEvent = $A.get("e.force:navigateToObjectHome");
homeEvent.setParams({
"scope": "myNamespace__myObject__c"
});
homeEvent.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

scope

String

Required. The API name of the custom or standard object, such as “Contact”, or
“namespace__objectName__c”.

resetHistory

Boolean

Resets history if set to true. Defaults to false, which provides a Back button in Salesforce1.

force:navigateToRelatedList
Navigates to the related list specified by parentRecordId.
To navigate to a related list, set the parent record ID on the parentRecordId attribute and fire the event. For example, to display
a related list for a Contact object, the parentRecordId is Contact.Id. This example displays the related cases for a contact
record.
gotoRelatedList : function (component, event, helper) {
var relatedListEvent = $A.get("e.force:navigateToRelatedList");
relatedListEvent.setParams({
"relatedListId": "Cases",
"parentRecordId": component.get("v.contact.Id")
});
relatedListEvent.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

parentRecordId

String

Required. The ID of the parent record.

relatedListId

String

Required. The API name of the related list to display, such as “Contacts” or “Opportunities”.

force:navigateToSObject
Navigates to an sObject record specified by recordId.

468

Reference

force:navigateToURL

To display the record view, set the record ID on the recordId attribute and fire the event.
The record view contains slides that displays the Chatter feed, the record details, and related information. This example displays the
related information slide of a record view for the specified record ID.
Note: You can set a specific slide in Salesforce1, but not in Lightning Experience.
createRecord : function (component, event, helper) {
var navEvt = $A.get("e.force:navigateToSObject");
navEvt.setParams({
"recordId": "00QB0000000ybNX",
"slideDevName": "related"
});
navEvt.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

recordId

String

Required. The record ID.

slideDevName

String

Specifies the slide within the record view to display initially. Valid options are:
• detail: The record detail slide. This is the default value.
• chatter: The Chatter slide
• related: The related information slide
This attribute has no effect in Lightning Experience.

force:navigateToURL
Navigates to the specified URL.
Relative and absolute URLs are supported. Relative URLs are relative to the Salesforce1 mobile browser app domain, and retain navigation
history. External URLs open in a separate browser window.
Use relative URLs to navigate to different screens within your app. Use external URLs to allow the user to access a different site or app,
where they can take actions that don’t need to be preserved in your app. To return to your app, the separate window that’s opened by
an external URL must be closed when the user is finished with the other app. The new window has a separate history from your app,
and this history is discarded when the window is closed. This also means that the user can’t click a Back button to go back to your app;
the user must close the new window.
mailto:, tel:, geo:, and other URL schemes are supported for launching external apps and attempt to “do the right thing.”
However, support varies by mobile platform and device. mailto: and tel: are reliable, but we recommend that you test any other

URLs on a range of expected devices.
Note: Only standard URL schemes are supported by navigateToURL. To access custom schemes, use window.location
instead.
When using mailto: and tel: URL schemes, you can also consider using ui:outputEmail and ui:outputURL components.
This example navigates a user to the opportunity page, /006/o, using a relative URL.
gotoURL : function (component, event, helper) {
var urlEvent = $A.get("e.force:navigateToURL");

469

Reference

force:recordSave

urlEvent.setParams({
"url": "/006/o"
});
urlEvent.fire();
}

This example opens an external website when the link is clicked.
navigate : function(component, event, helper) {
//Find the text value of the component with aura:id set to "address"
var address = component.find("address").get("v.value");
var urlEvent = $A.get("e.force:navigateToURL");
urlEvent.setParams({
"url": 'https://www.google.com/maps/place/' + address
});
urlEvent.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
Attribute Name

Type

Description

isredirect

Boolean

Indicates that the new URL should replace the current one in the navigation history.
Defaults to false.

url

String

Required. The URL of the target.

force:recordSave
Saves a record.
force:recordSave is handled by the force:recordEdit component. This examples shows a force:recordEdit
component, which takes in user input to update a record specified by the recordId attribute. The button fires the
force:recordSave event.



This client-side controller fires the event to save the record.
save : function(component, event, helper) {
component.find("edit").get("e.recordSave").fire();
// Update the component
helper.getRecords(component);
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.

force:recordSaveSuccess
Indicates that the record has been successfully saved.

470

Reference

force:refreshView

force:recordSaveSuccess is used with the force:recordEdit component. This examples shows a
force:recordEdit component, which takes in user input to update a record specified by the recordId attribute. The button
fires the force:recordSave event.





Record save status: {!v.saveState}

This client-side controller fires the event to save the record and handle it accordingly.
({
save : function(cmp, event) {
// Save the record
cmp.find("edit").get("e.recordSave").fire();
},
handleSaveSuccess : function(cmp, event) {
// Display the save status
cmp.set("v.saveState", "SAVED");
}
})

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.

force:refreshView
Reloads the view.
To refresh a view, run $A.get("e.force:refreshView").fire();, which reloads all data for the view.
This example refreshes the view after an action is successfully completed.
refresh : function(component, event, helper) {
var action = cmp.get('c.myController');
action.setCallback(cmp,
function(response) {
var state = response.getState();
if (state === 'SUCCESS'){
$A.get('e.force:refreshView').fire();
} else {
//do something
}
}
);
$A.enqueueAction(action);
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.

471

Reference

force:showToast

force:showToast
Displays a toast notification with a message.
A toast displays a message below the header at the top of a view. The message is specified by the message attribute.
This example displays a toast message “Success! The record has been updated successfully.”.
showToast : function(component, event, helper) {
var toastEvent = $A.get("e.force:showToast");
toastEvent.setParams({
"title": "Success!",
"message": "The record has been updated successfully."
});
toastEvent.fire();
}

Note: This event is handled by the one.app container. It’s supported in Lightning Experience and Salesforce1 only.
The background color and icon used by a toast is controlled by the type attribute. For example, setting it to success displays the
toast notification with a green background and checkmark icon. This toast displays for 5000ms, with a close button in the top right
corner when the mode attribute is dismissible.
Attribute Name

Type

Description

title

String

Specifies the toast title in bold.

message

String

Required. Specifies the message to display.

key

String

Specifies an icon when the toast type is other. Icon keys are available at the Lightning
Design System Resources page.

duration

Integer

Toast duration in milliseconds. The default is 5000ms.

type

String

The toast type, which can be error, warning, success, or info. The default is
other, which is styled like an info toast and doesn’t display an icon, unless specified
by the key attribute. Available in API version 37.0 and later.

mode

String

The toast mode, which controls how users can dismiss the toast. The default is
dismissible, which displays the close button. Available in API version 37.0 and
later.
Valid values:
• dismissible: Remains visible until you press the close button or duration
has elapsed, whichever comes first.
• pester: Remains visible until duration has elapsed. No close button is
displayed.
• sticky: Remains visible until you press the close buttons.

forceCommunity:analyticsInteraction
Tracks events triggered by custom components in Communities and sends the data to Google Analytics.

472

Reference

forceCommunity:routeChange

For example, you could create a custom button and include the forceCommunity:analyticsInteraction event in the
button's client-side controller. Clicking the button sends event data to Google Analytics.
onClick : function(cmp, event, helper) {
var analyticsInteraction = $A.get("e.forceCommunity:analyticsInteraction");
analyticsInteraction.setParams({
hitType : 'event',
eventCategory : 'Button',
eventAction : 'click',
eventLabel : 'Winter Campaign Button',
eventValue: 200
});
analyticsInteraction.fire();
}

Note:
• This event is supported in template-based communities only. To enable event tracking, add your Google Analytics tracking
ID in Settings > Advanced in Community Builder and publish the community.
• Google Analytics isn’t supported in sandbox environments.
Attribute Name

Type

Description

hitType

String

Required. The type of hit. 'event' is the only permitted value.

eventCategory

String

Required. The type or category of item that was interacted with, such as a button or video.

eventAction

String

Required. The type of action. For example, for a video player, actions could include play,
pause, or share.

eventLabel

String

Can be used to provide additional information about the event.

eventValue

Integer

A positive numeric value associated with the event.

forceCommunity:routeChange
The system fires the forceCommunity:routeChange event when a page’s URL changes. Custom Lightning components can
listen to this system event and handle it as required—for example, for analytics or SEO purposes.
Note: This event is supported in template-based communities only.
This sample component listens to the system event.




    Route was changed: {!v.routeChangeCounter} times
    
    

This client-side controller example handles the system event.
({handleRouteChange : function(component, event, helper) {
component.set('v.routeChangeCounter', component.get('v.routeChangeCounter') + 1);

473

Reference

lightning:openFiles

}
})

lightning:openFiles
Opens one or more file records from the ContentDocument and ContentHubItem objects.
On desktops, the event opens the SVG file preview player, which lets you preview images, documents, and other files in the browser.
The file preview player supports full-screen presentation mode and provides quick access to file actions, such as upload, delete, download,
and share.
On mobile devices, the file is downloaded. If the device supports file preview, the device’s preview app is opened.
This example opens a single file.
openSingleFile: function(cmp, event, helper) {
$A.get('e.lightning:openFiles').fire({
recordIds: [component.get("v.currentContentDocumentId")]
});
}

This example opens multiple files.
openMultipleFiles: function(cmp, event, helper) {
$A.get('e.lightning:openFiles').fire({
recordIds: component.get("v.allContentDocumentIds"),
selectedRecordId: component.get("v.currentContentDocumentId")
});
}

Note: This event is supported in Lightning Experience, Salesforce1, and communities based on the Customer Service (Napili)
template only.
Attribute Name

Type

Description

recordIds

String[]

Required. IDs of the records to open.

selectedRecordId String

ID of the first record to open from the list specified in recordIds. If a value isn’t
provided or is incorrect, the first item in the list is used.

ltng:selectSObject
Sends the recordId of an object when it’s selected in the UI.
To select an object, set the record ID on the recordId attribute. Optionally, specify a channel for this event so that your components
can select if they want to listen to particular event messages.
selectedObj: function(component, event) {
var selectedObjEvent = $A.get("e.ltng:selectSObject");
selectedObjEvent.setParams({
"recordId": "0061a000004x8e1",
"channel": "AccountsChannel"
});

474

Reference

ltng:sendMessage

selectedObj.fire();
}

Attribute Name

Type

Description

recordId

String

Required. The record ID associated with the record to select.

channel

String

Specify this field if you want particular components to process some event messages
while ignoring others.

ltng:sendMessage
Passes a message between two components.
To send a message, specify a string of text that you want to pass between components. Optionally, specify a channel for this event so
that your components can select if they want to listen to particular event messages
sendMsg: function(component, event) {
var sendMsgEvent = $A.get("e.ltng:sendMessage");
sendMsgEvent.setParams({
"message": "Hello World",
"channel": "AccountsChannel"
});
sendMsgEvent.fire();
}

Attribute Name

Type

Description

message

String

Required. The text that you want to pass between components.

channel

String

Specify this field if you want particular components to process some event messages
while ignoring others.

ui:clearErrors
Indicates that any validation errors should be cleared.
To set a handler for the ui:clearErrors event, use the onClearErrors system attribute on a component that extends
ui:input, such as ui:inputNumber.
The following ui:inputNumber component handles an error when the ui:button component is pressed. You can fire and
handle these events in a client-side controller.

Enter a number:





475

Reference

ui:collapse




For more information, see Validating Fields on page 230.

ui:collapse
Indicates that a menu component collapses.
For example, the ui:menuList component registers this event and handles it when it’s fired.


You can handle this event in a ui:menuList component instance. This example shows a menu component with two list items. It
handles the ui:collapse and ui:expand events.








This client-side controller adds a CSS class to the trigger when the menu is collapsed and removes it when the menu is expanded.
({
addMyClass : function(component, event, helper) {
var trigger = component.find("trigger");
$A.util.addClass(trigger, "myClass");
},
removeMyClass : function(component, event, helper) {
var trigger = component.find("trigger");
$A.util.removeClass(trigger, "myClass");
}
})

ui:expand
Indicates that a menu component expands.
For example, the ui:menuList component registers this event and handles it when it’s fired.


You can handle this event in a ui:menuList component instance. This example shows a menu component with two list items. It
handles the ui:collapse and ui:expand events.








This client-side controller adds a CSS class to the trigger when the menu is collapsed and removes it when the menu is expanded.
({
addMyClass : function(component, event, helper) {
var trigger = component.find("trigger");
$A.util.addClass(trigger, "myClass");
},
removeMyClass : function(component, event, helper) {
var trigger = component.find("trigger");
$A.util.removeClass(trigger, "myClass");
}
})

ui:menuFocusChange
Indicates that the user changed menu item focus in a menu component.
For example, this event is fired when the user scrolls up and down the menu list, which triggers a focus change in menu items. The
ui:menuList component registers this event and handles it when it’s fired.


You can handle this event in a ui:menuList component instance. This example shows a menu component with two list items.








ui:menuSelect
Indicates that a menu item has been selected in the menu component.
For example, the ui:menuList component registers this event so it can be fired by the component.


477

Reference

ui:menuTriggerPress

You can handle this event in a ui:menuList component instance. This example shows a menu component with two list items. It
handles the ui:menuSelect event and click events.








When a menu item is clicked, the click event is handled before the ui:menuSelect event, which corresponds to doSomething
and selected client-side controllers in the following example.
({
selected : function(component, event, helper) {
var selected = event.getParam("selectedItem");
// returns label of selected item
var selectedLabel = selected.get("v.label");
},
doSomething : function(component, event, helper) {
console.log("do something");
}
})

Attribute Name

Type

Description

selectedItem

Component[]

The menu item which is selected

hideMenu

Boolean

Hides menu if set to true

deselectSiblings Boolean
focusTrigger

Boolean

Deselects the siblings of the currently selected menu item
Sets focus to the ui:menuTrigger component

ui:menuTriggerPress
Indicates that a menu trigger is clicked.
For example, the ui:menuTrigger component registers this event so it can be fired by the component.


You can handle this event in a component that extends ui:menuTrigger, such as in a ui:menuTriggerLink component
instance.




478

Reference

ui:validationError






This client-side controller retrieves the label of the trigger when it’s clicked.
({
triggered : function(component, event, helper) {
var trigger = component.find("trigger");
// Get the label on the trigger
var triggerLabel = trigger.get("v.label");
}
})

ui:validationError
Indicates that the component has validation errors.
To set a handler for the ui:validationError event, use the onError system attribute on a component that extends ui:input,
such as ui:inputNumber.
The following ui:inputNumber component handles an error when the ui:button component is pressed. You can fire and
handle these events in a client-side controller.

Enter a number:







For more information, see Validating Fields on page 230.
Attribute Name

Type

Description

errors

Object[]

An array of error messages

System Event Reference
System events are fired by the framework during its lifecycle. You can handle these events in your Lightning apps or components, and
within Salesforce1. For example, these events enable you to handle attribute value changes, URL changes, or when the app or component
is waiting for a server response.

479

Reference

aura:doneRendering

aura:doneRendering
Indicates that the initial rendering of the root application has completed.
Note: We don't recommend using the legacy aura:doneRendering event except as a last resort. Unless your component
is running in complete isolation in a standalone app and not included in complex apps, such as Lightning Experience or Salesforce1,
you probably don’t want to handle this application event. The container app may trigger your event handler multiple times.
This event is automatically fired if no more components need to be rendered or rerendered due to any attribute value changes. The
aura:doneRendering event is handled by a client-side controller. A component can have only one  tag
to handle this event.


For example, you want to customize the behavior of your app after it’s finished rendering the first time but not after subsequent
rerenderings. Create an attribute to determine if it’s the first rendering.





    My component
    
    

This client-side controller checks that the aura:doneRendering event has been fired only once.
({
doneRendering: function(cmp, event, helper) {
if(!cmp.get("v.isDoneRendering")){
cmp.set("v.isDoneRendering", true);
//do something after component is first rendered
}
}
})

Note: When aura:doneRendering is fired, component.isRendered() returns true. To check if your element is
visible in the DOM, use utilities such as component.getElement(), component.hasClass(), or
element.style.display.
The aura:doneRendering handler contains these required attributes.
Attribute Name

Type

Description

event

String

The name of the event, which must be set to aura:doneRendering.

action

Object

The client-side controller action that handles the event.

aura:doneWaiting
Indicates that the app is done waiting for a response to a server request. This event is preceded by an aura:waiting event. This
event is fired after aura:waiting.
Note: We don't recommend using the legacy aura:doneWaiting event except as a last resort. The aura:doneWaiting
application event is fired for every server response, even for responses from other components in your app. Unless your component

480

Reference

aura:locationChange

is running in complete isolation in a standalone app and not included in Lightning Experience or Salesforce1, you probably don’t
want to handle this application event. The container app may fire server-side actions and trigger your event handler multiple times.
This event is automatically fired if no more response from the server is expected. The aura:doneWaiting event is handled by a
client-side controller. A component can have only one  tag to handle this event.


This example hides a spinner when aura:doneWaiting is fired.




    
    

This client-side controller fires an event that hides the spinner.
({
hideSpinner : function (component, event, helper) {
var spinner = component.find('spinner');
var evt = spinner.get("e.toggle");
evt.setParams({ isVisible : false });
evt.fire();
}
})

The aura:doneWaiting handler contains these required attributes.
Attribute Name

Type

Description

event

String

The name of the event, which must be set to aura:doneWaiting.

action

Object

The client-side controller action that handles the event.

aura:locationChange
Indicates that the hash part of the URL has changed.
This event is automatically fired when the hash part of the URL has changed, such as when a new location token is appended to the
hash. The aura:locationChange event is handled by a client-side controller. A component can have only one  tag to handle this event.


This client-side controller handles the aura:locationChange event.
({
update : function (component, event, helper) {
// Get the new location token from the event
var loc = event.getParam("token");
// Do something else
}
})

The aura:locationChange handler contains these required attributes.

481

Reference

aura:systemError

Attribute Name

Type

Description

event

String

The name of the event, which must be set to aura:locationChange.

action

Object

The client-side controller action that handles the event.

The aura:locationChange event contains these attributes.
Attribute Name

Type

Description

token

String

The hash part of the URL.

querystring

Object

The query string portion of the hash.

aura:systemError
Indicates that an error has occurred.
This event is automatically fired when an error is encountered during the execution of a server-side action. The aura:systemError
event is handled by a client-side controller. A component can have only one 
tag in markup to handle this event.


This example shows a button that triggers an error and a handler for the aura:systemError event .







This client-side controller triggers the firing of an error and handles that error.
({
trigger: function(cmp, event) {
// Call an Apex controller that throws an error
var action = cmp.get("c.throwError");
action.setCallback(cmp, function(response){
cmp.set("v.response", response);
});
$A.enqueueAction(action);
},
showSystemError: function(cmp, event) {
// Handle system error
console.log(cmp);
console.log(event);
}
})

The aura:handler tag for the aura:systemError event contains these required attributes.

482

Reference

aura:valueChange

Attribute Name

Type

Description

event

String

The name of the event, which must be set to aura:systemError.

action

Object

The client-side controller action that handles the event.

The aura:systemError event contains these attributes. You can retrieve the attribute values using
event.getParam("attributeName").
Attribute Name

Type

Description

message

String

The error message.

error

String

The error object.

SEE ALSO:
Throwing and Handling Errors

aura:valueChange
Indicates that an attribute value has changed.
This event is automatically fired when an attribute value changes. The aura:valueChange event is handled by a client-side
controller. A component can have multiple  tags to detect changes to different attributes.


This example updates a Boolean value, which automatically fires the aura:valueChange event.







These client-side controller actions trigger the value change and handle it.
({
changeValue : function (component, event, helper) {
component.set("v.myBool", false);
},
handleValueChange : function (component, event, helper) {
// handle value change
console.log("old value: " + event.getParam("oldValue"));
console.log("current value: " + event.getParam("value"));
}
})

The valueChange event gives you access to the previous value (oldValue) and the current value (value) in the handler action.
In this example, oldValue returns true and value returns false.

483

Reference

aura:valueDestroy

The change handler contains these required attributes.
Attribute Name

Type

Description

name

String

The name of the handler, which must be set to change.

value

Object

The attribute for which you want to detect changes.

action

Object

The client-side controller action that handles the value change.

SEE ALSO:
Detecting Data Changes with Change Handlers

aura:valueDestroy
Indicates that a component has been destroyed.
This event is automatically fired when a component is being destroyed. The aura:valueDestroy event is handled by a client-side
controller. A component can have only one  tag to handle this event.


This client-side controller handles the aura:valueDestroy event.
({
valueDestroy : function (component, event, helper) {
var val = event.getParam("value");
// Do something else here
}
})

Let’s say that you are viewing a component in Salesforce1. The aura:valueDestroy event is triggered when you tap on a different
menu item on the Salesforce1 navigation menu, and your component is destroyed. In this example, the value parameter in the event
returns the component that’s being destroyed.
The  tag for the aura:valueDestroy event contains these required attributes.
Attribute Name

Type

Description

name

String

The name of the handler, which must be set to destroy.

value

Object

The value for which you want to detect the event for. The value that is being destroyed.
Always set value="{!this}".

action

Object

The client-side controller action that handles the destroy event.

The aura:valueDestroy event contains these attributes.
Attribute Name

Type

Description

value

String

The component being destroyed, which is retrieved via
event.getParam("value").

484

Reference

aura:valueInit

aura:valueInit
Indicates that an app or component has been initialized.
This event is automatically fired when an app or component is initialized, prior to rendering. The aura:valueInit event is handled
by a client-side controller. A component can have only one  tag to handle this event.


For an example, see Invoking Actions on Component Initialization on page 229.
Note: Setting value="{!this}" marks this as a value event. You should always use this setting for an init event.
The init handler contains these required attributes.
Attribute Name

Type

Description

name

String

The name of the handler, which must be set to init.

value

Object

The value that is initialized, which must be set to {!this}.

action

Object

The client-side controller action that handles the value change.

aura:waiting
Indicates that the app is waiting for a response to a server request. This event is fired before aura:doneWaiting.
Note: We don't recommend using the legacy aura:waiting event except as a last resort. The aura:waiting application
event is fired for every server request, even for requests from other components in your app. Unless your component is running
in complete isolation in a standalone app and not included in Lightning Experience or Salesforce1, you probably don’t want to
handle this application event. The container app may fire server-side actions and trigger your event handler multiple times.
This event is automatically fired when a server-side action is added using $A.enqueueAction() and subsequently run, or when
it’s expecting a response from an Apex controller. The aura:waiting event is handled by a client-side controller. A component can
have only one  tag to handle this event.


This example shows a spinner when aura:waiting is fired.




    
    

This client-side controller fires an event that displays the spinner.
({
showSpinner : function (component, event, helper) {
var spinner = component.find('spinner');
var evt = spinner.get("e.toggle");
evt.setParams({ isVisible : true });
evt.fire();
}
})

485

Reference

Supported HTML Tags

The aura:waiting handler contains these required attributes.
Attribute Name

Type

Description

event

String

The name of the event, which must be set to aura:waiting.

action

Object

The client-side controller action that handles the event.

Supported HTML Tags
An HTML tag is treated as a first-class component by the framework. Each HTML tag is translated into an  component,
allowing it to enjoy the same rights and privileges as any other component.
For example, the framework automatically converts a standard HTML 
     tag to this component:


We recommend that you use components in preference to HTML tags. For example, use ui:button instead of 
    
								
    
							
    
		
		
    
			
    Navigation menu