Main Pages — Overview & Generating a New Page

A main page is the top-level landing page for an entity (e.g. Active Users, Hosts, DNS Zones). It displays a searchable, paginated table with bulk selection, toolbar actions, and modals for add/delete operations.

Main pages live under src/pages/<EntityName>/ and are named after the entity itself (e.g. Hosts.tsx, DnsZones.tsx). Files with suffixes like Settings, Tabs, Table, or PreSettings are not main pages — they are sub-components consumed by main pages or detail views.

Generating a New Main Page Using This Guide

This guide is designed to be used as context in AI-assisted prompts. To generate a complete main page, provide the following input alongside this file.

Required input

Input

Description

Example

Entity name

Human-readable name (drives component names, file names, page title)

HBAC Service Groups

FreeIPA API object

The IPA command prefix (determines RPC methods like *_find, *_show, etc.). Look it up at the IPA API commands list

hbacsvcgroup

Primary key field

LDAP attribute that uniquely identifies each entry

cn

Table columns

Fields to display and their labels

cn → “Name”, description → “Description”

Navigation placement

Sidebar section and sub-group where the page appears

Policy > Host-based access control

Route path

Kebab-case URL segment

hbac-service-groups

RPC service file

The src/services/rpc<Entity>.ts file that defines the RTK Query endpoints for this entity. See “RPC Service file” below

src/services/rpcHBACServiceGroups.ts

Add modal fields

Fields shown in the Add modal, each with: field name (IPA attribute), label, data type, UI component, and whether it is required. See Add Modal

cn → “Name” (string, InputRequiredText, required)

RPC service file

The RPC service file (src/services/rpc<Entity>.ts) must be created manually before or alongside the main page. It is not auto-generated from the prompt because each entity has its own custom queryFn implementations, typed payloads, and entity-specific logic that depend on the FreeIPA API behavior.

Every main page imports hooks from its RPC service file (e.g. useGetDnsZonesFullDataQuery from src/services/rpcDnsZones.ts, useGettingHbacRulesQuery from src/services/rpcHBACRules.ts). The main page component cannot function without them.

To create the RPC service file, follow the template in 09-rpc-service.md. At minimum, you need:

  • A query for listing entities (paginated, using the two-step *_find + *_show pattern)

  • A search mutation for explicit search submissions (or use the generic useSearchEntriesMutation from rpc.ts)

  • An add mutation and a delete mutation for the modals

Existing RPC service files to use as reference:

  • src/services/rpcTrusts.ts — newer pattern with domain-specific query

  • src/services/rpcHosts.ts — older pattern using the generic useGettingGenericQuery

  • src/services/rpcDnsZones.ts — complex example with many endpoints

Optional input

Input

Description

Default if omitted

Features

Enable/Disable buttons, kebab menu, contextual help panel

Add + Delete only

Entity fields

Full list of LDAP attributes with their types. Can be extracted from the IPA command docs (e.g. parameters from <entity>_show)

Stub with cn, description, dn

Data transformation

Whether API data needs a mapper with complexValues (mainly DNS-related entities)

Simple conversion only

Conditional rendering

Whether the page depends on server configuration (e.g. DNS enabled)

Always visible

Example prompt

Based on the src/pages/README.md doc, generate a main page for HBAC Service Groups with:

  • IPA API object: hbacsvcgroup

  • Primary key: cn

  • Table columns: cn (“Name”), description (“Description”)

  • Nav placement: Policy > Host-based access control

  • Route path: hbac-service-groups

  • Features: Add, Delete (no enable/disable, no kebab)

  • Entity fields: cn (string), description (string), dn (string), member_hbacsvc (string[])

  • Add modal fields:

    • cn → “Name” (string, InputRequiredText, required)

    • description → “Description” (string, TextArea, optional)

  • RPC service file: src/services/rpcHBACServiceGroups.ts (already exists / to be created manually)

What gets generated

A complete prompt with the input above and this guide as context should produce:

File

Content

src/pages/HBACServiceGroups/HBACServiceGroups.tsx

Main page component

src/utils/datatypes/globalDataTypes.ts

HBACServiceGroup interface (addition)

src/utils/utils.tsx

isHbacServiceGroupSelectable function (addition)

src/utils/hbacServiceGrpUtils.tsx

apiToHBACServiceGroup, createEmptyHBACServiceGroup, asRecord

src/navigation/AppRoutes.tsx

<Route> entries (addition)

src/navigation/NavRoutes.ts

Nav group ref + getNavigationRoutes entry (addition)

src/components/modals/.../AddHBACServiceGroupModal.tsx

Add modal

src/components/modals/.../DeleteHBACServiceGroupsModal.tsx

Delete modal

Not generated (must be created manually):

File

Why

src/services/rpcHBACServiceGroups.ts

Contains custom queryFn logic, typed payloads, and entity-specific API behavior. Use 09-rpc-service.md and existing files as reference