Guide 05 · Developer docs

Content types and custom entities

Which built-in type fits which purpose, how categories, tags, slugs, custom URLs and SEO settings behave across them, how revisions and publishing gate what the public sees, how to model a domain the platform has no type for, and where uploaded files live.

L1–L3

Unit 04 of 06 8 pages

Custom entities

Updated 23/10/2026 01:48

How to model your own content types as custom entities: definitions, relationships, hierarchies, templates, queries and the API, ending with a complete learning site. For site builders and developers.

Custom entities let a site builder add content types of their own, with fields, listings, URLs and links between them, and deliver a whole application without framework code. Start with the test for when a custom entity beats a page, then define one: its identifier, paths, layout and switches, and which of them you can change once records exist.

The middle of the unit is the domain model. Relationships between records get the most space, because they are what turns a flat list into a model; parent and child records are the other way records connect, with the rule for choosing between the two. Then come the templates: the listing and detail routes a definition gets, and querying records from any other template. The page on the API, GraphQL and MCP shows the same records to a headless front end or an agent, and the unit ends with a learning site built from all of it.

In this unit

Read in order

01 When a custom entity beats a page A custom entity is a content type you define in the admin, with its own layout areas, listing and URLs. This page gives the test for choosing one over a page, and works three cases. 02 Defining a custom entity The fields of a custom entity definition, what each one controls and which you can change once records exist, and how a record takes its layout and layout areas exactly as a page does. 03 Relationships between records A relationship definition is a typed link from records of one definition to records of another, with a minimum and a maximum. This page shows how to define one, what a save checks, and how to read it from both ends in a template. 04 Parent and child records Records can form trees, either among the records of one definition or as typed parent and child definitions. This page covers both, what a save enforces, what follows the parent, and how to render a tree safely. 05 Listing and detail templates How a definition's paths become a listing route and a detail route, what each route hands its template, and a worked pair of templates for a store locator. 06 Querying records from a template Read custom entity records on any page with the query helper's two custom entity methods: criteria, order and limit, and what each call costs. 07 Custom entities over the API and MCP List, read, create and change custom entity records over the REST API, read them through GraphQL, reach them through the site's MCP server, and import or export them in bulk: what is specific to custom entities. 08 Worked example: a course catalogue A complete learning site built from three custom entity definitions, a book, jobs and templates, with no PHP: courses, enrolments related to a course and a learner, tests as children of an enrolment, and certificates issued by a job.