Skip to main content

Events and Categories in TMX

The Events tab in TMX provides tools for creating and managing tournament events with flexible category configurations including age, gender, rating, and custom categories. This demonstrates usage of the Event Governor and Competition Governor.

TMX Events tab listing three events in table view

The Events tab in table view: each event with its type and gender and, in the icon columns, counts for its draws, entries and matchUps. The toggle at top right switches between cards and table; Add event opens the event drawer.

The screenshots on this page show TMX running locally with a tournament generated by the factory's mocksEngine; every participant is a generated mock person.

Overview​

Event management in TMX includes:

  • Event Creation - Single or multiple events with categories
  • Category Configuration - Age groups, gender categories, rating ranges
  • Entry Management - Assigning participants to events
  • Draw Creation - Draw size and structures are set when a draw is added (Draws)
  • Flight Configuration - Creating flights within events
  • Publishing - Visibility is controlled on the Publishing tab, not in the event drawer

Factory Methods Used​

Creating Events​

TMX Add event drawer with event name, format, gender, category, sport rules and dates

The Add event drawer: event name, format (Singles, Doubles or Team), gender, category, sport rules, and the event dates within the tournament.

// Create single event
tournamentEngine.addEvent({
event: {
eventName: "Men's Singles",
eventType: 'SINGLES',
gender: 'MALE',
category: {
categoryName: 'U18',
ageCategoryCode: 'U18',
},
},
});

// Create multiple events: addEvent takes one event (there is no events array)
[
{ eventName: "Men's Singles", eventType: 'SINGLES', gender: 'MALE' },
{ eventName: "Women's Singles", eventType: 'SINGLES', gender: 'FEMALE' },
{ eventName: 'Mixed Doubles', eventType: 'DOUBLES', gender: 'MIXED' },
].forEach((event) => tournamentEngine.addEvent({ event }));

Managing Event Details​

// Update event
tournamentEngine.modifyEvent({
eventId,
event: {
eventName: "Men's Open Singles",
startDate: '2024-06-15',
endDate: '2024-06-16',
},
});

// Delete event
tournamentEngine.deleteEvents({
eventIds: [eventId],
});

Entry Management​

TMX event Entries tab listing accepted entries with rating, draw position and draw

An event's Entries tab: accepted entries with their seeding number, rating, draw position and the draw they are placed in. Add entries, Seeding, Add flights and Add draw act on this list.

// Add entries to event
tournamentEngine.addEventEntries({
eventId,
participantIds: [id1, id2, id3],
entryStatus: 'DIRECT_ACCEPTANCE',
entryStage: 'MAIN',
});

// Remove entries
tournamentEngine.removeEventEntries({
eventId,
participantIds: [id1],
});

Key Features​

Event Types​

The Add event drawer offers the factory's three event types:

  • SINGLES - Individual competition
  • DOUBLES - Pairs
  • TEAM - Multi-player teams, whose matchUps are played as a tie of singles and doubles

Category System​

Age Categories​

{
category: {
categoryName: 'Under 18',
ageCategoryCode: 'U18',
ageMin: 0,
ageMax: 18,
ballType: 'YELLOW'
}
}

Rating Categories​

{
category: {
categoryName: 'Open',
ratingType: 'WTN',
ratingMin: 20,
ratingMax: 40
}
}

Gender Categories​

  • MALE
  • FEMALE
  • MIXED
  • ANY

Combined Categories​

{
category: {
categoryName: 'Women\'s U16',
ageCategoryCode: 'U16',
ageMax: 16
},
gender: 'FEMALE'
}

Flight Profile Configuration​

TMX uses Flight Profiles. Attach a profile before adding draw definitions. A profile lives on the event; replacing one requires deleteExisting: true and is refused if the event already has draws.

const result = tournamentEngine.attachFlightProfile({
eventId,
flightProfile: { flights: [{ flightNumber: 1, drawId: flightDrawId, drawName: 'Gold Flight', drawEntries: [] }] },
});
if (result.error) throw new Error(result.error.message);

For rating-based splitting, use generateFlightProfile with a scale, a split method and flightsCount, rather than assuming ratingMin/ratingMax configure a split on attachment.

Draw Definition Configuration​

const { drawDefinition, error } = tournamentEngine.generateDrawDefinition({
eventId,
drawSize: 32,
drawType: 'SINGLE_ELIMINATION',
automated: false,
});
if (error) throw new Error(error.message);
if (!drawDefinition) throw new Error('Draw generation failed');
tournamentEngine.addDrawDefinition({ eventId, drawDefinition });

UI Components​

TMX builds this tab from these courthive-components exports:

  • getCategoryModal - the category editor that Custom opens from the event drawer
  • getFlightProfileModal - flights within an event (see in docs)
  • getMatchUpFormatModal - an event's scoring format
  • buildEventCard and mapEventToCardData - the event cards of the cards view
  • controlBar - the toolbars above the events and entries tables
  • dropDownButton - the Add draw split button

