Building Uniquely Branded Lightning Component Single Page Apps for Salesforce Mobile

(part 1 of a 2-part series)

fwbfinalAt Dreamforce last week, Salesforce introduced a new feature that would enable administrators to more distinctly brand their Salesforce mobile apps.

As illustrated by the screenshot at right, that capability is actually available today through various CSS hacks, hand-wringing, and lots of tears.

Other titles that I’d considered for this post:

  • “Stuffing a round peg into a square hole”
  • “How to pull out all of your hair with maximum effort”
  • “I like to suffer”
  • “I should have become a patent lawyer”
  • “There be dragons here”

The fundamental problem is that the platform formerly known as Salesforce1 was clearly designed to render web pages (commonly referred to as Flexipages) and not single-page apps (SPAs). That’s why there’s no officially supported methodology (yet) for disabling the built-in “pull to refresh” feature, which can be quite convenient for refreshing web pages, but is inappropriate for single-page apps. There’s also lack of direct support for a “viewport” that would grab 100% of the visible screen, enabling developers to explicitly manage scrolling within their Lightning app.

Implementing Custom Branding in a Lightning App Builder Template

The first step in our branding odyssey is to create a Lightning App Builder template. This is a new feature in Winter ’18. The template defines drop target regions for Lightning App Builder components. About the only functionality that I’ve found that the app builder template will not support is (ironically) defining DESIGN properties on the template.

To define a template you need to:

  1. Add an implements=”lightning:appHomeTemplate” to the tag.
  2. Define a aura:attribute for each template region
  3. Define the template region in the DESIGN file

In order to implement the crazy branding, I also added the following global style to hide the flexipage page header, which by default consumes a fair amount of space at the top of the page:

<style>
 .oneAnchorHeader {
   display: none;
 } 
</style>

I also set a series of overrides to try and establish a “viewport” that occupied 100% of the width *and* height of the visible screen:

<style>
 .scroller.actionBarPlugin, 
 .oneFlexipage, 
 .flexipagePage,  
 .pageBody,  
 .mainbody, .mainbody > div {
    height: 100%
  }
</style>

Are we having fun yet?

Other global style overrides were added to remove some extraneous white-space as I’m trying to make use of every pixel in the phone form-factor.

Here’s the complete source code listing for the CMP file of the Lightning App Builder template:

<aura:component 
 implements="lightning:appHomeTemplate" 
 description="Friends with Beer Mobile Phone Template">
    
 <aura:attribute name="region1" type="Aura.Component[]" /> 
    
    <style>
        .oneAnchorHeader {
        	display: none;
        } 
        .scroller.actionBarPlugin  {
        	padding-bottom: 0px !important;
        }
        
        .scroller.actionBarPlugin, 
        .oneFlexipage, 
        .flexipagePage,  
        .pageBody,  
        .mainbody, .mainbody > div {
        	height: 100%
        }
        
        .oneFlexipage .pageBody {
        	margin-top: 0px;
        }
          
        .spacer-pull-to-load-more {
        	height: 0px !important;
        }
        
        .slds-table {
        	background-color: rgba(255, 255, 255, 0.3) !important;
        }
        
        .slds-card__header {
            margin: 0px !important;
            padding: 0px !important;
        }
        
    </style>
    
    <aura:handler name="render" 
                  value="{!this}" 
                  action="{!c.onRender}"/>
    
    
    <ui:scrollerWrapper class="maxHeight">
        <div class="mainbody" aura:Id="mainbody">
            <div class="fwbheader slds-align_absolute-center">
              Friends with Beer
            </div>
            {!v.region1}
        </div>
    </ui:scrollerWrapper>
    
</aura:component>

The corresponding design resource indicates the formfactors under which the region will be present:

<design:component label="Friends with Beer">
    <flexipage:template >
            <flexipage:region name="region1" defaultWidth="Small">
                <flexipage:formfactor type="MEDIUM" width="SMALL" />
            </flexipage:region>
    </flexipage:template>
</design:component>

Our template’s CSS resource is relatively tame by comparison. It loads a web font, styles the “Friends with Beer” bar, and sets the background image (beer, of course) for the app:

@font-face {
    font-family: 'Rambla';
    src: url('/resource/fwb/rambla/Rambla-Regular.otf');
}

.THIS .fwbheader {
    background-image: url('/resource/fwb/top-grain.png'), -webkit-radial-gradient(top center, circle, #9f5628, #5d2f17);
    background-repeat: repeat-x;
    color: #3a1515;
    text-shadow: 0px 1px rgba(255,255,255,.3);
    height: 50px;
    width: 100%;
    font-family: Rambla;
    font-size: 1.5em !important;
}

.THIS {
    background-image: url('/resource/fwb/background.png');
    background-size: cover;
}

.THIS .mainbody {
    position: absolute;
    width: 100%;
    height: 100%;
}

.THIS.maxHeight {
    height: 100%;
}

Disabling Pull to Refresh

You may have noticed that the template listens for the render event and fires off a controller function. The function, along with the use of ui:scrollerWrapper, intercepts the dragmove event that is fired when a user taps and drags the screen and prevents it from bubbling up to the native Salesforce mobile app.

({
    onRender: function(component,event,helper) {
        var cmpEl = component.getElement();
         cmpEl.addEventListener("touchmove", function(e) {
            e.stopPropagation();
        }, false); 
        var targetEl =  component.find("mainbody").getElement();
        targetEl.addEventListener("touchmove", function(e) {
            e.stopPropagation();
        }, false);       
    }
    
})

 
In my next post, we’ll review the Lightning components that were used to render data from Force.com, and how I was able to dock them into specific locations within the app. We’ll also discuss whether this approach is really viable on a going-forward basis or whether we should just file it away as an interesting hacking exercise that has run-amok.

And now, it’s time for a beer.

Happy coding!
 

 

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s