Forem: Kontent.ai

How To Check If Array Is Empty In TypeScript

Ondrej Polesny — Wed, 08 Dec 2021 09:12:06 +0000

When processing JSON responses in TypeScript, how do you safely check if a variable is an array and is not empty?

Let's say we get a response from an API (in this example, it's Kontent API):

const blogPosts: BlogPost[] = (await deliveryClient
  .items<BlogPost>()
  .type("blog_post")
  .toPromise())?.data?.items

We expect that response to be an array of BlogPost objects. Also, note the ?. notation that allows us to unwind the response and select just the data we need. If the response doesn't have the expected format, we will get null instead of undefined error.

Therefore, we first need to check if the response is a defined array:

if (!Array.isArray(blogPosts)) {
  throw new Error("Response has a wrong format")
}

The Array.isArray function will catch all possible values:

// all these calls return false
Array.isArray(undefined)
Array.isArray(null)
Array.isArray({})

// DON'T DO THIS
// as there is no need for checking the variable separately
if (blogPosts && Array.isArray(blogPosts)) { }

// DO THIS
// Array.isArray() is doing the null and
// undefined check automatically
if (Array.isArray(blogPosts)){ }

Note: Check MDN Web Docs for more information.

Then, we check if the array contains any items via .length property:

if (blogPosts.length == 0) {
  throw new Error("Response contains no items")
}

And that's it. 💪

The full code looks like this:

const blogPosts: BlogPost[] = (await deliveryClient
  .items<BlogPost>()
  .type("blog_post")
  .toPromise())?.data?.items

if (!Array.isArray(blogPosts) || blogPosts.length == 0){
  throw new Error("No data")
}

// all good here
console.log(blogPosts)

You can also wrap the code in try/catch block to make sure you also catch errors from network communication.

If you need any help with processing your Kontent data, join our Discord! 😎

Kontent Horizons developers news flash

Ondrej Polesny — Tue, 09 Nov 2021 08:25:12 +0000

Hey developers, thank you for attending Kontent Horizons! If you’re excited about our updates, find more information about them below or get in touch with us on Discord

Documentation

New streamlined overview of tech stacks

JavaScript + TypeScript

.NET

Nuxt 3

Discord

Join us on Discord to discuss other topics, like GraphQL :-)

What Gatsby v4 brings to your static site?

Ondrej Polesny — Tue, 21 Sep 2021 15:11:33 +0000

The new version of Gatsby is available in beta and brings many improvements. How are they going to affect you and the development and maintenance of your sites?

In this article, I summarize the key new features that Gatsby v4 brings and explain how each of them will affect your daily work with a Gatsby site.

Gatsby v4 Improvements

Gatsby v4 was officially introduced and made available as a public beta last week during Gatsby Camp and it brought major updates:

New rendering modes for pages
Parallel query processing
Improved Gatsby Cloud preview

Let's start with the first and see what changes for you.

New rendering modes for pages

Gatsby introduced support for two additional modes and now lets you use:

SSG - static site generation = pages generated during a build
DSG - deferred static generation
SSR - server-side rendered

SSG is the original concept of static site generators, so let's start with the second one - the deferred static generation. It's not a new concept. We've been successfully using it with Next.js and Netlify had already introduced a similar improvement for other static site generators with their Distributed Persistent Rendering and On-Demand Builders. The idea is, you pre-build only the core parts of a large site and leave the rest to be generated and cached (stored) only after the server receives a request for a specific page from the first visitor. In other words, on-demand.

Having DSG now available in Gatsby is definitely a great improvement. In the past, it was challenging to use Gatsby for large sites as the build times grew with content significantly. Now, with DSG and Server-Side-Rendering mode (that we all saw coming with the introduction of serverless functions this spring), you now get full control over how each page of your site gets rendered.

However, there is one downside. From my experience, Gatsby is often used by beginners. Don't get me wrong - many of them are experienced developers, just not with JavaScript. And what they value the most is the low entry barrier. They could get a site up and running very quickly, they didn't have to read any docs as the GraphQL data sourcing allowed them to see every content that's available, and for anything extra, there was always a plugin.

While all of that is still true, the added rendering modes (SSR, DSG) require developers to make informed decisions that require them to learn more. The time they need to invest to see their new site live increases. And the same applies to onboarding developers.

Now, you may argue here that they would need to learn that with any framework anyway and that's true. But Gatsby, until now, was a perfect stepping stone into Jamstack on React. Just like Gridsome is on Vue. I've seen many agencies tipping their toe in the Jamstack water with Gatsby and the low entry barrier was the biggest attraction for them.

Note: See the full explanation of Gatsby's rendering modes in this video or in their docs.

Parallel query processing

Another great improvement towards decreasing the build time. It's actually not optimizing the build but distributes the computation of page queries to multiple processor cores that work in parallel. The Gatsby team made this possible by moving the content from the Redux store to LMDB that supports concurrent access. So we're getting better build time by efficiently using the hardware. Good thing is, you don't need to take any action besides upgrading to the newest version of Gatsby.

Gatsby Cloud preview update

If you saw my talk at Gatsby Conf this spring, you know that editors expect their CMS to generate previews of their content and they expect it to do it instantly. With Gatsby, this was made possible with incremental builds that took only a few seconds. Now, the Gatsby team took the preview experience on Gatsby Cloud one level further and implemented a UI panel that tells the editor in real-time that preview is coming.

Of course, apart from that, the Gatsby team is constantly working on differentiating Gatsby Cloud from other hosting platforms and now claims that it is capable of 10x faster deploys.

Kontent and Gatsby v4

If you're using Kontent by Kentico as a content source for your Gatsby site, you're probably using both of these packages:

Gatsby Source Kontent Plugin Plugin providing data from Kontent REST API to Gatsby GraphQL model.
Gatsby Kontent Components Package with React components that process Kontent data.

We've prepared the new source plugin version ahead of the Gatsby v4 beta release. However, it will be merged only after the v4 is fully released, so until then, make sure to check out this version of the source plugin.

The Gatsby Kontent Components package is fully compatible with both the current and the new versions of the source plugin.

Should I upgrade?

The presented changes have one thing in common - Gatsby is trying hard to enable large-scale applications. They constantly work on decreasing build times (which interestingly brought new potential with the move of the content store), providing options to avoid building everything, improving the Gatsby Cloud services, focusing more on the content editor experience, and working closely with strategic partners.

