Build a model

A model is a content type: Article, Author, Product. This page walks through making one in the admin, from the name to the last field.

You need the Admin or Developer role.

Plan it firstCopy Anchor Link

Once a model has entries, changing a field means converting the values already stored. Before you start, sketch on paper:

• The models, one per kind of thing on the site.
• The fields each one needs, and which are required.
• The links between them: an article has an author, a product has related products.
• Which models hold one entry only, such as site settings or a home page.

See Content model for every field type and what the API returns for it.

Create the modelCopy Anchor Link

1. Choose Models, then New model.
2. Fill in Unique Model Name, such as Article.
3. Check the Namespace. Capa fills it in from the name: Blog Post becomes blog_post. This is the name your code uses, so keep it short and plain.
4. Optionally pick a category under Specify Category, or type a new one.
5. Set the Model Options you need.
6. Choose Create Model.

The new model has one field already: a required title. It appears on Models marked Draft until you first save its fields.

Add fieldsCopy Anchor Link

1. Open the model's ⋯ menu on Models and choose Edit fields. The entry editor opens in field-editing mode, showing the model's fields in cards.
2. At the bottom of a card, choose Add field, then pick a type.
3. The field's settings open. Set its Name. The Namespace follows the name until you change it.
4. Choose Done.
5. Add the rest of your fields the same way.
6. Choose Save fields in the top bar.

Nothing is saved until you choose Save fields. Done only closes a field's settings. If you leave with unsaved fields, Capa asks whether to save them.

You can also reach field editing from any entry of the model: press ⌘. (Ctrl+.), or choose Fields in the entry's details panel.

Field settingsCopy Anchor Link

There are no unique, default, minimum, maximum or pattern settings.

Link models togetherCopy Anchor Link

To give an article an author:

1. Create the Author model first.
2. In Article, add a field with the Model type and name it Author.
3. Under Related model, choose Author.
4. For several authors, set Entries to A list of values.
5. Choose Done, then Save fields.

A model can link to itself, for example a page with a parent page.

Editors then pick an author from a list, or create one without leaving the article. To show the author's own fields inside the article form, set the field's Display in the layout builder.

Store its fields inside this entry is an older way to embed, which copies values into the entry instead of linking. Prefer a link.

Arrange the editorCopy Anchor Link

The cards, columns and widths editors see are the model's layout. Set them up in the same field-editing mode. See Layout builder.

Model settingsCopy Anchor Link

In field-editing mode, choose Model settings above the fields to change:

• Model name.
• Namespace. Your code's reads of the old namespace stop working at once, with 404 model_not_found.
• Route and Slug field: the page of your site that shows an entry, such as /blog/[slug]. Preview uses it to open the right page.
• Pass through into parent forms by default: models that link to this one show its fields inline, instead of a link.

Choose Update to save.

CategoriesCopy Anchor Link

Categories group models on the Models page. Filter by one with Category. To add, rename or delete categories, open that filter and choose Manage categories. Deleting a category leaves its models alone.

Duplicate a modelCopy Anchor Link

Choose Duplicate in the model's ⋯ menu. The copy is named "Article Copy", with its fields and layout but no entries. Its namespace ends in _copy_ and a number: change it in Model settings before anyone uses it.

Delete a modelCopy Anchor Link

Choose Delete in the model's ⋯ menu and confirm.

After your team starts writingCopy Anchor Link

Once a model has entries, adding a field, rearranging the layout, renaming a field and changing Required still save at once. Changing a field's type, namespace or related model opens a review first, and so does removing a field. The review shows what happens to the stored values before anything changes. See Change a field's type.

RelatedCopy Anchor Link

• Content model: field types and relations.
• Layout builder: cards, columns and widths.
• TypeScript: types generated from your models.