Facebook Shimmer Tutorial

Update 4/11/2015: Updated for Xcode 6.3 / Swift 1.2

If you’re an iOS user, then you’ve definitely seen the fancy “slide to unlock” shimmering control on iOS.

If you’ve ever wanted to simulate this same effect yourself, this tutorial is for you!

Here’s the good news: Facebook also really liked this effect and decided to include it in its app, Paper. Not only that, the developers also released the code on GitHub as the Shimmer library, so you to could use the effect in your own projects!

In this short tutorial, you’ll learn:

• How to use Facebook’s Shimmer library via CocoaPods in a simple clock application.
• How to implement Shimmer in Swift with minimal coding by using a bridging header.
• How to set up the controls to configure timing, direction, and other fine details.

You’ll also learn how Shimmer works under-the-hood. Let’s dive in!

Getting Started

Start by downloading the starter project for this tutorial, and open it in Xcode.

SparkleClock is a very simple digital clock app. Build and run to see your working clock:

Everybody knows that a digital clock without shimmer is a clock without character, so you’ll sparkle it up!

The first step is to install Facebook Shimmer via CocoaPods.

Create a new file by selecting File\New\File… and select iOS\Other\Empty. Click Next. Enter Podfile as the filename in Save As and change the directory to save the file in the project’s root directory (where SparkleClock.xcodeproj is). Click Create.

Add the following text to Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'

pod 'Shimmer'

Close Xcode project via File\Close Project.

Run Terminal by opening Spotlight and typing terminal. Next, navigate to the directory where you saved the SparkleClock project (the folder containing SparkleClock.xcodeproj) by typing cd “The path to your project folder” and press enter.

Still in Terminal, install the Facebook Shimmer dependency by typing pod install and press enter. The output should look something like this:

$ pod install
Analyzing dependencies
Downloading dependencies
Installing Shimmer (1.0.2)
Generating Pods project
Integrating client project

[!] From now on use `SparkleClock.xcworkspace`.
$

Open the newly created workspace by simply double-clicking SparkleClock.xcworkspace in Finder. Alternatively, you can select File\Open… in the Xcode menu, select SparkleClock.xcworkspace, and then click Open.

Integrating Shimmer

Since this application is primarily in Swift and Facebook Shimmer is an Objective-C library, you need to add a bridging header which lets Swift know about the Objective-C classes that you’ll be working with.

Select the SparkleClock group under the project root in the Project Navigator (press Command-1 if it’s not showing), select File\New\File… from the menu, and then select iOS\Source\Header File. Click Next, name the file SparkleClock-Bridging-Header.h and click Create.

Replace the contents of the new file with the following:

#import "FBShimmering.h"
#import "FBShimmeringLayer.h"
#import "FBShimmeringView.h"

Next, select the project root in the Project Navigator, and then select the SparkleClock target.

Choose the Build Settings tab, and find the Swift Compiler – Code Generation\Objective-C Bridging Header item. As a shortcut, you can type bridging in the search field at the top of the settings to find the item quickly.

Double-click the value field to the right of the Objective-C Bridging Header label and enter the location of the bridging header that you just created: SparkleClock/SparkleClock-Bridging-Header.h.

Okay, almost there! All you’ve done so far is to add the Shimmer library to the project and set a bridging header up so that your Swift code can work with the Shimmer library, which is in Objective-C. Now comes the fun part – implementing the Shimmer functionality.

Select ViewController.swift and add another IBOutlet at the top of the file as follows:

@IBOutlet var shimmeringView: FBShimmeringView!

The above outlet will point to the Shimmer subview.

Add the following two lines to the end of viewDidLoad:

shimmeringView.contentView = clockLabel
shimmeringView.shimmering = true

The new lines set up the Shimmer view by pointing to the content view for the Shimmer view and enabling shimmering.

Finally, add this line to the beginning of didTapView:

shimmeringView.shimmering = !shimmeringView.shimmering

