Forem: Michael Kinkaid

🎉 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!

Headless CMS just isn't good enough...

Michael Kinkaid — Mon, 17 Aug 2020 12:35:15 +0000

OK, so before I get accused of clickbait (perhaps a fair accusation), let's start by finishing up that intentionally provocative title: Headless CMS just isn't good enough for - (🥁 drumroll)- those of us who have heads.

🤯

Still too vague and sensational? Concerned this post hasn't really kicked off and I've already used 2 emojis? OK - to be specific - headless CMS just isn't good enough for the actual people who log in to the platform to create and publish content for a website.

The problem? Well, whereas authoring content on a headless platform is generally a joyful experience, bringing that content all together to present it on a channel; e.g., creating a web page for your site, can be a little tricky.

This is because, to create that new web page, you have to deal with a whole bunch of very specific channel "things" like pages, templates, components, navigation, and URLs. This can be challenging on a headless CMS because, with the exception of a basic preview feature, they don't typically give great visual feedback to help with page composition.

It's hard to see where you're going without a head: The other just as obnoxious working title for this post...

This lack of visual feedback and contextual support can be frustrating for content creators (editors and marketers) to deal with. They're going to want as much control and flexibility with the channel as possible. If, like in this example, that channel is web, then they're going to want to work within that context - creating and managing web pages.

The Good Ol' Days

If you're a content creator who’s worked with traditional CMS platforms, then this lack of visual feedback when it comes to page composition is likely the first thing you'll notice when switching to a headless CMS.

Not only do traditional CMS platforms allow content creators to work with structured content, but they typically provide really rich editing experiences specific to making an actual website. You get features like visual page composition, drag and drop, a way to see and manage your site structure. You're managing content within the context of how it's actually going to be consumed.

The Somewhat Established "Newness"

In comparison, a headless CMS platform focuses on content authoring and making that content available to practically anything that can talk to its API. How much it knows or cares about the channels you present your content on is entirely up to whoever is designing the content model.

If one of your channels is a website then a common approach is to add content types to your model for all those website elements your editors are going to need to manage; e.g., Page, Navigation items, components like a Banner, and Call to Action. This provides the flexibility content creators want - but page composition is a little bit more abstract.

Depending on the number of moving parts in your model, creating and connecting all these bits of content can start to feel like you're trapped in Christopher Nolan's Inception. Here's an example of a dream within a dream within a dream...

I want to add a new Sponsor Call to Action (CTA) to the homepage:

Step	Task
1	Create a new Sponsor content item for the info specific to the new sponsor
2	Create the new Sponsor CTA content item to manage actions, URLs, web stuff
3	Associate the new Sponsor to the new Sponsor CTA
4	Find the Sponsor List component that we use to group our Sponsor CTAs
5	Add the Sponsor CTA to the Sponsor List component
6	Find and open the homepage content item
7	Click preview
8	Finally see what you've created
9	`Take a nap`

The solution to all this elaborate content juggling? Well, that's pretty obvious.

Give up on all the benefits of headless CMS and go back to using a more traditional CMS.

The End.

OK, so that's a knee-jerk reaction rather than a solution. We want all the benefits of a headless CMS. We'd also like more visual feedback when it comes to dealing with the channel our content will be available on. The solution is to bring all these things together.

How might that work? How do we do this without reverting our headless CMS back into a tool that only knows how to make a website?

Thankfully, answering these questions doesn't have to be a thought experiment as one headless CMS platform - Kentico Kontent - just announced how they intend to do it. Their solution is to provide an optional add-on to their headless CMS. This add-on is called Web Spotlight and it's a tool specifically tailored to helping content creators manage the web channel.

From the preview above it's clear Kentico Kontent is taking the frustrations of content creators head on:

Having difficulty finding the page you need to update? You can now manage the site structure using a content tree (shown on the left).
Able to see content you need to update in the preview, but have no idea where that content item lives in your inventory? You can now just click on the content and instantly jump into editing mode (shown on the right).

Even better: unlike a traditional CMS that typically locks you into coding your entire site in their preferred language, Web Spotlight uses an API so you're still free to use any technology stack. You just have to integrate with the API when rendering your preview.

The approach of releasing Web Spotlight as an optional add-on highlights how Kentico Kontent intend to evolve the whole headless paradigm without breaking it. If you're creating content for a website and want additional support, then Kentico's Web Spotlight provides a tool designed to enhance editing for that channel.

