Touring Dreamhouse: A Primer to Developing in Lightning Experience

Lightning Experience is the re-imagined user interface for Salesforce. It’s packed with new features to help Salesforce users sell faster, work more productively, and make better decisions. While the previous UI, now known as Classic, was built using a combination of technologies, Lightning Experience is built using the Lightning Component Framework. Lightning Components also drive all of the new tools and features Salesforce is building into Sales and Service Cloud.

Classic runs alongside Lightning Experience and users can be allowed to switch between interfaces. However, we recommend updating to Lightning Experience sooner rather than later – Lightning Experience is a lot more than just a fresh coat of paint on the same framework. It has an updated, more robust structure and carries new features that today’s users and app creators demand.

This 6-step primer is designed to help you become more familiar with Lightning Experience and how you can leverage Lightning Components. If you aren’t a code-centric builder, don’t worry – this tour isn’t going deep into the woods with code, but does highlight key points where you can customize the Lightning Experience with code. Some of the code may seem advanced, but by following along with us you’ll see where custom components can be used. If you are a developer who has already tried Lightning Components, this primer may still highlight new features of the framework for you.

To really understand Lightning Components, we’ll use the DreamHouse reference application. DreamHouse is an excellent way to see the kinds of things that can power your Lightning Experience and how you can get them done.

1: Start Lightning Experience

Sign up for a new Developer Edition and install DreamHouse

All new Developer Editions now start with the Lightning Experience enabled by default. The easiest way to get started with this tour is by installing the DreamHouse app into a fresh Developer Edition. You can get up and running by following the installation instructions here:

Important: Do not skip the part about setting up your own domain! It’s very easy to do, but custom Lightning Components can only be used in an instance with My Domain enabled. Remember that you have to register your domain, login and activate it before the installation will work.

Once installed, head to the DreamHouse app by selecting it from the app launcher (the grid like icon in the upper left). You will want to click on the Data Import tab to get some demo data inserted into your instance.

Got Lightning Experience and DreamHouse? Tweet it out.

We love to know people are starting the tour, so tweet out a screenshot of DreamHouse in Lightning Experience with the hashtag #TouringDreamHouse to let use know.

2: Using Visualforce in Lightning Experience

Can we still use Visualforce in Lightning Experience?

Yes, we’re taking a step back here to answer one of the most commonly asked questions about adopting Lightning Experience into your org: What about Visualforce?

Visualforce runs on completely different technology from Lightning Experience and Lightning Components. Because of this, it does not share the same structure and can’t communicate with Lightning Experience in the same way. That said, it is possible to retain your old Visualforce code and use it within Lightning Experience. There may be a few scenarios where keeping your existing Visualforce pages makes sense and may save some development time.

To Trailhead!

To walk you through the ins and outs of using Visualforce in Lightning Experience, we journey to Trailhead. Complete this introductory unit which is a high level overview of how Visualforce can be exposed in the new UI:

Update the DreamHouse HeatMap page

DreamHouse contains an excellent example of when a developer might decide to leverage an existing Visualforce page. One of the tabs is “HeatMap” which shows a geographical view of existing properties. This page is great to leverage as a VisualForce page as it:

  • leverages existing JavaScript libraries
  • does not rely on other components
  • does not need to communicate outside the context of the page.

You can see the page in action by going to the DreamHouse app and selecting the HeatMap tab. Notice how the page resembles and fits into the overall Lightning Experience look and feel. This is because the page leverages the Salesforce Lightning Design System (SLDS), which is the same styling and design as Lightning Experience.

However, the page uses a now slightly dated way to reference the design system (as of version 1.31). A Visualforce tag was recently released which allows developers to easily add SLDS to their pages. Currently the HeatMap page relies on a static resource containing SLDS to be referenced. With the SLDS tag that shouldn’t be needed.