If your site runs on Gatsby, I'd encourage you to try out the new features as they solve the problems of the majority of sites.

🎉 Weekly Win (27/2021)

Michael Kinkaid — Wed, 30 Jun 2021 20:04:47 +0000

TL;DR

Kentico Kontent support is fantastic. If you're stuck, reach out to them!

Why Did I Need Support?

Web Spotlight.

Sorry—web what, now?

I'm glad you asked (otherwise this would have been a very short post indeed).

Headless for Those with Heads

Kentico Kontent is a 100% headless CMS. It ticks all the boxes:

API-first
Technology agnostic
Channel agnostic
Software-as-a-Service
Has the word "content" in its name, kinda.

All cool stuff, but...

If you're making websites with a headless CMS, then the fact you can't easily see what you're doing—outside of having the site open in another tab—can make updates a little tiring (a lot of clicking through nested content items to find that one bit of text you need to update).

⚠️ Personal Opinion Alert: headless could be better.

Kentico Kontent is Better

A really great differentiator between Kentico Kontent and other headless CMS platforms is an app extension developed by Kentico called Web Spotlight. Web Spotlight extends Kentico Kontent with visual page building.

Click the edit button (pencil icon) beside the text in your web page to edit the content in your content inventory.

You can see the web page you're working on within the Kentico Kontent app. This provides an easy visual way to find and edit content, versus digging through your content model. Sweeeeet 🙌

Let Me Play with the New Features—NOW!

Web Spotlight just released a bunch of new features. The biggest of these is the Add Button. This swanky feature allows editors to add components into the page they're working on.

New orange buttons! Click them to add or create components into your web page.

Needless to say, once I spied the announcement on the update, I was eager to get the Add Button working on our site (Kontent + Gatsby). We're doing a bit of a refactor with the content model, so I'm already knee-deep in migration scripts. Where to start? The homepage.

Steps

