Walkthrough: Client-side embedding JSS applications in MVC sites

Version: 19.x

Client-side embedding of a JSS app is a technique that lets you run a JSS app in a regular Sitecore rendering. This technique essentially embeds the JSS app's markup and app wrapper tag within a regular MVC Sitecore rendering.

Client-side embedding does not render the JSS app on the server. This is an advantage in terms of simplicity (and Node.js is not required to be installed), but a disadvantage in terms of SEO compatibility and app startup time.

Client-side embedding is a good technique to use for micro-applications and tools, such as product configurators, financial calculators, multistep forms, e-commerce functionality (cart, checkout), and so on.

Characteristics of such apps include:

  • They are embedded in an existing/larger site.

  • SEO is not typically crucial for the app itself.

  • UX is often a multistep/sequential process.

  • They often have a complicated UX that benefits from modern JavaScript frameworks.

You can use the Embedded Wizard sample app if you do not want to build your entire site using JSS, but instead want to use tools, wizards, or calculators that have complicated UX and/or are primarily front-end driven.

The client.js file in the Embedded Wizard sample app uses react-dom to render the app on a page element with the wizard-app ID. The EmbeddedWizard.ascx sublayout adds a div with the wizard-app ID to the page and adds the needed scripts and styles to the page. In an MVC implementation, this could easily become a View Rendering.

In your implementation, if you do not want to globally include the scripts and styles for your JSS app(s), use a mechanism to include them dynamically based on the presence of the rendering, such as the Assets module in Sitecore Habitat. This approach is described in the Helix design priciples.

If you have a lot of apps and want to provide control to a content author, you can create your own registry of apps (with their DOM IDs) and allow the content author to choose which app to embed.

The Wizard component in the sample app uses a StepReference component so you can manage steps through a Sitecore editor, but then when rendering for the front end, it uses the component data to construct the step. Each step in the wizard is a separate JSS route for easier management/editing in a Sitecore editor. The Step component loads the referenced route from the Layout Service as each step is displayed. Each step registers in analytics as it is displayed. The Step component uses the same placeholder name as the App component, so that step contents can be rendered directly in the App.

Before starting this walkthrough, you must have access to a Sitecore instance with Sitecore Headless Services and install the JSS CLI globally.

This walkthrough describes how to:

  • Create the JSS app and deploy it to Sitecore

  • Configure wizard placement

  • Verify the configuration of the wizard

Create the JSS app and deploy it to Sitecore

The first step is to create a JSS application based on the Embedded Wizard sample application and connect it to Sitecore.

To create the app:

  1. In a terminal, run the following command:

    RequestResponse
    jss create embedded-wizard sitecore-embedded-jss-app

    The script copies the sample files locally and installs all dependencies.

  2. Using the terminal, navigate to the source directory for the embedded-jss app:

    RequestResponse
    cd embedded-wizard

  3. This app is designed to run on the out-of-the-box Sitecore website site and the sample Home page. Connect the application to your Sitecore instance, using the default hostname for your Sitecore instance.

  4. Verify that the app has deployed correctly by opening the Sitecore Content Editor and checking that the app is available in the content tree at /sitecore/content/Home/EmbeddedWizard:

    The Embedded Wizard app in the Sitecore content tree

  5. Verify that the app runs independently in integrated mode by browsing to http://[sitecorehost]/EmbeddedWizard/Wizard.

    Successful rendering of the Embedded Wizard app in the browser

Configure wizard placement

With the application deployed to Sitecore, you can proceed to configure the placement of the wizard.

To configure the necessary items and renderings:

  1. Deploy the included sublayout that can be used to embed the app from embedded-wizard/sitecore/rendering/EmbeddedWizard.ascx to the Website/layouts folder of the Sitecore instance. In a terminal, run the following script:

    RequestResponse
    jss deploy-rendering
    Note

    The deploy-rendering script is defined in the package.json file of the application.

  2. In Sitecore, create a new sublayout under /sitecore/layout/Sublayouts.

  3. Change the Ascx file field value for the sublayout to /layouts/EmbeddedWizard.ascx.

  4. On the /sitecore/content/Home item, on the ribbon, on the Presentation tab, in the Layout group, click Details, and in the Layout Details dialog, edit the default layout.

  5. Click Sample Rendering, Change. Select the sublayout you just created, then click OK.

Verify the configuration of the wizard

To verify that you have configured the embedded wizard correctly:

  1. Log out of Sitecore or open a private browser window.

  2. Navigate to your Sitecore instance's home page. You should see the app embedded on the home page.

    The Embedded Wizard on the Home page

Do you have some feedback for us?

If you have suggestions for improving this article,