Skip to main content

Surfaces

A surface is a named, styled part of the participant's home screen. It holds no content: user sequences are placed on it, and it decides where they sit and how they look. What a participant gets is decided by journeys and staff; how it looks, by surfaces.

The home screen is assembled on the phone each time it is drawn, from the user sequences assigned to the participant and the tenant's surfaces.

Order​

  • Surfaces stack by position, lowest at the top. A new surface starts at 0, the very top. Surfaces sharing a number fall back to an order that is stable but not one you choose, so give each its own.
  • Items within a surface are ordered by sort (position, assignedAt or name) and order. position is each assignment's position, set by the coach who assigns it or the journey step that does (Placing what a journey assigns). Two items assigned in the same second fall back to position.
  • An empty surface is not drawn: no heading, no placeholder.

Where an item lands​

The first rule that fits wins:

  1. The user sequence names a surface the phone holds: that surface.
  2. Otherwise it came from a journey: a surface of its own per journey, headed with the journey's name, styled as the DEFAULT_JOURNEY surface.
  3. Otherwise a member of staff assigned it: one per person, headed with their name, styled as DEFAULT_COACH.
  4. Otherwise the TODO surface.

A user sequence with no surfaceId takes the sequence's defaultSurfaceId. Journey and staff surfaces all share their template's position, so they sit together in alphabetical order of heading.

The template surfaces​

TODO, DEFAULT_JOURNEY and DEFAULT_COACH are found by code, so editing one restyles every item that falls to it, for every participant. DEFAULT_JOURNEY's and DEFAULT_COACH's own names are never shown; TODO's is. Keep them active: when the phone can't find one (archived, or not synced yet), it draws a plain substitute headed with the code in capitals, at the bottom. A heading reading TODO or DEFAULT_JOURNEY is that substitute.

Every tenant starts with seven surfaces, the same ids in every tenant: PINNED (5), NOW (10), TODO (20), CARD (30, a one-row shelf), RANKED (40, newest first), DEFAULT_JOURNEY (100) and DEFAULT_COACH (110). A coach's pin is a user sequence on PINNED.

Appearance​

The settings and their values are in the reference. Behaviour you won't see there:

  • maxRows 0 is a list; 1 to 4 is a sideways shelf that many rows deep. itemsPerRow only applies to a shelf.
  • variant: plain, maxRows: 0 and imagePosition: left together draw one card of rows divided by hairlines; any other combination draws separate cards.
  • A picture never reserves space: an item's cover is the sequence's assetId, and an item without one has no gap. Banner pictures (top, background) are held between 100 and 180 pixels tall, so on a full-width card square and landscape look the same.
  • perPage shows a preview with an arrow that opens the rest in place; nothing is hidden.
  • showCompletionState controls the automatic marks (the to-do ring, the tick); a sequence's startButtonLabel is content and always shows.
  • attribution adds a chip naming the journey or person each item came from.

A surface a user sequence points at can't be deleted; move those first.