iOS reference

The details behind the quickstart for iOS: what the HotLayout Swift package takes, what it does with documents, themes, data, actions, language, pictures and the network, what it reports, and how it decides whether it can read a document. The quickstart is the path from an empty app to a published screen; this page is the reference, ordered by topic. The README of the package is a short introduction.

What each schema minor added is in the contract changelog, and which package version reads which minor is in Which package reads which schema. What changed in each package version is on the releases of the package.

Related pages: quickstart for iOS · widgets · compatibility · placements · localization · theme · data dictionary

The package#

The public API#

Everything below is in the module HotLayout.

Drawing a document#

HotlayoutScreen(document:…) draws a document. The quickstart shows it with the usual callbacks; this table is the whole list.

The reader keeps its own stack of screens and performs navigation inside the document. It draws only the document and takes the size your layout gives it.

Loading a document and a theme#

do {
    let document = try HotlayoutDocument.load(documentData)
    let theme = (try? HotlayoutThemeSet.load(themeData)) ?? .builtIn
} catch let error as HotlayoutLoadError {
    // a document the reader cannot use: show your own screen
}

HotlayoutDocument.load(_:) and HotlayoutThemeSet.load(_:) take Data (or a parsed JSONValue) and throw HotlayoutLoadError. The quickstart reads them in .task so that the JSON is read once, and shows ProgressView() until it is: not an empty Group, because an empty view on the first frame never runs .task.

A theme that cannot be read is not a reason to refuse a screen: use HotlayoutThemeSet.builtIn. Where the document and the theme come from is your choice: your backend after a signed webhook, or the published address of the project. See Delivery options.

Version compatibility#

HotlayoutVersions.checkDocument(_:) applies the version rule without reading the whole document, for a host that wants to decide before it loads (and keep the old screen when the new document is too new). HotlayoutVersions.check(_:readerVersion:) takes the version to compare with. The rule is the same in every reader and is described in the compatibility policy: the major must match; a newer minor opens and the reader skips what it does not know.

Older package versions and what they read are in Which package reads which schema.

Data#

data maps paths to values, ["user.name": "Maya", "user.points": 1850]. The rules are the same for every reader: a number stays a number, dates are ISO 8601 strings with time and zone, a missing value shows the fallback of the document, and a list draws at most 50 records. Which paths exist is defined by the project's data dictionary; what your backend returns is in the backend guide. The reader takes the values you pass; it never calls your backend.

Language and right-to-left#

Pass the device locale as is: the reader picks the document's language by the contract's rule, formats numbers and dates for it and mirrors the layout for right-to-left scripts. LocaleResolution.resolve(_:available:source:) tells which translation, number format and direction a locale gets. See Localization.

