c Bluewolf, an IBM Company 2016-2017

c Copyright IBM Corporation 2018 — All rights reserved

Bluewolf Salesforce Lightning Standards v0.1

Date: May 17, 2018
Contents

Contents ii

1 Introduction 1

2 Components 2
2.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 Design File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Controllers 5
3.1 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Renderers 6

5 Event Handling 7
5.1 Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.2 Component Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.3 Special Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

ii
Chapter 1

Introduction [Intro.Scope]

(1)
The language in this document follows the ISO Directive standards as such:

• “shall” indicates a requirement

• “should” indicates a recommendation
• “may” is used to indicate that something is permitted
• “can” is used to indicate that something is possible, for example, that an orga-
nization or individual is able to do something
In the ISO/IEC Directives, Part 2, Seventh edition, 2016, 3.3.3, a requirement is
defined as an “expression in the content of a document conveying objectively verifiable
criteria to be fulfilled and from which no deviation is permitted if compliance with
the document is to be claimed.”
In the ISO/IEC Directives, Part 2, Seventh edition, 2016, 3.3.4, a recommendation
is defined as an “expression in the content of a document conveying a suggested pos-
sible choice or course of action deemed to be particularly suitable without necessarily
mentioning or excluding others.”

1
 Chapter 2

Components [Components]

(2)
1 A developer shall not use inline EMCAScript (JavaScript) for event handlers on elements.
Inline ECMAScript is not guaranteed to work properly as very few things are in the global
scope in lightning. Instead a developer should instead call the component’s Controller methods
to handle the events.
2 A developer shall not use the following elements:

• center
• b use <strong> instead if you need to indicate heavy emphasis that is non-stylistic
• i use <em> instead if you need to emphasize text that is non-stylistic
• strike use <del> instead if you need to indicate text is removed text that is non-stylistic
• listing use <pre> or <code> instead if you need to display pre-formatted content or code,
ensure that & and < are escaped as &amp; and &lt; respectively
• big if the content is a heading use the appropriate heading element otherwise use CSS
• spacer
• multicol
• hgroup
• tt

3 A developer shall not use href="#" on anchor (<a>) tags.

Hash navigation interferes with the runtime particularly on mobile. Using it will result in
unexpected navigation events.
4 A developer shall not use a third party MVC framework.
Lightning provides an MVC framework, using a 3rd party framework increases the likelihood
of the component or application breaking.
5 A component shall not modify the DOM of another component.
6 A component shall not reference the DOM of another component.
7 A developer should favor using components from the lightning namespace over the ui names-
pace, or custom developed components.

