From d74bd38cd4c393b9c311227fa94f978d386ba394 Mon Sep 17 00:00:00 2001 From: Chris Meagher Date: Sun, 22 Sep 2019 02:15:48 +0100 Subject: [PATCH] Kentico Cloud -> Kentico Kontent rename --- CHANGELOG.md | 4 +- README.md | 144 +++++++++--------- package.json | 11 +- src/GridsomeContentItem.js | 5 +- src/GridsomeRichTextHtmlTransformer.js | 6 +- ...CloudSource.js => KenticoKontentSource.js} | 4 +- src/index.js | 16 +- 7 files changed, 95 insertions(+), 95 deletions(-) rename src/{KenticoCloudSource.js => KenticoKontentSource.js} (96%) diff --git a/CHANGELOG.md b/CHANGELOG.md index c9f2ed7..7e2fabb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,5 +7,5 @@ All notable changes to this project will be documented in this file. ### Bug Fixes -* Prevent duplicate asset nodes ([9452267](https://github.com/CMeeg/gridsome-source-kentico-cloud/commit/9452267)), closes [#3](https://github.com/CMeeg/gridsome-source-kentico-cloud/issues/3) -* Prevent error being thrown when content with no URL slug field ([e857f11](https://github.com/CMeeg/gridsome-source-kentico-cloud/commit/e857f11)), closes [#4](https://github.com/CMeeg/gridsome-source-kentico-cloud/issues/4) +* Prevent duplicate asset nodes ([9452267](https://github.com/CMeeg/gridsome-source-kentico-kontent/commit/9452267)), closes [#3](https://github.com/CMeeg/gridsome-source-kentico-kontent/issues/3) +* Prevent error being thrown when content with no URL slug field ([e857f11](https://github.com/CMeeg/gridsome-source-kentico-kontent/commit/e857f11)), closes [#4](https://github.com/CMeeg/gridsome-source-kentico-kontent/issues/4) diff --git a/README.md b/README.md index 05713e7..9f947d8 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,46 @@ -# @meeg/gridsome-source-kentico-cloud +# @meeg/gridsome-source-kentico-kontent -A [Kentico Cloud](https://kenticocloud.com/) data source plugin for [Gridsome](https://gridsome.org/) that aims to support all of the main features of Kentico Cloud: +A [Kentico Kontent](https://kontent.ai/) data source plugin for [Gridsome](https://gridsome.org/) that aims to support all of the main features of Kentico Kontent: ✔ Content (including all content element types)\ ✔ Taxonomy\ ✔ Assets -The plugin also provides additional features and extension points to ease working with your Kentico Cloud content in Gridsome. Please keep reading to learn about: +The plugin also provides additional features and extension points to ease working with your Kentico Kontent content in Gridsome. Please keep reading to learn about: * How to [get started](#getting-started) with this plugin -* The object types and object models that are added to the Gridsome [GraphQL schema](#kentico-cloud-graphql-schema) by this plugin +* The object types and object models that are added to the Gridsome [GraphQL schema](#kentico-kontent-graphql-schema) by this plugin * How to [render Rich Text fields](#rendering-rich-text-fields) using Vue single file components that you define in your app * How to [customise routing](#routing) of content and taxonomy objects * How to [work with Taxonomy](#working-with-taxonomy-in-gridsome) in Gridsome * How to [work with Assets](#working-with-assets-in-gridsome) in Gridsome, and how to transform Asset URLs directly in your GraphQL queries -* How to [create content models](#creating-content-models) to allow you to customise how content from Kentico Cloud is represented as data in Gridsome +* How to [create content models](#creating-content-models) to allow you to customise how content from Kentico Kontent is represented as data in Gridsome * The full list of plugin [configuration options](#configuration) --- ## Getting started -> This getting started guide assumes that you have an existing Gridsome project, and that you want to add Kentico Cloud as a data source using this plugin. If you haven't yet created a Gridsome project, please follow the [Gridsome getting started guide](https://gridsome.org/docs) first and then come back here. +> This getting started guide assumes that you have an existing Gridsome project, and that you want to add Kentico Kontent as a data source using this plugin. If you haven't yet created a Gridsome project, please follow the [Gridsome getting started guide](https://gridsome.org/docs) first and then come back here. ### Install -Use your preferred package manager to add a dependency on `@meeg/gridsome-source-kentico-cloud` to your Gridsome app, for example: +Use your preferred package manager to add a dependency on `@meeg/gridsome-source-kentico-kontent` to your Gridsome app, for example: -* `yarn add @meeg/gridsome-source-kentico-cloud` -* `npm install @meeg/gridsome-source-kentico-cloud` +* `yarn add @meeg/gridsome-source-kentico-kontent` +* `npm install @meeg/gridsome-source-kentico-kontent` ### Add and configure the plugin -Add `@meeg/gridsome-source-kentico-cloud` to the plugins array in your `gridsome.config.js` file, and configure the Kentico Cloud delivery client to fetch data from your [project](https://docs.kenticocloud.com/tutorials/set-up-projects/manage-projects/adding-projects) by specifying your project id in the plugin options: +Add `@meeg/gridsome-source-kentico-kontent` to the plugins array in your `gridsome.config.js` file, and configure the Kentico Kontent delivery client to fetch data from your [project](https://docs.kontent.ai/tutorials/set-up-projects/manage-projects/adding-projects) by specifying your project id in the plugin options: ```javascript plugins: [ { - use: '@meeg/gridsome-source-kentico-cloud', + use: '@meeg/gridsome-source-kentico-kontent', options: { deliveryClientConfig: { - projectId: process.env.KENTICO_CLOUD_PROJECT_ID + projectId: process.env.KENTICO_KONTENT_PROJECT_ID } } } @@ -114,7 +114,7 @@ export default { ### Query and render your content -From this point on you are ready to work with your Kentico Cloud content as data in Gridsome 😎 +From this point on you are ready to work with your Kentico Kontent content as data in Gridsome 😎 > If you are new to Gridsome, the following areas of the [docs](https://gridsome.org/docs) should help you get up and running with data: > @@ -130,9 +130,9 @@ From this point on you are ready to work with your Kentico Cloud content as data --- -## Kentico Cloud GraphQL schema +## Kentico Kontent GraphQL schema -The following types of data are sourced from Kentico Cloud and made available for querying via the Gridsome GraphQL data store: +The following types of data are sourced from Kentico Kontent and made available for querying via the Gridsome GraphQL data store: * [Content objects](#content-objects) * [Taxonomy objects](#taxonomy-objects) @@ -140,7 +140,7 @@ The following types of data are sourced from Kentico Cloud and made available fo ### Content objects -Content is available by querying against object types named using the codename of the [content type](https://docs.kenticocloud.com/tutorials/set-up-projects/define-content-models/creating-and-deleting-content-types) they belong to converted to pascal case. For example: +Content is available by querying against object types named using the codename of the [content type](https://docs.kontent.ai/tutorials/set-up-projects/define-content-models/creating-and-deleting-content-types) they belong to converted to pascal case. For example: * Given the codename `article`, the object type will be named `Article` * Given the codename `landing_page`, the object type will be named `LandingPage` @@ -151,7 +151,7 @@ Content is available by querying against object types named using the codename o Every content object type shares a core set of fields that include: -* System fields provided by the Kentico Cloud delivery client +* System fields provided by the Kentico Kontent delivery client * Fields required by this plugin * Fields required by Gridsome @@ -159,21 +159,21 @@ As such, every content object has at least the following fields: | Name | Type | Notes | | --- | --- | --- | -| `id` | `String` | Kentico Cloud's id is used as the object's id | -| `name` | `String` | The name of the content item in Kentico Cloud | -| `codename` | `String` | The codename of the content item in Kentico Cloud | +| `id` | `String` | Kentico Kontent's id is used as the object's id | +| `name` | `String` | The name of the content item in Kentico Kontent | +| `codename` | `String` | The codename of the content item in Kentico Kontent | | `languageCode` | `String` | The language codename of the content item | -| `type` | `String` | The codename of the content type in Kentico Cloud that this content item belongs to | +| `type` | `String` | The codename of the content type in Kentico Kontent that this content item belongs to | | `typeName` | `String` | The GraphQL object type name | | `route` | `String` | The [route](#content-routing) defined for this object type - if this object's `isComponent` field is `true`, this will always be `null` | | `isComponent` | `Boolean` | `true` if this object represents a content component; otherwise `false` - see the section on [content component objects](#content-component-objects) for further details | -| `date` | `Date` | This is equal to the Kentico Cloud `last_modified` date, but is named `date` because that is the convention in Gridsome | +| `date` | `Date` | This is equal to the Kentico Kontent `last_modified` date, but is named `date` because that is the convention in Gridsome | | `slug` | `String` | This is set to the value of the "URL slug" content element if one is defined on the content type that this content belongs to; otherwise `null` | | `path` | `String` | This is the path generated by Gridsome and is based on the route defined for this object type | #### Content element fields -As well as system fields, each object type contains fields that represent each of the content elements of the Kentico Cloud content type that the content belongs to. +As well as system fields, each object type contains fields that represent each of the content elements of the Kentico Kontent content type that the content belongs to. These fields are named using the codename of the corresponding content element converted to camel case. For example: @@ -182,9 +182,9 @@ These fields are named using the codename of the corresponding content element c > If there is a collision of field name a positive auto-incremented integer will be added as a suffix to the field name. > -> For example, a Kentico Cloud content type has a content element with the codename `date` that will collide with the "system" `date` field so it will receive the field name `date1` when added to the corresponding object type in the GraphQL schema. +> For example, a Kentico Kontent content type has a content element with the codename `date` that will collide with the "system" `date` field so it will receive the field name `date1` when added to the corresponding object type in the GraphQL schema. -All types of content element available in Kentico Cloud are supported and are represented in the object type definition as fields: +All types of content element available in Kentico Kontent are supported and are represented in the object type definition as fields: | Content element | Type | Notes | | --- | --- | --- | @@ -203,7 +203,7 @@ All types of content element available in Kentico Cloud are supported and are re #### Content component objects -Content [components](https://docs.kenticocloud.com/tutorials/write-and-collaborate/structure-your-content/structuring-editorial-articles-with-components) used in Rich Text fields are also added to object types in the Gridsome GraphQL schema. +Content [components](https://docs.kontent.ai/tutorials/write-and-collaborate/structure-your-content/structuring-editorial-articles-with-components) used in Rich Text fields are also added to object types in the Gridsome GraphQL schema. The difference between content component objects and "regular" content objects is that content component objects will never have values in their `route` or `path` fields because they are components of larger pieces of content and therefore not intended to be used in isolation. @@ -213,7 +213,7 @@ The `isComponent` system field can be used to filter content component objects i > Item links are primarily used when [rendering Rich Text fields](#rendering-rich-text-fields) so feel free to skip this section unless you really want to read it! 🤓 -When editing content inside Rich Text elements in Kentico Cloud you can [add links to other content items](https://docs.kenticocloud.com/tutorials/write-and-collaborate/write-content/composing-content-in-the-rich-text-editor#a-adding-links) within your Kentico Cloud project. To resolve these links within your Gridsome app, the `path` of the content item that has been linked to must be used as the URL of the link. +When editing content inside Rich Text elements in Kentico Kontent you can [add links to other content items](https://docs.kontent.ai/tutorials/write-and-collaborate/write-content/composing-content-in-the-rich-text-editor#a-adding-links) within your Kentico Kontent project. To resolve these links within your Gridsome app, the `path` of the content item that has been linked to must be used as the URL of the link. Gridsome generates the `path` value for an object (based on a [defined](#content-routing) `route`) when it is inserted into the GraphQL data store via the [Data Store API](https://gridsome.org/docs/data-store-api#collectionaddnodeoptions). @@ -228,7 +228,7 @@ The `ItemLink` object type has these fields: | Name | Type | Notes | | --- | --- | --- | -| `id` | String | Kentico Cloud's id and the id of the corresponding content object | +| `id` | String | Kentico Kontent's id and the id of the corresponding content object | | `typeName` | String | The GraphQL object type name of the corresponding content object | | `path` | String | The path of the corresponding content object | @@ -236,7 +236,7 @@ The `ItemLink` object type has these fields: ### Taxonomy objects -Taxonomy terms are available by querying against object types named using the codename of the [taxonomy group](https://docs.kenticocloud.com/tutorials/set-up-projects/define-content-models/organizing-your-content-with-taxonomies) they belong to converted to pascal case, and prefixed with "Taxonomy". For example: +Taxonomy terms are available by querying against object types named using the codename of the [taxonomy group](https://docs.kontent.ai/tutorials/set-up-projects/define-content-models/organizing-your-content-with-taxonomies) they belong to converted to pascal case, and prefixed with "Taxonomy". For example: * Given the taxonomy group codename `tag`, the object type will be named `TaxonomyTag` * Given the taxonomy group codename `article_topics`, the object type will be named `TaxonomyArticleTopics` @@ -247,7 +247,7 @@ Taxonomy terms are available by querying against object types named using the co Taxonomy term object types share a core set of fields that include: -* System fields provided by the Kentico Cloud delivery client +* System fields provided by the Kentico Kontent delivery client * Fields required by this plugin * Fields required by Gridsome @@ -255,8 +255,8 @@ As such, every taxonomy term object has the following fields: | Name | Type | Notes | | --- | --- | --- | -| `id` | `String` | The codename of the taxonomy term in Kentico Cloud is used as the object's id | -| `name` | `String` | The name of the taxonomy term in Kentico Cloud | +| `id` | `String` | The codename of the taxonomy term in Kentico Kontent is used as the object's id | +| `name` | `String` | The name of the taxonomy term in Kentico Kontent | | `slug` | `String` | A slug is generated so that it can be used when specifying [routes](#taxonomy-routing) for object types | | `terms` | `[]` | Taxonomy terms can have child terms, which are an array of references to [taxonomy objects](#taxonomy-objects) | | `path` | `String` | If a [route](#taxonomy-routing) has been specified for this taxonomy object type Gridsome will generate a path for each object belonging to that type; otherwise the path will be `undefined` | @@ -265,13 +265,13 @@ As such, every taxonomy term object has the following fields: ### Asset objects -[Assets](https://docs.kenticocloud.com/tutorials/write-and-collaborate/manage-assets/viewing-all-your-project-s-assets) are available by querying against an object type named `Asset`. +[Assets](https://docs.kontent.ai/tutorials/write-and-collaborate/manage-assets/viewing-all-your-project-s-assets) are available by querying against an object type named `Asset`. 🙋 See the section on [configuration](#configuration) for options on how to customise naming of the asset object type. #### Asset fields -Every asset object has the following fields provided by the Kentico Cloud delivery client: +Every asset object has the following fields provided by the Kentico Kontent delivery client: | Name | Type | Notes | | --- | --- | --- | @@ -291,7 +291,7 @@ A Rich Text field is a string containing HTML markup, and that HTML markup can c * Anchor links to other content that require resolving the link URL to the actual URL within your application * Assets such as images that may require some flexibility in rendering (such as the use of lazy loading and/or `srcset` and `sizes`) -* Custom elements that represent [content components](https://docs.kenticocloud.com/tutorials/write-and-collaborate/structure-your-content/structuring-editorial-articles-with-components) +* Custom elements that represent [content components](https://docs.kontent.ai/tutorials/write-and-collaborate/structure-your-content/structuring-editorial-articles-with-components) As briefly touched on in the [getting started](#configure-gridsome-to-resolve-rich-text-fields-using-vue-single-file-components) guide, the recommended way to render Rich Text fields when using this plugin is to use a Vue single file component to represent a Rich Text field, which will: @@ -469,7 +469,7 @@ Now if the Rich Text field HTML passed in the `html` prop of the `RichText` comp ### Rendering content components in Rich Text fields -First add a query to your `RichText` component inside a `` block that will fetch all `` objects. The alias for `all` must match the codename of the Kentico Cloud content type that the `` belongs to: +First add a query to your `RichText` component inside a `` block that will fetch all `` objects. The alias for `all` must match the codename of the Kentico Kontent content type that the `` belongs to: > In the following examples, we will create a component to render code snippets, so the `` object type is `CodeSnippet` and content type codename is `code_snippet`: @@ -556,7 +556,7 @@ For example: ```javascript plugins: [ { - use: '@meeg/gridsome-source-kentico-cloud', + use: '@meeg/gridsome-source-kentico-kontent', options: { ... contentItemConfig: { @@ -572,13 +572,13 @@ plugins: [ } ``` -If you opt out of this approach you can use features of the Kentico Cloud delivery client to resolve [content links](https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#url-slugs-links) and [content components](https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#resolving-content-items-and-components-in-rich-text-elements), but not assets. These features of the delivery client are exposed by this plugin when [creating content models](#creating-content-models). +If you opt out of this approach you can use features of the Kentico Kontent delivery client to resolve [content links](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#url-slugs-links) and [content components](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#resolving-content-items-and-components-in-rich-text-elements), but not assets. These features of the delivery client are exposed by this plugin when [creating content models](#creating-content-models). 🙋 See the section on [configuration](#configuration) for options on how to customise Rich Text transformation. ## Routing -The Kentico Cloud plugin will add routes for all [content types](#content-routing) in your project, and can optionally add routes for [taxonomy groups](#taxonomy-routing). +The Kentico Kontent plugin will add routes for all [content types](#content-routing) in your project, and can optionally add routes for [taxonomy groups](#taxonomy-routing). #### Content routing @@ -588,15 +588,15 @@ The default [route](https://gridsome.org/docs/routing) for all content objects a Where: -* `codename` is the [slugified](https://github.com/sindresorhus/slugify) codename of the Kentico Cloud content type that the content belongs to; and +* `codename` is the [slugified](https://github.com/sindresorhus/slugify) codename of the Kentico Kontent content type that the content belongs to; and * `slug` is the [system field](#system-fields) named "slug"; or if no such field is present the `name` system field is slugified -It is possible to override the default route for each of your Kentico Cloud content types using the options exposed by this plugin. To do so you must add an item to the `contentItemConfig.routes` object with a key matching the content type codename you wish to specify the route for, and a value matching the desired route that you wish to use for that content type. For example: +It is possible to override the default route for each of your Kentico Kontent content types using the options exposed by this plugin. To do so you must add an item to the `contentItemConfig.routes` object with a key matching the content type codename you wish to specify the route for, and a value matching the desired route that you wish to use for that content type. For example: ```javascript plugins: [ { - use: '@meeg/gridsome-source-kentico-cloud', + use: '@meeg/gridsome-source-kentico-kontent', options: { ... contentItemConfig: { @@ -623,12 +623,12 @@ If you do not wish for a content type to have a route (and therefore no path i.e There is no routing of Taxonomy objects by default. -To define a route for a Kentico Cloud taxonomy group you must use the options exposed by this plugin. To do so you must add an item to the `taxonomyConfig.routes` object with a key matching the taxonomy group codename you wish to specify the route for, and a value matching the desired route that you wish to use for that taxonomy group. For example: +To define a route for a Kentico Kontent taxonomy group you must use the options exposed by this plugin. To do so you must add an item to the `taxonomyConfig.routes` object with a key matching the taxonomy group codename you wish to specify the route for, and a value matching the desired route that you wish to use for that taxonomy group. For example: ```javascript plugins: [ { - use: '@meeg/gridsome-source-kentico-cloud', + use: '@meeg/gridsome-source-kentico-kontent', options: { ... taxonomyConfig: { @@ -655,9 +655,9 @@ The `slug` field is added to each taxonomy term object by this plugin and is gen The Gridsome documentation describes how to [create a taxonomy page](https://gridsome.org/docs/taxonomies) template to display a `Tag` object and the `Post` objects that reference that `Tag`. -To achieve this with the Kentico Cloud plugin you will need to ensure that you first set up [routing](#taxonomy-routing) for the taxonomy group that you want to list (i.e. your equivalent of `Tag`), and then you can follow along with the documented approach. +To achieve this with the Kentico Kontent plugin you will need to ensure that you first set up [routing](#taxonomy-routing) for the taxonomy group that you want to list (i.e. your equivalent of `Tag`), and then you can follow along with the documented approach. -> The plugin will take care of adding the required references between [Taxonomy objects](#taxonomy-objects) (i.e. your equivalent of `Tag`) and [Content objects](#content-objects) (i.e. your equivalent of `Post`) via any [Taxonomy content elements](#content-element-fields) defined on the the Content object's content type in Kentico Cloud. +> The plugin will take care of adding the required references between [Taxonomy objects](#taxonomy-objects) (i.e. your equivalent of `Tag`) and [Content objects](#content-objects) (i.e. your equivalent of `Post`) via any [Taxonomy content elements](#content-element-fields) defined on the the Content object's content type in Kentico Kontent. ### Other Taxonomy scenarios @@ -697,7 +697,7 @@ query Tags { ## Working with Assets in Gridsome -Assets are represented by the `Asset` object type in the Gridsome GraphQL schema and working with assets is largely the same as working with any other object type. The only "special" thing about `Asset` objects is that the `url` field accepts arguments that allow you to specify [image transformations](#https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#image-transformations) via a custom [field resolver](https://gridsome.org/docs/data-store-api#collectionaddschemafieldfieldname-fn) that uses the `ImageUrlBuilder` class provided by the Kentico Cloud delivery client. +Assets are represented by the `Asset` object type in the Gridsome GraphQL schema and working with assets is largely the same as working with any other object type. The only "special" thing about `Asset` objects is that the `url` field accepts arguments that allow you to specify [image transformations](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#image-transformations) via a custom [field resolver](https://gridsome.org/docs/data-store-api#collectionaddschemafieldfieldname-fn) that uses the `ImageUrlBuilder` class provided by the Kentico Kontent delivery client. The arguments accepted are (omit any of the arguments if you do not wish to use it): @@ -741,15 +741,15 @@ query Assets { ## Creating content models -The default behaviour of this plugin when translating content from Kentico Cloud to objects in the [Gridsome GraphQL data store](#content-objects) should hopefully be sufficient in the majority of cases - a goal of the plugin is to allow consumers to get up and running with as little configuration as possible. However, the plugin does provide an extension point should you find yourself in a position where you want to modify the default behaviour. +The default behaviour of this plugin when translating content from Kentico Kontent to objects in the [Gridsome GraphQL data store](#content-objects) should hopefully be sufficient in the majority of cases - a goal of the plugin is to allow consumers to get up and running with as little configuration as possible. However, the plugin does provide an extension point should you find yourself in a position where you want to modify the default behaviour. -> Extending the translation of `Taxonomy` and `Asset` objects is not currently supported as those types are essentially comprised only of "system" fields and cannot be extended in Kentico Cloud; compared to content types that also have "system" fields, but are designed to be extended in Kentico Cloud by adding content elements. +> Extending the translation of `Taxonomy` and `Asset` objects is not currently supported as those types are essentially comprised only of "system" fields and cannot be extended in Kentico Kontent; compared to content types that also have "system" fields, but are designed to be extended in Kentico Kontent by adding content elements. -The majority of the work required to translate content from Kentico Cloud to the Gridsome GraphQL data store is performed via a custom `ContentItem` [model](https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#creating-models) that is automatically passed to the delivery client as a [type resolver](https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#initializing-deliveryclient). +The majority of the work required to translate content from Kentico Kontent to the Gridsome GraphQL data store is performed via a custom `ContentItem` [model](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#creating-models) that is automatically passed to the delivery client as a [type resolver](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#initializing-deliveryclient). -The default behaviour is to use the same content model for all Kentico Cloud content types. This content model is represented by the `GridsomeContentItem` class, which is a sub-class of `ContentItem`. +The default behaviour is to use the same content model for all Kentico Kontent content types. This content model is represented by the `GridsomeContentItem` class, which is a sub-class of `ContentItem`. -To modify the default behaviour you can create a new class that extends `GridsomeContentItem` and register it as the type resolver for one or more Kentico Cloud content types. +To modify the default behaviour you can create a new class that extends `GridsomeContentItem` and register it as the type resolver for one or more Kentico Kontent content types. ### Extending `GridsomeContentItem` @@ -757,7 +757,7 @@ For demonstration purposes we will use an example where we want to manipulate co This is our scenario: -* There is a Kentico Cloud content type called `Post` that has a codename of `post` +* There is a Kentico Kontent content type called `Post` that has a codename of `post` * The content type has a content element called `Date` with a codename of `date` that can be used to manually specify the date that the post was posted, with the intention being to fall back to the system last modified date if no `Date` value is specified * When this plugin runs it creates an object type in the Gridsome GraphQL schema named `Post`, but the field that represents the `Date` content element is called `date1` because it [collides](#content-element-fields) with the system `date` field @@ -769,7 +769,7 @@ The goal is to: To do this we must first create a custom content model somewhere in our application that extends `GridsomeContentItem` and implements the desired behaviour: ```javascript -const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-cloud'); +const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-kontent'); class PostContentItem extends GridsomeContentItem { // Override the `addFields` function - this is called after all "system" fields are set @@ -817,7 +817,7 @@ class PostContentItem extends GridsomeContentItem { return true; } - // If a date value is null in Kentico Cloud it can be parsed as a zero UTC date + // If a date value is null in Kentico Kontent it can be parsed as a zero UTC date return date.getTime() === 0; } @@ -839,7 +839,7 @@ module.exports = { ... plugins: [ { - use: '@meeg/gridsome-source-kentico-cloud', + use: '@meeg/gridsome-source-kentico-kontent', options: { ... contentItemConfig: { @@ -872,14 +872,14 @@ The `addFields` function seen [earlier](#extending-gridsomecontentitem) effectiv The function that is executed receives a `node` and `field` as arguments: * `node` represents the data that will eventually be inserted into the Gridsome GraphQL data store -* `field` represents the content element data that has come from Kentico Cloud +* `field` represents the content element data that has come from Kentico Kontent The responsibility of the function is to set a value on the `node` that will contain the data from the `field` transformed into whatever format is deemed suitable for the Gridsome GraphQL data store. Field resolvers can be used like this: ```javascript -const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-cloud'); +const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-kontent'); class PostContentItem extends GridsomeContentItem { // This function will be used when resolving the "author" content element of this type @@ -911,23 +911,23 @@ module.exports = PostContentItem; #### Set a field value based on linked content items -We saw earlier that you can [extend how field data is set](#extending-gridsomecontentitem) within a content model by overriding the `addFields` function. The `addFields` function receives a `node` object that represents the data from a single content item from Kentico Cloud transformed into a data structure that will be used to populate the Gridsome GraphQL data store. +We saw earlier that you can [extend how field data is set](#extending-gridsomecontentitem) within a content model by overriding the `addFields` function. The `addFields` function receives a `node` object that represents the data from a single content item from Kentico Kontent transformed into a data structure that will be used to populate the Gridsome GraphQL data store. In the previous example we used the `item` property of the `node` to get and set field values, but the `node` object has other properties that can be used when manipulating field data. For example, in this scenario: -* We have a `Post series` content type in Kentico Cloud with a codename of `post_series` +* We have a `Post series` content type in Kentico Kontent with a codename of `post_series` * The `Post series` content type has a "Linked items" content element called `Posts in series` with codename `posts_in_series` * `Posts in series` has a constraint requiring at least one linked item be set The goal is to: -* Add a `lastUpdated` field to the corresponding `PostSeries` object type in the Gridsome GraphQL schema (there is no corresponding content element on the Kentico Cloud content type) +* Add a `lastUpdated` field to the corresponding `PostSeries` object type in the Gridsome GraphQL schema (there is no corresponding content element on the Kentico Kontent content type) * Set the value of the `lastUpdated` field by getting the linked posts in its `postsInSeries` field, and using the most recent `date` value of the linked `Post` objects ```javascript -const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-cloud'); +const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-kontent'); class PostSeriesContentItem extends GridsomeContentItem { addFields(node) { @@ -974,13 +974,13 @@ module.exports = PostSeriesContentItem; #### Custom Rich Text and Link resolvers -`GridsomeContentItem` uses custom [richTextResolver](https://github.com/Kentico/kentico-cloud-js/blob/master/packages/delivery/DOCS.md#globally) and [urlSlugResolver](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#resolving-url-slugs-globally) functions to aid in the approach for [rendering Rich Text fields](#rendering-rich-text-fields), but if you decide to [opt out](#opting-out-of-this-approach) of that approach you may want to provide your own resolver functions. +`GridsomeContentItem` uses custom [richTextResolver](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#globally) and [urlSlugResolver](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#resolving-url-slugs-globally) functions to aid in the approach for [rendering Rich Text fields](#rendering-rich-text-fields), but if you decide to [opt out](#opting-out-of-this-approach) of that approach you may want to provide your own resolver functions. You can do so like this: ```javascript -const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-cloud'); +const { GridsomeContentItem } = require('@meeg/gridsome-source-kentico-kontent'); class PostContentItem extends GridsomeContentItem { // We need to override the constructor of `GridsomeContentItem` @@ -1013,8 +1013,8 @@ The plugin defines the following namespaces: | Namespace | Description | | --- | --- | -| `gridsome-source-kentico-cloud` | Use this to log very basic info about when the plugin starts and finishes its work | -| `gridsome-source-kentico-cloud:source` | Use this to log detailed information about the work that the plugin is doing | +| `gridsome-source-kentico-kontent` | Use this to log very basic info about when the plugin starts and finishes its work | +| `gridsome-source-kentico-kontent:source` | Use this to log detailed information about the work that the plugin is doing | Please read the debug docs for usage instructions. @@ -1025,16 +1025,16 @@ The plugin exposes various configuration options that are split into the followi ```javascript plugins: [ { - use: '@meeg/gridsome-source-kentico-cloud', + use: '@meeg/gridsome-source-kentico-kontent', options: { deliveryClientConfig: { - // Options for the Kentico Cloud delivery client + // Options for the Kentico Kontent delivery client }, contentItemConfig: { - // Options used when loading Kentico Cloud content data + // Options used when loading Kentico Kontent content data }, taxonomyConfig: { - // Options used when loading Kentico Cloud taxonomy data + // Options used when loading Kentico Kontent taxonomy data } } } @@ -1045,13 +1045,13 @@ plugins: [ ### `deliveryClientConfig` options -These options are identical to the Kentico Cloud delivery client configuration options, with one exception: +These options are identical to the Kentico Kontent delivery client configuration options, with one exception: | Key | Type | Default value | Notes | | --- | --- | --- | --- | | `contentItemsDepth` | `Number` | `3` | Sets the `depth` parameter on content queries, which can be used to [handle missing referenced linked items](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#handling-missing-referenced-linked-items) | -Please see the [Kentico Cloud documentation](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#client-configuration) for a description of all other available options, which include options for setting preview mode, secure mode, and language. +Please see the [Kentico Kontent documentation](https://github.com/Kentico/kentico-kontent-js/blob/delivery%406.2.0/packages/delivery/DOCS.md#client-configuration) for a description of all other available options, which include options for setting preview mode, secure mode, and language. ### `contentItemConfig` options diff --git a/package.json b/package.json index 0acf5df..40c56a6 100644 --- a/package.json +++ b/package.json @@ -1,17 +1,18 @@ { - "name": "@meeg/gridsome-source-kentico-cloud", + "name": "@meeg/gridsome-source-kentico-kontent", "version": "0.1.1", - "description": "Kentico Cloud data source plugin for Gridsome.", + "description": "Kentico Kontent data source plugin for Gridsome.", "author": "Chris Meagher", "license": "MIT", - "homepage": "https://github.com/CMeeg/gridsome-source-kentico-cloud#readme", - "repository": "https://github.com/CMeeg/gridsome-source-kentico-cloud.git", + "homepage": "https://github.com/CMeeg/gridsome-source-kentico-kontent#readme", + "repository": "https://github.com/CMeeg/gridsome-source-kentico-kontent.git", "main": "src/index.js", "keywords": [ "gridsome", "gridsome-plugin", "gridsome-source", - "kentico-cloud" + "kentico-kontent", + "kontent" ], "files": [ "src/*.js" diff --git a/src/GridsomeContentItem.js b/src/GridsomeContentItem.js index 95b2c68..d1583e5 100644 --- a/src/GridsomeContentItem.js +++ b/src/GridsomeContentItem.js @@ -19,8 +19,7 @@ class GridsomeContentItem extends ContentItem { if (richTextHtmlTransformer.canTransformLinks()) { defaultData.urlSlugResolver = (link, context) => { - // TODO: Ask Kentico Cloud why this seems to be being ignored - // TODO: Does this now work? + // TODO: This doesn't always appear to get called - raise issue with Kentico Kontent when have repro steps // Removing this results in warnings from the DeliveryClient when advanced logging is turned on return this.resolveLink(link, context); }; @@ -120,7 +119,7 @@ class GridsomeContentItem extends ContentItem { if (element.type === 'asset') { field.value = field.value.map(asset => { // We will use the asset url as the id as it is unique, and the id is not provided - // TODO: Ask Kentico Cloud if it can be provided + // TODO: Raise issue with Kentico Kontent to ask if asset ids can be provided asset.id = asset.url; diff --git a/src/GridsomeRichTextHtmlTransformer.js b/src/GridsomeRichTextHtmlTransformer.js index 94c4883..332d565 100644 --- a/src/GridsomeRichTextHtmlTransformer.js +++ b/src/GridsomeRichTextHtmlTransformer.js @@ -40,7 +40,7 @@ class GridsomeRichTextHtmlTransformer { const $ = cheerio.load(html, { decodeEntities: false }); - // Kentico Cloud can return an empty paragraph element if there is no content, which is of no use + // Kentico Kontent can return an empty paragraph element if there is no content, which is of no use // If the rich text element has no text content, just return an empty string if ($(`.${wrapperCssClass}`).text().trim() === '') { @@ -48,8 +48,8 @@ class GridsomeRichTextHtmlTransformer { } // Transform item links - // N.B. This shouldn't be necessary, but the `urlSlugResolver` feature of the Kentico Cloud SDK doesn't appear to work - // TODO: Does the feature now work, and this can be removed? + // N.B. This shouldn't be necessary, but the `urlSlugResolver` feature of the Kentico Kontent SDK doesn't appear to work all of the time + // TODO: If this does work consistently in future, this can be removed this.transformItemLinks($); diff --git a/src/KenticoCloudSource.js b/src/KenticoKontentSource.js similarity index 96% rename from src/KenticoCloudSource.js rename to src/KenticoKontentSource.js index 7243f0e..156e22d 100644 --- a/src/KenticoCloudSource.js +++ b/src/KenticoKontentSource.js @@ -1,6 +1,6 @@ const { ImageUrlBuilder, ImageCompressionEnum, ImageFormatEnum } = require('@kentico/kontent-delivery'); -class KenticoCloudSource { +class KenticoKontentSource { constructor(deliveryClient, contentItemFactory, taxonomyItemFactory, logger) { this.deliveryClient = deliveryClient; this.contentItemFactory = contentItemFactory; @@ -399,4 +399,4 @@ class KenticoCloudSource { } } -module.exports = KenticoCloudSource; +module.exports = KenticoKontentSource; diff --git a/src/index.js b/src/index.js index 4a7c646..80d0575 100644 --- a/src/index.js +++ b/src/index.js @@ -1,11 +1,11 @@ const DeliveryClient = require('./GridsomeDeliveryClient'); -const KenticoCloudSource = require('./KenticoCloudSource'); +const KenticoKontentSource = require('./KenticoKontentSource'); const GridsomeContentItemFactory = require('./GridsomeContentItemFactory'); const GridsomeContentItem = require('./GridsomeContentItem'); const GridsomeTaxonomyItemFactory = require('./GridsomeTaxonomyItemFactory'); const Logger = require('./Logger'); -class KenticoCloudSourcePlugin { +class KenticoKontentSourcePlugin { static defaultOptions() { return { deliveryClientConfig: { @@ -36,28 +36,28 @@ class KenticoCloudSourcePlugin { }; constructor(api, options) { - const logger = new Logger('gridsome-source-kentico-cloud'); + const logger = new Logger('gridsome-source-kentico-kontent'); api.loadSource(async store => { const deliveryClient = new DeliveryClient(options.deliveryClientConfig); const contentItemFactory = new GridsomeContentItemFactory(options.contentItemConfig); const taxonomyItemFactory = new GridsomeTaxonomyItemFactory(options.taxonomyConfig); - const kenticoCloudSource = new KenticoCloudSource( + const kenticoKontentSource = new KenticoKontentSource( deliveryClient, contentItemFactory, taxonomyItemFactory, logger ); - logger.log('Started loading content from Kentico Cloud'); + logger.log('Started loading content from Kentico Kontent'); - await kenticoCloudSource.load(store); + await kenticoKontentSource.load(store); - logger.log('Finished loading content from Kentico Cloud'); + logger.log('Finished loading content from Kentico Kontent'); }); } } -module.exports = KenticoCloudSourcePlugin; +module.exports = KenticoKontentSourcePlugin; module.exports.GridsomeContentItem = GridsomeContentItem;