Device language. Locale.current gives the language of the device only if the app declares the languages it is localized for (the app's localizations in the Xcode project, or CFBundleLocalizations in Info.plist). Without that iOS reports English, and a document that has an Arabic translation stays English on an Arabic device. Declare the languages of your documents, or pass Locale.preferredLanguages.first as locale.

Actions and navigation#

• Navigation inside a document (navigate, navigate.back, navigate.section) is done by the reader; onNavigate may cancel it by returning false.
• openUrl, deeplink, close and the actions of your app go to onAction. The reader opens nothing itself. A standard action arrives checked against the forms of the contract, and StandardActions.url(for:allowedDeeplinkSchemes:) checks it again before you open it (the form of the address, the scheme of a deeplink against the allowed ones), so an action assembled by hand is not trusted because of its type.
• An onAction may be async. A button that confirms by a swipe then stays busy until the handler returns; with a plain handler it stays busy until the screen changes, or eight seconds:

HotlayoutScreen(document: document, onAction: { action, source async in
    if action.type == "redeem" { await redeem(source.record?["item.id"]?.stringValue) }
})

source.record is the record of the node that was pressed: a row of a list carries its own record, so one handler serves every row.

Swipe fill#

A swipe button with confirmTransition: 'ripple' that leads to another screen fills the screen with its colour before the screen changes. By default the fill lies over the view of HotlayoutScreen and the reader changes its own screens under it. If your app keeps its own stack of screens (you cancel the change with onNavigate and show your own view), pass onScreenCovered: the fill then lies in a layer over the whole window, above your views, so it outlives the screen the button was on. The handler gets true when a fill starts to cover the screen, before the action reaches onNavigate or onAction (change your screen then, without a transition of your own), and false once the last fill is gone. With no window to draw in there is no fill and the action runs at once.

Writes#

Fields, setValue and toggleValue write to the session of the screen and to onWrite, with a string, a flag or a number. WritablePaths says which paths a document may write; by default every path of the form of a data path is allowed. A path that is refused is written neither to the session nor to the host.

Images#

Images load only from an address of the form of an openUrl address (https: and a public host name) by default. Pass an ImagePolicy as images to decide yourself:

A refused address makes no request and goes to onReport.

Fonts#

Fonts are the app's: the package ships none. A family the theme names that the device lacks is drawn with the system font.

Accessibility and labels#

The few texts the reader says to assistive technology (the name of the back arrow) are not in the document. Pass ScreenLabels in the language of your app as labels; the defaults are English.

What the reader reports#

onReport receives a list of HotlayoutReport: what the reader skipped or replaced in the document, the theme or while drawing, for your log or analytics. Each report is handed over once, as it appears. It is never shown to the person.

• Documents, themes and data are untrusted input. A piece of the wrong shape is skipped and reported, never a crash. A tree deeper than 32 levels is refused.
• Lists draw at most 2550 instances of list templates per screen, nested lists included; what is beyond is not drawn and is reported once.
• Haptic feedback is asked of the host (onHaptic); the reader never vibrates.

The trust boundary and the tests that pin it are described in the security notes of the package.

Placements#

A placement is a named place of your app (home.banner). The app names the place in code; which published document stands there is decided in the admin, and changed without a release. The files and the rules of the map are in Placements; this part is what the iOS reader does with them.

// Draws what the admin put in the place `home.banner`, and nothing when it is empty.
HotlayoutPlacementView(
    name: "home.banner",
    projectBase: projectBase,
    onPlacement: { placement in
        if let report = placement.report { print("home.banner:", report, placement.mapStatus) }
    }
)

/// Without a view: load the place, then draw the document yourself.
func loadBanner(projectBase: URL) async -> HotlayoutDocument? {
    let placement = await HotlayoutPlacement.load(name: "home.banner", projectBase: projectBase)
    return placement.document  // `placement.entry` is the entry point to pass to `HotlayoutScreen`
}

The reader asks placements/published.json under projectBase with its ETag, and the document of the place under documents/{documentId}/published.json. It keeps the last map and document it read, and falls back, in this order, on the last known map and then on bundledMap (the text of a copy shipped with the app, for a first start without a network). Nothing throws; a place that draws nothing says why in placement.report:

placement.mapStatus says why that map is in use: fresh, offline (the network was silent), corrupt (it answered with something that is not a map), unsupported (a map of another major version) or notPublished (404).

• A name is lowercase Latin letters and digits in dot-separated segments; a name of another form is unknown and no request is made for it.
• Use HotlayoutPlacementView(name:projectBase:…content:) to draw with a HotlayoutScreen of your own configuration.
• store: (the last known map), documents: (the documents read; files in the caches directory by default) and session: choose where the last known copies live and how the requests are made.
• Redirects are not followed and a request is given up after 20 seconds.
• The view loads the map once per name; it does not poll.
• onPlacement is called with the first state and again whenever placement.event (status, report, mapStatus, documentId, entry) changes.

Schedule#

A place may carry a schedule: promotions {documentId, entry?, from, until} shown over its permanent content while from (included) to until (excluded) lasts, in UTC. An item with documentId: null is a pause: the place is empty (report == .empty) for its window. After the last window the permanent content is back.

The schedule is resolved by the clock of the device, without a network. The view sets a timer for the next edge of the schedule and, when it fires, resolves the place again: it does not ask for the map again, and only reads the document the new window brings. It also resolves again when the app returns to the foreground, because the clock may have been set. The change is an ordinary onPlacement event (documentId, entry, and empty to document and back); if the answer is the same, there is no event.

HotlayoutPlacement.load(…, clock:) and HotlayoutPlacementView(…, clock:) take the clock (@Sendable () -> Date, the device clock by default), which is how you test a schedule. HotlayoutPlacementMap has resolve(_:at:) and nextBoundary(_:after:) to ask a map yourself.

An empty place draws nothing, but the view stays in your layout, and so do the padding and the frame you put around it. Take your own out when the place is empty, and keep the view mounted so that it can wake up on the next window:

HotlayoutPlacementView(
    name: "home.banner",
    projectBase: projectBase,
    onPlacement: { placement in empty = placement.document == nil }
)
.padding(.horizontal, empty ? 0 : 16)
.padding(.vertical, empty ? 0 : 8)

A reader older than the schedule shows the permanent content of a place and ignores its schedule.

Limitations#

• Where Apple's platform differs from the other readers is listed in the platform notes of the package.
• Fonts are not shipped (see Fonts).
• A list draws at most 2550 template instances per screen (see What the reader reports).

Next#

• Quickstart for iOS — the path from an empty app to a published screen.
• Widget reference — what each widget takes.
• Compatibility policy — what a reader does with a document newer than itself.