Authoring Swift PlaygroundBooks — part 1
PlaygroundBook structure
Hello, world!
Since I started my Youtube channel, the “Programa de Indio”, I have been going deeper into the creation of PlaygroundBooks, so I want to share here with you a little bit of my learning journey.
If you still don’t know about the channel, take a break here and check it out. I guarantee you will enjoy it! Don’’ forget to sign up to continue watching the videos, ok? Most of the videos are in Portuguese, but you can always enable closed captions!
My desire to work with Swift Playgrounds increased when Apple started using playgrounds to assess students in the annual Scholarship for the WWDC: a celebration of students from around the world aiming to become iOS developers and willing to participate in the biggest iOS developer event promoted by Apple.
Every year, I see that people are raising the bar on playgrounds and there have been some really amazing things coming out of that.
If you never worked on Swift Playgrounds, check it out. It looks like this:
Available for iPad and mac, it’s a platform mainly used to study Swift programming logic through PlaygroundBooks (these interactive and fun books). This one in the image above is called Learn to Code 1, in which the character called Byte presents the initial programming concepts.
It may looks pretty simple, but the app is a great tool for learning and testing code. And it is not exclusive for those who are starting now. Developers use the platform to test some algorithm before applying it to the main project.
In the application it is possible to use some basic templates to start coding. These are called Starting Points!
Each of them has a well-defined structure that gives access to some of Apple’s main frameworks and other ones that were created specifically for the Playgrounds.
If you are already a developer, keep an eye out for news! This year we have some new templates that give you access to accessibility frameworks! Check out the videos from WWDC2020
In this series of articles, I want to show you how to go beyond the basics and become an author of amazing playgroundbooks!
Each of these templates can be duplicated and changed by any user. However, if the file is reset, it returns to its original state. If we use a template of the default blank type, for instance, when we reset it, all our change is lost.
While this is interesting for learning, as we can always go back to the starting point, it can sometimes be quite frustrating when you distribute a snippet of code.
Here are some situations where this can be a problem:
1. Creating from a template
In the youtube channel I have been discussing a lot about Generative Art and looking to create simple algorithms with cool visual effects. In one of the videos I talked about the 10Print algorithm. Check it out:
In the video, I developed a playgroundbook with the main classes I have created for displaying this piece of Art.
So far so good! Now imagine you want to build something on top of what I started. If you duplicate this file and start editing, you’ll have something new within minutes. But imagine that you had a code problem, which caused your playground to crash and you had to reset it to be able to continue coding. Everything you did and everything I did was erased once I used the blank template.
One way we can get around this problem is to generate a PlaygroundBook that works as a template. Thus, it will have the code base that will be kept every time it is reset.
2. Creating classroom content
If you are a teacher and are creating content for your programming classes you may want to leave your code base unchanged and allow the student to continue editing only what is convenient for the moment.
With a well-defined template, you can determine which part of the code can be changed, create animated opening scenes for each chapter, assess your student’s progress and much more. And most interestingly, you can share the basic PlaygroundBook with students without fear that it will be lost.
The structure
OK! Now that we’ve talked about why we use a custom PlaygroundBook, let’s dive deep into the structure of this file.
Just like a book, the PlaygroundBook is made up of chapters and pages, which are presented throughout the student/user experience. The file that is generated in Apple’s Playgrounds app has the extension .playgroundbook.
By accessing Apple’s documentation, it is possible to identify its parts, but you have to navigate between several pages to understand how it works. But in the end, it’s not that complicated. Let me show you!
In practice, the .playgroundbook format file is just a compressed folder with a structure of other folders and files needed for the app to work well. It looks like this:
Isn’t it simple?
Just one folder called Contents and another one called Edits.
Okay, I know it’s not just that! But trust me that even though we have more folders and files here, the structure is still pretty smooth.
The Contents folder is responsible for holding all of your playground’s base content. That is everything that should remain when it is reset.
The Edits folder, in turn, is created from the moment you run the playground and start making your changes as a user. That is, everything you modify in a playground is saved here.
You will see that its content is very similar. Let’s start by detailing the Contents folder, which will be the focus of this article series.
Inside it, we have two new folders: one for the chapters and one for the code modules of our project. Also, we have a file called Manifest.plist
Manifest.plist
Let’s talk about the file first. The plist format (which comes from Property List) is nothing more than a specific XML domain, a DTD. Did I speak Greek? Let’s take it easy! XML is a markup file format that serves to determine elements and their relationships. A DTD defines which elements are valid in this domain.
If I open this file on Xcode, this is how it looks like:
See that it is a list of properties. Each property has its name, or key, a type and a value.
For example, the last property of this file is called UserModuleMode, it is of type string and its value is Full.
Xcode actually created a cute tabular view of this XML file. But actually it looks like this:
Here I opened the same file in the common mac text editor.
Calm down, don’t be scared!
Breathe and take a look at it again. Some words in this code you already know!
In the image, the first 4 lines are there to say that this XML must be validated as a specific properties format created by Apple (the DTD, remember?).
Then we have a tag called dict. Tag in a markup language indicates an element. Every element needs to be opened, have its content indicated and then closed. In XML (and derived languages such as HTML), a tag is delimited by the < and > signs. When we’re talking about a closing tags, we add a / after the first sign.
Look again at the image, on the fifth line we have the <dict> tag and on the penultimate line, the </dict> tag. This means that all the content between the two is part of this element called dict, which is an abbreviation for dictionary.
Analogously, we can analyze the tags inside of this element. See that we have a pattern. We always have a key tag followed by another tag that can vary depending on the context. Thus, the key tag represents the name of the property and the tag that comes right below it represents the type and value.
Can you identify the same property we saw in the XCode example (UserModuleMode)?
That’’ easy. It is right before the</dict> tag. Ee have two other tags (in the two lines above). Here:
Great! We then have the UserModuleMode property, of type string (which is a text format) and its value is Full.
Exactly as we checked in XCode.
XCode presents the file in a friendlier way, but you don’t necessarily need this app to work with your playgroundBook. You can edit these properties in any text editor.
But what is this file for?
Its purpose is to connect the folders we have created in a way that the compiler (the Playgrounds app) can understand.
This is a contextual file, which means that it determines the properties of folders and files that are on the same level as it.
In a PlaygroundBook we will find other files like this. This is the first one and brings the properties of the book as a whole.
Throughout this series, we’ll change several properties in this file, but if you’re curious about what they are, here’s the link to the official documentation:
Chapters and Pages
Each chapter of a PlaygroundBook is created inside the Chapters folder:
Inside this folder we have a folder for each chapter. In the case of this example, we have only one chapter. The folder name can be determined by you and should always end with .playgroundchapter.
We have another Manifest.plist file there, which will now bring the properties of this chapter. Plus, there’s a new folder there called Pages.
And what do we have inside the Pages folder? I’ll give you a candy if you can guess!
Exactly! a series of folders for each page of our chapter. Each page folder has a properties file (what a surprise!) and a swift file with its code.
Note that page folders end with the format .playgroundpage. We’ll see more about them and the template folder later.
That’s it! That simple. A set of folders, properties files and code files.
Something is missing? Oh yes, the modules!
Modules
In the UserModules folder we will have all the Swift code that can be used.
See that we have a SharedCode.swift file there. In it we can store the first algorithms shared with the user.
But are we going to talk about this in another article. Ok?
Don’t be afraid to do something wrong! It may seem like a lot, but little by little you will become familiar with the structure.
This series of articles is organized to help you increasingly get to work with the PlaygroundBook.
Be brave! Let’s create something wonderful at the end of the series, ok? Don’t hesitate to call me if you need a helping hand. And if you haven’t signed up for my Youtube Channel by now, go there and hit that button!
See you!
