Contents.swift is the source file where your users interact with the playground source code.

You can also use it to add playground prose that's shown to your users using special markup comments within that swift file. The Playground Markup Prose describes what the user is to do - providing objectives, goals, and instructions.

hacks_IMG_0010_2_copy.png
Example from Swift Playground for Bluefruit

When you open the Swift Playground Book for Bluefruit, you'll notice that the Playground prose is separate from the Playground source code. To create a prose we'll add a Block Comment Marker in the Contents.swift file.

Block Comment Marker

Using a Block comment marker helps you to enclose multiple lines of text containing markup delimiters. Here's what that looks like:

/*:

"Your Content"

*/

Here's an example of a Block comment marker in the Contents.swift file of the Swift Playground book for Bluetooth:

/*:
**Goal:** Learn how to use basic movement functions.

It’s time to race! Start your engines!

Use your Swift programming skills to control the Robot Rover with **basic motion** function calls like `moveForward()`, `turnRight()`, `turnLeft()`, and `moveBack()`.

*/

Once you've added the block comment marker to your playground book, you'll notice lines between the opening and closing comments that you've added. The Block comment maker does not interfere with the process of run your code.

Now let's look at the Playground Source Code.

Playground Source Code

The Playground Source Code is where your users interact with your playground book adding their code. This is where your users enter their code. Once they've added their code, they'll hit the "Run My Code" button to execute what they've written. 

hacks_SourceCode.png
Example from Swift Playground for Bluefruit

Hidden Code

You can hide code that doesn't relate to the content of your playground page to do things like importing frameworks or code completions ... basically anything that you don't want the user to see or manipulate.

Hidden code is still executed when the playground is run and all of the public symbols are accessible on the playground page.

Hidden code can be placed between //#-hidden-code and //#-end-hidden-code. Here's an example of that in the Contents.swift file.

/*:
 **Goal:** Learn how to use basic movement functions.
 
 It’s time to race! Start your engines!
 
 Use your Swift programming skills to control the Robot Rover with **basic motion** function calls like `moveForward()`, `turnRight()`, `turnLeft()`, and  `moveBack()`.
 
 */

//#-code-completion(everything, hide)
//#-code-completion(identifier, show, moveForward(), turnLeft(), moveBack(), turnRight(), wait(), wheelie(), dance())
//#-hidden-code
import Foundation
import PlaygroundSupport

setup()

//#-end-hidden-code

//#-editable-code 

moveForward()

//#-end-editable-code

//#-hidden-code

//#-end-hidden-code

Editable Areas

Editable areas work the same way the Hidden Code does. You'll need to add inline editable areas within your playground book so that you can receive code entered by the user. It's very simple to add an editable area, here's how you add one:

//#-editable-code 

"Add your code here"

//#-end-editable-code 

Runtime Errors 

Swift Playgrounds will display runtime errors that occur in the Playground book. Swift Playgrounds is able to determine which line of code caused the execution to crash and then highlights the line with the text that's provided.

This guide was first published on Dec 22, 2017. It was last updated on Nov 14, 2017.

This page (Playground Markup and Source Code) was last updated on Nov 21, 2017.

Text editor powered by tinymce.