Read the docs
Make a feature branch
Make sure I'm on the latest version of the Kentico Kontent Smart Link SDK
Add some code (new data attributes)
Paranoid check I'm playing in the Kentico Kontent development environment and not production 😉
gatsby develop -S because I'm impatient and can't be bothered with ngrok at this exact moment
Update the homepage preview URL in Kentico Kontent to https://localhost:8000
See the new Add Button (#win)
Click on the new Add Button (heart now racing)
And...

WOMP WOMP.

Sad Face 🙁

Nope. Error. Something about "missing data attributes"—even though they were right there in the code. RIGHT THERE. I should be looking pretty. All other Web Spotlight features are working. The Kentico Kontent SmartLink SDK is hooked up correctly. Why?!

Support to the Rescue

I was about to stomp off to the kitchen to comfort eat when I spotted the wee-help-thingamajig in Kentico Kontent's UI:

Talk to—and get support from—a REAL person.

Yes. Yes, I do have questions. I quickly typed up the issue I was experiencing and within a minute a very polite and capable chap called Keith started helping me through the issue.

I explained that I was trying to set up the Add Button with a Linked Item Element (supported). We talked through the model, and I mentioned that the Linked Item Element was coming from a Content Snippet, and that this was the only thing that stood out as maybe being unique to what I was trying to do.

He agreed and said he'd go pester the developers to ensure that the use case of having the Add Button configured to a content element coming from a Content Snippet is actually supported.

The Win?

It wasn't supported. Wait, isn't that a #fail and not a #win? Isn't now the time to slink off into the shadows and just avoid using the Add Button on the homepage?

Absolutely not! The #win here is the support provided by Kentico Kontent. In less than a week the developers had coded, tested, and deployed a fix. Not only that, but Keith kept me up to date the entire time on their progress via the chat support feature in Kentico Kontent.

It Works!

Behold. The first Add Button of many.

Adding a new component to the homepage. Refresh status and quick update thanks to Gatsby and incremental builds.

Onwards with the refactoring!

Python and Headless: How to make interactive, adaptable, affordable reports

Michael Berry — Wed, 16 Jun 2021 19:31:01 +0000

In this article, I'll show you how to pull data from a headless CMS and create a content type report using the Python framework: Dash.

Seeing is believing

I am a visual learner. I really appreciate when a graph or diagram accompanies data, or when a visual aid gets to "the point" in a presentation. Not everyone is as much of a fan of charts as I am, but representing data visually is universally helpful. For example, which is easier to understand in a presentation:

these side-by-side numbers: 101 | 443 | 102 | 320 | 82

this graph:

With just the delimited list of numbers, you don't get a good idea of how the values compare to one another. The graph makes differences and similarities more obvious.

Let's say that you are a new manager or member of a marketing team that uses a headless CMS to produce content. Knowing what types of content the team has been producing will be useful for better understanding their current content strategy. However, when you are looking at content models in a headless CMS, you're normally met with a long running list of names and numbers:

To assess the kinds of content in the project, you're forced to scan the entire content type listing and mentally compare the values. Without a visual aid, it's hard to tell what topics are prevalent in your project. Furthermore, once you've finished your analysis, you can't easily share your findings with other members of your team. Making them believe your analysis is correct is much easier with a visual report.

But what if you don't have the time or resources to integrate a commercial reporting tool into your project? Luckily, there are open source frameworks and libraries for building web analytic applications, like Dash.

What is Dash?

Dash is framework built upon the popular Plotly graphing library, that allows you to build interactive visual applications and render them in a browser. Although it uses JavaScript libraries behind the scenes, Dash apps are written purely in Python and don't require familiarity with JavaScript.

If you know some Python, Dash is well suited to create reports from headless CMS data because it supports a wide variety of well-documented graph types, and the open-source edition is completely free.

How to create a report from a headless CMS

Let's create a content report using the Kentico Kontent headless CMS, the open source Kontent Python SDK, and Dash.

In our sample scenario, we'll create three reports about a coffee shop website, and aggregate them in a tabbed report.

In our report we want to show:

what type of content exists in the project
the audiences our articles are targeting
the timeline showing when they were published.

These reports will give us more insight into the "who, what, when" strategy surrounding our previously published articles.

Application setup

First we need to install Dash, our SDK, and dependencies. I recommend that you do this in a virtual environment. In the terminal run:

pip install dash
pip install kontent_delivery
pip install pandas

Alternatively, you can download and then install this requirements.txt using pip install -r /path/to/requirements.txt.

By the end of the exercise, we will have a file structure that looks like this:

kontent-dash-blog (root)/
    reports/
        article_timeline.py
        content_types.py
        personas.py
    report_dashboard.py
    requirements.txt

Dash and Kontent Initialization

Once we've installed the requirements, we need to:

setup our Flask application for running Dash
initialize our Kontent SDK delivery client using our Kontent project ID
setup some methods to build our three reports

We'll do this in a file called report_dashboard.py and create it in the root of the project:

import dash
import flask
from kontent_delivery.client import DeliveryClient
# report methods
from reports.content_types import build_types_chart
from reports.personas import build_personas_pie
from reports.article_timeline import build_post_timeline

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

# dash
server = flask.Flask(__name__)
app = dash.Dash(server=server, external_stylesheets=external_stylesheets)

# kontent
client = DeliveryClient("your_Kontent_Project_ID")

# custom methods to create reports
bar = build_types_chart(client)
pie = build_personas_pie(client)
timeline = build_post_timeline(client)

Report 1: bar chart showing content types

In this chart, we'll call the Kontent API and count how many content types exist of a given type. We'll create the file content_types.py in a reports directory:

import plotly.express as px

def build_types_chart(client):
    type_response = client.get_content_types()
    item_response = client.get_content_items()

    types = {}

    # add Kontent type counts to a dictionary
    for content_type in type_response.types:
        types[content_type.codename] = 0

    # increment content type count per item of respective type
    for item in item_response.items:
        types[item.content_type] += 1 

    data = {"content types":types.keys(), "count": types.values()}

    fig = px.bar(data, x="content types", y="count")

    return fig

In the build_types_chart method, we create key value pairs from the codename of our content types, and a count of how many items are published of that type. With that data, we use Plotly Express to create and return a bar graph to our Dash application.

Report 2: pie chart showing article personas

In our second chart, we want to show what percentage of personas our article content targets. Let's assume we know that the article content type uses a taxonomy group called personas:

We'll create the file personas.py in the reports directory:

from kontent_delivery.builders.filter_builder import Filter
import plotly.express as px

def build_personas_pie(client):
    # only return "article" content items
    item_response = client.get_content_items(
        Filter("system.type", "[eq]", "article")
    )

    # get the taxonomy group that articles use
    personas_response = client.get_taxonomy("personas")
    chart_personas = {}

    # identify personas to be counted
    def get_taxonomy_terms(terms):
        for persona in terms:
            chart_personas[persona.name] = 0
            if persona.terms:
                get_taxonomy_terms(persona.terms)


    get_taxonomy_terms(personas_response.terms)

    # increment persona count per item
    for item in item_response.items:
        for persona in item.elements.personas.value:
            chart_personas[persona.name] += 1 

    data = {"personas":chart_personas.keys(), "count": chart_personas.values()}

    fig = px.pie(data, names="personas", values="count",
                title='Assigned article personas')
    return fig

In the build_personas_pie method, we pull all of our article content items. We then create key value pairs from the name of taxonomy terms that exist in our Personas taxonomy group, and a count of how many items are tagged with a particular term. With that data, we use Plotly Express to create and return a pie graph to our Dash application.

Report 3: timeline showing date posted

Information about when these articles were published could provide more context about what our content strategy was previously, or how it changed over time. Let's assume we have a "posted date" element on our articles that we can use to create our timeline:

We'll create the file article_timeline.py in the reports directory:

from kontent_delivery.builders.filter_builder import Filter
import pandas as pd
import plotly.express as px

def build_post_timeline(client):
    # only return "article" content items
    item_response = client.get_content_items(
        Filter("system.type", "[eq]", "article")
    )

    # setup two arrays for Plotly scatter
    chart_items = []
    chart_post_date = []

    # populate arrays with respective item name and post date
    for item in item_response.items:
        chart_items.append(item.name)
        chart_post_date.append(item.elements.post_date.value)

    df = pd.DataFrame(dict(item=chart_items, post_date=chart_post_date))

    # use column names of df for the different parameters x, y, ...
    fig = px.scatter(df, x="post_date", y="item",
                    title="Article post timeline",
                    labels={"Post Date":"Date item posted"} # customize axis label
                    )

    return fig

Like the other methods, we retrieve the article items from Kontent, but in this example we take an extra step to convert two arrays into a dictionary and pass them into a pandas DataFrame. This is only for the sake of matching the basic dot plot example in the Plotly documentation.

Tying it all together in a tabbed report with Dash

It's time to pull all the visual aids together in a single report and add some interactivity with Dash. We created the report_dashboard.py file earlier to add the Kontent client and our chart building methods, and now we'll add a layout with some interactive components:

# ... other imports from before
# add these for components:
import dash_html_components as html
import dash_core_components as dcc
from dash.dependencies import Input, Output

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

# dash
server = flask.Flask(__name__)
app = dash.Dash(server=server, external_stylesheets=external_stylesheets)

# kontent
client = DeliveryClient(config.project_id, options=config.delivery_options)

bar = build_types_chart(client)
pie = build_personas_pie(client)
timeline = build_post_timeline(client)

# -- end of "Dash and Kontent Initialization" code --

# -- start of "Tying it all together..." code --

# adding the dash layout
app.layout = html.Div([
    # dash tabs component that wraps individual tabs
    dcc.Tabs(id='tabs-example', value='tab-1', children=[
        dcc.Tab(label='Content Types', value='tab-1'),
        dcc.Tab(label='Article Personas', value='tab-2'),
        dcc.Tab(label='Article Post Timeline', value='tab-3'),
    ]),
    # div used as a canvas to show reports
    html.Div(id='tabs-example-content')
])

# onclick events that call our chart building methods
@app.callback(Output('tabs-example-content', 'children'),
              Input('tabs-example', 'value'))
def render_content(tab):
    if tab == 'tab-1':
        return html.Div([
            dcc.Graph(figure=bar)
        ])
    elif tab == 'tab-2':
        return html.Div([
             dcc.Graph(figure=pie)
        ])
    elif tab == 'tab-3':
        return html.Div([
             dcc.Graph(figure=timeline)
        ])

# run the application when report_dashboard.py is called
if __name__ == '__main__':
    app.run_server(debug=True)

In the final code file of our report, we use Dash's core HTML components to create a simple two div layout. The first div contains Dash "Tab" components that we use to toggle between graphs, and the second div acts as a canvas to show the graphs we generated.

Following the layout, we use Dash callbacks to generate a different graph depending upon which tab we click. More information about Dash's core components, including "Graph" and "Tabs" can be seen in the Dash documentation here.

At this point, you can run report_dashboard.py in your terminal and watch Dash spin up a localhost server for your newly created reporting application. Follow the link in the terminal, and VOILA! You've created your own interactive, custom report for free.

You can check out a live hosted example or the full source code on GitHub.

Conclusion

In this article we discussed what Dash is, and how you can use it to create interactive reports from your headless CMS data. Now you know with a little Python knowledge, and an open-source framework like Dash, you don't have to miss out on having headless CMS reports.

Want more Dash and headless samples? Check out this Dash + Kontent app for making modular content graphs.

Are you having issues with the samples from the article? Get in touch on our Discord.

Build and Deploy a Next.js Blog with Kentico Kontent and Vercel

Ondřej Chrastina — Fri, 11 Jun 2021 09:23:51 +0000

Kentico Kontent delivers all the benefits of a headless CMS while empowering your marketing team to manage the experience across your digital channels.

This guide showcases how to use Kontent with Next.js Static Generation to generate static pages from your Kontent data, delivering a lightning-fast experience for your users.

Following text is an extended explanation of the Statically generated blog using Next.js and Kontent repository.

Step 1: Creating a Kontent + Next.js Project

You can view a working demo, the app you will create is shown in the screenshot below:

The Next.js + Kontent demo app.

Register Kontent project

To get started, create an account on Kontent.ai. After signing up, create an empty project.

Create the content models and fill them with data

The content model defines the data structures of your application/websites. The structures are flexible and you can tailor them to your needs.

For this example, you need to create a content model that defines an author and a post content type.

You can create the content model and fill it with data manually to familiarize yourself with the Kontent user interface.

To import the content models with their data automatically, follow the next steps:

Enter Kontent application
Go to "Project Settings", select API keys
Activate Management API
Copy Project ID and Management API key
Install Kontent Backup Manager and import data to newly created project from kontent-backup.zip file (place appropriate values for apiKey and projectId arguments):

npm i -g @kentico/kontent-backup-manager
kbm --action=restore --apiKey=<Management API key> --projectId=<Project ID> --zipFilename=kontent-backup

💡 Alternatively, you can use the Template Manager UI for importing the content.

Go to your Kontent project and publish all the imported items. > You could deactivate the Management API, it is not necessary anymore.

Application initialization

Initialize the application locally with following command:

npm init next-app --example cms-kontent nextjs-kontent-app && cd nextjs-kontent-app

Initializing a Next.js + Kontent app and entering the project directory.

Step 2: Set up Environment Variables

Copy the .env.local.example file in this directory to .env.local (which will be ignored by Git):

Then set each variable on .env.local using the keys Project settings > API keys:

KONTENT_PROJECT_ID - Should be the Project ID in Project settings > API keys.
KONTENT_PREVIEW_API_KEY - One of the Preview API keys in Project settings > API keys.
KONTENT_PREVIEW_SECRET - Can be any random string (but avoid spaces), like MY_SECRET - this is used for Preview Mode.

After installing the required dependencies, you are now able to run and develop your Next.js + Kontent app locally.

npm install
npm run dev

yarn
yarn dev

Step 3: Understanding the Code

To understand how the app works, there are three main areas to explore:

Page Setup
Retrieving Content
Image Optimization

Page Setup

Each page displays a single blog post with the dynamic Object slug and two latest blog posts teasers from Kontent:

import { useRouter } from 'next/router'
import ErrorPage from 'next/error'
import Container from '../../components/container'
import PostBody from '../../components/post-body'
import MoreStories from '../../components/more-stories'
import Header from '../../components/header'
import PostHeader from '../../components/post-header'
import SectionSeparator from '../../components/section-separator'
import Layout from '../../components/layout'
import {
  getAllPostSlugs,
  getPostBySlug,
  getMorePostsForSlug,
} from '../../lib/api'
import PostTitle from '../../components/post-title'
import Head from 'next/head'
import { CMS_NAME } from '../../lib/constants'

export default function Post({ post, morePosts = [], preview }) {
  const router = useRouter()
  if (!router.isFallback && !post?.slug) {
    return <ErrorPage statusCode={404} />
  }
  return (
    <Layout preview={preview}>
      <Container>
        <Header />
        {router.isFallback ? (
          <PostTitle>Loading…</PostTitle>
        ) : (
          <>
            <article className="mb-32">
              <Head>
                <title>
                  {post.title} | Next.js Blog Example with {CMS_NAME}
                </title>
                <meta property="og:image" content={post.coverImage.url} />
              </Head>
              <PostHeader
                title={post.title}
                coverImage={post.coverImage}
                date={post.date}
                author={post.author}
              />
              <PostBody content={post.content} />
            </article>
            <SectionSeparator />
            {morePosts.length > 0 && <MoreStories posts={morePosts} />}
          </>
        )}
      </Container>
    </Layout>
  )
}

export async function getStaticProps({ params, preview = null }) {
  return await Promise.all([
    getPostBySlug(params.slug, preview),
    getMorePostsForSlug(params.slug, preview),
  ]).then((values) => ({
    props: {
      post: values[0],
      morePosts: values[1],
      preview,
    },
  }))
}

export async function getStaticPaths() {
  const slugs = await getAllPostSlugs(['slug'])
  return {
    paths: slugs.map(
      (slug) =>
        ({
          params: {
            slug,
          },
        } || [])
    ),
    fallback: false,
  }
}

The pages/posts/[slug].js file for your Next.js +
Kontent app.

Retrieving Content

Kontent data is retrieved in the lib/api.js file making requests to the Kontent Delivery API using the Kontent Delivery SDK.

import { DeliveryClient } from '@kentico/kontent-delivery'
import { name, version } from '../package.json'

const sourceTrackingHeaderName = 'X-KC-SOURCE'

const client = new DeliveryClient({
  projectId: process.env.KONTENT_PROJECT_ID,
  previewApiKey: process.env.KONTENT_PREVIEW_API_KEY,
  globalHeaders: (_queryConfig) => [
    {
      header: sourceTrackingHeaderName,
      value: `@vercel/next.js/example/${name};${version}`,
    },
  ],
})

function parseAuthor(author) {
  return {
    name: author.name.value,
    picture: author.picture.value[0].url,
  }
}

function parsePost(post) {
  return {
    title: "post.title.value,"
    slug: post.slug.value,
    date: post.date.value.toISOString(),
    content: post.content.value,
    excerpt: post.excerpt.value,
    coverImage: post.cover_image.value[0].url,
    author: parseAuthor(post.author.value[0]),
  }
}

export async function getAllPostSlugs() {
  const postsResponse = await client
    .items()
    .type('post')
    .elementsParameter(['slug'])
    .toPromise()

  return postsResponse.items.map((post) => post.slug.value)
}

export async function getMorePostsForSlug(slug, preview) {
  return client
    .items()
    .queryConfig({
      usePreviewMode: !!preview,
    })
    .type('post')
    .orderByDescending('elements.date')
    .withParameter('elements.slug[neq]', slug)
    .limitParameter(2)
    .toPromise()
    .then((res) => {
      return res.items.map((post) => parsePost(post))
    })
}

export async function getPostBySlug(slug, preview) {
  const post = await client
    .items()
    .queryConfig({
      usePreviewMode: !!preview,
    })
    .type('post')
    .equalsFilter('elements.slug', slug)
    .toPromise()
    .then((result) => result.getFirstItem())
    .then((post) => parsePost(post))
  return post
}

export async function getAllPosts(preview) {
  return await client
    .items()
    .queryConfig({
      usePreviewMode: !!preview,
    })
    .type('post')
    .orderByDescending('elements.date')
    .toPromise()
    .then((postsResponse) => postsResponse.items.map((post) => parsePost(post)))
}

The lib/api.js file for your Next.js + Kontent app.

Image Transformation possibilities

If you want to optimize the speed of your site, it is possible to use Kontent Image Transformation API to transform retrieved images and reduce the download time for images. This could be applied to the blog post's cover image or the author's profile picture. The easiest way is to use the Image transformation support in Kontent Delivery SDK.

import cn from 'classnames'
import Link from 'next/link'
import {
  ImageUrlBuilder,
  ImageCompressionEnum,
  ImageFormatEnum,
} from '@kentico/kontent-delivery'

export default function CoverImage({ title, src, slug }) {
  const transformedSrc = new ImageUrlBuilder(src)
    .withCompression(ImageCompressionEnum.Lossless)
    .withAutomaticFormat(ImageFormatEnum.Webp)
    .withQuality(80)
    .getUrl()

  const image = (
    <img
      src={transformedSrc}
      alt={`Cover Image for ${title}`}
      className={cn('shadow-small', {
        'hover:shadow-medium transition-shadow duration-200': slug,
      })}
    />
  )
  return (
    <div className="-mx-5 sm:mx-0">
      {slug ? (
        <Link as={`/posts/${slug}`} href="/posts/[slug]">
          <a aria-label={title}>{image}</a>
        </Link>
      ) : (
        image
      )}
    </div>
  )
}

Possible modification of components/cover-image.js
component using Image Transformation API to get images in
modern WebP format.

Step 4: Using Preview Mode

To add the ability to preview content from your Kontent project using Preview Delivery API, open your Kontent project, go to Project Settings > Preview URLs, and set a new preview URL for the Post content type to:

http://localhost:3000/api/preview?secret=<KONTENT_PREVIEW_SECRET>&slug={URLslug}

Replace <KONTENT_PREVIEW_SECRET> with its respective value in .env.local:

Once saved, go to one of the posts you've created and:

Create a new version of the post
Update the title. For example, you can add [Draft] in front of the title. > Mind the title also regenerates the URL slug, if you want to change any other field that does not influence the URL slug, feel free to do so.
Do not publish it. By doing this, the post will be in the draft workflow step.
On the menu, you will see the Preview button. Click on it!

You will now be able to see the updated title. To exit preview mode, you can click on Click here to exit preview mode at the top of the page.

Step 5: Deploying Your App with Vercel

To deploy your Next.js + Kontent site with a Vercel for Git Integration, make sure it has been pushed to a Git repository.

During the import process, you will need to add the following environment variables:

KONTENT_PROJECT_ID
KONTENT_PREVIEW_API_KEY
KONTENT_PREVIEW_SECRET

Import the project into Vercel using your Git Integration of choice:

After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly "main") will result in a Production Deployment.

