My JAMstack Journey: A Guide To A (very simple) JAMstack Site — Part 3
Welcome to the third and final part of this series, where we build a very simple JAMstack site. To recap our journey so far; in part one we installed Gridsome and created content in Kontent.ai. In part two we got stuck into Gridsome and created a skeleton HTML website. In part three, we will configure the connection between Gridsome and Kontent.ai, use GraphQL to query Kontent.ai and hydrate our site pages, and finally we’ll deploy our website to Netlify.
Integrate Kontent.ai into Gridsome project
First off, we need to integrate Gridsome with Kontent.ai and if you remember from article part one, we installed a connector which will do just that: @meeg/gridsome-source-kentico-kontent
As the plug-in is installed, the next step is to register and configure it in the gridsome.config.js file:
\gridsome.config.js
As per figure 1 below, we need set the configuration details as follows:
When connecting up to Kontent.ai, we are required to provide a project ID which is used to securely connect to the correct Kontent.ai project. Using environment variable to keep our project ID secure is best practice and this is also how we would handle other forms of storing sensitive data. If you notice in figure 1 above, on line:12 the project ID value references an environment variable:
projectId: process.env.KENTICO_KONTENT_PROJECT_ID
For cases such as this, in Gridsome we can create an environment file (.env). This file is specifically used for storing environment variables — such as a project ID in our case — and lives in the root of the project:
\.env
With the .env file in place, we can then define and initialise the environment variable as below (remember to replace the x’s with your actual project ID):
More information on setting the environment variable above, can be found on the plug-in’s GitHub repo page:
https://github.com/CMeeg/gridsome-source-kentico-kontent#getting-started
Hook Up Dynamic Data From Kontent.ai
GraphQL time! This is where we take the skeleton HTML website that we built in part two and hydrate the pages with data from our headless CMS.
When we run the below Gridsome command to run our website project as per figure 3 below:
We get information on the hosting runtime URLs (figure 4), which also include the GraphQL explorer. In my case below, the GraphQL explorer is accessible on:
http://localhost:8081/__explore
Using the GraphQL explorer, we can run GraphQL queries against our CMS connection and see the live data returned as JSON. In the .NET world, when I need to retrieve data from SQL Server I build and optimise my T-SQL queries using SQL Management Studio — similarly, using the GraphQL explorer we can also build and fine-tune data queries before embedding them into Vue pages.
An intellisense style helper makes it easier to query the correct objects. In figure 5 below, we are choosing to retrieve a list of the Article object type:
The intellisense also extends to object properties, as you can see in figure 6 below, it picks up the Article properties we defined when building our Kontent.ai content types in article part one as well as the other system properties returned by Kontent.ai. Very handy, indeed.
Home page
First step is to write our query in the GraphQL explorer which will retrieve the home page from Kontent.ai, along with the properties we require such as the heading, banner and body copy:
Next step, we open the Index Vue page from our skeleton site, add our GraphQL query and code to reference the query object to replace the dummy HTML content with actual CMS data.
\pages\Index.vue
In the Index.vue page in figure 8 above, we add the GraphQL query (from figure 7) between the <page-query></page-query> which are defined below the </template> closing tag.
In the HTML within the <Layout></Layout> tags we can now reference the GraphQL object and associated properties to replace the dummy HTML. For example, the home page title is referenced on line:5 below as:
<h1>{{ $page.home.title }}</h1>
Note on line:13 above, we don’t call the main content property as:
<p>{{ $page.home.mainContent }}</p>
This is because rich text content must be processed in a special way. Instead, we pass it to custom component we need to create which will help to render rich text content properly.
Instructions on how to do configure Gridsome to handle rich text data can be found below, on the Kontent.ai plug-in’s GitHub repo page:
https://github.com/CMeeg/gridsome-source-kentico-kontent#rendering-rich-text-fields
The result:
Home page done! 🎉
News Page
Next, we tackle the news page — which will be a little bit more complex as there is a listing of news articles, and that means we have to iterate a collection of objects.
First step, we work in the GraphQL explorer to define a query which will yield the desired results:
Next, we edit the News Vue page:
\pages\News.vue
We add the GraphQL query within the<page-query> tags and then we reference the properties of each article object node as per figure 11 below.
Note the for-loop that we create which iterates the Article node collection — on line:7:
v-for=”edge in $page.articles.edges”
Also, note the read more g-link on line:25. We set the path property of the current node (in the collection we’re iterating), which will ensure the URL slug that’s set in Kontent.ai is used — remember the routing we set for Articles in part two (figure 10).
The result:
The news page now renders a collection of Article teaser blocks for each article that was retrieved from Kontent.ai via our GraphQL query.
Article Page
Last but not least, the Article template for displaying single news articles needs updating. In figure 11 (line:25) above, when we defined the more news the g-link we passed the path as the link destination — we expect this path in our <page-query> definition so that the query can pull the specific node representative of the article we expect to view.
We need to edit our Article template file:
\src\templates\Article.vue
Note in figure 13 below, on line:25, we define an expected parameter named $path of type String. On line:27 we retrieve the Article object where the path matches the path that is set in the $path parameter — the path passed from the News page via its g-link (from figure 11).
Below is the complete code:
The result:
Our site is now pulling dynamic content from the CMS. Every time we build the site and it’s deployed, a snapshot is taken of the hydrated pages and the static HTML files are served with up to date content. 🏆
Deployment
The website is now done and the final step is to deploy our site to Netlify. For this to occur, our source code needs to be stored in Git as Netlify will pull from Git on each build process.
GitHub
If not already done, we need to add out code into a GitHub repo. If you don’t have a GitHub account, set one up, it’s easy and free. Assuming this is done and your files are up to date, add and commit your files to Git.
If you notice the uploaded files in GitHub, the .env file that holds our Kontent.ai project key was not copied over. This is a security feature that ensures sensitive information, such as API keys, do not get pushed up.
How will the Kontent.ai connecter work you say? 😱
Netlify gives us the facility to create secure configuration settings such as our project key — as we will see in the next step. ✔️
Netlify
In part one we created a Netlify account — then we did nothing with it. Well, the moment has come to put it to good use. Log into your Netlify account and create a New Site from Git by clicking the button below:
The new site wizard will screen appear and the simple 3 step process that follows should have our site configured and deployed after step 3.
Step 1
Step 1 asks us to specify the Git provider — select to connect to GitHub (unless you’re using one of the others).
Step 2
Step 2 asks us to choose our repo — this step will initially ask you to allow access by authorising Netlify to access your Git repo.
Note: my repo was not showing and I was super lost, until I finally stumbled onto a forum post which basically pointed me to something that was right under my nose. At the bottom of the screen above, the Configure the Netlify app on GitHub link will take you to a screen where you’re able to authorise which of your repos will be selectable here.
Step 3
Step 3 — the final step allows you to configure our build settings and this is also where we will add out Kontent.ai Project key. We need to configure some settings for when Netlify builds our code — such as build settings, deploy settings, and environment variables.
Done!
Once built, an auto-generated URL is provided for us to view our live site on. We can configure a proper domain for our site also.
Here is the site we’ve built:
https://admiring-liskov-39b08f.netlify.app/
Conclusion
Though a simple JAMstack site, this was a bit of a journey — three parts worth to be exact. If you followed through all the way, I hope you found some parts of the journey useful. As the preface of this series stated, this was a very simple JAMstack website with only but the bare minimum concepts covered, enough to enable one to be empowered enough to build a small, very simple website with the minimum architecture required, but (hopefully) to leave enough of a mark to encourage someone to take the next steps on the JAMstack journey.
For me personally, my next step will include adopting a CSS frame-work, moving on to try my luck with another static site generator (perhaps Nuxt), building out a larger real-world website in Kontent.ai where it’s power and feature-set can be utilised, and really taking a deep-dive into Netlify and utilising the more of its awesome features.
