Skip to main content

Sitecore - JSS Collection

Introduction

JSS can be used to create a headless omnichannel customer experience, that is reliable and easy to use. As a developer, JSS will enable you to build your websites using your favorite JavaScript framework (React, Angular, Vue) using any operating system.

Determine Methods for Using JSS

Identify Types of CMSs

The modern web content management system (CMS) is used for creating, managing, and optimizing your customers’ digital experience. CMSs are generally the best way to organize and deliver content through a web service. There are three types of CMSs for you to identify in this track: traditional, headless, and Sitecore Omni™.

A traditional CMS displays web content from a front-end delivery layer. This content is created in a front-end WYSIWYG editor such as Joomla! or WordPress and then saved to a back-end database.

A headless CMS decouples the CMS’s back-end content functions (e.g. creation, management, and storage) from front-end functions (e.g. presentation and delivery). This decoupling allows developers to render the content with different heads to serve the various content devices or applications (also known as channels). This multi-channel setup is also called the omnichannel. Examples of different channels include websites, mobile apps, and smartwatches.

Sitecore Omni is a headless CMS architecture that includes the easy editing ability found in a traditional CMS but uniquely offers personalization on any device or application. This approach is great for both back-end and front-end developers because the two roles can work in parallel.

For example, Sitecore developers can focus on applying their programming language expertise, while JavaScript developers can build the look, feel, and functionality of user experiences using the tools they know well (e.g. JavaScript libraries and frameworks). Developers can then push content out to any device or application using the latest APIs.

Sitecore has 5 offerings in its Omni Product family, described as:

Explore Sitecore JSS Capabilities

Now that you can identify the the different types of CMSs, you will explore Sitecore JSS and its capabilities. JSS is a software development kit and one of the Sitecore Omni products you can use to create JavaScript applications, or apps, for a headless omnichannel customer experience. Any server running server-side JavaScript can host the apps. JSS offers several capabilities to front-end developers, including:

You can build apps with these types of capabilities independently or disconnected from Sitecore and by using your favorite JavaScript framework (Angular, React, or Vue). Once you deploy your app to Sitecore, you’ll be able to manage the application in the Sitecore Experience Platform (XP) enterprise backend.

To better understand how to implement the JSS capabilities, you’ll want to be familiar with the four JSS features. Let’s take a closer look at this set of features and their functions.

Examine the Code-First Approach

Now that you know about the JSS capabilities and features that help front-end developers create JSS apps, you will examine how initial JSS app development can be done while disconnected from Sitecore, which is the code-first approach. The code-first approach allows developers to create and deploy apps in their preferred environment.

Code-First Details and Benefits

Choose the code-first approach when:

The benefits of the code-first approach include:

Either way, the designer and developer need to collaborate. This collaboration between them ensures they focus on the correct level of detail for the types of content and format in the site’s design.

Build a JSS Application in a Local Development Environment

Identify JSS Requirements

Before you create an app, first make certain you meet the experience and Sitecore requirements discussed below. These requirements identify the necessary skills to use Sitecore JSS.

Experience Requirements

To create and build Sitecore JSS apps, you should have experience with the following applications to ensure you have the necessary skills:

Sitecore Requirements

In addition to having experience with the above applications, you also need to ensure you’ve done the following:

Explore the JSS CLI

Now that you understand the requirements, you are ready to set up a local development environment with the JSS command line interface (CLI) tool to create JSS apps. This track includes the following steps:

  1. Explore the purpose of the JSS CLI

Sitecore JSS includes the JSS CLI, which is a node-based command line tool with development scripts. The JSS CLI is the base tool for the code-first workflow. You use it to:

To learn more about the JSS CLI and available scripts you can use, see JSS CLI Scripts.

  1. Install and run the JSS CLI

  2. Install the JSS CLI with your command line tool of choice (e.g. bash, PowerShell, cmd prompt, or Node JS cmd prompt):

npm install -g @sitecore-jss/sitecore-jss-cli

Parts of the JSS CLI Command

npm - Node Package Manager

install - Install command

-g - Flag that enables the jss command to run from any directory (global)

@sitecore-jss/sitecore-jss-cli - Package name of the JSS CLI

  1. To verify that your CLI installation was successful, enter the command:

jss --help

The jss commands change when running within a JSS apps’ directory. The --help option will always show the currently available commands.

Create a JSS Application

Now that you have the JSS CLI installed, you are ready to create your sample JSS app.

Steps to Create Sample JSS App

  1. Identify Framework Options

With the JSS CLI installed, you are now ready to create applications. The first step is to identify the template that matches your framework (Angular, React, or Vue).

Each sample app includes the mocked Sitecore Layout Service so you can develop without the need to connect to a Sitecore installation.

  1. Create a Sample Application

