Campaign app layout

The app layout defines navigation and page presentation for visitors and authenticated users of your app. The layout is configured through menu items, app pages, and styling options. The app's content is configured separately in Campaign content.

Menu items

GameBus lets you configure navigation through the app using its side menu. GameBus Core provides the following menu item types.

Each item has a slot (top, center, or bottom) and an optional order. Items are sorted by slot, then by order. Items without an order appear last in their slot.

Depending on its type, an item can also have a translatable title and subtitle, an icon, an associated app page—that is opened when the item is clicked—and optional configuration parameters.

Who sees a menu item

Menu item availability depends on waves and, optionally, groups:

• Waves. An item must be linked to at least one active wave. A wave is active when its start is unset or in the past and its end is unset or in the future.
• Groups. An item without group links is unrestricted by group. Otherwise, the user needs a Participant-membership in at least one linked group. Other membership types, including Ghost-memberships, do not grant access.

Users see all menu items available through these wave and group rules. For example, a Team progress menu item linked to Team A and the October wave is available to Team A's participants while that wave is active.

Generate a list of menu items

The list of items-menu item is a somewhat special type.

It creates one menu entry for each value selected by its iterable path. The data comes from linked input collections, which contain input requests. Each request has a key and an endpoint.

The iterable is a plain path. It supports object properties, array indexes such as [3], and array expansion with [*]. For example: $participantMissions.missions[*].

Each selected value is available as both row and item. Use expressions such as $row.name, $row.description, or $row.slug in menu fields and route parameters through configuration.params.

This example creates one menu entry for each active mission returned by /api/me/missions:

inputCollections:
  - key: participantMissions
    inputRequests:
      - key: missions
        endpoint: /api/me/missions
        doFailOnError: true
        doFailOnEmpty: false

appPages:
  - type: showMission
    slug: /missions/[missionSlug]
    requiresAuthentication: true
    isGloballyAvailable: false
    layout: HEADER

menuItems:
  - type: LIST_OF_ITEMS
    appPageSlug: /missions/[missionSlug]
    iterable: participantMissions.missions
    slot: CENTER
    order: 1
    title:
      default: $row.name
    subtitle:
      default: $row.description
    hideWhenAuthenticated: false
    configuration:
      params:
        missionSlug: $row.slug
    inputCollectionKeys:
      - participantMissions

Custom menu items

A Custom embed-menu item displays its embed URL in an iframe inside the side menu. It communicates with the app through iframe messages. See Custom menu items for the protocol and implementation details.

App pages

An app page defines what appears at a route and who can access it.

Where a page type accepts fallback route parameters, values captured from the slug take precedence over matching values in configuration.params.

Who can access a page

Page access depends on authentication and global availability:

For pages that require menu access, the menu item's wave and group restrictions also apply to direct URLs. When several menu items link to a page, access through any one qualifying item is enough.

Page types may apply additional checks, such as whether the requested group belongs to the current user.

Page types

GameBus Core provides the following page types. The routes below are defaults; use the page's slug to set a different route.

Custom pages

An External page-page displays an external URL at its configured app route. It follows the same access rules as built-in pages. These pages need some additional configuration:

For example, a Team progress menu item can open an external team dashboard. Input collections supply its data, while iframe messages let it communicate with Core.

See Custom pages for the protocol and implementation details.

Styling

Set CSS variables under :root for the light theme and .dark for dark mode. Settings merge recursively with the application defaults, so you only need to supply the values you want to change.

{
  ":root": {
    "--primary": "#0057b8",
    "--primary-foreground": "#ffffff",
    "--background": "#ffffff",
    "--foreground": "#172033",
    "--radius": "0.75rem"
  },
  ".dark": {
    "--primary": "#78b7ff",
    "--primary-foreground": "#071525",
    "--background": "#071525",
    "--foreground": "#f4f7fb"
  }
}

Theme variables

For each color pair, choose a foreground color that provides enough contrast with its background.

Browser theme colors

The app publishes the --background values from :root and .dark as separate <meta name="theme-color"> tags. Supporting browsers can use these light and dark colors for their interface.

Progressive web app (PWA)

The app can be installed as a progressive web app (PWA). Use a web app manifest to define its name, icons, launch behavior, and installation appearance.

Manifest settings

Manifest colors are configured separately from CSS. Keep them aligned with the app's theme, but note that each manifest color has one static value rather than separate light and dark values.

Support for installation features varies by browser and operating system.

Display mode

The display setting controls how the installed app appears:

Icons

Provide icons as an array of definitions. Each icon supports:

Include a maskable icon so supporting platforms can crop it to their required shape.

Example manifest

{
  "name": "Example Missions",
  "short_name": "Missions",
  "description": "Achieve your missions.",
  "lang": "en",
  "scope": "/",
  "start_url": "/",
  "display": "standalone",
  "orientation": "any",
  "background_color": "#ffffff",
  "theme_color": "#0057b8",
  "icons": [
    {
      "src": "/core-logo.svg",
      "sizes": "any",
      "type": "image/svg+xml",
      "purpose": "any"
    },
    {
      "src": "/core-logo-maskable.png",
      "sizes": "1024x1024",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}