πŸ“’ Attention Salesforce Certified Trailblazers! Maintain your credentials and link your Trailhead and Webassessor accounts by April 19th. Learn more.
close

Build the Account Map Display

Learning Objectives

After completing this unit, you’ll be able to:
  • Describe the Salesforce CLI commands used to sync your project with your scratch orgs.
  • Describe the Salesforce CLI command to create a permission set.
  • Understand how to build an app using Aura components.

What Are We Building?

In this step, we’ll build the final components of our geolocation app, which bring all the features together. We’ll create an Aura component that visualizes account addresses as markers on a map, and create a custom tab so we can navigate to our app. We’ll use a permission set to grant users access to our app, too.

Create the Account Map Aura Component

This component uses the <lightning:map> component to display accounts on a map.

  1. Create the AccountMap component in the aura folder.
    sfdx force:lightning:component:create -n AccountMap -d force-app/main/default/aura
  2. Open AccountMap.cmp and replace its contents with the following code, then save the file.
    <aura:component>
        <aura:handler event="c:AccountsLoaded" action="{!c.onAccountsLoaded}"/>
        <aura:attribute name="mapMarkers" type="Map[]"/>
        <lightning:card title="Account Map" iconName="action:map">
            <lightning:map mapMarkers="{!v.mapMarkers}"/>
        </lightning:card>
    </aura:component>

    This component listens for the AccountsLoaded event and displays the event data as map markers.

  3. Open AccountMapController.js and replace its contents with the following code, then save the file.
    ({
        onAccountsLoaded: function( component, event, helper ) {
            var mapMarkers = [];
            var accounts = event.getParam( 'accounts' );
            for ( var i = 0; i < accounts.length; i++ ) {
                var account = accounts[i];
                var marker = {
                    'location': {
                        'Street': account.BillingStreet,
                        'City': account.BillingCity,
                        'PostalCode': account.BillingPostalCode
                    },
                    'title': account.Name,
                    'description': (
                        'Phone: ' + account.Phone +
                        '<br/>' +
                        'Website: ' + account.Website
                    ),
                    'icon': 'standard:location'
                };
                mapMarkers.push( marker );
            }
            component.set( 'v.mapMarkers', mapMarkers );
        }
    })

    The client-side controller’s onAccountsLoaded function transforms the event data into the format expected by the <lightning:map> component.

  4. Push your new code to the scratch org.
    sfdx force:source:push

Create the Account Locator Aura Component

This is our main component, which we use to display our app to end users in Lightning pages, Salesforce mobile, and custom tabs. It’s also the last component you create for this project!

  1. Create the AccountLocator component in the aura folder.
    sfdx force:lightning:component:create -n AccountLocator -d force-app/main/default/aura
  2. Open AccountLocator.cmp and replace its contents with the following code, then save the file.
    <aura:component implements="force:appHostable,flexipage:availableForAllPageTypes">
        <lightning:layout horizontalAlign="space" multipleRows="true">
            <lightning:layoutItem size="12"
                                  mediumDeviceSize="12"
                                  padding="around-small">
                <c:AccountSearch/>
            </lightning:layoutItem>
            <lightning:layoutItem size="12"
                                  mediumDeviceSize="6"
                                  padding="around-small">
                <c:AccountList/>
            </lightning:layoutItem>
            <lightning:layoutItem size="12"
                                  mediumDeviceSize="6"
                                  padding="around-small">
                <c:AccountMap/>
            </lightning:layoutItem>
        </lightning:layout>
    </aura:component>

    This component is composed of the other components you created throughout this project. Two powerful features of the Lightning Component Framework are component encapsulation and component reusability. Composing fine-grained components in a larger component enables you to build more interesting components and applications.

  3. Push your new code to the scratch org.
    sfdx force:source:push

Create the Account Locator Custom Tab

