Ordering and priority
In the portal: Settings, then Surfaces. priority sits on each one.
What it is
The home screen is a stack of surfaces, and the order is decided by one number.
Every surface has a priority, and lower numbers sit higher up the screen.
Before the order can be worked out, every item has to be put into a surface. A delivery that names a surface is easy. A delivery that names nothing is the interesting case, and the platform never drops it. It works down a chain of four steps and takes the first one that fits.
The whole thing happens on the participant's phone, freshly, every time the home screen is drawn.
What it looks like
How an item finds its surface
The chain, in order. The first step that applies wins and the rest are not consulted.
| Step | The delivery has | The surface it lands in | Its heading |
|---|---|---|---|
| 1 | a surface, and the phone knows that surface | that surface | the surface's own name |
| 2 | no usable surface, but a journey | a surface of its own, one per journey | the journey's name |
| 3 | no usable surface and no journey, but an assigning staff member | a surface of its own, one per person | that person's name |
| 4 | none of the above | the surface coded TODO | the TODO surface's name, which ships as To-do |
Steps 2 and 3 do not add a surface you can edit. They borrow the look of a template surface, which is what the next page is about.
Step 1 needs both a named surface and a copy of that surface on the phone. If the surface was deleted, or archived, or the phone has not synced since it was created, step 1 is skipped and the delivery carries on down the chain. The content still appears, under the next heading that fits. So if a delivery turns up under a heading you did not expect, check that its surface is still active and that the phone has synced since the surface was created.
A surface headed TODO or DEFAULT_JOURNEY in capital letters is a sync
symptom. When the phone cannot find the template surface a delivery needs, it
invents a plain one, names the surface after the code, and gives it a priority of
1000 so it sinks to the bottom. The content is all there. It means the template
surface is missing from that tenancy, or the phone has not synced yet.
When you would change a priority
You change priority when a surface is in the wrong place down the screen.
A worked example. A tenancy adds a mindfulness surface, laid out as a shelf, and it lands under everything else, because a new surface starts at priority 0 and so does every other new surface. Giving it a priority of 15 puts it between the seeded Now surface at 10 and the seeded To-do surface at 20. Nothing else has to move.
Leave gaps of five or ten between your priorities. It costs nothing and it means the next surface can be slotted in without renumbering.
The controls
| Control | What it accepts | Default | What changes on screen |
|---|---|---|---|
priority | any whole number from 0 up | 0 | Where the surface sits down the screen. Lower is higher. A new surface therefore starts at the top, above the seeded Pinned surface at 5. Priority is position and not importance: the place you set is the place the surface holds, whether the items in it are overdue or finished. |
surfaceId on the delivery | a surface, or nothing | the sequence's defaultSurfaceId, else nothing | Which surface the item lands in. Nothing means the chain above decides. |
journeyId on the delivery | a journey, or nothing | nothing | Step 2 of the chain, and the source of the surface's heading. |
sort and order on the surface | see the surface page | sortKey, ASC | The order of items inside a surface, set separately from anything on this page and with no effect on the order of surfaces. sortKey uses the number you put on each item, assignedAt uses when the participant was given it, and name is alphabetical. The full note is on Anatomy of a surface. |
The number is the whole mechanism. Set the priority and the stack follows.
How it renders
Give every surface its own number and the stack is yours to set. Where two share a number, the platform falls back to the surface's internal id. That order is stable, so it never changes between one opening of the app and the next, but it is not one you choose. Give them different numbers where the order matters.
Journey surfaces and staff surfaces all share one priority, so they sit in alphabetical order of their headings, which is the journey's name or the person's name. To lift one journey above the others, give its content a surface of its own.
Each surface is drawn exactly once. Deliveries that name the TODO surface
and deliveries that named nothing at all land in the same surface, not two
surfaces with the same name.
Journey surfaces and coach surfaces multiply. A participant on three journeys, none of whose content names a surface, gets three surfaces. That is usually what you want. Where it is not, place that journey's deliveries in a surface of your own.
The phones do not re-order anything. Both render the surfaces in the order they are handed, top to bottom. What you set is what appears.
An empty surface is not drawn at all. It is skipped, so a priority you have set on an empty surface has no visible effect until something lands in it.
Worked settings
A course that should sit above everything. Give its surface a priority below 5, which is where the seeded Pinned surface sits. Content there will be the first thing the participant sees under the greeting.
A library that should sit at the bottom. A priority of 200 puts it below every seeded surface, including the journey surfaces at 100 and the coach surfaces at 110.
Two courses that must not mix. Give each its own surface and place the deliveries explicitly, rather than relying on step 2 of the chain. Step 2 does separate them by journey, but it also means the heading is the journey's name, which is often an internal name rather than a participant-friendly one.
Next
One number decides the whole stack, and the placement chain means a delivery always lands somewhere. Leave gaps of five or ten between your priorities and the next surface slots in without renumbering anything.
Template surfaces is steps 2, 3 and 4 of the chain: the three surfaces that style content nobody placed.
The seven you start with lists the priorities a new tenancy already has, so you know what you are slotting between.