@kentico/gatsby-source-kontent
Advanced tools
This repo contains a Gatsby (v2) source plugin that retrieves data from the Kentico Kontent Delivery API.
You can use the plugin in any of the following ways:
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.
Install the @kentico/gatsby-source-kontent NPM package.
npm install --save @kentico/gatsby-source-kontent
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
module.exports = {
...
plugins: [
...
{
resolve: `@kentico/gatsby-source-kontent`,
options: {
deliveryClientConfig: { // Configuration object
projectId: `XXX`,
typeResolvers: []
},
languageCodenames: [ // example configuration
`default`, // default language
]
}
}
...
]
...
}
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.Use the gatsby-starter-kontent starter site, which includes this source plugin.
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.
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.
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
}
}
}
}
}
Gatsby source plugin is including GraphQL nodes by the language fallbacks configuration. As a part of that, there is a preferred_language property allowing to distinguish whether the fallback has been used or not.If the fallback is used preferred 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.
This relationship is captured by the otherLanguages navigation property of all content item nodes in other language.
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.
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.
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
}
}
}
}
}
}
}
}
}
: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.
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 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.
Each taxonomy group can be returned as a nested group of taxonomy terms. To retrieve the Personas, the following graphQL can be used:
query MyQuery {
allKontentTaxonomyPersonas {
nodes {
terms {
terms {
codename
name
}
name
codename
}
system {
codename
name
}
}
}
}
This would result in the following response:
{
"data": {
"allKontentTaxonomyPersonas": {
"nodes": [
{
"terms": [
{
"terms": [
{
"codename": "barista",
"name": "Barista"
},
{
"codename": "cafe_owner",
"name": "Cafe owner"
}
],
"name": "Coffee expert",
"codename": "coffee_expert"
},
{
"terms": [
{
"codename": "coffee_lover",
"name": "Coffee lover"
},
{
"codename": "coffee_blogger",
"name": "Coffee blogger"
}
],
"name": "Coffee enthusiast",
"codename": "coffee_enthusiast"
}
],
"system": {
"codename": "personas",
"name": "Personas"
}
}
]
}
}
}
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.
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.
{
...
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
}
}
}
...
}
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.
{
allKontentItemBlogpostReference {
nodes {
elements {
summary {
value
linked_items {
... on KontentItemBlogpostReference {
elements {
title {
value
}
}
}
}
}
}
}
}
All rich text properties with content items linked in the element also have an accompanying links property.
{
allKontentItemBlogpostReference {
nodes {
elements {
summary {
value
links {
codename
linkId
type
urlSlug
}
}
}
}
}
}
All rich text properties with content items linked in the element also have an accompanying images property.
{
allKontentItemBlogpostReference {
nodes {
elements {
summary {
value
images {
imageId
description
url
width
height
}
}
}
}
}
}
Resolved Data in Rich text elements are not automatically generated using Schema API.
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.
Queries allKontentItem and kontentItem allow to load content items from unified endpoint regardless of type.
Queries allKontentType and kontentType allow to load content types from unified endpoint.
query {
allKontentItem {
nodes {
system {
type
name
}
}
}
allKontentType {
nodes {
elements {
codename
name
type
taxonomyGroup
options {
codename
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"
}
},
...
]
}
}
}
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.
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.
To see upgrade instructions see Upgrade section.
For more developer resources, visit the Kentico Kontent Docs.
Check out the contributing page to see the best places for file issues, to start discussions, and begin contributing.
FAQs
Source plugin providing Kontent data from REST Delivery API
The npm package @kentico/gatsby-source-kontent receives a total of 132 weekly downloads. As such, @kentico/gatsby-source-kontent popularity was classified as not popular.
We found that @kentico/gatsby-source-kontent demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 12 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.