Using Swift Playgrounds & Playground Books

9 min readApr 2, 2019

I’ve recently had a condensed 10 day experience with the playground development suite by working on my WWDC 2019 Student Scholarship application BeatMatch (check it out here). I will be using my project for the examples in this article. If you don’t know what a playground looks like on an iPad feel free to watch my youtube video here.

For those that aren’t familiar with the student scholarship you need to submit a creative playground (can be anything) alongside some written responses. There are a few thousand applicants every year and this year Apple says in their terms and conditions that they will be selecting up to 350 giving the winners a free ticket, lodging for the week, an early day of activities (meeting Tim Cook!), and food.

What is a Playground?

A playground is a quick way to flesh out ideas, try out a new api, and have a closer interaction between code and UI. You may have used playgrounds before as a quick way to try out an algorithm in Swift but they’re much more versatile than meets the eye. These playgrounds can be run in Xcode (with targets for iOS, macOS, and tvOS) or run on an iPad in Swift Playgrounds (their proprietary iPad app on the App Store which lets you run playgrounds).

Starting a playground you will see you have playground level “Sources” folder (for code) and a “Resources” (for assets), adding a new playground page gives you nested pages with their own sources and resources. When you first start your playground you will just have one page which is named after your project. This page is of type .playground. Additional pages that you add will be of type .xcplaygroundpage. With all these pages a playground can be thought of as book, different content can go on different pages.

A good way to think about the utility of a playground is if you have an API in which you want to make the onboarding process easier. You can setup a playground that will take the developer through different pages and allow them to play around with different parts of it on each page.

Here’s how my game, BeatMatch, looks like in Swift Playgrounds (remember this is the iPad app that runs playgrounds and playground books).

What is a Playground Book?

A Playground Book is a playground with extended functionality that runs exclusively on iPads. With these you can add an “app icon” for your playground, make your playground go full screen and is generally a more flexible, albeit complicated, option. Taking a look at the file navigator you can see that the folder structure here is a lot more complicated and that we’re also running in the full Xcode IDE.

Now let’s see how it looks in playgrounds.

A lot better, right? The game is running full screen, we have a book cover image and once you open it up it tracks your progress through the chapters and pages.

Playgrounds Vs. Playground Books

With a playground, you can add source code and assets to run your playground in the live view simulator directly in Xcode, or run it on your iPad. With a playground book, you don’t get a live view since you’re using the Xcode IDE, instead you can use your device simulator or you export to your iPad.

One issue I ran into was that I started off my project as a playground and whenever it was running on the iPad and the keyboard came up it would squish the view… Yikes, playgrounds might not be the best option if you’re going for an iPad experience.

When Should I Use A Playground?

When you’re just looking to provide a simple app/code interface to either try something out or teach people how to use an API. There’s no reason to use playground books if you don’t have an iPad.
You’re trying to do something quickly, like try out a new view component for your app. Playgrounds are convenient because they can be added into your Xcode project space giving you, or your developers, a place to flesh out ideas.
You want code completion. That’s right, Playground Books in the Xcode IDE does not offer code completion.

When Should I Use A Playground Book?

When you’re trying to create a more immersive experience for Swift Playgrounds (on the iPad).
If you want to communicate from your left pane (where people type in code) directly with the view in real time without having to re-run the code.
If you want to have chapters and pages (these are just tools you can use to structure your playground and the end user experience).
You don’t want your live-view area to be squashed whenever the keyboard comes up on an iPad.
For your WWDC Student Scholarship Submission if you’re using a Swift Playgrounds submission type (ie. you’re telling the judges to run your submission on an iPad).

Why I switched from Playgrounds to Playground Books

I had spent the first 9 days, we only got 10 days this year for our submission, working out of a Playground. It was simple and easy to use. One of my last issues was the keyboard crushing the view when it came up. So I then set out to learn and transfer my playground over to a playground book. This is the ONLY way since playground book pages have a property called LiveEdgeToEdge display (specified at the page level manifest.plist) which lets you fill up the view BEHIND the buttons.

