Template surfaces

In the portal: Settings, then Surfaces. Look for the codes TODO, DEFAULT_JOURNEY and DEFAULT_COACH.

What it is

Change the look of the surface coded TODO and you have changed the look of every unplaced item, for every participant in the tenancy, at once. It is the highest leverage control on the home screen. From the portal it looks like any other surface, so check the code before you edit.

Three surfaces do this job. They are ordinary surfaces with ordinary settings, and the platform looks them up by their codes.

code	What it styles
TODO	Any delivery that names no surface, no journey and no assigning staff member
DEFAULT_JOURNEY	Every per-journey surface, one surface per journey the participant is on
DEFAULT_COACH	Every per-staff-member surface, one surface per person who has assigned something

A template is a look, not a place. DEFAULT_JOURNEY never appears on a screen under its own name. What appears is a surface headed with the journey's own name, wearing DEFAULT_JOURNEY's settings. Ten journeys means ten surfaces and one template.

A template is all or nothing. A delivery either names a surface of its own or it takes the template's look entire, so when one item needs to look different, give it its own surface.

An edit here is tenancy-wide. Treat it the way you would treat a change to a shared template anywhere else: make it deliberately, and look at a participant's phone after the next sync.

What it looks like

The surface playground lets you move any of these settings and watch the result.

When you would touch one

You touch a template when the same kind of surface is wrong everywhere.

A worked example. A tenancy runs eight journeys. Every one of them draws its content as a plain vertical list, and the programme owner wants journey content to read as picture cards on a sideways shelf. The wrong fix is eight surfaces and eight sets of deliveries pointing at them. The right fix is one edit to DEFAULT_JOURNEY: set maxRows to 1, imagePosition to top, and an aspect ratio. Every journey surface on every participant's phone changes on the next sync.

The reverse also holds. If you want one journey to look different from the other seven, a template cannot do it. Give that journey's content its own surface and place the deliveries there.

The controls

There are no controls specific to a template. A template surface takes every setting on Anatomy of a surface, and they all mean exactly what they mean anywhere else.

Two fields behave differently in practice, though, because of the job these three surfaces are doing.

Field	What is different about it here
code	It is the whole mechanism. The platform finds these three by code, so TODO, DEFAULT_JOURNEY and DEFAULT_COACH must exist under exactly those codes. A code cannot be changed after creation, so you cannot break this with an edit.
name	It is the heading only for TODO. On the other two the heading comes from the journey or the person, and the template's own name is never shown to a participant. Default Journey Surface is an internal label, so renaming it changes nothing a participant sees. If a journey surface has an unhelpful heading, the fix is the journey's name.
priority	It is where every surface of that kind sits. All the journey surfaces share one number, so you move the whole group up or down the screen together, and moving TODO up the screen moves everything unplaced with it. To lift one journey above the others, give that journey's content its own surface.

Leave the three templates active. An archived surface is not sent to the phones, so archiving TODO puts a surface headed TODO in capital letters at the bottom of every participant's home screen. Where a template's look is wrong, restyle it.

A delete is refused once anything points at a template, which is what keeps the content on screen. TODO in particular collects deliveries that named it explicitly, so the delete comes back as surface_in_use. Move those deliveries first.

How it renders

TODO does two jobs, so style it for both. It is the catch-all for unplaced content, and it is also an ordinary surface that deliveries can name directly. Both kinds of item land in the same surface, drawn once, sharing one heading. Where a group of content needs a look of its own, give it its own surface and place the deliveries there.

Journey surfaces and staff surfaces are grouped, one per source. Two journeys make two surfaces, both wearing DEFAULT_JOURNEY. Two members of staff make two surfaces, both wearing DEFAULT_COACH.

A staff surface is headed with that person's name, and reads From your coach until one is available. Give every member of staff who assigns content a display name, and the heading follows on the next sync.

A journey surface is headed with the journey's own name, the name in the catalog. Read those names once from a participant's point of view, because that is where they appear.

When a template is missing, content still shows. The phone builds a plain substitute rather than dropping anything: a vertical list with the default look, headed with the code in capital letters, at priority 1000, which puts it under everything else. A surface on the home screen headed TODO or DEFAULT_JOURNEY is that substitute, and it means the real surface is missing from the tenancy or the phone has not synced.

Worked settings

All journey content as a picture shelf. On DEFAULT_JOURNEY, set maxRows: 1, itemsPerRow: 1.5, imagePosition: top, imageAspectRatio: landscape. Every journey surface becomes a shelf of picture cards with the next one peeking in from the edge.

Unplaced content styled as a tight checklist. On TODO, set variant: plain, maxRows: 0, imagePosition: left. Those three together produce a single card of rows divided by hairlines rather than separate cards.

Staff assignments credited. On DEFAULT_COACH, set attribution: true. Every item a member of staff assigned then carries a small chip naming them, which is worth doing because a coach surface can otherwise look like automated content.

Next

Three surfaces, one edit each, and the look of every unplaced item in the tenancy follows. It is the cheapest way to change how journey content or coach-assigned content reads, because nothing has to be re-assigned and no deliveries have to move.

Where one journey needs to look different from the rest, a template cannot do it: give that journey's content its own surface and place the deliveries there. See Anatomy of a surface for the settings, and How surfaces are ordered for the chain that sends content to a template in the first place.