diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index a89ce419ac..6729dc1c96 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -57,6 +57,9 @@ Component models can't be created with CLI tools. Use the [Content-type Builder] Components models are stored in the `./src/components` folder. Every component has to be inside a subfolder, named after the category the component belongs to (see [project structure](/cms/project-structure)). +Components also accept an optional preview image, displayed in the dynamic zone picker +instead of their icon (see [Component preview images](#component-preview-images)). + ## Model schema The `schema.json` file of a model consists of: @@ -96,6 +99,13 @@ The `info` key in the model's schema describes information used to display the m | `singularName` | String | Singular form of the content-type name.
Used to generate the API routes and databases/tables collection.

Should be kebab-case. | | `pluralName` | String | Plural form of the content-type name.
Used to generate the API routes and databases/tables collection.

Should be kebab-case. | | `description` | String | Description of the model | +| `icon` | String | Name of the [Strapi icon](https://github.com/strapi/design-system) used to represent the model in the admin panel | +| `preview` | String | Path or URL of an image used to represent a component in the admin panel.

Components only. See [Component preview images](#component-preview-images). | + +:::note +This `preview` parameter is unrelated to the [Preview feature](/cms/features/preview). +That feature previews front-end content, and uses the `preview` object of `config/admin`. +::: ```json title="./src/api/[api-name]/content-types/restaurant/schema.json" @@ -107,6 +117,35 @@ The `info` key in the model's schema describes information used to display the m }, ``` +#### Component preview images + +Components accept an optional `preview` parameter in their `info` object. It points to an image representing the component in the [dynamic zone picker](/cms/features/content-manager#dynamic-zones). + +The `preview` parameter accepts: + +- A root-relative path to an image placed in the project's `public` directory, for instance `/_component-screenshots/hero-section.png`. The image is served by the [`public` middleware](/cms/configurations/middlewares#public), which does not serve paths starting with `/uploads/`. +- An absolute URL pointing to an external image host. + +:::caution +[Media Library](/cms/features/media-library) images are served from `/uploads/`, so they cannot be used as preview images. Commit the file to `public` instead. +::: + +```json title="./src/components/sections/hero-section.json" +{ + "info": { + "displayName": "Hero Section", + "icon": "layout", + "preview": "/_component-screenshots/hero-section.png" + } +} +``` + +When `preview` is omitted, or when the image fails to load, the admin panel falls back to the component's `icon`. + +:::note +The `preview` parameter must be set manually in the component's schema file. The Content-type Builder cannot upload a preview image yet. +::: + ### Model attributes The content structure of a model consists of a list of attributes. Each attribute has a `type` parameter, which describes its nature and defines the attribute as a simple piece of data or a more complex structure used by Strapi. @@ -572,6 +611,10 @@ Component fields create a relation between a content-type and a component struct } ``` +These parameters are set on the attribute of the content-type using the component. +Parameters set on the component itself, such as its preview image, belong to its own +`info` object (see [Component preview images](#component-preview-images)). + #### Dynamic zones Dynamic zones create a flexible space in which to compose content, based on a mixed list of [components](#components-json). diff --git a/docusaurus/docs/cms/features/content-manager.md b/docusaurus/docs/cms/features/content-manager.md index 2692df834f..0d1f5d15ea 100644 --- a/docusaurus/docs/cms/features/content-manager.md +++ b/docusaurus/docs/cms/features/content-manager.md @@ -426,6 +426,10 @@ Dynamic zones are a combination of components, which themselves are composed of }} /> +In the component picker, each component displays an icon. +A component whose schema defines a preview image displays that image as a thumbnail instead, and hovering over it shows an enlarged version. +Developers set this image in the [component schema](/cms/backend-customization/models#component-preview-images). + 1. Click on the **Add a component to [dynamic zone name]** button. 2. Choose a component available for the dynamic zone. 3. Fill in the fields of the component.