To update the page:

  1. Open the Developer Console, accessible under the setup dropdown (which looks like a gear in the upper right).
  2. In Developer Console, go to “File ? Open”, Select “Pages” and open “HeatMap”.
  3. Update the HeatMap API version to 39. The API version drop down is by the Preview button.
  4. Comment out the line which has a link tag referring to “$Resource.SLDS212”.
  5. Below the remoteObjects component, add “<apex:slds />” to the page.
  6. Change the “<body>” tag to be “<body class=”slds-scope”>”
  7. Save the page and either click “Preview” or reload it in the DreamHouse app.

3: Using the Lightning Component Framework

So what is the Lightning Component Framework?

Lightning Experience is built using the Lightning Component Framework. With the exception of some legacy screens, the Lightning Component architecture is what Salesforce uses to build all new tools and features.

But what exactly is it?

The Lightning Component framework resembles many modern HTML5 frameworks like Angular and React. These frameworks are JavaScript based, extremely modular and event driven. Comparatively, technologies like Visualforce rely on a maintaining state between the server and client at the page level where as component frameworks focus on pages being comprised of distinct portions (the components themselves). With Visualforce, turning something into a reusable component was the exception where with Lightning Components it would be the rule.

To Trailhead!

To cover the basics of Lightning Components, we will head back to the forest of Trailhead. Complete this introductory unit into the framework to get a more detailed rundown of how it works.

Examine the Mortgage Calculator

Now that we have an overview of the Lightning Component Framework, let’s dive into a specific example. If you go to the Properties tab and click on any of the properties (if you don’t see any, you may need to go to the Data Import tab and create some data). If you scroll down towards the bottom you see towards the right a Mortgage Calculator. Notice that the principal amount is already filled out and that you can update either the years or rate of the term.

However if you completely clear out the rate input, you will get an error from the framework (as of version 1.31). In order to figure out how to fix that, we are going to explore how that component works. In our next section, we’ll tour e different parts of a component and see how they work together.

4: Use Resources in a Lightning Component

Open the MortgageCalculator Component in Developer Console

Let’s look under the hood of the MortgageCalculator to walk back to the point where we need to catch how that number is being calculated:

  1. If you don’t already have it open, open Developer Console via the setup dropdown (the gear icon in the upper right).
  2. In Developer Console, Go to “File ? Open Lightning Resources”.
  3. In the list of resources, click “c:MortgageCalculator” and click Open Selected.

The page that loads into Developer Console is a summary of the component. A component is functionally a bundle of resources, including the component itself and all of the related files needed to make it run. You can see the list of resources to the right where it says:


We are going to focus on those first three.

Open the Component resource

Click on COMPONENT. An XML file will now be available in Developer Console. This describes the actual component the user will be interacting with when the component is added to a page or application. Some of the tags used here describe elements the user will not see, such as attribute and handler tags. Those are describing specific properties which will hold values the component needs (like the price of the property or the rate of the mortgage). Then lower down we see tags like lightning:input which allows the user to input values themselves.

Warning: Developer Preview! Beta!

There are actually two parts of the component resource which are using new features of the Lightning Component Framework. The force:recordPreview tag leverages Lightning Data Services to load information about the current record without requiring any server side code in Apex. This is currently in Developer Preview. The lightning:input tags are part of the new lightning UI elements which are in beta.

Lightning Components are Event Based

Now focus your gaze on the aura:handler tags. These handle specific events like when the component loads or when input changes occur. Notice they all reference {!c.calculateMonthlyPayment} as their action. When those events fire, what part of our component bundle is here to catch them? For that, we move on to the controller resource.

Open the Controller resource

Now click the second resource on the list, CONTROLLER. This is the first of two possible controllers for a component. The one included in the bundle is a client side controller in JavaScript. If we needed Apex to do heavy lifting for us, it would coordinate with an Apex class as a second class. In this case, we get everything we need from the force:recordPreview tag.

There isn’t much code here and that is by design. The controller is meant to coordinate changes back down to the component resource. Any logic we might want to use in multiple places in the controller should be maintained by its faithful assistant, the helper resource.