Not creating a website, or don't need the additional context of Web Spotlight? Then you don't have to use it.

It's easy to imagine how Web Spotlight could evolve to provide even more web-focused enhancements for content creators (easier management of channel-specific content types, drag and drop components, etc.).

And why stop at web? Now that a model of optional channel editors is established, Kentico Kontent could provide add-ons to enhance working with other channels or integrations.

As with any new feature, users will ultimately decide the fate of this approach. It'll be interesting to see if other headless CMS platforms adopt something similar. There are already a few out there with visual editors (e.g., StoryBlok), but Web Spotlight is the first I've seen as a separate add-on that extends the headless CMS. This separation feels like the best way to allow both parts to evolve independently.

For an extended trial of Kentico Kontent, go use this magical link!

Migrating Model Changes with the Kentico Kontent CLI

Michael Kinkaid — Wed, 01 Jul 2020 11:55:03 +0000

Kentico Kontent has a CLI that you can use to manage your content model - using code.

Not only can you build your model using code, but you can also migrate your model changes across any environments that you've set up in Kentico Kontent i.e. Development, QA, UAT, Production etc.

In this post we're going to use the migrations feature of the CLI to create a content model from scratch. We won't be designing the model in Kentico Kontent's user interface. Instead, we'll be doing everything by code.

We'll need a blank project to work with - so go over to Kontent and create a new one. Don't go modelling anything, though 😁.

If you want to grab the final code then clone the following GitHub repository.

Before you start, make sure you have Node 10+ and npm 6+.

Step 1 - Set up a Migration Project

Create a folder wherever you set up your projects. Open a new command window or terminal at that folder location. Kick off a new project using npm or yarn. I'm going to use npm, so run the following command:

npm init -y

We're going to need a few dependencies in order to run our scripts. These are:

RxJS

The CLI uses the Kentico Kontent Management API (v2). This has a peer dependency on RxJS, so let's install this before we add the CLI. I've heard rumour this dependency may be going away some time in the future. That, or I've been having weird dreams again. Comment below if I'm horribly wrong.

npm i rxjs

Kentico Kontent CLI

Next, let's go grab the CLI. This does support global installation (add the '-g' flag to the line below). I've been installing it locally, given the RxJS dependency.

npm i @kentico/kontent-cli

Dotenv

The migration process will use project keys from Kentico Kontent. Dotenv allows us to store secret API keys as environment variables, which saves you from putting these directly into your code. Be sure to keep this information out of source control as well.

npm i dotenv

Step 2 - Grab your Project Keys

OK, so we do need to bounce into Kentico Kontent to get those secret API keys. Open the blank project you created and go to Project Settings (the cog icon in the menu). When we create a new project, Kentico Kontent creates a single Production environment.

Let's grab the settings for this environment:

The Product ID
The Management API Key (make sure to activate it)

Let's use the Kentico Kontent CLI to save these settings into our project. Add in your unique settings to the line below and run the command:

kontent environment add --name PROD --project-id "<YOUR_PROJECT_ID>" --api-key "<YOUR_MANAGAMENT_API_KEY>"

The --name parameter can be anything you want. You'll use this name ("PROD" in our example) to target the environment you want to run your migrations on.

If this has worked as intended then the Kentico Kontent CLI will have created a file called .environments.json.

{
    "PROD": {
        "projectId": "<THE_PROJECT_ID_YOU_ENTERED>",
        "apiKey": "<THE_MANAGAMENT_API_KEY_YOU_ENTERED>"
    }
}

You can repeat Step 2 for each environment that you set up on a project. We don't have to do this now. Because we're starting from a blank project, our Production environment is enough. However, if this was a real gig our content pipeline could have multiple environments, such as:

Development to QA to UAT to Production.

Environments are managed under Settings > Environments

When you click Clone, Kentico Kontent will copy everything from the selected environment into a new environment (the content model and all content items). The new environment will have completely new settings (Project ID and Management API Key), which is why you would repeat the step to save those settings into your .environments.json file.

Step 3 - Add a New Migration Script

The Kentico Kontent CLI has a handy command to get started with migration scripts. Run the following:

kontent migration add --name 01_create_album_review_content_type

This creates a new JavaScript migrations file (with the catchy name of 01_create_album_review_content_type.js). The module has the following code:

const migration = {
    order: 1,
    run: async (apiClient) => {
    },
};

module.exports = migration;

You can have multiple migration scripts. Depending on what you're doing to your model, you'll likely have an order you want to run these in. That execution sequence is controlled through the order property.

The run function is where you put the migration code that you want to execute on your content model. The parameter getting passed here is an instance of the Kentico Kontent Management API client. As we'll see, this client allows you to do some pretty cool things to your content model and all your content items.

Running the command also created a folder called Migrations (within your project folder). This is where Kentico Kontent put the script. All your migration scripts need to be in a folder called Migrations, otherwise an error will be thrown 🔥🔥🔥.

Open the project up in your favourite editor. It's time to start writing some code.

Step 4 - Creating Content Types

As the name of our first migration script would suggest (01_create_album_review_content_type.js), we're going to create a new content type called Album Review.

This content type is going to start with the following fields:

Title (text content element)
Album name (text content element, required)
Artist (text content element, required)
Review (rich text content element)

Update your migration script with the following code:

const migration = {
    order: 1,
    run: async (apiClient) => {
        await apiClient
            .addContentType()
            .withData(BuildAlbumReviewTypeData)
            .toPromise();
    },
};

const BuildAlbumReviewTypeData = (builder) => {
    return {
        name: 'Album Review',
        codename: 'album_review',
        elements: [
            builder.textElement({
                name: 'Title',
                codename: 'title',
                type: 'text',
            }),
            builder.textElement({
                name: 'Album Name',
                codename: 'album_name',
                type: 'text',
                is_required: true,
            }),
            builder.textElement({
                name: 'Artist',
                codename: 'artist',
                type: 'text',
                s_required: true,
            }),
            builder.textElement({
                name: 'Review',
                codename: 'review',
                type: 'rich_text',
            }),
        ],
    };
};

module.exports = migration;

The run function shows the client call to create a new content type. We're defining the structure of our Album Review content type in BuildAlbumReviewTypeData.

To run this migration script ("01_create_album_review_content_type") on the default production environment (which we registered as "Prod"), execute the following command:

kontent migration run --environment PROD -n 01_create_album_review_content_type

If the migration ran successfully then you should see the following in your output:

The "01_create_album_review_content_type.js" migration on a project with ID "" executed successfully.

If you jump into Kentico Kontent and go to the Content models, then you'll see the new content type:

If you click on the content type to open it up, then you'll see the structure we added using our migration script:

You'll also notice that the Kentico Kontent CLI has created a status.json file at the root of your project:

{
  "<YOUR_PROJECT_ID>": [
    {
      "name": "01_create_album_review_content_type.js",
      "order": 1,
      "success": true,
      "time": "2020-06-29T22:15:10.115Z"
    }
  ]
}

As the name suggests, this file keeps track of the status returned from your migration scripts. This file will get updated as you run future scripts.

Let's create one more content type so that we'll have a little more in our model to play with. Create a second file in the migrations folder called 02_create_reviewer_content_type.js and add the following code:

const migration = {
    order: 2,
    run: async (apiClient) => {
        await apiClient
            .addContentType()
            .withData(BuildReviewerTypeData)
            .toPromise();
    },
};

const BuildReviewerTypeData = (builder) => {
    return {
        name: 'Reviewer',
        codename: 'reviewer',
        elements: [
            builder.textElement({
                name: 'First Name',
                codename: 'first_name',
                type: 'text',
                is_required: true,
            }),
            builder.textElement({
                name: 'Last Name',
                codename: 'last_name',
                type: 'text',
                is_required: true,
            }),
            builder.textElement({
                name: 'Twitter Handle',
                codename: 'twitter',
                type: 'text',
            }),
        ],
    };
};

module.exports = migration;

The migration script will create a new Reviewer content type that we're going to use in a relationship with our Album Review content type.

Run this migration with the following command:

kontent migration run --environment PROD -n 02_create_reviewer_content_type

Note: You can run migrations individually or as a batch. Use the following Kentico Kontent CLI command to run all your migrations:

kontent migration run --all --environment PROD

The migration process will skip any migration that it has already processed. You'll see this in the output in your command window / terminal:

Skipping already executed migration 01_create_album_review_content_type.js

Step 5 - Updating a Content Type