For example: jss create my-first-jss-app angular jss create my-first-jss-app react jss create my-first-jss-app vue

  1. Inspect the App Viewer Feature

The app viewer is a local webpack-dev-server feature to view your app in a browser without importing any items to Sitecore. After the JSS start command runs, this feature automatically launches your app in the default browser, http://localhost:3000.

This app includes a website with all the JSS resources you need to develop your site without publishing them first. Resource items include different dates, time, languages, multiple device view settings, and more.

Create JSS Routes to Host Components and Their Data

Maintain App Directories

Now that you know how to create a JSS app, you need to understand routes. The first step in understanding routes is to examine how the JSS app directory structure works. Understanding the app directory will be important when you customize your apps with new routes from templates to host components and their data.

To maintain your site’s directory structure, you will use various tools that are described below.

The following five topics will help you learn how to use the tools described above to maintain your app directories. Each topic includes examples that demonstrate using or applying these tools.

  1. An app’s project folder in Explorer

Visual Studio Code’s Explorer window lists the following folders created by the JSS CLI when you made your app:

  1. An app’s project folder in a CLI

You can also view your site contents in PowerShell / Terminal.

  1. From Visual Studio Code’s Explorer window, you should:

You’ll automatically be in the Master Folder directory.

  1. From PowerShell / Terminal, you can ensure the PATH environment variable lists the global npm cachefolder. Type the command: npm –version

  2. The role of the manifest API

The JSS app is a repository structure. In disconnected mode, use the manifest application programming interface (API) to do the following:

To see the list of available manifest objects, see Manifest Objects.

  1. Directory organization

The way you organize a site correlates with your content needs. In disconnected mode, the manifest API creates a manifest of the JSS app’s content. With respect to this content, the manifest does the following:

  1. An app’s main directory elements

There are three types of directory items specific to Sitecore terminology you’ll want to know: arbitrary content, routes, and components. Continue below to look at each one in more detail.

Arbitrary Content:

Routes:

Components:

Create a Route in an App

Routes are important because they are needed to display component content and their data.

  1. Purpose of routes - JSS extends Sitecore’s dynamic, component-based layout model to the frontend. With JSS’s layout model, you create routes so the components can display content.

Compare How Routes Work

NOTE when connecting a JSS app to Sitecore:

* After importing an app to Sitecore, Sitecore then defines the data dynamically. The route data is retrieved using calls to the Sitecore Layout Service—via HTTP or in-process for integrated mode server-side rendering (SSR). SSR is the process of taking a client-side JavaScript framework website and rendering it to HTML and CSS on the server.

* Prior to JSS, Sitecore did not render data. Instead, you added the rendering code to the .cshtml file or the .ascx file. Also before JSS, to define what renderings to add to a placeholder in Sitecore, you needed to set the Allowed Controls on Placeholder Settings in the Sitecore Experience Editor.

  1. What JSS needs to create routes - JSS relies on two features to create routes. They are:
  1. Mock Layout Service - This third topic about understanding routes covers the mock Layout Service. The mock Layout Service emulates the data you would receive from the actual Sitecore Layout Service, while also preparing your JSS app for code-first deployment.

Why It’s Important:

  • The mock Layout Service provides a consistent API to create a complex single-page JSS application that includes components, routes, and custom route types as well as the needed data for each component.
  • The mock Layout Service also provides integration with Sitecore.

Three Notable Factors for the Layout Service Process:

NOTE when connecting a JSS app to Sitecore:

* Currently, there are no tools built into the JSS SDK to retrieve and store Sitecore-connected Layout Service data as files.

* Should you later import your JSS app to Sitecore and no longer need the mock Layout Service that the sample apps use, you can instead save Layout Service data queried from Sitecore in a JSON file.

* Once you have that data locally (i.e., you’re disconnected), you might consider building your own service layer to fetch “raw” Layout Service data from the JSON file(s) you saved.

  1. Routes and templates
  1. Fields on routes vs. components - For our fifth topic, we’ll consider whether to add fields to a route or to a component. To help you decide, you want to consider how the page will be used. For most sites, you will likely want to have different types of pages that include product-specific fields. Each JSS app has one default route template, routes.sitecore.js, which is automatically set as a base template for any route types defined in the app’s manifest.

In general, you want to:

* If you use the same default template and put all data into components, it will be difficult to query these pages.

NOTE when connecting a JSS app to Sitecore:

* For integrated or connected mode, A GraphQL query accesses the page’s field, while a search by fields of components requires looking deep into the nested folder structure.

* The JSS import process will always generate a route template for each app.

JSS extends Sitecore’s dynamic, component-based layout model to the frontend. With the layout model, you create routes so the components can display content. Now, let’s see how we’ll go about actually making routes.

Steps to Create a Route

  1. Add a Route Type