2
8 A developer should favor using unbound expressions ({#v.foo}) versus bound expressions ({!v.foo})
when binding variables to components.
Unbound expressions when used correctly dramatically reduce the overhead in a component
and speed up how fast a user can interact with it. Bound expressions require the framework to
check if the value has changed and propagate that change. This is expensive and is one of the
primary performance hits in lightning.
9 A developer shall implement force:hasRecordId if a component’s functionality focuses on a
single record.
The force:hasRecordId provides several key benefits to a developer:

• automatically creates a public attribute named recordId

• clarifies that the component is designed to focus on a single record
• integrates with the Lightning Page Builder (assuming the appropriate interfaces are also
implemented)

2.1 Attributes [Components.Attributes]

(2.1)
1 A developer shall specify the access of all attributes on a component that are intended to be
private.
Specifying access on attributes makes it clear that those attributes should not be modified
outside the component. This in turn makes it much clearer where external updates can come
from. It also allows each component to better guard the internal business logic.
2 A developer shall specify a description for all public or global attributes.
A description on each attribute clarifies what each attribute’s purpose is. This significantly
assists later developers in understanding the logic of the component.
3 A developer should specify a description for all private attributes.
Descriptions on private attributes make it clear to the reader why the information is being
stored.

2.2 Styling [Components.Styles]

(2.2)
1 A developer shall not include the Salesforce Lightning Design System as a resource.
The lightning design system resources are already provided by salesforce as part of the light-
ning markup. Including them twice not only creates the potential for inconsistent styling, but
bloats the page and uses more bandwidth than necessary.
2 A developer shall extend force:slds if their lightning application needs salesforce lightning
design system styles.
3 A developer should avoid inline styles.
Inline styles bloat the markup. Furthermore browser vendors have consistently stated that
CSS based styling is always faster.
4 A developer shall not use the <style> element for styling their component.
Styles should be included via the component’s styles file. This allows the styles to be more
efficiently included in the overall application. Style elements in the markup create situations
where styles may apply to components or elements the developer did not intend for.
 2.3 Design File [Components.Design]
(2.3)
The design file of a component is used by the lightning page builder to allow non-developers
to arrange and use components. By properly implementing a design file a developer enables
reuse of their components without development effort.
1 All components implementing:

• flexipage:availableForAllPageTypes
• flexipage:availableForRecordHome
• forceCommunity:availableForAllPageTypes
shall have a design file.
2 Every public or global attribute on a component should have a corresponding entry in the
component’s design file.
3 Every component implementing force:hasRecordId shall have an sfdc:Objects enumeration
in the design file with a sfdc:object entry for the sObjects the component is valid to be used
with.
 Chapter 3

Controllers [Controllers]

(3)
1 A developer shall not modify the DOM in the controller
If a developer needs to modify the DOM they should put the logic to do so in the appropriate
renderer method. Modifying the DOM from a controller can have unpredictable results.
2 A developer shall put business logic in the Helper, not the controller.
A controller is designed to handle events and should be focused on event handling. Mixing
in business logic results in business logic being preformed inconsistently. Rather the controller
should delegate to the helper which can ensure that business logic is always applied correctly.

3.1 Initialization [Controllers.Init]

(3.1)
1 A developer shall not call server methods that perform DML from the init method
Doing DML in init creates an opportunity for Cross Site Request Forgery.

5
 Chapter 4

Renderers [Renderers]

(4)
1 A developer shall not fire an event from any renderer method.
Firing events from a component’s renderer can trigger an infinite rendering loop.
2 A developer shall only manipulate the DOM from a renderer.
A component’s renderer is the only place where DOM elements can be manipulated without
causing odd behavior in the application.
3 A developer should avoid assigning to document.location.href.
4 A developer should avoid using <unescapedHTML>, v.body, or innerHTML.
All of these methods can allow for Cross Site Scripting, and should be avoided. Instead prefer
using attributes and innerText.
5 A developer shall escape string attributes if they are not rendered via Lightning.
6

6
 Chapter 5

Event Handling [Events]

(5) Best Practices for developing Events in Lightning Components

1 A developer should favor using Component Events when communicating between components.
When components communicate with events, a developer must consider how the events be-
have. Component events are based on the component tree, whereas application events are broad-
cast to all components registered to handle them. Favoring component events assists in focusing
what can listen for a particular event. In most cases the event does not need to be broadcast
but rather is simply to inform a parent component of a state change.

5.1 Application Events [Events.Application]

(5.1) Application Events should be leveraged for distinct and individualized components at the
application level.
1 A developer should avoid calling stopPropagation() on application events.
Application events are broadcast to the entire application, as such they may have multiple
listeners. Calling stopPropagation() could result in some listeners not getting the event causing
unpredictable behavior.

5.2 Component Events [Events.Component]

(5.2)
Component Events should be leveraged in scenarios where you want to use the Event in the
Lighting App more than once. This prevents interference with other Events created.
1 A developer should call stopPropagation() to prevent propagation unless there is a clear need
to go up to the next level.
Component Events bubble up to the root level. By stopping propagation we prevent this
unnecessary behavior.

5.3 Special Events [Events.Special]

(5.3)

5.3.1 The Init Event [Events.Special.Init]

(5.3.1)

7
1 A developer shall not call stopPropagation() on the Init event.
The init event is special in the sense that it is called during the initialization process. Calling
stopPropagation() during this time disrupts initialization.