Once deployed, you will get a URL to see your site live, such as the following: https://next-blog-kontent.vercel.app/

Set up a Next.js + Kontent site with a few clicks using the Deploy button, and create a Git repository for it in the process for automatic deployments for your updates.

If you want to explore a more complex example for Kentico Kontent and Next.js, check out this Corporate Starter.

Kentico / kontent-starter-corporate-next-js

Next.js corporate starter site using Kentico Kontent as a data source.

Vue.js cheat sheet: Rendering data into HTML

Ondrej Polesny — Fri, 07 May 2021 20:14:44 +0000

Are you just starting out with Vue.js? Or has it been long since you’ve worked with Vue? This cheat sheet lists the nine most common tasks and solutions when outputting data to HTML.

In all these samples, the first part shows the syntax, and the second part shows the usage with real data.

Outputting data into HTML

The first test of your app or rendering data between HTML elements:

{{ variable }}
↓
{{ metadata.subtitle.value }}

Adding the standard class attribute

After testing the app, you want to make it look nice with styles:

<... class="classname">
↓
<div class="sidebar__inner">

Outputting data into HTML attributes

When adding links or rendering images with alt tags, this is how you can fill the elements’ attributes:

< ... :name="variable">
↓
<a :href="`https://twitter.com/${author.twitter.value}`">