Getting Started With Playgrounds

First step is to create a new playground by going to File>New>Playground inside Xcode

Picking the “Single View” option you’ll see that the template code declares a controller class and presents it on the current Playground page’s “LiveView”

To see the live view make sure your assistant editor is on and that you select your current playground page under the live view

If you press the play button on that blue line up to line 21 you will see the controller presented in the live view

And that’s it! That’s all the setup needed. You can add pages, add your own source code and run it in the live view.

Important Notes:

Classes, structs and enums inside the sources folders MUST be declared as public for your pages to recognize them.
It’s normal for the Xcode playground IDE to crash while you’re working on it, especially if you CMD+S after every little change like I do. The most you can do is submit bug reports to Apple and hope that the Xcode team will fix it up.

Further Resources:

Getting The Most Out Of Playgrounds WWDC 2018

Getting Started With Playground Books

To preface this, the setup is considerably more complicated, patience is necessary because rushing through is bound to give you issues. The documentation is very good so I can at least guide you through what to read :)

First step is to read this page and download the Swift Playground Books Author Template
Next is READING THE README (you seriously don’t want to skip out on this)

The README will tell you everything you need to know about structuring the manifest files, changing the chapter names, page names, and adding chapters and pages. Play around with it and make sure you get a solid feel for the folder/manifest structure. Remember to not deviate from the structure or else your playground book will not work, there’s a reason Apple gives you a template for this.

At this point all you care about is what’s in the “PlaygroundBook” folder. You have your Chapters folder holding the .playgroundchapter folders, and nested inside those you have .playgroundpage folders for your pages.

Manifests

You let your playground know about its chapters and top level properties by updating the playground level manifest. You let a chapter know about its pages by updating the chapter manifest. The page level manifest is used for page specific things.

Running it!

In playground books we build the target “PlaygroundBook” which builds to your Products folder. To use it you have to right click show in finder then send that to your iPad (I use airdrop).

Notice that what you’re sharing to your iPad is a .playgroundbook file, the build target specifications packs it all up into a bundle that is similar to how a regular playground looks in the XCode playground IDE.

Now that looks pretty straight forward, hopefully this is a clear representation of how a Playground Book works.

Adding Stuff To Our Playground Book/Manifest Options

To add your own files you want to to add it directly to the PlaygroundBook > Sources / Private Resources. Either right-click and select “New File” or select “Add Files” making sure the “copy items as needed” is selected and that the target is the PlaygroundBook.

Inside the playground page folder

By default you have 2 main files you can use, a Contents.swift file and a LiveView.swift file. The Contents.swift file is what the user sees on the left hand side of the screen and the LiveView.swift file is what the user sees on the right hand side of the screen.

The code inside the LiveView.swift file is ran when the page opens up NOT when the user presses “run code”. Any communications between the Contents.swift file and the LiveView.swift file must be done through messages. Having both these files is necessary if you’re trying to build a playgroundbook like this.

In my case I opted out of using messages to communicate between the Contents and LiveView (due to time constraints) and instead figured out that if you delete the LiveView.swift file you can just have the LiveView be populated when “Run Code” is pressed. Another reason to not have a LiveView is if the page only contains text that you want the user to read.

Important Notes:

Due to the lack of code completion, I’d recommend having a regular playground in which you make changes then copying it over into your playground book.
If you try adding a new page or chapter folder and Xcode refuses to open up that folder inside your project you need to work out of a different IDE, or add content manually inside the project using Finder. This happened to me and it took Xcode a while before it let me open up those folders.

Further Resources:

I’ll leave this one up to Apple, the documentation is solid.

That’s everything, I hope I’ve been able to help out with getting started! If you have any questions feel free to leave a comment and I will get back to you as soon as I can. This is my first medium story and I look forward to publishing more on topics such as using a MTKView to process and display a live camera feed, using the Metal and Accelerate frameworks for audio visualization and more :)

Don’t forget to clap and follow!