Authoring Swift PlaygroundBooks — part 3
Adding a cover
Hello, world!
Now that we have our Polar Roses Playground structure ready, let’s start customizing our book. The first thing we can do with quick visual feedback is add a cover image!
And this activity may seem pretty simple, but it’s the starting point for us to begin to better understand the property files that make up PlaygroundBook. Come on?
Preparing the image
According to Apple’s documentation, the image must have an aspect ratio of 4:3 to fill all available space for the book’s cover. It is recommended to create an image of size 400px x 300px and minimum 72dpi.
This is the time to get creative and create an image that references the content of the book. See how the colorful covers with well-designed images draw a lot of attention on Playgrounds:
In the bottom section, we see several playgroundBooks covers created by Apple and in the top section, we have several other books that represent templates for the already known ones. See there is a pattern. Many authors have followed this pattern.
From what we see, the books have colorful and flashy covers, while the creation templates have a color pattern in a gradient that goes from blue to red.
Is this pattern mandatory? Not! But it’s very beautiful and makes us easily recognize when a book has developed content or makes code available for free creation.
With that in mind, I created an image for our example that conforms to the template pattern, since what we are creating is a basis for creating generative art.
See that the cover follows the template pattern, giving the impression that it’s possible to create something new from this book. The central figure is a polar rose, so we can easily identify our book among the others.
Opening the folder structure
Ready! Once we think about the design of our image, we need to save it inside our PlaygroundBook structure. Not sure where to save? Follow these steps:
- Open the Swift Playgrounds app
- Right-click on your file and then on the option show in Finder. You will be redirected to the Finder App, in the folder where all your playgroundbooks are.
P.S.: You can access directly from the iCloud > Playgrounds folder
3. Now let’s open this file to show its structure. Right-click on the file and then on Show Package Contents:
Great! You’re directed to the folder that contains the structure we introduced in the first article in the series. You should be seeing the Contents and Edits folders, as shown in the following image:
Saving the image file
Excellent! We’ve already been able to access the structure, now let’s create a new folder called PrivateResources. In it we will put all the files that will be resources for the book as a whole. It can be images, videos, audio files…
Copy the image file into this new folder.
The image name does not have to follow a specific pattern, but the folder must have the exact name PrivateResources (camel case). I suggest you adopt your own standard to name your files intuitively.
Editing the Manifest file
Last step: edit the property list!
Let’s add a new property to the Manifest.plist file inside the Contents folder. Remember that this file is contextual, that is, it determines the properties at the level of the directory in which it is located. In this case, we are editing the properties of the book as a whole.
Add the following lines of code just before the </dict> tag
Note that the property is called ImageReference, written between the <key> and </key> tags. its value is a string (a type of text) and the value is the same as the image file name: cover.png.
If you’re editing this file in a simple text editor, like TextEdit on mac, for example, you have something like this:
But if you’re editing through XCode, you have something like this:
The two images have the same file, but the first shows its content in native text form, while the second shows the table view generated by XCode.
Feel free to edit as you see fit.
Save the file and go! You should already be able to find your PlaygroundBook with the beautiful cover we created!
Here we have the book generated in my Youtube channel, with the black cover and the template that we are creating with the template cover. See how easy it is to spot them among others!
See how easy it was? Step by step, we’re going to create an amazing PlaygroundBook! We start with the cover and at the end we will have a very nice template to work with Polar Roses.
Take the opportunity while opening the next article to take a look at my Youtube channel. I’ve been creating a lot of cool stuff with Playgrounds over there!