Outputting HTML

In certain cases, like when consuming rich texts from a headless CMS, you need to render already formatted HTML:

< ... v-html="variable"></...>
↓
<div v-html="article.teaser"></div>

Iterating over data sets

Iterating is useful for creating lists of items, like index pages of blogs or product catalogs:

< ... v-for="item in collectionVariable" :key="item.uniqueKey">
↓
<article v-for="article in articles" :key="article.id" ... >

Iterating over data sets with index

The same use case as before, but this way, you can access an index of each item:

< ... v-for="(item, index) in collectionVariable" :key="item.id">
↓
<article v-for="(article, index) in articles" :key="article.id" ... >

Rendering conditional markup

Conditions allow you to hide or display specific parts of markup based on data:

<... v-if="variable !== null">
↓
<div v-if="data.length > 0"> ... </div>

Rendering conditional markup including else branch

They can also be used to display preloaders in case of async data fetching to let your visitors know that something is happening:

<... v-if="variable !== null"> ...
<... v-else>
↓
<div v-if="data.length > 0"> ... </div>
<div v-else>Loading...</div>

Passing data to child components

When you start using components, this is how you can provide them with data from the parent:

<component :componentVariable="variable">
↓
<links :author="author">

You can also download this cheat sheet in printable form and check out its alternatives for React and Angular.

