Guide learning by marking code that learners can change or copy forward.
You mark a region of code as editable by surrounding the region with a special comment syntax. You use editable and noneditable regions of code to guide learners to the part of the code they should change while completing the task on a page.
By default, all of the code on a playground page is editable until you add at least one editable region. Marking any region in a playground page as editable locks the rest of the code on the page. For playground pages geared toward beginners, restrict the editable area to a small region to avoid accidental edits that might be difficult to recover from.
Mark Inline Editable Areas
You use an inline editable area to let learners edit a small region of code. For example, you might want to progressively disclose how a larger region of code works by first letting a learner experiment with changing a single value or variable to see how it influences the execution of the whole page.
You add an inline editable area by using the special comment expression:
The placeholder text is text that's displayed until the learner starts editing and adds their own code. The content is text that represents the default value for the Swift code until the value is edited.
The inline editable area in the example below displays “number of repetitions” until edited, and uses
1 as the initial value for the Swift code.
When displayed on a playground page, the code from the example above is displayed with the placeholder text in a tappable button that activates editing.
Mark Multline Editable Areas
You use the same special comment syntax to mark editable areas that span multiple lines.
The content you write inside multiline editable areas must be indented to the same level as the surrounding code.
Mark Editable Areas with Placeholder Tokens
You can add placeholder tokens to editable areas. Placeholder tokens are rendered as selectable labels and can contain spaces and special characters. You can include the name of any Swift type in a placeholder token to restrict the type of values entered in the editable area.
Selecting a placeholder on a playground page shows the shortcut bar. Selecting a placeholder with a defined type shows a type-specific popover, if one exists. For example, if a typed placeholder specifies an
Int; selecting the placeholder opens the number-entry popover.
The following shows variable declarations with untyped and typed placeholders tokens.
The image below shows how a placeholder token with an
Int type displays a number entry interface.
Mark Editable Areas as Copyable
You can mark editable areas with an identifier that lets learners reuse code between pages. Mark an editable area as a source area by using the
end-copy-source comment syntax. Mark another editable area as a copy destination by using the
) comment syntax. Once you've marked both the source and destination areas, the code a learner types in the source area becomes available in the destination area if they've passed the source page's assessment.
Copy-source areas depend on information you specify in the playground page's
Copy dictionary. Use the following keys and values in the
Copy dictionary to configure a copy-source area:
Command Button Title
The title for the copy command button. If you don't specify a title, it's set to “Copy my code.”
Command Button Title
The title of the button used to copy the default code to the current playground page. If you don't specify a title, it's set to “Start with provided code.”
Command Button Title
The title for the navigate command button. If you don't specify a title, it's set to “Go to
<PREVIOUSis substituted for the name of the previous page.
Ready To Copy Instructions
Required. The text to show when the code isn’t ready to be copied to the current page because the learner hasn't passed the required assessment.
To Copy Instructions
Required. The text to show when the code is ready to be copied to the current page.
For more information on configuring a page's manifest, see Specify the Page Name and Metadata.
The example below uses a copy-source area named
id1 to arrange the page so that when a learner changes the code in the editable area to a different emoji, such as 🤔, the new emoji replaces the default emoji in copy destinations that reference
The following uses the identifier from the code above to determine which code to copy forward into a copy-destination area.