The seven standard surfaces
In the portal: Settings, then Surfaces.
What it is
Every new tenancy starts with seven surfaces already made. Five of them are ordinary surfaces you place content in. Two are templates that style content which was never placed anywhere, and there is a third template among the five.
You do not have to use any of them. Most tenancies use two or three and add one or
two of their own. A delete is refused once deliveries point at a surface, and comes
back as surface_in_use, which is what keeps that content on a participant's screen.
Move the deliveries first, then delete.
What it looks like
Every heading down that screen is a surface. The items under it arrived from a journey or from a coach, and the surface decided how they look and where they sit.
And now one at a time
Same seven, drawn separately so you can see each one's settings beside it. The button switches between how they ship and how they look once somebody has styled them.
The seven, in the order they appear down the screen.
code | name | priority | Settings that are not the default |
|---|---|---|---|
PINNED | Pinned | 5 | none |
NOW | Now | 10 | none |
TODO | To-do | 20 | none |
CARD | Cards | 30 | maxRows: 1, a single-row shelf |
RANKED | Recommended | 40 | sort: assignedAt, order: DESC |
DEFAULT_JOURNEY | Default Journey Surface | 100 | none |
DEFAULT_COACH | Default Coach Surface | 110 | none |
Everything not listed in the last column takes the platform default:
variant: outlined, maxRows: 0, itemsPerRow: 1.5, showHeader: true,
showCompletionState: true, imagePosition: left, imageAspectRatio: square,
attribution: false, no perPage, sort: sortKey, order: ASC.
So a default home screen, top to bottom, reads: the greeting, then Pinned, then Now, then To-do, then Cards as a sideways shelf, then Recommended, then one surface per journey, then one surface per member of staff who has assigned something. Any surface with nothing in it is skipped, so most participants see two or three of these rather than all seven.
When you would use each
Pinned is for the one or two things that should always be at the top. It is a
position rather than a rule, so keep the list short yourself. If a long list needs
trimming, perPage shows the first few with an arrow beside the heading, and tapping
the arrow opens the rest in place. Read the note about it on
Anatomy of a surface before you reach for it.
Now is for what the participant should do next, and it is an ordinary surface
like the others. Content that should open by itself is set that way on the delivery,
with the autoOpen flag. The two controls are independent: use Now for position and
autoOpen for opening.
To-do is the general list, and it is also the template that catches unplaced content. Read Template surfaces before you restyle it, because a restyle reaches content you placed there deliberately as well as content that arrived by default.
Cards is the only seeded surface laid out as a shelf. It is the natural home for reading material and picture-led content.
Recommended shows newest first. It ships with sort: assignedAt and
order: DESC, so the top item is whatever the participant was given most recently.
The sort choices are the ordinary ones, sortKey, assignedAt and name, so pick
the order you want, and rename the surface if Recommended is not the word your
participants should read.
Default Journey Surface and Default Coach Surface are templates. No delivery should ever point at them directly, and content never lands in them by name.
The controls
The seeded surfaces have ordinary controls, so every setting on Anatomy of a surface applies to all seven.
Two identity facts matter more here than elsewhere.
| Field | Why it matters on a seeded surface |
|---|---|
code | The platform looks up the three templates by code, so TODO, DEFAULT_JOURNEY and DEFAULT_COACH must keep their codes. A code cannot be changed after a surface is created, so there is no way to break this by accident. |
name | Only the heading text, and it is free to change. Renaming To-do to something warmer changes nothing about how the surface works. |
The seeded surfaces also hold fixed identifiers that stay the same in every tenancy and every fresh install, which is what lets shared content and journey actions point at a surface by name without knowing which tenancy they are in.
How it renders
All seven exist from the first day, and a participant sees the ones with content in them. An empty surface is skipped, so seven surfaces routinely draw two.
The gaps between the priorities are deliberate. Five, ten, twenty, thirty, forty, then a jump to one hundred. That leaves room to put your own surfaces between them without renumbering anything.
The two default templates sit at 100 and 110 so they land under your own work. A surface you add at any priority under 100 will sit above every journey surface and every coach surface.
Move the deliveries before you archive one of the seven. An archived surface stops being sent to the phones, so on the next sync every delivery pointing at it loses its surface and falls down the placement chain described on How surfaces are ordered. Leave the three templates active: the phone keeps the content on screen by building a plain substitute named after the code, under a heading you did not write.
Worked settings
A course with one surface of its own. Leave the seven alone, create one surface at priority 15, and place the course's deliveries there. It will sit between Now and To-do, and nothing else moves.
A picture-led home. Use Cards for the reading material, which is already a shelf, and put the daily actions in To-do above it. Two seeded surfaces, no new ones.
A tenancy that wants To-do renamed. Change the name on the surface coded
TODO. Every participant sees the new heading, and the placement chain is
untouched, because it looks up the code and never the name.
Next
Seven surfaces exist from the first day and most tenancies see two or three of them, because an empty surface is skipped. The gaps in the priorities are there so you can add your own between them without renumbering anything.
Template surfaces is the three of the seven that style content nobody placed, and the one edit with the widest reach on the home screen.
Anatomy of a surface is every setting you can move on any of them.