Animating multiple elements with Vue transitions (and CSS var() function)

Ondrej Polesny — Thu, 29 Apr 2021 18:06:49 +0000

Transitions are a great way to make your app interactive. Vue.js allows us to animate any dynamic events on elements with the <transition> component. But what if you need to animate multiple elements that are related to each other?

TLDR: CodePen link

I stumbled upon this problem when I wanted to animate graph bars. Each bar needed to have a specific width and had to be animated right after the previous one. Also, I did not want to hardcode the number of bars, so it all needed to be data-driven.

Building the data and template

So let's isolate the problem, this is how the bars are defined in a Vue app:



data(){
  return {
    bars: [75, 50, 100]
  }
}

And they are rendered in a for loop:



<div v-for="(bar, i) in bars" :key="i" class="bar">{{bar}}%</div>

Animating the bars using

The first step in animating them is to add a component and a single root as that's what Vue requires:



<transition name="bars" appear>
  <div>
    <div v-for="(bar, i) in bars" :key="i" class="bar">{{bar}}%</div>
  </div>
</transition>

Note the appear attribute. It instructs Vue to animate the first (and only) child element when it appears in the DOM. Vue is clever enough to search the applied styles for transition and it will add a few special classes to the element for the duration of the transition:

bars-enter-active for the whole duration
bars-enter-from at the start to define CSS to animate from, e.g. width: 0
bars-enter-to at the end to define CSS to animate to, e.g. width: 75%

The problem is, we need to define these properties on a more granular level - for each bar.

Connecting data with CSS using var()

The CSS var() function allows us to nicely connect dynamic data with CSS. We configure the data just like any other style definition of the element:



<div style="--variableName: variableValue"></div>

And use var(variableName) in the actual stylesheet:



.selector {
  CSS property: var(--variableName);
}

In this case, we'll need each bar to define its width and calculate the animation delay using the item's index:



<div v-for="(bar, i) in bars" :key="i" class="bar" :style="`--width: ${bar}%; --delay: ${i}s`">{{bar}}%</div>

And add the accompanying styles:



.bar {
  width: var(--width);
}

.bars-enter-from .bar {
  width: 0;
}

.bars-enter-active .bar {
  transition: all 2s;
  transition-delay: var(--delay);
}

The last thing to keep in mind is that Vue will only keep the special CSS classes on the root element for the amount of time defined in its transition. So let's add the expected animation time as transition duration:



<div style="`transition: all ${(bars.length-1)+2}s`">

The animation will take exactly N+2 seconds if N is the number of bars and each bar takes 2s to render. If you set it to a lower value than needed, the animation of some bars will not finish and just skip to the final position.

See the functional sample on CodePen.

Conclusion

The combination of --variableName: variableValue and var(--variableName) is a nice way to avoid generating too many style definitions (that are even then limited) through for loops.

If you want to share your experience or get in touch, join the Kontent Discord and ping me a message 😊

How to use Kontent Delivery SDK with native ESM and Vite

Ondrej Polesny — Wed, 31 Mar 2021 12:11:40 +0000

Why native ESM and Vite?

When working on JavaScript projects, we are used to bundling every bit of functionality into a JS bundle that is then served to all visitors of our sites. With native ESM we can get around the bundling and serve modular JS code to modern browsers directly and dynamically.

One of the tools that help us with this task is Vite. It effectively replaces Webpack and allows for instant cold-start of your development server as well as ensures optimal output for production. In turn, it asks for all code to be compatible with ES2015 and newer, so no CommonJS anymore.

If you try to build your site with Vite and your code does not comply, you will most likely see the following error:

❌ Uncaught ReferenceError: exports is not defined at ...

The error occurs after you generate the production build and comes from your Vite-optimized code bundle. It means there is some unsupported functionality left in your code or in the packages that you use.

The Kontent JS Delivery SDK may be one of them. To configure it to work with Vite you need to do the following:

Target ESNext version of the Delivery SDK

The Kontent JS Delivery SDK from version 10.4.1 comes with the ESNext version in a subfolder _esNext so you just need to ensure your code uses it. But to make it a bit more complicated, you also need to use _es2015 (the newest) version of kontent-core package that the kontent-delivery depends on.

So you see, you can't just adjust all your imports to use a subfolder _esNext. To solve this issue, you need to tell Vite to redirect all relevant imports to that specific subfolder. Vite passes this information to Rollup - the module bundler it uses internally. The vite.config.ts looks like this:

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@kentico/kontent-core': '@kentico/kontent-core/_es2015',
      '@kentico/kontent-delivery': '@kentico/kontent-delivery/_esNext'
    }
  }
})

We are redirecting all kontent-core and kontent-delivery imports to the respective subfolders.

Note: If you're not using Vite and need to do the same with Webpack, see this page in their docs.

Add BrowserRichTextParser to DeliveryClient config

The SDK may be used in both browser and Node environments. Because Node.js does not feature browser API, the SDK is capable of dynamically loading a (much larger) Node.js parser based on the runtime context. However, some compatibility issues with Angular required the use of CommonJS's require.

You're building a website, so you can get around this by defining the browser-specific parser in the DeliveryClient config:

import { BrowserRichTextParser } from '@kentico/kontent-delivery'

