Authoring Swift PlaygroundBooks — part 4
Chapters and Pages
Hello, world!
You may have noticed that most official Apple PlaygroundBooks have a good division of content into chapters and pages. See the image below for the book Learn to Program 1.
The chapters were organized by specific programming logic topics. The pages, in turn, were organized in order to present the chapter content in a fluid and dynamic way, so the student can follow their progress throughout the study.
The Playgrounds summary presentation is very simple:
Chapters are represented by the leftmost text (with the option to show or hide via the arrow next to their name). Pages are grouped further to the right. The selected page has a vertical marker in front of the name.
But how to create new chapters and pages?
Adding Chapters
You may have noticed that there is no option for this in the Swift Playgrounds app, as the idea is to keep the template created by the author, even if it is an empty template. So we need to go back to the file’s folder structure.
Remember how we can access the structure
1. Right click on the playground and click Show in Finder
2. Right click on the file and then Show Package Content
To create a new chapter, just duplicate the first chapter folder and rename it. Then change the manifest.
See that in the structure of a chapter (folder Chapter1.playgroundchapter), we have some well-defined things:
- The folder name must end with the .playgroundchapter extension
- Only the last chapter can contain page templates
- There must be a Manifest.plist file
- It must contain a Pages folder with all folders related to the chapter.
Let’s talk about every detail of these:
Folder name
The name of the folder that has the chapter data is not the name that appears in PlaygroundBook. You can put more intuitive names for programming, like Chapter1, Chapter2… as long as it always ends with the chapter extension.
The actual name of the chapter, which appears in the summary, will be configured later in Manifest.plist
Templates for Pages
Some books allow the student to add a new page to it, which can be seen by the + button that appears when hovering over the table of contents:
However, it is only allowed (by the official documentation) to add pages to the last chapter created. This template is presented in two parts:
- Template.playgroundpage folder inside Chapter Pages folder
- TemplatePageFilename property in Manifest.plist file
If you duplicate the first chapter folder of the basic template, these settings will be duplicated. Be aware of this. Remove folders and properties so there’s no problem running your book.
Only leave this default setting in the last chapter and only if your intention is really to allow the student to create a new page.
Remember that when the student creates a new page it is created in the Edits folder, that is, it can be lost when resetting the PlaygroundBook
Manifest
Now let’s deal with the properties file inside the chapter folder.
Remember that it can be edited in any text editor, as shown in the images below (same file opened in XCode and TextEdit). Don’t you remember? Go back to the first article in the series for a moment.
Note that we only have two properties in this file: Name and InitialUserPages.
As expected, the Name property defines the actual name of the chapter. In the default case it comes with My Playground. Change to the desired name.
The second property is a chapter page list. See that we have an <array> tag and inside it a <string> tag with the name of the default page folder. When creating new pages, remember to add new <string> tags here with the created folders.
Pages
Finally, each chapter must then have the Pages folder with the pages that belong to it. We’ll talk about this folder later as we add new pages.
Editing the main Manifest
We’ve added new folders and set up the chapters, but they still don’t show up in our book. In order for them to appear, we need to configure the properties of the main manifest.
Navigate to the Contents folder in the PlaygroundBook directory root. Open Manifest.plist. It’s the same one we used to add a cover in the previous article.
In the image below, I have highlighted the list of chapters, which we are going to edit, and separated a pair (key-value) with a blank line, to help you visualize the information.
In this selected region, we must add folders for the new chapters. Just duplicate the <string> tag inside the <array> and change the name to match the folder you created:
In short: I duplicated the folder, changed the name property in the manifest inside each folder, and added the chapter to the main manifest.
Adding new Pages
The process here is similar to what we did with the chapters:
- Duplicate and rename the page folder
- Change your name on Manifest.plist within this page
- Add the new page to the chapter’s Manifest.plist.
Adding a new page in chapter 2, we have something like this:
See that I renamed the folders on each page to better organize the directory.
The manifest on page 2 looks like this:
The only change was the Name property, which has the actual name of the page (which appears in the book’s table of contents).
I’ve already highlighted two new properties in the page manifest:
- LiveViewEdgeToEdge — tells whether the playground interaction area fills the entire screen or not. Its default is NO, indicating that it occupies the right half of the screen. If YES, this area occupies the entire screen.
- LiveViewMode — tells whether the interaction area (Live View) should appear open on page opening or not. By default it appears hidden (HiddenByDefault), but it can be displayed by default with the value (VisibleByDefault). We’ll talk specifically about this topic in a later article at the end of the series.
This is the summary of what was generated:
Quiet simple, right? Added chapters, created pages, now all that’s left is to start working on customizing the content!
