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.

Pro tip: In Terminal, first type cd followed by a space, and then drag and drop the icon for your project folder into the Terminal right next to the cd. Terminal should automatically add the full path to the project directory.

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.

Note: If you saved the bridging header file to a different location, or if you get the location wrong above, when you build the project later you’ll get errors. So make sure that the location you enter above is correct.

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.

Note: The view you want to shimmer doesn’t have to be a subview of the FBShimmeringView. Whatever view you assign to shimmeringView.contentView becomes shimmery.

One easy way to verify this is to modify Main.storyboard by moving the UILabel so it’s outside of the view hierarchy, as shown here:

Build and run, and you’ll see that everything still works just as before.

It’s this line below that sets the content view for the Shimmer effect.:

You can modify that line to point to any view that you want to use as the content view.

shimmeringView.contentView = clockLabel

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.