const client = new DeliveryClient({
      ...
      richTextParserAdapter: new BrowserRichTextParser()
    });

And that's it. You're good to go 🤗 Try npm run build and npm run serve and your console should be nice and clean.

If you're using only ES2015+ compatible packages, using Vite you can get a much better development experience with zero waits and more effective production bundles.

Follow my Twitter if you don't want to miss any new articles 🐤

Get Kontent Project ID from the Management API key

Ondřej Chrastina — Mon, 22 Mar 2021 14:00:03 +0000

It is possible to parse out Kontent Project ID out of the Management API Key. That means no more necessity to ask for two keys for your Kontent tools.

Do you develop any Kontent tool using Management API and still ask for both - Project ID and Management API key? Following lines will help you to improve your UX as well as cleanout your code.

The management API key is just a JWT token containing the payload (in between header with signature). So you could decode it i.e. by using JWT.io, And as a payload, you could see this:

{
    "jti": "b6a9ee86bfdc41c89f20048c3baaba04",
    "iat": "1612535158",
    "exp": "1958135158",
    "project_id": "06c2b8951700013e5f3160283aff1100",
    "ver": "2.1.0",
    "uid": "usr_0vMrpCH2TkOK5oK3y3bKNS",
    "aud": "manage.kenticocloud.com"
}

The project_id could be used to identify the project with one modification. It is necessary to add dashes on appropriate places to respect the GUID format.

To do all of that, the code would end up looking like that (or any other language alternative) - or you just use a library like jwt-decode. But it is always good to know what they do.

const managementApiKey = "ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAianRpIjogImI2YTllZTg2YmZkYzQxYzg5ZjIwMDQ4YzNiYWFiYTA0IiwNCiAgImlhdCI6ICIxNjEyNTM1MTU4IiwNCiAgImV4cCI6ICIxOTU4MTM1MTU4IiwNCiAgInByb2plY3RfaWQiOiAiMDZjMmI4OTUxNzAwMDEzZTVmMzE2MDI4M2FmZjExMDAiLA0KICAidmVyIjogIjIuMS4wIiwNCiAgInVpZCI6ICJ1c3JfMHZNcnBDSDJUa09LNW9LM3kzYktOUyIsDQogICJhdWQiOiAibWFuYWdlLmtlbnRpY29jbG91ZC5jb20iDQp9.aEqGajw7e9m13lnID0z9PBCL0MytqYlvoYg_rwPfEJo";

