Skip to content
Gatsby source plugin for Kentico Kontent
JavaScript
Branch: master
Clone or download
Simply007 Merge pull request #86 from Kentico/CollierCZ-patch-1
Restore links to sourcing guide and starter site.
Latest commit 1b59522 Nov 20, 2019

README.md

Gatsby source plugin for Kentico Kontent

Gatsby plugin library Stack Overflow

npm version Build Status npm Maintainability Test Coverage

⚠️ This version is still in beta phase, it is possible that some adjustments might cause other breaking changes. For previous version snapshots see Previous versions section.

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

Get started

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

A) Use the Kentico Kontent sourcing guide

If you are new to the Gatsby ecosystem. The best way to start with using Gatsby & Kentico Kontent is to follow the official sourcing guide for Kentico Kontent. To learn more about sourcing from headless CMSs see the Gatsby docs overview page.

B) Install the plugin in your existing Gatsby project

  1. Install the @kentico/gatsby-source-kontent NPM package.

    npm install --save @kentico/gatsby-source-kontent
  2. Configure the plugin in gatsby-config.js file.

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

    • deliveryClientConfig* - Kentico Kontent client configuration object of the JS SDK (like Preview API, Secure API, etc.).

    • languageCodenames* - array of language codenames that defines what languages a configured for the project - the first one is considered as the default one. Initial "Getting started" project has configured just one language default.

    • enableLogging - enable logging of the source plugin. Turned off by default.

    • includeRawContent - allows to include internal.content property as a part fo the GraphlQL model. Turned off by default.

      * required property

    Configuration object

    module.exports = {
      ...
      plugins: [
        ...
        {
          resolve: `@kentico/gatsby-source-kontent`,
          options: {
            deliveryClientConfig: { // Configuration object
              projectId: `XXX`,
              typeResolvers: []
            },
            languageCodenames: [ // example configuration
              `default`, // default language
            ]
          }
        }
        ...
      ]
      ...
    }
  3. Run gatsby develop and data from Kentico Kontent are provided in Gatsby GraphQL model. All Kentico Kontent content element values reside inside of the elements property of KontentItem nodes.

C) Scaffold your project using the Gatsby Kentico Kontent starter site

Use the gatsby-starter-kontent starter site, which includes this source plugin.

Features

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

The node names are prefixed with Kontent. More specifically, content type nodes are prefixed by KontentType and content items and their language variants are prefixed with KontentItem.

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 subsections.

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 KontentType nodes. In the opposite direction, in all KontentItem 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 allKontentItemProjectReference) and use the contentType navigation property to get a full list of all of the elements in the underlying content type. Like so:

{
  allKontentItemProjectReference {
    nodes {
      elements {
        name___teaser_image__name {
          value
        }
      }
      contentType {
        elements {
          name
          codename
          type
        }
      }
    }
  }
}

Language fallbacks

Gatsby source plugin is including GraphQL nodes by the language fallbacks configuration. As a part of that, there is a prefered_language property allowing to distinguish whether the fallback has been used or not.If the fallback is used prefered language is set to the desired language codename, but system.language value is using the actual culture that has been used (the fallback one). If the values are same, fallback is was not used.

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 KontentItemSpeakingEngagement) in their default language as well as other languages all at once:

{
  allKontentItemSpeakingEngagement (filter: {preferred_language: {eq: "default"}}) {
    nodes {
      elements {
        name {
          value
        }
      }
      otherLanguages {
        elements {
          name {
            value
          }
        }
      }
    }
  }
}

returns in case of two languages

{
  "data": {
    "allKontentItemSpeakingEngagement": {
      "nodes": [
        {
          "elements": {
            "name": "Speaking engagement"
          },
          "otherLanguages": [
            {
              "elements": {
                "name": "Hablando de compromiso"
              }
            }
          ]
        }
      ]
    }
  }
}

Other Languages are not automatically generated using Schema API.

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 (under the related_project_references.linked_items 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.linked_items will give you the full-fledged Gatsby GraphQL nodes with all additional properties and links.

{
  allKontentItemProjectReference {
    nodes {
      elements {
        related_project_references {
          name
          type
          itemCodenames
          linked_items {
            ... on KontentItemBlogpostReference {
              elements {
                title {
                  value
                }
              }
            }
            ... on KontentItemProjectReference {
              elements {
                project_name {
                  value
                }
              }
            }
          }
        }
      }
    }
  }
}

💡 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.

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

Custom element parting support

Custom element is now supported including custom element models definition. SO besides of the raw value property value it is possible to parse it and include it in the GraphQL model.

External properties are not automatically generated using Schema API.

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 Kontent Delivery SDK could resolve links and also linked items and components in rich text elements by implementing the resolvers, Kentico Kontent Gatsby source plugin is enriching the rich text elements in GraphQL model by resolvedData property containing html property with the resolved value and for the url slug elements, there is a resolvedUrl property containing resolved link from the link resolver.

`summary` rich text element example
{
  ...
    node {
      elements {
        summary {
          value // NORMAL value
          resolvedData {
            html // resolved output
            linkedItemCodenames // only inline liked items codenames
            componentCodenames // only content component codenames
          }
          linkedItemCodenames // inline linked items + content components codenames
        }
      }
    }
  ...
}

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
{
  allKontentItemBlogpostReference {
    nodes {
      elements {
        summary {
          value
          linked_items {
          ... on KontentItemBlogpostReference {
            elements {
              title {
                value
              }
            }
          }
        }
      }
    }
  }
}

Links in Rich text elements

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

Example
{
  allKontentItemBlogpostReference {
    nodes {
      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
{
  allKontentItemBlogpostReference {
    nodes {
      elements {
        summary {
          value
          images {
            imageId
            description
            url
            width
            height
          }
        }
      }
    }
  }
}

Resolved Data in Rich text elements are not automatically generated using Schema API.

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.

All items queries

There are two queries (allKontentItem and kontentItem) allows to load content items from unified endpoint regardless of type.

Example
query {
  allKontentItem {
    nodes {
      system {
        type
        name
      }
    }
  }
}

Response

{
  "data": {
    "allKontentItem": {
      "nodes": [
        {
          "system": {
            "type": "about_us",
            "name": "About us"
          }
        },
        {
          "system": {
            "type": "fact_about_us",
            "name": "How we roast our coffees"
          }
        },
        {
          "system": {
            "type": "fact_about_us",
            "name": "How we source our coffees"
          }
        },
        ...
      ]
    }
  }
}

Development prerequisites

Debugging

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

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

To see upgrade instructions see Upgrade section.

For more developer resources, visit the Kentico Kontent Docs.

Running projects

Guides and blog posts

Previous versions

Feedback & Contributing

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

Analytics

You can’t perform that action at this time.