I’ve done web development for nearly 20 years, all of which has primarily been on the Microsoft stack. Sure, I’ve looked at other languages, but always seemed to fall back to C# and Windows-based development throughout my career. Well, like any good developer these days, I know it takes more than being singularly focused on one framework to succeed. Because of that, I’m always looking to expand my skills with new technologies and systems.

With Kentico Cloud, it’s easy to branch out and try something new. Because the API is consumable from just about everywhere, you can grab nearly any language and start working with it. Being a backend-focused developer, JavaScript and I have a… uhm…”volatile” relationship at times. Yes, I know it’s very powerful and capable and runs all the cool sites these days, but we haven’t always gotten along when we’ve worked together. 

To help me get over my JS disagreements, I decided to check out the Kentico Cloud JavaScript Sample App. As I went through the process of using the project, I thought it might be good to provide some tips for you, in case you were looking to do the same. 

Tip

Be sure to check out the Kentico Cloud Developer Hub for other sample projects and SDKs!

Preparing your environment

The first step in any project is to get your environment setup. In this case, that means ensuring you have a few key pieces installed. Because the sample project is a full React site, you will need to install Node.js on your machine to run it. And it helps to have some sort of code editor, unless you really love Notepad.

Install Visual Studio Code 

You will need some sort of editor to update your code. When working with JavaScript/TypeScript sites, I highly recommend installing Visual Studio Code. It provides nice highlighting and formatting for those languages.

You can install Visual Studio Code here. 

Installing Node.js 

In the Visual Studio Installer, you can select the Node.js development package. This option will install Node.js support, additional JavaScript and TypeScript support, as well as some diagnostic features. 

Install Node.js manually

If you like to do things by hand, you can head over the Node.js site and download the files there.

Clone the sample repository

After getting all your installs in order, you are ready to get the sample project. Head over to GitHub to download the latest version.

Because this project is open source, you can expect continual updates as more and developers contribute. 

Running the sample site

With the sample project cloned, you are ready to launch the site. Open your Node.js Command Prompt and navigate to the root of your cloned project. Run the npm install command to download the packages and configure the site.

After installing the packages, run the npm start command to launch the Node.js server. This command will also initialize the React libraries and start listening on http://localhost:3000 for requests.

From here, you can view the sample site. I recommend clicking around the application to familiarize yourself with the content. This will help in updating it in the future. 

Understanding the project structure

Because the site is a pure React application, it’s built considerably different than a .NET web application. First off, there are only a bunch of JavaScript and supporting files. This means no compilation, and really fast performance. If you are new to React, be sure to read up on the framework to help you understand the sample site. You can find out more about React here. 

Some of the notable files within the sample project are:

Client.js

This file centralizes the creation of the Kentico Cloud client and requests. This makes it very easy to include this file within your pages to ensure your calls are consistent and handled properly.

Stores/XXX.js

These files define the structure and container for data retrieved from Kentico Cloud. This includes pulling the data, refreshing it on state changes, and filtering. If you want to pull another type of data, you will want to duplicate this structure for your Kentico Cloud content types.

Pages/XXX.js

These files contain the layout for the actual content. Leveraging the /Stores/xxx.js files, they make the request to retrieve Kentico Cloud content and define how it will be displayed. Be sure to learn how to format your layout with React when you implement a new page. 

Adding your custom code

Now that you have the sample project running, you may be thinking “How can I use this for my project?” If you want to build your site using the sample foundation, you will need to update a few pieces, to get your KC content structure and data. In my case, I wanted to update the application to pull the Kentico Cloud blog posts and display it similar to the Articles section.

Update the Project ID

In the Client.js file, you’ll find the Kentico Cloud Project ID. You will need to update this value with your project ID to retrieve your content.

const projectId = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

Tip

If you still have the site running, updating that page will cause the site to refresh. This is because React is constantly monitoring the state of the files and recognizes there is a change. Once that happens, it reloads the code. You’ll also quickly find that much of the content will disappear on the sample site. This is because your new KC project doesn’t have the content types / content the sample site is expecting. 

Adding a new store

If you want to see your content, you’ll want to make a new store. In the /Stores folder, create a new file for your content. In my case, I created one named Blogpost.js to pull the Kentico Cloud blog posts.

In my new file, I used an existing store as a blueprint, and updated the code with my specific content structure. 

    Client.getItems({
        "system.type": "blog_post",
        "elements" : "title,date,header_image,perex,url_slug",
        "order": "elements.date[desc]",
        "limit": "5"
    }).then((response) => {
        blogposts = response.items;
        notifyChange();
    });

In the sample site, each store pulls and structures data little differently. Some leverage multiple functions to return filtered and ordered content, depending on the needs. Be sure to review each store to understand the different possibilities.

Adding a new page

With your new store created, you are ready to make a new page. This file will define the layout for the content and how it’s presented. You will want to follow the same structure as the other pages and create your new file in the /Pages folder. I created a new file named /Pages/Blogpost.js. 

Again, use the existing pages as a sample to how you can present the content. In my case, I used the existing Articles.js structure for the blog posts.

        result.push(
         <div className="col-md-3" key={counter++}>
          <div className="article-tile">
            <a href={url} target="_blank">
              <img alt={"Blogpost " + title} className="article-tile-image" src={imageLink} title={"Blogpost " + title} />
            </a>
            <div className="article-tile-date">
          {postDate}
            </div>
            <div className="article-tile-content">
              <h2 className="h4">
            <a href={url} target="_blank">{title}</a>
              </h2>
              
            <RichTextElement className="article-detail-content" element={perex} />
            </div>
          </div>
        </div>
        );

Routing/Header

The last step you will need to do is to add a route for the new page and a link in the top menu. In the index.js file, you will want to add a new route.

import BlogpostsPage from './Pages/Blogposts';
...
<Route path="blogposts" component={BlogpostsPage} /
...

And in the /Components/Header.js file, add a link to the new page.

          <nav role="navigation">
            <ul>
                ...
                <Link to="/blogposts">Blog posts</Link>
              </li>
            </ul>
          </nav>

Testing

After making the new files and updates, you are ready to test. If you have stopped the site, repeat the npm start command to launch your Node server. Then, browse to the site and view your new page.

In my demo, the new page is correctly pulling the Kentico Cloud blog posts and displaying them. If your content is not displaying, check your /Stores/XXX.js and /Pages/XXX.js files to make sure you have the correct content structure defined.

Moving forward

Because Kentico Cloud can be implemented with so many technologies, the possibilities are limitless for developers. You are free to use any language, OS, or framework for your development, while leveraging our cloud-based SaaS for your content. We will continue to provide sample projects like the one in this blog to help you get started. And because they’re open source, we would love for you to contribute if you like. Good luck! 

Get the code