Gatsby source plugin for Kentico Cloud

This repo contains a Gatsby (v2) source plugin that retrieves data from the Kentico Cloud Delivery API.

How to run the code

You can use the plugin in any of the following ways:

Install to your existing Gatsby project

Install the gatsby-source-kentico-cloud NPM package,
```
npm install --save gatsby-source-kentico-cloud
```
Configure the plugin in gatsby-config.js file

The source plugin uses the Kentico Cloud SDK in the background.

Configuration object(example)

deliveryClientConfig* - Kentico Cloud client configuration object of the JS SDK.
languageCodenames* - array of language codenames that defines what languages a configured for the project - the first one is considered as the default one.

* required property

module.exports = {
  ...
  plugins: [
    ...
    {
      resolve: `gatsby-source-kentico-cloud`,
      options: {
        deliveryClientConfig: { // Configuration object
          projectId: `XXX`,
          typeResolvers: []
        },
        languageCodenames: [ // example configuration
          `en-US`, // default language
          `es-ES`,
        ]
      }
    }
    ...
  ]
  ...
}

Run gatsby develop and data from Kentico Cloud are provided in Gatsby GraphQL model. All Kentico Cloud content element values reside inside of the elements property of kenticoCloudItem nodes.

Scaffold your project using Gatsby Kentico Cloud starter site

Use the gatsby-starter-kentico-cloud starter site that includes this source plugin

Gatsby gallery

Features

The plugin creates GraphQL nodes for all Kentico Cloud content types, content items, and its language variants.

The node names are prefixed with kenticoCloud. More specifically, content type nodes are prefixed by kenticoCloudType and content items and their language variants are prefixed with kenticoCloudItem.

GraphQL nodes of content items contain the ordinary system and elements properties. However, the properties inside elements always have an internal structure that the aforementioned Delivery SDK produces with modifications described in following section.

Content item <-> content type relationships

This relationship is captured in the contentItems navigation property of all kenticoCloudType nodes. In the opposite direction, in all kenticoCloudItem nodes, it can be found in the contentType navigation property.

Example

You can use the GraphiQL interface to experiment with the data structures produced by the source plugin. For instance, you can fetch a content item of the Project reference type (by querying allKenticoCloudItemProjectReference) and use the contentType navigation property to get a full list of all of the elements in the underlying content type. Like so:

{
  allKenticoCloudItemProjectReference {
    edges {
      node {
        elements {
          name___teaser_image__name {
            value
          }
        }
        contentType {
          elements {
            name
            codename
            type
          }
        }
      }
    }
  }
}

Language variant relationships

This relationship is captured by the otherLanguages navigation property of all content item nodes in other language.

Example

For instance, you can get the names of all content items of the Speaking engagement type (by querying kenticoCloudItemSpeakingEngagement) in their default language as well as other languages all at once:

{
  allKenticoCloudItemSpeakingEngagement {
    edges {
      node {
        elements {
          name {
            value
          }
        }
        otherLanguages {
          elements {
            name {
              value
            }
          }
        }
      }
    }
  }
}

returns in case of two languages