Open the Helper resource

Now click the third resource, HELPER. Now we see the real inner workings of the component. Here you see some component.get functions, which grab the current values from our inputs on the component resource, followed by some calculations and then a component.set function which updates the actual mortgage payment value the user sees.

So what is the cause of our error? If rate is blank it is handled by JavaScript as Not a Number or NaN. This causes the payment to also be NaN and the formattedNumber input can’t output that (it is still in beta). So before the component.set function, just add:

if(isNaN(monthlyPayment)) { monthlyPayment = 0; }

This forces the value to zero before handing it to the formattedNumber. Save that change and refresh the page and you should be able to clear out the rate input without error. You may have to do a hard refresh if the component is cached on the record page.

5: Use Apex with Lightning Components

The Lightning Data Services is a powerful new feature of the Lightning Component Framework that allows developers to work with data without the need of a server side controller. However, when you need to bring Apex to bear against a problem it is pretty easy to do so.

Check out the Property Explorer

If you go back to the DreamHouse app and click on the Property Explorer tab you will see a page which displays dynamic results based on a series of filters. To handle this kind of custom search, we use an Apex controller.

Similar to how we walked through the Mortgage Calculator, let’s walk through those results to see how they are being rendered.

  1. If you don’t have it open already, open Developer Console via the setup dropdown (the gear icon in the upper right).
  2. In Developer Console, Go to “File ? Open Lightning Resources”.
  3. In the list of resources, click “c:PropertyTileList” and click Open Selected.

Open the Component Resource

Like before, click on the COMPONENT resource from the list on the right of the PropertyTileList summary. You’ll see a lot of attributes and handlers like before, but notice that this component’s very first tag aura:component has an attribute controller. This refers to a specific Apex class.

Open the Helper Resource

We’ll skip the JavaScript controller this time as it is acting as a middleman between events and the helper resource again. Click HELPER from the list on the right.

In the function getProperties, the first line looks like this:

var action = component.get(“c.findAll“);

That “c.findAll” refers to a function in our Apex class, which we will look at next. Now that we have that reference we can set the values the Apex class needs using action.setParams and how we will react to the results of the class with action.setCallback. Once action is all set, we add it to the framework’s queue of server side requests using:


Open the Apex Class

Now in Developer Console, Go to “File ? Open”. Select “Classes” and then select “PropertyController”. This is the Apex class referenced in the component resource. The code is fairly straightforward, but notice specifically the following:

  1. Any function exposed to a Lightning Component needs to have the AuraEnabled annotation
  2. Any function exposed to a Lightning Component must be static
  3. The parameters here match what is being set by action.setParam
  4. The return value must match what is expected by action.setCallback

To Trailhead!

That’s a peek into how server side controllers work with Lightning Components. If you want a deeper dive, complete the following Trailhead unit:

6: Going further with Lightning Components

There is so much more…

We are only scratching the surface here on learning development in Lightning Experience. However the scope of this primer hasn’t gone into detail on events, features like Lightning Out, using Lightning App Builder and so, so much more.

To Trailhead!

One of the best resources would be to hit the trails on Trailhead. We have already referenced parts in this primer, but a great place to start is the whole Developing on Lightning Experience trail:

To DreamHouse!

We have also only scratched the surface on the DreamHouse application itself. DreamHouse is not just a reference application for Lightning Experience but for many Salesforce related technologies like IoT, Bots, and Einstein. Check out the latest here:


Remember that is your portal for all things on developing for the Salesforce Platform, including our Developer Relations blog. Here are some recent posts on DreamHouse and Lightning Components:

Meet DreamHouse
Modularizing Code in Lightning Components 
Base Lightning Components
Communicating with Visualforce and Lightning Components
Example Org Chart Component 
Spring ’17 New Lightning Features

Leave your comments...

Touring Dreamhouse: A Primer to Developing in Lightning Experience