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_BUCKET | An event is in it when | Default title |
|---|---|---|
live | It is published and between its start and end | "Ongoing" |
upcoming | It is published and has not started, or registration has not opened | "Upcoming" |
closed | It has ended, or is completed, cancelled or resolving | "Finished" |
joined | The 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.
Featured events
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 type | Tabs |
|---|---|
BASIC, COLLABORATIVE | overview, quests, rewards, leaderboard |
SCORE | overview, 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.
kind | When | Show |
|---|---|---|
STARTS_IN | Not started | Events.startin and a countdown to target |
LIVE | Started, not ended | Events.ongoing, and a countdown to target |
ENDED | Ended or cancelled | Events.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.state | Means |
|---|---|
UPCOMING | Not reached yet |
ACTIVE | Happening now. Only an active tile has progress, from 0 to 100. |
ENDED | Done |
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
SCOREevent 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