{
  "data": {
    "allKenticoCloudItemSpeakingEngagement": {
      "edges": [
        {
          "node": {
            "elements": {
              "name": "Speaking engagement"
            }
            "otherLanguages": [
              {
                "elements": {
                  "name": "Hablando de compromiso"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

### Linked items elements relationships

Each Linked items element does differ from classic JS SDK structure. They are replaced by Gatsby GraphQL node references that can be used to traverse to the nodes linked through the use of the Linked items element.

Example

Should a Linked items element in KC contain items of only one type, you’ll be able to specify elements and other properties of that type directly (directly under the related_project_references in the following example). However, once you add linked items of multiple types, you’ll have to specify their properties using the ... on [type name] syntax (so called “inline fragments” in the GraphQL terminology).

The related_project_refereces_nodes will give you the full-fledged Gatsby GraphQL nodes with all additional properties and links.

:bulb: Notice the encapsulation into the ... on Node GraphQL inline fragment. This prevent failing creating GraphQL model when this field does not contain i.e. Blog post (KenticoCloudItemBlogpostReference) linked item.

{
  allKenticoCloudItemProjectReference {
    edges {
      node {
        elements {
          related_project_references {
            ... on Node {
              __typename
              ... on KenticoCloudItemBlogpostReference {
                elements {
                  name___teaser_image__name {
                    value
                  }
                }
              }
              ... on KenticoCloudItemProjectReference {
                elements {
                  name___teaser_image__name {
                    value
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

:bulb: When you are modelling linked items, make sure you have no element with the same codename of different type. In case you had some, they would be omitted from the model and the following warning is logged during model generation.

KenticoCloudItemArticle.elements.related_articles[].elements.manufacturer.value:
 - type: array<object> # THIS IS CHECK BOX ELEMENT
   value: [ { name: 'Aerobie', codename: 'aerobie' } ]
 - type: string # THIS IS TEXT ELEMENT
   value: 'Hario'

Since v 3.0.0 it is possible to model circular dependency in Kentico Cloud and use this plugin at one time. When the circular dependency is detected during the GraphQL generation, warning is logged to the console and a flag cycleDetected is placed next to the elements and system property.

Rich text resolution

With following features, it is possible to resolve rich text into the HTML string, that could be injected to the site. For more complex scenarios, it is possible to use the raw value property in combination with linked_items, links, and images property

Embedded JS SDK resolution

Since Kentico Cloud Delivery SDK could resolve links and also linked items and components in rich text elements by implementing the resolvers, Kentico Cloud Gatsby source plugin is enriching the internal SDK structure in GraphQL model by resolvedHtml property containing the resolved value.

`summary` rich text element example

{
  ...
    node {
      elements {
        summary {
          value // NORMAL value
          resolvedHtml // resolved output
        }
      }
    }
  ...
}

Content items and components in Rich text elements

As with the previous example, all rich text element containing inline content items or components have an accompanying linked_items property which is referencing them.

Example

{
  allKenticoCloudItemBlogpostReference {
    edges {
      node {
        elements {
          summary {
            value
            linked_items {
              ... on Node {
              __typename
              ... on KenticoCloudItemBlogpostReference {
                elements {
                  name___teaser_image__name {
                    value
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Links in Rich text elements

All rich text properties with content items linked in the element also have an accompanying links property.

Example

{
  allKenticoCloudItemBlogpostReference {
    edges {
      node {
        elements {
          summary {
            value
            links {
              codename
              linkId
              type
              urlSlug
            }
          }
        }
      }
    }
  }
}

Images in Rich text elements

All rich text properties with content items linked in the element also have an accompanying images property.

Example

{
  allKenticoCloudItemBlogpostReference {
    edges {
      node {
        elements {
          summary {
            value
            images {
              imageId
              description
              url
            }
          }
        }
      }
    }
  }
}

Reverse link relationships

All nodes have a usedByContentItems property that reflects the other nodes in which the given node is used as linked content in Linked items or Rich text elements.

Development prerequisites

Node.js with NPM installed

Debugging

To get a smooth debugging experience, you can temporarily copy the gatsby-source-kentico-cloud directory of the source plugin to the /plugins directory of your project and run npm install and npm run build there. Then your project would use this local source plugin.

Note: It might be necessary to remove /.cache, /node_modules, /package-lock.json and run npm install again.

Troubleshoot

When you change the structure of the data, or the data itself and then gatsby develop, or gatsby build command raise an error about the Gatsby presumes the old data structure. Try to remove .cache folder and run the command again, it is quite usual that Gatsby is caching the information about the content structure and does not clear it.

Further information

For more developer resources, visit the Kentico Cloud Developer Hub at https://developer.kenticocloud.com.

Running projects

Guides and blog posts

Previous versions

For version 2 use this branch.

Feedback & Contributing

Check out the contributing page to see the best places for file issues, to start discussions, and begin contributing.