Who this is for. Content modellers adding "related", "featured" or "pick a form" fields, and the developers who render them. After this page you can configure a picker that offers the author the right records, and render the result safely.
Choosing the content type
An input type in the record category (one record) or records category (several, in the author's order) must name a Content type. Without one the input type is refused ("Has to be specified"), and a content type outside the list is refused too ("Entity not supported"). The list:
| Module | Content types |
|---|---|
| Pages | Pages |
| Blogs | Blogs, blog posts |
| Books | Books, units, book pages |
| FAQ | FAQ pages, FAQ questions |
| Products | Products, product categories |
| Common | Categories, tags |
| Forms and menus | Forms, menus |
| Users | Authors, people, groups, users |
| Custom entities | The records of one custom entity type |
One input type serves one content type. A "Related page" type and a "Featured product" type are two types, each reusable on any layout.
Narrowing the picker to one parent
A Parent record narrows what the author is offered. For content arranged in a tree, such as pages or categories, the picker then lists only the records under that parent; for content grouped under another record, such as blog posts under their blog, it lists only that group. Use it whenever the right answer is a subset: "a case study" means the pages under /case-studies, not every page on the site.
The parent narrows the picker only. A record written through the API, or chosen before the parent was set, can be outside that subset. If the template depends on the subset, check it there.
What is stored
A record area stores the record's id; a records area stores the ids, separated by commas, in the author's order. Like every area value, the ids are stored on a revision of the record, and a template reads them from the active revision. Through the API, a record area takes an id and a records area a list of ids, and an id that does not exist is refused: see Writing areas.
What a template gets back
Read the area with the shorthand, $page->relatedPages in Smarty or page.relatedPages in Twig; it returns what the explicit getter returns. getAreaRecord() loads the record and returns it, or nothing; getAreaRecords() loads them all in one query and returns them in the stored order, or nothing when the area is empty. Either way the records are looked up as the visitor: a record the visitor may not see, because it is unpublished or restricted to a group they are not in, is left out, exactly as if the author had not chosen it. Signed in to the admin, you may see records your visitors do not, so check a page with these areas signed out.