Common Workflows​

Creating a Standard Event​

// 1. Define event
const event = {
eventName: "Men's Open",
eventType: 'SINGLES',
gender: 'MALE',
category: {
categoryName: 'Open',
ageCategoryCode: 'OPEN',
},
};

// 2. Add event
const { event: createdEvent } = tournamentEngine.addEvent({ event });
const eventId = createdEvent.eventId;

// 3. Add participants
const { participants } = tournamentEngine.getParticipants({
participantFilters: {
participantTypes: ['INDIVIDUAL'],
genders: ['MALE'], // the filter is genders (an array); an unknown key such as sex is ignored
},
});

const participantIds = participants.map((p) => p.participantId);

tournamentEngine.addEventEntries({
eventId,
participantIds,
entryStatus: 'DIRECT_ACCEPTANCE',
});

// 4. Generate the draw, then attach it to the event
const { drawDefinition } = tournamentEngine.generateDrawDefinition({
eventId,
drawSize: 32,
drawType: 'SINGLE_ELIMINATION',
seedingProfile: 'WATERFALL',
});
tournamentEngine.addDrawDefinition({ eventId, drawDefinition });

Creating Multiple Age Group Events​

const ageCategories = [
{ code: 'U10', max: 10 },
{ code: 'U12', max: 12 },
{ code: 'U14', max: 14 },
{ code: 'U16', max: 16 },
{ code: 'U18', max: 18 },
];

const events = ageCategories.flatMap((cat) => [
{
eventName: `Boys ${cat.code}`,
eventType: 'SINGLES',
gender: 'MALE',
category: {
categoryName: cat.code,
ageCategoryCode: cat.code,
ageMax: cat.max,
},
},
{
eventName: `Girls ${cat.code}`,
eventType: 'SINGLES',
gender: 'FEMALE',
category: {
categoryName: cat.code,
ageCategoryCode: cat.code,
ageMax: cat.max,
},
},
]);

events.forEach((event) => tournamentEngine.addEvent({ event }));

Auto-Assignment by Category​

// Get all participants
const { participants } = tournamentEngine.getParticipants();

// Get all events
const { events } = tournamentEngine.getEvents();

// Auto-assign to matching categories
events.forEach((event) => {
const matchingParticipants = participants.filter((p) => {
// Match gender
if (event.gender !== 'ANY' && p.person.sex !== event.gender) {
return false;
}

// Match age category
if (event.category?.ageMax) {
const age = calculateAge(p.person.birthDate);
if (age > event.category.ageMax) return false;
}

return true;
});

if (matchingParticipants.length > 0) {
tournamentEngine.addEventEntries({
eventId: event.eventId,
participantIds: matchingParticipants.map((p) => p.participantId),
entryStatus: 'DIRECT_ACCEPTANCE',
});
}
});

Entry Status Management​

TMX handles various entry statuses:

// Direct acceptance (main draw)
tournamentEngine.addEventEntries({
eventId,
participantIds,
entryStatus: 'DIRECT_ACCEPTANCE',
entryStage: 'MAIN',
});

// Alternate entries
tournamentEngine.addEventEntries({
eventId,
participantIds,
entryStatus: 'ALTERNATE',
entryStage: 'MAIN',
});

// Qualifying entries
tournamentEngine.addEventEntries({
eventId,
participantIds,
entryStatus: 'DIRECT_ACCEPTANCE',
entryStage: 'QUALIFYING',
});

Publishing Configuration​

// Publish the event's draws under the PUBLIC status key.
tournamentEngine.publishEvent({ eventId, status: 'PUBLIC' });

// Restrict the publication to selected draws.
tournamentEngine.publishEvent({ eventId, status: 'PUBLIC', drawIds: [drawId] });

Entries, participants and order of play have their own publishing APIs and visibility policies; there is no event-level published: { draws, entries, results, schedule } switch. See the Publishing Governor and publishing status keys.

Best Practices​

Event Planning​

  • Create events before adding entries
  • Use consistent naming conventions
  • Configure categories before assignment
  • Set draw sizes based on expected entries

Category Configuration​

  • Use standard age category codes (U10, U12, U14, etc.)
  • Set appropriate rating ranges for flights
  • Consider ball type for age categories
  • Use gender filtering appropriately

Entry Management Best Practices​

  • Validate participant eligibility before assignment
  • Use appropriate entry status
  • Handle wait lists with ALTERNATE status
  • Track entry stage (MAIN, QUALIFYING, CONSOLATION)

Performance​

  • Create multiple events at once with addEvents
  • Batch participant assignments
  • Query events once and filter in UI
  • Cache event configurations

Next Steps​

Once events are configured with entries, proceed to Draws to generate draw structures and position participants.