In Visual Studio Code’s Explorer window, browse to where you define/add your routes, \sitecore\definitions\routes.sitecore.js, and then create a routes folder.

In this new route file, use the addRouteType function as seen in the example code below. The addRouteType function is important because:

import { CommonFieldTypes, Manifest } from '@sitecore-jss/sitecore-jss-manifest”;

export default function (manifest) {
    manifest.addRouteType({
    name: 'MyRoute',
    displayName: "My Route",

  fields: [
    {
    name: "description",
    type: CommonFieldTypes, RichText,
    displayName: "My Route",
    required: false
    },
    ]
  });
}
  1. Add a Template Property

Continue in this new route file [Pagename]Route.sitecore.js to add a template property.

Use the example code below, which matches the route name, to tell JSS that a page should use the custom route.

Tip: If you are pulling route data from files, you may want to apply this dynamically, especially if all your routes utilize the same type.

{
    "name": "route",
    "template": "MyRoute",
    "displayName": "MyRoute",
    "placeholders": {
        // ...
    }
}

Inspect JSS App Templates

Now that you have some experience using directories and creating routes, you are ready to inspect how to use an application template for your preferred framework (Angular, React, or Vue).

Step 1: Identify Template Contents

To create an app for your framework with JSS, you need an application template. The application template contains:

Step 2: Examine Role of JSS CLI

  1. First, the JSS CLI creates your app with your framework’s application template, each of which is housed in the Sitecore’s JSS Github repository.

  2. Then, the JSS CLI extracts the template on your file system in the folder with your application’s name, where it installs the package using the package manager, Yarn.

  3. Once the app is created, you can check the Visual Studio Code console to verify the local development server compiled the application successfully at http://localhost:3000.

Step 3: View Sample Site

When the app build is complete, the app’s site automatically opens in a browser to http://localhost:3000. There, you can view the sample site. This site’s homepage includes the following important documentation links:

Determine JSS Content Presentation

Define Component Rendering

In order to determine content presentation, you need to first understand what rendering components is and why it’s important. Rendering JSS components is the same as rendering the components in your framework (e.g. Angular, React, or Vue). You render your built component by adding it to a placeholder on the page using a route. To draw an analogy, a component in React represents a rendering with the same name in Sitecore.

JSS injects the content data from the mock or Sitecore Layout Service to a page. A component in the framework template is a rendering of the JSS component that uses the router library to sync the framework library (e.g. React Router Redux) and allows navigation between pages.

Examine How Rendering Works

Now that you understand what rendering is, you will learn how it works. Rendering is important because it is how you display content in your app like text and images.

1. Learn Layout Service’s process in rendering

As we switch between pages, the router requests the content from a corresponding item (page) in the mock or Sitecore Layout Service. These fields are stored in a database. Then the Layout Service processes the request.

An item is basically just a collection of fields, or an item might also represent a webpage. In a typical Sitecore site, every page is an item, but the reverse is definitely not true.

There are many items that may represent page content but are not necessarily a page themselves. For example, the item might be used as a datasource or a field source, or it might just represent a configuration setting.

2. View Output Data

Next, you will look at an example of a JSON file’s output data to see how content items might be represented.

{
    "context": {
        "pageEditing": false,
        "site": { "name": "MyApplication" },
        "language": "en",
        "currentContact": null
    },
    "name": "Home",
    "displayName": "Home",
    "fields": {
        "Metadata Keywords": {
            "value": "",
            "editable": ""
        },
    }
}

The above includes context data that is common for each of the following:

Here’s another section of a JSON file’s output data:

"placeholders": [
    {
        "name": "Main",
        "path": "Main",
        "elements": [
            {
                "componentName": "serviceScreen",
                "renderingName": "Service Screen",
                "renderingParams": {},
                "uid": "261adcfd-6ca7-4d60-aa37-d92a11c49594",
                "dataSource": "{9F2C1F61-FE87-4BC0-B223-8289A81912C1}",
                "placeholders": [].
                "name": "code",
                "type": "data/json",
                "contents": {
                    "path": "/special service plan",
                    "fields": {
                        "ServiceDiscount": {
                            "value": "0",
                            "editable": "0"
                        }
                    }
                }
            }
        ]
    }
]

The above rendering takes place inside the elements property. Rendering includes:

Download the complete output data file described in the section above

3. Identify How to Render a Component

In the previous procedure, you explored an example of components being rendered in the JSON output file. You learned earlier in this track that you render a component to display its content in your app. Now, in order to render a component, you first you add your component to a page and then you add your content into fields on the component. The JSS SDK provides framework-specific field helpers to render fields so authors can edit them in Sitecore’s Experience Editor after connecting your app to Sitecore.

Render Components

Now that you understand what component rendering is and how it works, you are ready to render components.

1. Register a Component

2. Add a Field to a Component