Secure Wrappers for Global References

LockerService applies restrictions to global references. LockerService provides secure versions of non-intrinsic objects, such as window. For example, the secure version of window is SecureWindow. You can interact with a secure wrapper in the same way as you interact with the non-intrinsic object, but the secure wrappers filter access to the object and its properties. The secure wrappers expose a subset of the API of the underlying objects.

Here’s a list of the secure objects that you’ll most commonly encounter.

SecureAura
Secure wrapper for $A, which is the entry point for using the framework in JavaScript code.
SecureComponent
Secure wrapper for the Component object.
SecureComponentRef
SecureComponentRef is a subset of SecureComponent that provides the external API for a component in a different namespace.
When you’re in a controller or helper, you have access to a SecureComponent, essentially the this object. In other contexts when you’re working with a component, you get a SecureComponentRef instead if you reference a component in a different namespace. For example, if your markup includes a lightning:button and you call cmp.find("buttonAuraId"), you get a SecureComponentRef as lightning:button is in a different namespace from the component containing the button markup.
SecureDocument
Secure wrapper for the Document object, which represents the root node of the HTML document or page. The Document object is the entry point into the page’s content, which is the DOM tree.
SecureElement
Secure wrapper for the Element object, which represents an HTML element. SecureElement is wrapped in a Proxy object as a performance optimization so that its data can be lazily filtered when it’s accessed. The HTML element is represented by a Proxy object if you’re debugging in the browser console.
SecureObject
Secure wrapper for an object that is wrapped by LockerService. When you see a SecureObject, it typically means you don’t have access to the object so some properties aren’t available.
SecureWindow
Secure wrapper for the Window object, which represents a window containing a DOM document.

Example

Let’s look at a sample component that demonstrates some of the secure wrappers.

<!--c:secureWrappers-->
<aura:component >
    <div id="myDiv" aura:id="div1">
        <p>See how LockerService uses secure wrappers</p>
    </div>
    <lightning:button name="myButton" label="Peek in DOM"
        aura:id="button1" onclick="{!c.peekInDom}"/>
</aura:component>

The c:secureWrappers component creates a <div> HTML element and a <lightning:button> component.

Here’s the client-side controller that peeks around in the DOM.

({ /* secureWrappersController.js */
    peekInDom : function(cmp, event, helper) {
        console.log("div1: ", cmp.find("div1").getElement());
        
        console.log("button1: ", cmp.find("button1"));
        console.log("button name: ", event.getSource().get("v.name"));
        // add debugger statement for inspection
        // always remove this from production code
        debugger;
    }
})

We use console.log() to look at the <div> element and the button. The <div> SecureElement is wrapped in a Proxy object as a performance optimization so that its data can be lazily filtered when it’s accessed.

We put a debugger statement in the code so that we could inspect the elements in the browser console.

Type these expressions into the browser console and look at the results.

cmp
cmp+""
cmp.find("button1")
cmp.find("button1")+""
window
window+""
$A
$A+""

We add an empty string to some expressions so that the object is converted to a String. You could also use the toString() method.

Here’s the output.Browser console output

Let’s examine some of the output.

cmp+""
Returns a SecureComponent object for cmp, which represents the c:secureWrappers component.
cmp.find("button1")+""
Returns a SecureComponentRef, which represents the external API for a component in a different namespace. In this example, the component is lightning:button.
window+""
Returns a SecureWindow object.
$A+""
Returns a SecureAura object.