iOS 8: Interactive Playgrounds
WWDC 2014 was full of surprises and exciting technology to explore, and the new
Playground was high on that list.
Playgrounds provide a convenient environment for rapidly developing and trying out code. Apple’s
Balloons.playground demonstrates much of the power of the
Playground: it can serve as both a document and as a REPL. The combination of the two means that a
Playground is a fully interactive document.
Playgrounds are highly interactive, they are a wonderful vehicle for distributing code samples with instructive documentation. They can furthermore be used as an alternative medium for presentations. Consider a typical presentation: the presenter is giving a talk using whatever software she or he prefers, and then it is time to show off some code. Or, perhaps the presenter was asked a question that requires experimentation. In either scenario, the presentation is deferred momentarily in favor of Xcode. While this process is somewhat effective, it disturbs the flow of the presentation.
Playgrounds provide us with a mechanism to experiment with and demonstrate code without ever leaving the presentation.
In this post, I will show you how to peek inside the
.playground file to gain a sense of how a
Playground is put together. Glancing at these internals will help you to create your own interactive document. At the end of this post, you will have created your own
Playground featuring text and external resources, all the while taking advantage of the
A Peek Inside
Let’s begin by downloading Apple’s
Balloons.playground. Go ahead and click on the link above. One you have it downloaded, move the file somewhere convenient.
Now that you have the file, right-click on the
Balloons.playground file and select “Show Package Contents.” Doing so will reveal a number of files. Interestingly, what appeared to be a single file is actually made up of several others. It is this hidden organization that drives some of the subtle power delivered by a
Playground. You should see something like the image below.
Notice that you have three types of files, and two directories. For files, you have: 1)
contents.xcplayground, 2) a number of
.swift files, and 3) a
timeline.xctimeline. The first is a sort of manifest file that tells the
Playground how to display and organize its content; I will discuss this file in greater detail in the next section. The second set of file types contains the actual Swift code that is executed in the
Playground. Third, the
timeline.xctimeline file describes the timeline feature displayed in the Assistant Editor.
For directories, the
Balloons.playground file has “Documentation” and “Resources”. Clicking on this first folder reveals that it contains a number of
.html files and one
.css file. The “Documentation” folder holds all of the textual content of the
Playground described as a series of web pages. The CSS file defines the
Playground's styling of these pages. Finally, the “Resources” folder contains all of the external assets that the
Playground uses to render the game’s content.
Now that you have seen the hidden secrets of the Swift
Playground, let’s make our own interactive document.
An Interactive Presentation
As mentioned above, imagine that you are teaching a class on Swift. You would like to make a presentation on constants and variables, and would prefer that your presentation takes advantage of the Swift REPL. Good news! You can make your presentation right inside of Swift.
Create a new
Interactive.playground. Save this file where you like. Next, right-click on
Interactive.playground and select “Show Package Contents.” You will see two files of note:
section-1.swift. Go ahead and open
contents.xcplayground in your text editor of choice. You should see something similar to the image below.
As you can see, this is an XML file that acts as a manifest for the
Playground; it describes the organization of the
Playgrounds’s content. You will put your content inside the
sections tag. Notice the
code tag? This tag links to a file in the
Playground that contains your Swift code. If you open the
section-1.swift file, you should see the standard
Playground boilerplate code:
var str = "Hello, playground"
Delete the contents of this file, and replace it with the following:
let myName = "YOUR NAME HERE"
// try to change myName; what happens?
var myAge = // your age here
// try to change myAge; what happens?
If you open the
Playground, then you should see that the code has changed.
Balloons.playground had a directory called
Documentation. The directory contained a number of
.html files, and each of these files were linked against in the XML inside the
contents.xcplayground file. Copy that organization by creating a new folder inside
It is worth mentioning that each section of content in the
Documentation directory describes a distinct web page, which is displayed in the
Playground as a web view. There is a lot of room for creativity here.
Switch to the
Documentation folder and add a new file called
section0.html. Open this file, and copy and paste the following HTML to it.
<link rel="stylesheet" type="text/css" href="style.css" />
<h1>Constants and Variables</h1>
Swift is more explicit about the mutability of an instance than Objective-C. While ObjC's mutability is determined by the class the developer uses, Swift requires that mutability be declared when an instance of a type is created.
When you want a constant, you must use <code>let</code>. Use <code>let</code> when you don't want an instance's value to change. If you would like a variable, you must use <code>var</code>. <code>var</code> is used when you know that an instance will change at some point.
Notice that this means that mutability is more of a conscious decision. You decide what you want right when you make an instance. In Swift, mutability is no longer an artifact of which class you use. Thus, more careful thought is required.
It is our suggestion that you initially opt for a constant, an immutable instance. Your application will be easier to maintain, read, and develop for if it is very clear what values can change, and what values cannot.
section0.html gives a simple description of the role and use of constants and variables in Swift.
Formatting Documentation with CSS
section0.html links to a CSS file called
style.css. This CSS file works just the same way that you would imagine: it defines the styling of the HTML pages in your
Documentation directory. Go ahead and create a new file called
style.css and add it to your
Documentation directory. Open this file and add the code below.
margin: 10px 25px;
This CSS file is a very basic description of your HTML page’s style in terms of margins, colors, fonts and text alignment. If you prefer more or less styling, change it to match your taste.
Mapping the Content
The last step entails teaching the
Playground how to organize its content. You will use the
contents.xcplayground file to complete this task. Open this file in a text editor and update it to match the listing below.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<playground version='3.0' sdk='iphonesimulator'>
The XML inside this file remained largely the same. The only difference is that you have added a tag called
documentation. As you can probably guess, the role of this tag is to specify the location of a
.html file for the
Playground. This HTML file describes the web page content for the first section of the
Playground. Finally, the order of the elements within the
sections tag determines the order in which they will appear in the
Make sure that you have saved all of your CSS and HTML files and that they are in the appropriate folders. If Xcode is open, go ahead and close it. Reopen Xcode, select
Interactive.playground and you should see something like the image below.
Playgrounds are among the most exciting new tools for the Mac and iOS developer. They are a great resource for rapidly testing and developing solutions to a problem. The tight feedback loop between the Playground and the user can also serve other purposes.
Playgrounds offer some pedagogical benefits as well. Done well, a
Playground can be a presentation tool with a full Swift REPL inside of it. It is also feasible that entire lessons can be mapped out in a single, or collection of,
Playgrounds. Each section of the
Playground could describe a new concept or pattern, and then be followed by a section for writing Swift code.
It is worth mentioning that there is more to explore in
Playgrounds. For example, I didn’t cover using the
Resources folder. You can use this folder to expose a variety of assets to your
Playground, as demonstrated in the
Balloons.playground. I leave it as an exercise for the reader to experiment with this feature.
Playgrounds even have an API that you can explore. Type in
import XCPlayground at the top of a
Playground and command-click on
XCPlayground to see what is available. Functions like
XCPShowView(_:, view:) look particularly interesting. Check back here soon for another post exploring this API.