Interactive Learning Document Format Reference

An interactive learning document is a kind of playground that lets the reader interact with code mixed with rich HTML content. Its file format is a package that contains Swift source code, HTML content, assets such as CSS and images, and a manifest file.

For example, the directory structure of an example document is as follows:

• My Example.playground
  • contents.xcplayground
  • Documentation/
    • style.css
    • Art/
      • cow.png
      • dog.jpg
    • section–1.html
    • section-3.html
  • Resources/
    • data.json
    • background.png
  • section–2.swift
  • section–4.swift

The manifest is an XML file named contents.xcplayground at the top level of the package. Example contents.xcplayground file shows the manifest file for an example playground.

Listing 2-1  Example contents.xcplayground file

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<playground version=‘3.0‘ sdk=‘macosx‘ allows-reset=‘YES‘>

    <sections>

        <code source-file-name=‘section-1.swift‘/>

        <documentation relative-path=‘section-2.html‘/>

        <code source-file-name=‘section-3.swift‘/>

        <documentation relative-path=‘section-4.html‘/>

    </sections>

    <timeline fileName=‘timeline.xctimeline‘/>

</playground>

The manifest contains the XML elements described below.

playground

Root element of the XML file.

Contains one sections element and one timeline element.

Attributes

version

Required. File format version. Use 3.0 as the value.

Important: Always check the version number. The interactive learning document file format is expected to continue to evolve. Future versions of this file format might have different elements, attributes, or structure.

sdk

Required. SDK used by the playground. Use macosx for OS X or iphonesimulator for iOS—Xcode always uses most recent version of the selected SDK.

allows-reset

Indicates whether users can edit the playground and then reset it to its original state. Use yes to enable resetting or no (the default).

If resetting is enabled, when the user edits a playground, Xcode saves a copy of the original source code files at the top level of the package, adding the suffix -original to their filenames. These original files do not appear in the manifest and shouldn’t be edited.

sections

List of the sections of the document.

Contains documentation and code elements.

documentation

HTML documentation section.

Each HTMS documentation section is rendered in its own web view. This means, for example, that JavaScript running in one section can access the DOM structure of only that some section.

Attributes

relative-path

Required. Path to the HTML file relative to the Documentation folder at the top level of the package.

All HTML files and resources such as images and CSS files that are used by the those files are stored in the Documentation folder. You can organize the Documentation folder with subfolders.

code

Swift source code section.

The file names of code sections are not guaranteed to be preserved after the user edits the document in Xcode.

Attributes

source-file-name

Required. File name of the Swift source file.

All Swift source files are stored at the top level of the package.

Assets such as images and input data that are used by the Swift code are stored in the Resources folder at the top level of the package.

style

Display style for the code fragment.

To display the code in a disclosable region, use setup as the value.

timeline

Xcode timeline information. This element and the file it refers to are populated by Xcode based on the items in the playground’s timeline, and shouldn’t be edited by hand.