Anatomy of a surface
In the portal: Settings, then Surfaces.
What it is
A surface is one named section of the home screen. It is the strip with a heading, and the items sitting under that heading.
A surface holds no content of its own. It decides how items look and what order they sit in, and nothing else. What actually lands in it is a delivery, which is one piece of content assigned to one participant. So a surface is closer to a picture frame than to a folder.
That distinction is the one to hold on to before you touch any setting. Content arrives on the home screen because a journey scheduled it, or because a coach assigned it. The surface then decides where it sits and what it looks like.
What it looks like
When you would use one
You create a new surface when a group of items needs its own heading and its own look.
A worked example. A tenancy running a six week wellbeing course wants the daily
check-in to sit at the very top as a plain list, and the reading material to sit
below it as a sideways shelf of picture cards. That is two surfaces: one with
maxRows: 0 for the list, one with maxRows: 1 and a picture position for the
shelf.
You do not create a surface to hold a journey. Journeys get their own surface automatically.
The controls
There are twelve settings, and this is all of them.
| Setting | What it accepts | Default | What changes on screen |
|---|---|---|---|
priority | any whole number from 0 up | 0 | Where the surface sits down the screen. Lower numbers sit higher. Surfaces with the same number fall back to the surface's internal id, which is stable but is not one you choose. Give them different numbers where the order matters. |
variant | outlined, elevated, plain | outlined | The card edge. Outlined draws a hairline border at half opacity. Elevated drops a soft shadow. Plain draws neither. All three sit on a solid card colour. |
maxRows | a whole number from 0 to 4 | 0 | The single switch between a list and a shelf. Zero stacks the items down the screen. One to four turns the surface into a sideways shelf that many rows deep. A shelf never grows more rows than it has items. |
itemsPerRow | 1, 1.5, 2, 2.5 | 1.5 | Only does anything on a shelf. Each card is the usable screen width divided by this number, so 1.5 leaves half the next card showing at the edge. That peek is what tells a participant to scroll. |
showHeader | true or false | true | Whether the surface shows its own name, description and image. |
showCompletionState | true or false | true | Whether items draw the automatic state marks: the dashed ring on something still to do, and the green tick once it is done. Turn it off and the surface reads as plain tiles. A start button is authored content and is never removed by this. |
imagePosition | left, right, top, background | left | Where an item's picture sits inside its card. Left and right put it in a 56 pixel square beside the text. Top puts it above as a banner. Background puts the text on top of it, over a dark gradient. Whether an item shows a picture at all is a property of the content, and the surface chooses only where it goes. |
imageAspectRatio | square, landscape, portrait, wide, ultrawide, panorama | square | The shape a banner picture is cropped to. Only affects top and background. |
attribution | true or false | false | Whether each item shows a small chip saying which journey or which coach it came from. |
perPage | a whole number, or nothing | nothing | How many items the surface shows before it stops. Leave it empty to show everything. |
sort | sortKey, assignedAt, name | sortKey | Which value the items are ordered by. sortKey is the number you set on each item, assignedAt is when the participant was given it, and name is alphabetical. With order: DESC, assignedAt means newest first. Two deliveries made in the same second fall back to sortKey, so a journey handing out several at once still comes out in a stable order. |
order | ASC, DESC | ASC | Whether that ordering runs up or down. |
Four more fields identify the surface rather than style it.
| Field | Notes |
|---|---|
code | Capitals, numbers and underscores, starting with a letter. Unique within your tenancy and fixed once created. Reusing one returns surface_exists. |
name | The heading text. Up to 128 characters, and it shows on one line only. |
description | The line under the heading. Up to 500 characters, and it also shows on one line only, so treat 60 as the real limit. |
assetId | The surface's own small round image, 32 pixels across. It must be a public asset. |
Three of the codes are looked up by the platform, and editing one of those
surfaces changes every participant's home at once. The surfaces coded TODO,
DEFAULT_JOURNEY and DEFAULT_COACH style items that were never given an explicit
surface. Change the look of TODO and you have changed the look of every unplaced
item for everybody. Those three codes are the highest leverage control on this page, so
they have a page of their own: see Template surfaces.
A surface in use is protected from deletion. If any delivery still points at
it, the delete is refused with surface_in_use, so no participant loses an item to
a tidy-up. Move those deliveries first, then delete the surface.
How it renders
An empty surface is invisible, not empty. A surface with no items is skipped entirely. There is no placeholder and no "nothing here yet" line. If you create a surface and see nothing on the phone, nothing has gone wrong. Nothing has been delivered to it yet.
A completely empty home shows one line, "Nothing scheduled right now", and that single line covers every zero-content case.
The heading appears when showHeader is on, or when perPage is set. The cap
needs its arrow, and the arrow lives in the heading.
Pictures never reserve space. An item with no picture has no gap where one would go. A surface with a mix of both stays tidy without any effort from you.
Text wraps, it does not trail off. An item title takes up to three lines, or two when it sits over a background picture. An item description takes two. The surface heading and its description take one line each.
Banner pictures are held between 100 and 180 pixels tall. The height is the card
width divided by the aspect ratio, then clamped. On a full width card, square and
landscape both hit the 180 ceiling, so they look identical. The differences only
appear on a shelf, where the cards are narrower.
The start button is not a surface setting, and the tick and the ring are. Whether an item shows a start button is decided entirely by the content it delivers. If that content carries a start button label, the button appears, and nothing on the surface can take it away. If it does not, the item shows the automatic state mark instead: a dashed ring while the item is outstanding, a green tick once it is done. Either way the whole card stays tappable.
Those automatic marks are the part you control, with showCompletionState. Turning
it off gives you plain tiles, which is what reading material usually wants. A done
item still dims its own content, so the participant can still tell.
The distinction is worth holding on to. Authored content wins over surface settings. Automatic behaviour is what the surface gets to switch off.
perPage shows a preview, not a hard limit. The surface renders the first
perPage items with an arrow beside the heading. Tapping the arrow opens the rest of
the list in place, on both phones, and the arrow then goes away. The space it
occupied is held either way, so the heading does not jump when it disappears. A cap
is therefore a way of keeping a long surface from dominating the screen. It is not a
way of hiding anything, and nothing behind it is out of reach.
Three settings together give you a grouped list. Set variant to plain,
maxRows to 0 and imagePosition to left, all three, and the surface stops
drawing separate cards. It becomes a single card of rows divided by hairlines, which
is the right look for a set of small actions that belong together. Any other
combination draws separate cards.
Worked settings
A plain daily list. variant: outlined, maxRows: 0, imagePosition: left,
showHeader: true. The default, and the right answer most of the time.
A shelf of reading cards. variant: elevated, maxRows: 1, itemsPerRow: 1.5,
imagePosition: top, imageAspectRatio: landscape. Picture led, and the half card
at the edge invites a scroll.
A tight grouped checklist. variant: plain, maxRows: 0, imagePosition: left,
showHeader: false. The rows join into one solid card with no heading, for a set of
small actions that belong together.
Next
Between them, those twelve settings cover every look the home screen has. A surface never decides what a participant gets, so you can change any of these in a live tenancy without touching anybody's content.
The seven you start with is what a new tenancy already has, with the settings that differ from the defaults called out.
What puts an item there is the other half: the deliveries that fill a surface up.