This code toggles the shimmer effect on and off each time the user taps the view.

That’s all there is to set up the Shimmer library via code. Simple, right?

But hold on, you’re not done yet :] Remember the new outlet we setup a little while ago? Did you find yourself asking, “Where is the view for that outlet?” If you did, you’ll get the answer next.

Configuring the Storyboard

Select Main.storyboard in the Project Navigator. This is where you’ll set up the FBShimmeringView outlet.

Expand the Document Outline so that you can see the full view hierarchy for the View Controller scene. Then, select the subview under the main view.

Then, switch to the Identity Inspector (press Option-Command-3 to show) and set the Class under Custom Class to FBShimmeringView.

Next, select View Controller in the Document Outline and switch to the Connections Inspector (press Option-Command-6 to show). Find the shimmeringView outlet and connect it to the subview you just modified by dragging from the plus sign to the subview.

That’s it, the bulk of the work is done!

Build and run the project to see your cool shimmering clock.

Tapping on the clock starts and stops the shimmering effect. However, the shimmering effect is a little offbeat; it’s not synchronized with the ticking by of the seconds. Timing is one of the many variables you can tweak to achieve the perfect effect, and this tutorial will discuss the various values you can configure, in a bit.

shimmeringView.contentView = clockLabel

And that’s it – congratulations! You’re done with the coding part of this short tutorial; the rest is simply an under-the-hood tour of shimmer and a quick reference.

How Shimmer Works

How exactly does Shimmer work?

There are three main components to Shimmer:

1. FBShimmering is a protocol that defines the list of properties that all shimmering views should have – both FBShimmeringView and FBShimmeringLayer implement this protocol.
2. FBShimmeringView is UIView subclass that acts as manager for the view you want to shimmer. Its contentView property has a setter method that adds your view as a subview and saves a reference to the subview’s CALayer to use when shimmering. Notice that each property is simply a pass-through to its underlying FBShimmerLayer.
3. FBShimmeringLayer is where all the magic happens. It creates a CAGradientLayer subclass and sets it as the mask of the contentView. Usually when you set a mask on a layer, you use it to “cut out” only part of a layer to be visible, but you can also use masks to make parts of a layer more or less transparent than others; this is what Shimmer does.

   Basically Shimmer sets up the gradient layer to make part of the content view more transparent than other parts – i.e. the area that is “not shimmering” is 50% transparent, and the area that is shimmering is not transparent at all, so it appears like a highlight. It also runs an animation to move the gradient along the shimmer view, from left to right by default.

Feel free to look through the code to get an understanding of it – then proceed to the quick reference if you want to tweak Shimmer’s behavior!

Shimmer Quick Reference

Here’s a list of all the properties you can configure via the FBShimmering protocol that’s used by Shimmer.

• shimmeringPauseDuration: Adds length to the gradient to give additional time (default 0.4 seconds).
• shimmeringAnimationOpacity: The opacity of the content before it is shimmering (the non-highlighted area; default 0.5).
• shimmeringOpacity: The opacity of the content while it is shimming (the highlighted area; default 1.0).
• shimmeringSpeed: This changes the speed of the shimmer; a lower number means a faster shimmer. You use this in combination with pause duration (default 230 points per second).
• shimmeringHighlightLength: The highlight length of shimmering (range between 0-1; default 0.33).
• shimmeringDirection: Allows you to set the direction of the shimmer between right/left/up/down (default FBShimmerDirectionRight).

To see more options, check out FBShimmering.h. Have fun!

Where To Go From Here?

Here’s the final project source code.

Adding a shimmer effect to your application is extremely simple with Facebook Shimmer. The library is easy to use, and though it’s written in Objective-C, it plays nicely with Swift.

Try changing the values of the various protocol properties and see what happens. Can you make the shimmer happen once for every passing second?

Feel free to chime in on the forums below if you have questions, comments, or just want to show off how you implemented shimmer in your own app. I look forward to hearing from you!