From 5af9d6d1cb13a3880e314a810878d9a954d0a422 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bruno=20Zori=C4=87?= Date: Tue, 11 Jan 2022 20:44:09 +0100 Subject: [PATCH] refactor(content-model-plugins): rename plugins (#377) --- .../headless-cms/content-model-plugins.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/how-to-guides/webiny-applications/headless-cms/content-model-plugins.mdx b/docs/how-to-guides/webiny-applications/headless-cms/content-model-plugins.mdx index a44576547..1d2436461 100644 --- a/docs/how-to-guides/webiny-applications/headless-cms/content-model-plugins.mdx +++ b/docs/how-to-guides/webiny-applications/headless-cms/content-model-plugins.mdx @@ -38,7 +38,7 @@ The most straightforward way to define content models and content model groups w ### Using Plugins -And although we can get pretty far by defining content models and content model groups via the Admin Area, on the other hand, we can also do this within our application code, by registering one or more [`ContentModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelPlugin.ts#L4) and [`ContentModelGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelGroupPlugin.ts#L4) plugins. Once defined, content models and content model groups can be then used via the Admin Area in the same way as if they were created regularly, via the Content Model Editor. +And although we can get pretty far by defining content models and content model groups via the Admin Area, on the other hand, we can also do this within our application code, by registering one or more [`CmsModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsModelPlugin.ts#L4) and [`CmsGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsGroupPlugin.ts#L4) plugins. Once defined, content models and content model groups can be then used via the Admin Area in the same way as if they were created regularly, via the Content Model Editor. Some of the benefits of this approach are: @@ -56,12 +56,12 @@ In the following sections, we cover a couple of examples that show how to define In this example, we show how we can define a simple **Product** content model, that belongs to the **E-Commerce** content model group. Both plugins can be defined within a single file, in our case, [`api/code/headlessCMS/src/plugins/models.ts`](https://github.com/webiny/webiny-examples/blob/master/headless-cms/content-model-plugins/basic/api/code/headlessCMS/src/plugins/models.ts): ```ts title="api/code/headlessCMS/src/plugins/models.ts" -import { ContentModelPlugin } from "@webiny/api-headless-cms/content/plugins/ContentModelPlugin"; -import { ContentModelGroupPlugin } from "@webiny/api-headless-cms/content/plugins/ContentModelGroupPlugin"; +import { CmsModelPlugin } from "@webiny/api-headless-cms/content/plugins/CmsModelPlugin"; +import { CmsGroupPlugin } from "@webiny/api-headless-cms/content/plugins/CmsGroupPlugin"; export default [ // Defines a new "E-Commerce" content models group. - new ContentModelGroupPlugin({ + new CmsGroupPlugin({ id: "ecommerce", name: "E-Commerce", slug: "e-commerce", @@ -69,7 +69,7 @@ export default [ }), // Defines a new "Product" content model. - new ContentModelPlugin({ + new CmsModelPlugin({ name: "Product", modelId: "product", group: { @@ -124,13 +124,13 @@ Once registered, we should end up with the following two items in our Admin Area src={basicsPluginsWork} /> -As shown in the example, the [`ContentModelGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelGroupPlugin.ts#L4) receives a [`CmsContentModel`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/types.ts#L282) object upon instantiation. It lets us define all of the content model's properties, like its name, ID (`modelId`), a content model group to which it belongs to, and most importantly, all of the fields that it consists of. +As shown in the example, the [`CmsGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsGroupPlugin.ts#L4) receives a [`CmsContentModel`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/types.ts#L282) object upon instantiation. It lets us define all of the content model's properties, like its name, ID (`modelId`), a content model group to which it belongs to, and most importantly, all of the fields that it consists of. -All of the fields of a single content model are defined via the [`fields`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/types.ts#L327) property, which is an array of [`CmsContentModelField`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/types.ts#L99) objects. Note that some of the properties that we need to define for each field are simpler than others, for example `label` or `placeholderText`. On the other hand, properties like `type`, `renderer.name`, and `validation.name` contain values that actually reference other registered plugins. In case an invalid reference was provided, an error will be thrown and you will have to make corrections. +All of the fields of a single content model are defined via the [`fields`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/types.ts#L327) property, which is an array of [`CmsContentModelField`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/types.ts#L99) objects. Note that some of the properties that we need to define for each field are simpler than others, for example `label` or `placeholderText`. On the other hand, properties like `type`, `renderer.name`, and `validation.name` contain values that actually reference other registered plugins. In case an invalid reference was provided, an error will be thrown and you will have to make corrections. :::info -All available [field types (`type`)](https://github.com/webiny/webiny-js/tree/v5.11.0/packages/api-headless-cms/src/content/plugins/graphqlFields), [field renderers (`renderer.name`)](https://github.com/webiny/webiny-js/tree/v5.11.0/packages/app-headless-cms/src/admin/plugins/fieldRenderers), and [field validators (`validators.name`)](https://github.com/webiny/webiny-js/tree/v5.11.0/packages/api-headless-cms/src/content/plugins/validators) can be found in our GitHub repository. +All available [field types (`type`)](https://github.com/webiny/webiny-js/tree/v5.21.0/packages/api-headless-cms/src/content/plugins/graphqlFields), [field renderers (`renderer.name`)](https://github.com/webiny/webiny-js/tree/v5.21.0/packages/app-headless-cms/src/admin/plugins/fieldRenderers), and [field validators (`validators.name`)](https://github.com/webiny/webiny-js/tree/v5.21.0/packages/api-headless-cms/src/content/plugins/validators) can be found in our GitHub repository. ::: :::tip @@ -144,8 +144,8 @@ Finally, note that both the **Product** content model and the **E-Commerce** con In this example, we show how we can define content models and content model groups only for a specific locale, in our case, the `en-US`. ```ts title="api/code/headlessCMS/src/plugins/models.ts" -import { ContentModelPlugin } from "@webiny/api-headless-cms/content/plugins/ContentModelPlugin"; -import { ContentModelGroupPlugin } from "@webiny/api-headless-cms/content/plugins/ContentModelGroupPlugin"; +import { CmsModelPlugin } from "@webiny/api-headless-cms/content/plugins/CmsModelPlugin"; +import { CmsGroupPlugin } from "@webiny/api-headless-cms/content/plugins/CmsGroupPlugin"; import { ContextPlugin } from "@webiny/handler/plugins/ContextPlugin"; import { CmsContext } from "@webiny/api-headless-cms/types"; @@ -157,10 +157,10 @@ export default [ } context.plugins.register([ - new ContentModelGroupPlugin({ + new CmsGroupPlugin({ ... }), - new ContentModelPlugin({ + new CmsModelPlugin({ ... }) ]); @@ -168,7 +168,7 @@ export default [ ]; ``` -Note that we've used the [`ContextPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/handler/src/plugins/ContextPlugin.ts#L7) first, in order to be able to access the dynamic `context` object, and the `context.i18nContent.getLocale` method. Once we've determined that the `en-US` is the current locale, we proceed by registering the [`ContentModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelPlugin.ts#L4) and [`ContentModelGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelGroupPlugin.ts#L4) plugins, as seen in the previous example. +Note that we've used the [`ContextPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/handler/src/plugins/ContextPlugin.ts#L7) first, in order to be able to access the dynamic `context` object, and the `context.i18nContent.getLocale` method. Once we've determined that the `en-US` is the current locale, we proceed by registering the [`CmsModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsModelPlugin.ts#L4) and [`CmsGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsGroupPlugin.ts#L4) plugins, as seen in the previous example. :::tip @@ -188,17 +188,17 @@ When it comes to security, both ways of defining content models and content mode #### Can I convert a content model that was defined via Admin Area into a plugin (and vice-versa)? -You can, but it will require a bit of manual work. For example, if you wanted to convert a content model that was defined via Admin Area into a plugin, you would have to find it directly in the database, and copy the data into your application code and try to fit it into the [`ContentModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelPlugin.ts#L4) plugin. +You can, but it will require a bit of manual work. For example, if you wanted to convert a content model that was defined via Admin Area into a plugin, you would have to find it directly in the database, and copy the data into your application code and try to fit it into the [`CmsModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsModelPlugin.ts#L4) plugin. If you're doing this and require additional assistance, feel free to contact us over our community [Slack](https://www.webiny.com/slack). -#### What's the difference between the `id` and `fieldId` properties in the [`ContentModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelPlugin.ts#L4) plugin? +#### What's the difference between the `id` and `fieldId` properties in the [`CmsModelPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsModelPlugin.ts#L4) plugin? Both `id` and `fieldId` fields represent unique IDs of the field. We can assign any string value to them, but, for easier maintenance, we suggest you use a [camelCase](https://en.wikipedia.org/wiki/Camel_case) version of the actual name of the field. So, if the name of the field was **Author Name**, then we'd use `authorName` as the `id` and `fieldId`. There is a difference in how these two IDs are used internally within Headless CMS' application code, but this is more important when a content model is defined regularly, via the [Content Model Editor](/docs/how-to-guides/webiny-applications/headless-cms/content-model-plugins#via-the-admin-area). In case where a content model is defined via a plugin, we can simply use the same value for both fields. -#### What are the values that I can pass to the `icon` property of the [`ContentModelGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.11.0/packages/api-headless-cms/src/content/plugins/ContentModelGroupPlugin.ts#L4) plugin? +#### What are the values that I can pass to the `icon` property of the [`CmsGroupPlugin`](https://github.com/webiny/webiny-js/blob/v5.21.0/packages/api-headless-cms/src/content/plugins/CmsGroupPlugin.ts#L4) plugin? When defining content model groups via Admin Area, we pick its icon via a simple drop-down menu: