kontent-ai / gatsby-starter

Gatsby starter site with Kontent.ai

Gatsby starter site with Kontent.ai

This repo contains a Gatsby starter site pre-configured with Kontent.ai source plugin. The site portrays a list of articles written by a coffee shop called dancing goat.

Prerequisites

• Node.js with NPM installed

How to run the code

The preferred way is to use Gatsby CLI gatsby new command, but you can of course simply clone or fork this repo.

Use Gatsby CLI

Make sure you have Gatsby CLI installed via npm list -g gatsby-cli. If not, you can install CLI via npm install --global gatsby-cli.

Then, navigate to your projects directory and run gatsby new [subdirectory name] https://github.com/kontent-ai/gatsby-starter. Replace [subdirectory name] with your project directory's name. The CLI tool will essentially do three things:

• create a subdirectory
• clone the starter site code files into that subdirectory
• run npm install to get all dependencies for you
  • that also copies content from .env.template to newly created .env file using prepare npm script

Clone or fork the repo

Clone or fork this repo. Once it's done, navigate to the app's root directory and run:

npm install

Run the starter site

Now, run:

npm run develop (or gatsby develop, should you have the Gatsby CLI installed)

This will bootstrap the site, build all static pages and start the site at http://localhost:8000 . You'll also be able to test arbitrary GraphQL queries in the GraphiQL interface via http://localhost:8000/___graphql.

Developing

You may use any IDE, however, we recommend Visual Studio Code as we have added a settings file for easier debugging.

Get to the content source

1. Go to app.kontent.ai
2. Click on the account icon and click on the projects
3. Select Sample Project. If there is not any, there should be a card with an option to create it.
4. Set environment variables to .env (created automatically by running npm install)
   • KONTENT_PROJECT_ID from Go to "Project Settings" -> "API keys" -> "Project ID"
   • KONTENT_LANGUAGE_CODENAMES from "Project Settings" -> "Localization" (use "Codename" of each language)

Retrieve both published and unpublished content

To load data from Preview API just set the following environment variables to your .env file (created automatically by running npm install)

• KONTENT_PREVIEW_KEY from Go to "Project Settings" -> "API keys" -> "Preview API" -> "Primary key/Secondary key"
• KONTENT_PREVIEW_ENABLED to true

Experimenting

Of all the artifacts of Kontent.ai, the starter site only displays content items and only in the default language. But, our source plugin also provides content types and items in non-default languages.

Check out the source plugin's readme for more details on which kinds of data and relationships it supports.

gatsby-starter's Issues

Convert this starter to a Gatsby theme

Motivation

The motivation is primarily to ensure the project is kept in line with the direction Gatsby is taking and to solve the drawbacks outlined in their documentation:

https://www.gatsbyjs.org/docs/themes/what-are-gatsby-themes/#gatsby-starters

Proposed solution

The proposed solution is to convert to a theme, the documentation can be found here:

https://www.gatsbyjs.org/docs/themes/converting-a-starter/

Spike: Support partial rebuild of node store

Expected outcome

Currently, the source plugin fetches all KC content during the bootstrap process. In large content projects, the bootstrap may take too long. By storing the last update date, the plugin could fetch only content that was created and updated afterwards (delta). Find ways of implementing such story.

Note: There is currently no way of getting the collection of deleted/unpublished content off of the Delivery API. Only web hooks can serve this purpose. Find out if a simple web hook listener can be implemented in a Gatsby site.

Reference

• gatsbyjs/gatsby#3790

Spike: How to deploy to Netlify via icon

Motivation

Some Gatsby starters utilize a nice icon that deploys the site to an arbitrary Netlify account.

We'd also like to employ Travis CI in our starter.

Expectations

Investigate what it takes to use the "Deploy to netlify" icon, preferably with Travis.

Demonstrate content components

Motivation

In Rich text elements, one can create non-reusable, typed chunks of content called components.

Proposed solution

Use the "Component-only type", together with the "Component-using content type" types to demonstrate the usage of components.

Additional context

Should you wish to create some more real-world content types for the starter, drop a comment to this issue to get edit permissions to the project in Kentico Cloud.

Spike: Find out how to rebuild automatically

Expected result

Gatsby's store is rebuilt upon bootstrap (npm run develop, npm run deploy). Find out:

• whether there have to be provisions made in the source code of either an app, or a plugin, to rebuild the store automatically
• or, if only the automated CLI commands in the hosting environment can make the automatic rebuilds

Resources

• https://github.com/justinwhall/gatsby-wordpress-netlify-starter
• https://www.netlify.com/docs/api/
• gatsbyjs/gatsby#4202
• gatsbyjs/gatsby#2753
• https://github.com/danielmahon/gatsby-starter-procyon

Submit starter into Gatsby starters library

Motivation

The starter is not visible on https://www.gatsbyjs.com/starters/ - keep the source data to our Sample project

Proposed solution

Fullfil https://www.gatsbyjs.com/starters/submissions

Additional context

Add any other context, screenshots, or reference links about the feature request here.

Split the repo into two

Motivation

Currently, this repo contains both the source plugin and a sample app. While this setup has advantages in initial phases of development, it is not sustainable in the long term.

Proposed solution

Split the repo into two: a standalone source plugin and the sample app.

Upgrade to Gatsby v2

Motivation

Gatsby just released their v2. Keep up.

Resources

• https://next.gatsbyjs.org/docs/migrating-from-v1-to-v2/

Dump content and models via Content Management API into the repo

Motivation

Those who clone this repo can only guess what the content models and items in the KK project are.

Design guidelines

Dump the entire content project into JSON files so that everyone can clone the project.

Demonstrate content items linked in Rich text elements

Motivation

In Rich text elements, one can link to other content in multiple ways.

It would be great to have a showcase on the starter, how to resolve rich text editor.

Proposed solution

Make use of the rich text resolvers of the future transformer plugin or the GraphQL _nodes properties produced by the decorateItemNodeWithRichTextLinkedItemsLinks method. Use them to display inline linked items in the Summary element of the Blogpost reference content type.

Content components are described in #28

Demonstrate the Linked items elements

Motivation

One of the elements in Kentico Cloud content types is called Linked items (formerly "modular content"). It contains a list of pointers to other content items. These can be rendered as either hyperlinks or in full in the app.

Proposed solution

Make use of the Related project references element in the Project reference content type to demonstrate the feature.

Additional context

As advertised above, render the related references as either hyperlinks or as partially rendered. For instance, in the form of "[Name of the related reference] ([Started at] - [Finished at])".

Reorder package.json properties

Motivation

After the project is bootstrapped, a content of package.json file is usually modified. It is not necessary to have dependencies at the beginning of the file.

Proposed solution

Order properties by the generate package.json file (using npm init command) as following in one:

{
  "name": "a",
  "version": "1.0.0",
  "description": "description",
  "main": "index.js",
  "scripts": {
    "test": "testcommand"
  },
  "repository": {
    "type": "git",
    "url": "git repository"
  },
  "keywords": [
    "keywor1",
    "keyword2"
  ],
  "author": "author",
  "license": "MIT",
  "dependencies": {
    "lodash": "^4.17.11"
  },
  "devDependencies": {
    "babylon": "^6.18.0"
  }
}

Demonstrate the use of Rich text elements

Blocked: kontent-ai/gatsby-packages#19

Motivation

Once we create our transformer plugin, we should demonstrate the use of link resolvers and rich text resolvers in the starter site.

Proposed solution

Make use of the Summary element of the Blogpost reference content type to demonstrate the resolvers.

Support relationships between content items and their modular items

Motivation

Kentico Cloud content items can be composed of other content items, so called modular content items. They can be put into modular content elements or into the rich text elements.

Design guidelines

Bring support for modular content linking by adding new navigation properties to content item nodes. Make use of the ___NODE convention to tell Gatsby that a field contains an ID of a linked node.

Reference

• gatsbyjs/gatsby#1583
• https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-filesystem/README.md
• https://github.com/Kentico/cloud-gatsby/blob/master/plugins/gatsby-source-kentico-cloud/normalize.js

Add tests for decorate* methods

Motivation

While the tests/normalize.js test file tests whether content type nodes and content item nodes get properly created, it still doesn't test the decorateTypeNodesWithItemLinks and the decorateItemNodeWithLanguageVariantLink methods.

Design guidelines

• Use the existing contentItemNodes.json and contentTypeNodes.json files as test fixtures.
• Adjust them to be ready for testing of the above two methods (e.g. add more data into the JSON files).
• Add test counterparts for the above two methods into the tests/normalize.js Jest file.
• Run the tests for the first time to generate new snapshots.
• Check the correct shape of the snapshots.

Reference

• https://jestjs.io/docs/en/snapshot-testing

Unknown field `system` on type `KenticoCloudItemProjectReference`

Hi,

Cloned the repo and npm installed in both the plugin directory and the main site (.cmd file didn't work on a Mac, obvs). I get the following error:

GraphQL Error Unknown field `system` on type `KenticoCloudItemProjectReference`

   1 |
   2 |   query projectReferenceQuery($slugStep2: String!) {
   3 |     site {
   4 |       siteMetadata {
   5 |         title
   6 |       }
   7 |     }
   8 |     kenticoCloudItemProjectReference(fields: { slugStep1: { eq: $slugStep2 }}) {
>  9 |       system {
     |       ^
  10 |         name
  11 |       }
  12 |       name___teaser_image__name {
  13 |         value
  14 |       }
  15 |       name___teaser_image__teaser_image {
  16 |         assets {
  17 |           url
  18 |         }
  19 |       }

I tried commenting out that specific part of the query, but it complains about many other missing fields.

Also curious why the source plugin isn't its own npm module? Is this just while you're building it? My recommendation would be to publish it as an alpha and use npm link to work on it locally

Spike: Make source plugin independent of sample app

Expected outcome

To develop a Gatsby source plugin, it is necessary to have a sample app that tests the correct behavior of the plugin. Calling into Gatsby APIs cannot be tested via automated tests in Gatsby. One can test the plugin either as a "local plugin" that resides under the directory of a sample app, or pack the plugin into an NPM package upon each change (which is unacceptable for development). Find a way of separating the source plugin files out of the file system structure of the sample app.

Reference

• https://blog.github.com/2016-02-01-working-with-submodules/
• http://codewinsarguments.co/git-submodules-vs-git-subtrees/

Demonstrate multilanguage capabilities

Motivation

As the source plugin now supports getting language variants of content items, the sample app should also be able to demonstrate this capability.

Design guidelines

• Create a language switch in the index.js page.
• Make the listing of blogpost references, project references and speaking engagements reflect the preferred language.
• Render the detail pages of project references and speaking engagements accordingly.
• Optional: create a language switch in these detail pages as well.

Reference

• https://www.gatsbyjs.org/docs/creating-and-modifying-pages/
• https://developer.kenticocloud.com/docs/localization

Demonstrate Multiple choice elements

Motivation

Kentico Cloud has two artifacts to support categorization of content: Taxonomy elements and Multiple choice elements. The difference is in the scope: While taxonomies are project-wide, multiple choice elements are content type-only.

Currently, we have the Format table row in the speaking-engagement.js template that only displays the selected value(s).

Proposed solution

Rework the UI of the Format row to showcase the advantage of the contentType GraphQL property. That way, not only the selected values will be rendered.

Additional context

In the definition of a content type, the multiple choice elements contain all possible values. On the other hand, in the content items in the Delivery response, these elements hold only values used in a given content item.

Do make use of the links between items and their types produced by the createContentItemNode method of our source plugin. Demonstrate the usage of those links to show which of the values have and haven't been selected in a given content item. For instance, render a list of disabled checkboxes and make some of them checked.

Format DateTime values in templates

Motivation

The project-reference.js and speaking-engagement.js templates display data of date & time content elements. They're currently formatted in the original ISO format.

Design guidelines

Format the date & time information in a user-friendly way.

Use yarn instead of npm

Motivation

When generating a new project based on this starter - the warning is showed up:

warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.

Proposed solution

Use yarn instead of npm and remove package-lock.json

Additional context

Mind updating the Readme.md.
The bootstrapped project is containing package,json and also yarn.lock file.

Docs: Explain the usage of Preview API and secured Delivery API

Motivation

The kontent-ai/gatsby-packages#9 PR deals with passing the configuration object onto the source plugin (the JS SDK respectively). It will be possible to use the Preview API and the secured Delivery API.

Expected outcome

Describe how to employ the two APIs in a Gatsby site.

Adapt to a breaking change in source plugin

Motivation

Make the starter work even after kontent-ai/gatsby-packages#10 is merged.

Design guidelines

Use the elements property of kenticoCloudItem nodes.

Convert the sample app into a starter site

Blocked by #11 .

Motivation

The current sample app serves just to the demoing purpose. The starter site may serve as a template for the gatsby new command.

Proposed solution

Convert the sample app into a starter site. Make provisions to use the starter site with the gatsby new command.

Reference

• https://www.gatsbyjs.org/docs/gatsby-starters/

Demonstrate links to content items in Rich text elements

Motivation

In Rich text elements, one can link to other content using hyperlinks.

Proposed solution

Use links property to resolve links or use the embedded SDK support for link resolution for showcasing how it is possible to resolve links.

[TO BE GROOMED] Taxonomy

Motivation

Why is this feature required? What problems does it solve?

Proposed solution

An ideal solution of the above problems.

Additional context

Add any other context, screenshots, or reference links about the feature request here.

Demonstrate taxonomies

Blocked: kontent-ai/gatsby-packages#1

Motivation

Kentico Cloud has two artifacts to support categorization of content: Taxonomy elements and Multiple choice elements. The difference is in the scope: While taxonomies are project-wide, multiple choice elements are content type-only.

We don't have any taxonomy elements in the sample Portfolio project yet.

Proposed solution

If you're interested in implementing the story, drop a comment to this issue and you'll be given edit permissions to the project in Kentico Cloud. You'll be able to create a taxonomy of your choice and use it in a Taxonomy element in one of the content types. Then, you'll be able to implement the story in the starter.