As your model extends, you're going to want to update content types that you've already created. This can also be done in a migration script.

Now that we've got a Reviewer content type, we should create a content element (fancy pants term for a field) in our Album Review content type so we can link these two; i.e., an Album Review will be written by one Reviewer.

Create a new migration script in the migration folder called 03_add_reviewer_linked_item.js. Add the following code:

const migration = {
    order: 3,
    run: async (apiClient) => {
        const modification = [
            {
                op: 'addInto',
                path: '/elements',
                value: {
                    name: 'Reviewer',
                    codename: 'reviewer',
                    type: 'modular_content',
                },
            },
        ];

        await apiClient
            .modifyContentType()
            .byTypeCodename('album_review')
            .withData(modification)
            .toPromise();
    },
};

module.exports = migration;

If you look first at the API call we're building, you'll see we're modifying the Album review content type (which we target through the code name). Our modification is an array of operations that contain content type data.

We only have one operation defined in this call. Our operation is going to add (addInto) a new modular content element. "Modular Content" is a legacy API name. You'll see it called a "Linked Item" in the user interface.

Run your migrations again. This time, try:

kontent migration run --all --environment PROD

You should notice that the first two migrations are skipped, and that only the third runs.

If we jump into Kentico Kontent and look at the Album Review content type then at the bottom we will see our new field:

Step 6 - Configuring Relationships

If you're familiar with Kentico Kontent then you'll know that the Linked Item content element offers a lot in terms of handy configuration that will make editors' lives easier - and protect our model.

The screenshot above is from another project. You can see that the Linked Item content element is required, and that it can have only one relationship to a Widget-Logo Grid content item.

The Reviewer content element should only allow an association to one Reviewer. However, that's not how things are currently set up in our content model. An editor could link an Album Review to any number of different content types.

Now, we could've set the following configuration in our previous step, but I wanted to show you how you can make deeper-level edits and replace or add new configuration to content elements that are already part of a content type.

Add a new migration script in the Migrations folder called 04_update_reviewer_linked_item.js.

Add the following code:

const migration = {
    order: 4,
    getReviewerId: async (apiClient) => {
        const response = await apiClient
            .viewContentType()
            .byTypeCodename('reviewer')
            .toPromise();
        return response.data.id;
    },
    run: async (apiClient) => {
        reviewerId = await migration.getReviewerId(apiClient);

        const modification = [
            {
                op: 'replace',
                path: '/elements/codename:reviewer/item_count_limit',
                value: {
                    value: 1,
                    condition: 'exactly',
                },
            },
            {
                op: 'replace',
                path: '/elements/codename:reviewer/allowed_content_types',
                value: [
                    {
                        id: reviewerId,
                    },
                ],
            },
        ];

        await apiClient
            .modifyContentType()
            .byTypeCodename('album_review')
            .withData(modification)
            .toPromise();
    },
};

module.exports = migration;

There are a few things of note in this migration.

We're applying multiple operations to the Album Review content type Reviewer content element. Or, in other words, we're doing a bunch of stuff to the Reviewer field 😎. We set the item_count_limit to '1' and set the allowed_content_types to our Reviewer content type.
In order to create the relationship we need to use the ID of the Reviewer content type. We don't have this - but we can ask for it. This is done in the function getReviewerId, which uses the API to query for the Reviewer content type data.

Run the migration.

kontent migration run --environment PROD -n 04_update_reviewer_linked_item

If you pop over to Kentico Kontent and check out the Album Review content type, you'll see that the Reviewer content element now has the configuration we need to keep our model nice and tidy.

Next Steps

A lot can be done with the Kontent CLI and Kontent Management API. For me, the next step is definitely doing more homework on managing changes across environments.

Managing your model through code requires you to understand the structure Kentico Kontent uses to represent your content model and content items.

For example, when it came to setting the allowed content types (allowed_content_types) to Reviewer (a GUID), how did I know the name of the property and the fact that a GUID was required?

This is where querying the Delivery API or Management API with a tool like Postman comes super in handy.

For that matter, how did I know the correct format for the path property (elements/codename:reviewer/allowed_content_types)? For this type of insight, you really need to check out the excellent Kentico Kontent documentation.

Interested in another example that also includes TypeScript? Check out Kentico Kontent's own boilerplate project.

Have fun migrating your content model changes!

Photo at the top by Pille Kirsi.