An easy way to display Aura components in both Lightning Experience desktop and Salesforce mobile is with a custom tab. After this step, you access your app by navigating to this custom tab.

  1. Open your scratch org.
    sfdx force:org:open
  2. From Setup, enter Tabs in the Quick Find box, then click Tabs.
  3. In the Lightning Component Tabs section, click New and enter the details:
    • Lightning Component: c:AccountLocator
    • Tab Label: Account Locator
    • Tab Name: Account_Locator
    • Tab Style: Click the magnifier icon and select Map as the tab icon.
    New Lightning Component tab dialog
  4. Click Next.
  5. For Apply one tab visibility to all profiles, choose Tab Hidden.
  6. Click Save.

Create the Geolocation Permission Set

To control who has access to your geolocation app, create a permission set and grant it visibility to the Account Locator tab.

  1. From Setup, enter Permission Sets in the Quick Find box, then click Permission Sets.
  2. Click New and enter the details:
    • Label: Geolocation
    • API Name: Geolocation
    • Description: Grants access to the Account Geolocation app
  3. Click Save.
  4. Under Apps, click Object Settings.
  5. Click Account Locator.
  6. Click Edit.
  7. For Tab Settings, select both Available and Visible, then click Save.

Next, assign the permission set to yourself. We’ll see in a later step how to automate assigning permission sets using Salesforce CLI.

  1. Click Manage Assignments, then Add Assignments.
  2. Select the checkbox next to the scratch org username (User, User), click Assign, then click Done.

Metadata Magic: Pull Changes into Your Project

Until recently, you’ve been working locally and pushing metadata into your scratch org. In this step, you made some changes directly in that scratch org. Now the magic happens. With one single command, you pull all the metadata that you changed in the scratch org to your local project.

Before we do that, though, we want to configure our .forceignore file to ignore syncing some metadata. When you created the Account Locator tab and assigned its visibility to all the profiles, the automatic change-tracking in the scratch org noted that the profiles have changed. Naturally, the next time you pull metadata from the scratch org to sync with your local project, the CLI will want to pull down profile metadata. Since the profiles are not pertinent to your geolocation app and not something to track in your source control repository for this project, we need to tell Salesforce CLI to ignore the profile changes.

In your geolocation project directory, open the .forceignore file and add **/profiles as a new line to the file, then save the file. Your .forceignore file should look something like this:

package.xml
**/jsconfig.json
**/.eslintrc.json
**/profiles

Now you’re ready to sync metadata. In the command window, sync the changes you made in the scratch org with your local project.

sfdx force:source:pull

The output of the force:source:pull command looks something like this:

=== Pulled Source
STATE FULL NAME       TYPE          PROJECT PATH
───── ─────────────── ───────────── ────────────────────────────────────────────────────────────────────────
Add   Account_Locator CustomTab     force-app/main/default/tabs/Account_Locator.tab-meta.xml
Add   Geolocation     PermissionSet force-app/main/default/permissionsets/Geolocation.permissionset-meta.xml

Note that none of the profile changes synced because they are ignored in .forceignore.

Validate Your App

While you can absolutely use the same scratch org you’ve used during development to perform your testing, we recommend that you always start with a fresh scratch org. A fresh scratch org ensures you’ve properly externalized all your source from the org.

  1. Create a new scratch org.
    sfdx force:org:create -f config/project-scratch-def.json -a GeoTestOrg
  2. Push your local source and metadata to the scratch org.
    sfdx force:source:push -u GeoTestOrg
  3. Assign your permission set.
    sfdx force:user:permset:assign -n Geolocation -u GeoTestOrg
  4. Load your sample data into the org.
    sfdx force:data:tree:import -f data/Account.json -u GeoTestOrg
  5. Open your org.
    sfdx force:org:open -u GeoTestOrg
  6. Test the Account Locator tab, and verify that it works as expected. Click the App Launcher, then Account Locator.
Account Locator component with Account Search, Account List, and Account Map components

Congratulations! You’ve successfully built and tested a new app with scratch orgs and Salesforce CLI. Don’t forget to add everything to your source control repository!

retargeting