const payloadBase64 = managementApiKey.split('.')[1];
const payloadBase64Cleared = payloadBase64.replace(/-/g, '+').replace(/_/g, '/');
const jsonPayload = decodeURIComponent(
    atob(payloadBase64Cleared)
    .split('')
    .map((c) => 
        ('%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2))
    )
    .join('')
);

const payloadObject = JSON.parse(jsonPayload);

const projectIdWithoutDashes = payloadObject.project_id;

const projectId = 
    `${projectIdWithoutDashes.substr(0, 8)}-\
${projectIdWithoutDashes.substr(8, 4)}-\
${projectIdWithoutDashes.substr(12,4 )}-\
${projectIdWithoutDashes.substr(16, 4)}-\
${projectIdWithoutDashes.substr(20)}`

console.log(projectId);

If you want to play with it - check out this Codepen.

...and of course, I invalidated the showcased API key 🤞

Reporting .NET 5 XUnit Code Coverage in Codecov via GitHub Actions and Coverlet

Petr Švihlík — Fri, 05 Mar 2021 14:56:10 +0000

You might remember my earlier post where I described how to set up code coverage reporting for .NET Core 3 using AppVeyor + OpenCover + Codecov.

Time has moved on, .NET 5 has arrived, and the best practices have changed, so let's see how to collect code coverage for .NET projects in 2021.

The stack

For some time, I have been intrigued by the coverlet.collector that you can find in any new XUnit .csproj. What it is? How can I use it? Can I replace OpenCover with it?

Also, I started noticing people migrating to GitHub Actions and I didn't have any experience with it and kinda felt that I'm missing the train. This observation has been confirmed recently in the 2020 State of Open Source Code Coverage report where GitHub Actions scored the #1 fastest growing CI used with Codecov (and also the #1 in absolute numbers).

I was thinking I could modernize the stack that I use for .NET projects both at work and for my personal projects. Of the three tools that I've been using previously, I'll be keeping just Codecov (because it's awesome ❤). Let's get to it.

Generating coverage

I like to use the dotnet CLI for as many tasks as possible. The good news is that coverlet offers deep integration with msbuild.
This is how you can generate code coverage for the whole solution:

dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

The command will generate coverage.opencover.xml files in all your test projects (if you run dotnet test on the solution level).

All you need to do to make the code coverage-related /p: switches work is to install also the coverlet.msbuild NuGet package. So your .csprojs will look something like this:

<PackageReference Include="coverlet.collector" Version="3.0.3">
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  <PrivateAssets>all</PrivateAssets>
</PackageReference>
<PackageReference Include="coverlet.msbuild" Version="3.0.3">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

Make sure to leave in the /p:CoverletOutputFormat=opencover switch as this is the format that's accepted by Codecov.

For more advanced configuration, I recommend reading the documentation on Coverlet's integration with MSBuild. This is especially useful when your solution or projects don't stick to naming conventions and you need to do some extra filtering, etc.

Integrating into GitHub Actions

Plugging the dotnet test into the CI pipeline is just a matter of creating a new workflow step. No matter if you use the ubuntu-latest or windows-latest runner, it works flawlessly.

- name: Restore dependencies
  run: dotnet restore
- name: Build
  run: dotnet build --no-restore /p:ContinuousIntegrationBuild=true
- name: Test
  run: dotnet test --no-build --verbosity normal /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

Collecting coverage by Codecov

The last step is to upload the test coverage to Codecov. You can find an official Codecov GitHub Action on the marketplace which makes the process super easy - no need to install the Codecov CLI, etc.

Just add the following lines to your workflow:

- name: Codecov
  uses: codecov/codecov-action@v1

Codecov will search through the folder structure of your project and discover your coverage reports based on conventions. You don't even have to include the CODECOV_TOKEN for public repos.

Summary

As you can see, this approach is much more convenient than the one I was using before - downloading and installing tools, running PowerShell scripts, etc.

If you stick to standard .NET naming and folder structure conventions, setting up code coverage is actually very easy nowadays.

To see the whole workflow in action, head to some of our SDK repos. You can also explore how we do releases using GitHub Actions. All code is in the workflows folder.

In my next article, I'll cover how to secure secrets when building pull requests from forks.

Can you evolve your documentation from fossil to fantastic?

Michael Berry — Tue, 22 Dec 2020 13:17:57 +0000

We can all agree that repeating the same information over and over wastes time and that writing comprehensive and accessible documentation is essential. But have you thought about how you’re creating that documentation? Are you still dusting off printed instructions or digging up ancient word documents? Is there a more modern approach?

In my opinion: "Boilerplates" are beautiful. They make using a new framework, language, or platform possible without starting from scratch, and can vastly simplify starting a new project. To simplify my documentation creation process, I've made a Kontent + Docusaurus boilerplate that will handle styling, navigation, and structure, while also allowing me to maintain my content using a headless CMS.

In this article, I’ll talk about the benefits of using Kentico Kontent, Facebook’s Docusaurus, and my Kontent + Docusaurus boilerplate to create scalable, attractive, easy-to-manage documentation.

Why my documentation went “the way of the dinosaurs”

I wear a lot of hats in my organization: I’m a manager, support engineer, content creator, internal trainer, to name a few. Shifting attention between varying tasks and functions is a common occurrence and can be pretty overwhelming. To save time (and my sanity), documenting my processes and responsibilities helps me stay organized and allows me to delegate tasks to my team more effectively. But until recently, I didn’t have a great way to create this resource. I’ve used our crowded company wiki, Word documents, PowerPoint presentations, and a lot of information is given verbally from memory. Something had to change as this approach locked me into a perpetual loop of updating static presentations and documents with no hope of delegation.

How does it help you?

Maybe you’re not managing a team or on-boarding anyone, but I’m confident at some point you’ve had to walk a teammate or multiple colleagues through a process a few times. Let’s be fair: your colleagues don’t want to take valuable time away from you. They just need answers, and those answers happen to live in your head, are hiding in your notes, or are just not documented in an accessible location.

Furthermore, updating and maintaining documentation or guides doesn’t have to (and normally shouldn’t) rely upon developers, specialized, or senior team members. You should be able to write the original copy, hand-off the maintenance to a colleague or team, and move on to other tasks that are burning for your attention.

The boilerplate: Our cloning DNA

Creating a new piece of documentation shouldn’t be an ordeal; you don’t need another project vying for your time. Using a template as a starting point is a good way to make sure starting the documentation isn’t a major line item blocking out your calendar. So clone this repository and save time—no prehistoric mosquitoes required (you knew a Jurassic Park reference was coming).

This boilerplate comes with:

A navigation sidebar with collapsible sub-sections
Attractive pre-made styles, including light & dark mode
A minimal amount of content to act as a “starting point”
Quick and easy setup instructions in the Boilerplate’s documentation or GitHub README

Kontent + Docusaurus boilerplate pictured above.

The headless CMS: Advancing our reptile brains

When documentation is required, jumping into a simple word processor is second-nature to a lot of us. It’s comfortable, it’s quick, it’s familiar. This doesn’t mean it is the best approach for the job, though, and I argue that breaking this habit is key for making scalable and accessible documentation. Using a headless CMS addresses scalability head-on and future-proofs your documentation.

I work in Kentico Kontent all the time, so it is a go-to comfort pick for me when choosing a CMS, but those who aren’t fluent in Kontent will still reap major benefits from using it:

It’s a Software-as-a-Service platform, meaning no managing upgrades, hosting, or security patches.
Kontent’s search bar, filters, and “Home” allows you to quickly locate content.
Inserting code snippets into the Rich Text Editor using a WYSIWYG editor is easy.
Reusable content and content links mean no more copy-pasting swaths of documentation between sections.
Its features, API, and SDKs are well documented.

Sample content item in Kentico Kontent pictured above.

These are just a few of the benefits when using Kentico Kontent, but if you need more proof, the official Kontent documentation uses Kontent, and there is a two-part article series that talks about why.

Docusaurus: More Barney than an apex predator

In addition to the list of benefits from Docusaurus’ website, the plugins and presets provided by the Docusaurus team make getting up and running fast. Its creators’ focus on documentation sites, along with 20,000 GitHub stars and being backed by Facebook, is what really drew me to using Docusaurus as the front-end application for my documentation. It’s also a nice fit because:

It’s a static site generator making it fast and secure.
It can be deployed and hosted virtually anywhere for free.
The Docusaurus team wrote easy-to-read documentation about everything from Installation *to *Lifecycle APIs.

This React and MDX markdown powered project has T-Rex-level power in its extensibility and out-of-the-box functionality, but the features and configuration are intuitive, so its learning curve isn’t intimidating. For example, in just three terminal commands you can have their classic preset site running. Docusaurus is definitely a friendly dinosaur.

So...is it actually fantastic?

For me personally, I’m a lot happier to point a colleague to up-to-date stylized on-boarding resources than having to muddle together PowerPoint presentations, but this depends on your use case. If you just need a few quick, static paragraphs to document something, Kontent + Docusaurus might be overkill. But, if you have living documentation that needs frequent updates, reusable content, and structured navigation, it could be a better choice than passing around Word documents or jamming information into overflowing wikis.

Additionally, since the content is available over an API in a headless CMS, this documentation can evolve with the times; Create a voice-app that pulls the documentation from Kontent, integrate personalization to better serve the visitor, add analytics or commenting with machine learning to gauge the helpfulness of a page. The possibilities and complexity can scale with the project needs. I’d say that’s pretty fantastic!

Kentico Kontent architecture possibilities pictured above.

Can I see this evolution in action?

Absolutely! The documentation explaining how to set up the Kontent + Docusaurus Boilerplate was written using Kontent and Docusaurus. You can also set up your own project using the instructions in the Kontent + Docusaurus Boilerplate GitHub repository.

Don’t wait for a meteorite

In this article, we highlighted the benefits of replacing old documentation with Kontent and Docusaurus and how a boilerplate can streamline your documentation creation. So don’t wait for a cataclysmic event, blow up your ancient documentation habits, and give Kontent and Docusaurus a try!