Events

The event page

Listing events in sections, mounting one, and the header, tabs and timeline around it.

Two builds on this page: the list a fan browses, and the page one event opens into.

Listing events

useQuestEvents returns the community's events, already filtered into the section you ask for and sorted newest first.

import {
  QUEST_EVENT_LIST_BUCKET,
  resolveMessage,
  toQuestEventShortId,
  useQuestEvents,
} from '@xborglabs/fanbase-react'

function EventSection({ bucket, title }: { bucket: 'live' | 'upcoming' | 'closed'; title: string }) {
  const { data: events = [], isPending, isError } = useQuestEvents({ buckets: [bucket] })

  if (isPending) return <SectionSkeleton />
  if (isError) return <p>{resolveMessage('Errors.globalErrors.events_list_rejected', undefined, { events: 'Events' })}</p>
  if (events.length === 0) return null

  return (
    <section>
      <h2>{title}</h2>
      {events.map((event) => (
        <a key={event.eventId} href={`/event/${toQuestEventShortId(event.eventId)}`}>
          <img src={event.images?.coverImageUrl} alt="" />
          {event.title} · {event.totalParticipants}
        </a>
      ))}
    </section>
  )
}

export function EventsPage() {
  return (
    <>
      <EventSection bucket={QUEST_EVENT_LIST_BUCKET.LIVE} title={resolveMessage('Events.subtitle.live')} />
      <EventSection bucket={QUEST_EVENT_LIST_BUCKET.UPCOMING} title={resolveMessage('Events.subtitle.upcoming')} />
      <EventSection bucket={QUEST_EVENT_LIST_BUCKET.CLOSED} title={resolveMessage('Events.subtitle.closed')} />
    </>
  )
}

Do not pass a communityId. The hook resolves it from the slug you gave FanbaseProvider.

Buckets

QUEST_EVENT_LIST_BUCKETAn event is in it whenDefault title
liveIt is published and between its start and end"Ongoing"
upcomingIt is published and has not started, or registration has not opened"Upcoming"
closedIt has ended, or is completed, cancelled or resolving"Finished"
joinedThe fan is taking part"Live"

Pass more than one bucket and an event has to be in all of them. ['live', 'joined'] is the events the fan is in right now.

Hide a section with no events, title included. An empty "Upcoming" heading reads as broken.

The whole list comes back at once

The hook reads every event in the community and hands you one array. There is no total and no server page to ask for. If you want pages, slice the array:

const pageCount = Math.ceil(events.length / size)
const visible = events.slice((page - 1) * size, page * size)

Keep page in your URL and reset it to 1 when the bucket changes.

useFeaturedQuestEvents() returns the events your team marked as featured that are still running. Render the first two and a "view all" link when there are more.

import { useCommunity, useFeaturedQuestEvents } from '@xborglabs/fanbase-react'

const { data: community } = useCommunity()
const { data: featured = [] } = useFeaturedQuestEvents({
  communityId: community?.communityId,
  enabled: Boolean(community),
})

This is the one event hook that does not scope itself. Without communityId the featured list is not limited to your community, so pass it.

When there are no events at all

Three strings cover the empty page: Events.noEvent, Events.comebackLater and Events.viewQuests, the last one as a link to your quests page. Sending a fan somewhere they can still earn beats a blank page.

Short ids in your URLs

An event id is long: urn:xb-quest-event:abc123. toQuestEventShortId(id) returns abc123, which is what belongs in a route. Everything that takes an event id accepts the short id, the full id or the event's slug, so you never convert back.

Mounting one event

Wrap the page in QuestEvent.Provider and read everything from useQuestEvent().

import { QuestEvent, useQuestEvent } from '@xborglabs/fanbase-react'

export function EventRoute({ id, rowFromList }: { id: string; rowFromList?: QuestEvent }) {
  return (
    <QuestEvent.Provider eventId={id} event={rowFromList}>
      <EventPage />
    </QuestEvent.Provider>
  )
}

function EventPage() {
  const { state } = useQuestEvent()

  if (state.error) return <NotFound />
  if (!state.event) return <EventSkeleton />

  return (
    <>
      <EventHeader />
      <EventTabs tabs={state.tabs} />
    </>
  )
}

event is optional. Pass the row the fan clicked in the list and the page paints with it straight away, while the full event loads behind it. The list and the page do not share a cache, so this prop is the only way to carry the row over. Keep it in router state, or look it up from useQuestEvents() by short id.

The event itself is public. A fan who is not signed in sees the page, the quests and the prizes. What they do not get is anything personal: the leaderboard, their rank and their rewards all need a session.

The description is rich text. Render it with Parser, the same way as a quest description.

Tabs

state.tabs is the list of tabs this event has, in order.

Event typeTabs
BASIC, COLLABORATIVEoverview, quests, rewards, leaderboard
SCOREoverview, scoring, rewards, leaderboard

Labels are Events.overview, Events.quests, Events.scoring, Events.rewards and Events.leaderboard. Which tab is open is your state. A query parameter works well, because the event button links straight to the rewards and leaderboard tabs once an event ends.

The header and the timeline

Everything time-based on the page is already worked out. Render what state says and re-render on a timer of your own, every ten seconds or so, so a countdown reaching zero flips the page without a reload.

The time badge

state.timeBadge says which of three phases the event is in, and what to count down to.

kindWhenShow
STARTS_INNot startedEvents.startin and a countdown to target
LIVEStarted, not endedEvents.ongoing, and a countdown to target
ENDEDEnded or cancelledEvents.eventEnded

target is the start date before the event and the end date during it. The countdown component is yours.

Time left to join

state.joinDeadline is the last moment a fan can join. It is undefined once the event has ended, and that is your cue to hide the timer.

Participants

state.event.totalParticipants, and state.event.maxParticipants when the event is capped.

The three tiles

state.tiles is the timeline: registration, live, ends. Each tile says which state it is in.

function Timeline() {
  const { state } = useQuestEvent()

  return state.tiles.map((tile) => (
    <div key={tile.tile} data-state={tile.state}>
      <p>{resolveMessage(tile.labelKey, undefined, { event: 'Event' })}</p>
      <time dateTime={tile.date}>{formatDate(tile.date)}</time>
      {tile.progress !== undefined ? <progress max={100} value={tile.progress} /> : null}
    </div>
  ))
}
tile.stateMeans
UPCOMINGNot reached yet
ACTIVEHappening now. Only an active tile has progress, from 0 to 100.
ENDEDDone

The tiles are personal. For a fan who has joined, the registration tile is done and the live tile fills as the event runs. For a fan who has not, the registration tile is the active one until joining closes.

Your own nouns

Event strings carry placeholders. Join {event} expects you to say what an event is called in your product.

resolveMessage('Events.join', undefined, { event: 'Tournament' })   // "Join Tournament"

The strings the provider resolves for you, like the button label, use "Event" and "Quests". To rename those everywhere, pass an i18n adapter. Display strings covers it.

Checklist

  • The list makes no request per event, and empty sections are hidden
  • Cards link with the short id
  • The event page paints from the list row, then fills in
  • A signed-out fan sees the event and its prizes
  • A SCORE event shows a scoring tab where the others show quests
  • The badge, the join timer and the tiles all come from state, with no date maths of your own
  • The join timer disappears when the event ends

On this page