This is a technique to allow a JSS app to run within a traditional Sitecore rendering. Doing this allows embedding a JSS app within an existing Sitecore MVC site, as opposed to as its own standalone site. This technique essentially embeds the JSS app's markup and app wrapper tag within a Sitecore rendering.
Client-side embedding is a good technique to use for micro-applications and tools.
Examples of such tools might be:
- Product configurators
- Financial calculators
- Signup or other multi-step forms
- E-commerce functionality (cart, checkout)
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 multi-step / sequential process
The Embedded Wizard Sample
The Embedded Wizard sample app was created based on community feedback about common use cases for JSS. You may not wish to build your entire site using JSS -- rather just particular tools, wizards, calculators, etc. which have complicated UX and/or are primarily frontend-driven.
Running the Sample
Step 1. Build and deploy the app
- Ensure you have already installed the JSS server packages and configured it.
- The The Embedded Wizard sample app is downloaded locally in a directory.
cmdinside the directory with the sample app.
npm installto install all required packages.
jss setupto configure the path and URL to your Sitecore instance. > This app is designed to run on the out-of-the-box Sitecore
websitesite and sample page, so the default hostname for your Sitecore instance will work here.
jss deploy configto deploy the included app configuration.
Alternatively, you can manually copy
sitecore\configto your Sitecore instance's
This will also put the
websitesite into Live Mode.
Deploy the app to Sitecore with
jss deploy app --includeContent --includeDictionary(or shortcut
jss deploy app -c -d).
Open the Sitecore Content Editor and ensure the app has installed at
Browse to http://[sitecorehost]/EmbeddedWizard/Wizard and ensure the app runs independently in Integrated Mode:
Step 2. Configure wizard placement
Option 1: Install a package
Fastest option. This package contains the rendering items, Sublayout and modified Home item.
Recommended if you are installing on a vanilla Sitecore instance. If you would like to learn how the item configuration is put together, use Option 2 below.
Download the Sample package.
Install it via Sitecore Installation Wizard.
The package overwrites the existing Home item. Select Merge/Clear when prompted. Selecting Overwrite will delete the previously deployed app under
If you have changed the default Home item, do not overwrite and follow Option 2 below instead.
Proceed to the Verification step below.
Option 2: Configure items and hosting rendering manually.
jss deploy-renderingto deploy the included Sublayout that can be used to embed the app. > The Sublayout source file will be copied from
sitecore-embedded-jss-app/sitecore/rendering/EmbeddedWizard.ascxto your Sitecore instance
- In Sitecore, create a new Sublayout under
- Give it whatever name you like
- Tell Sitecore to create the file under
/tempor another location
- After creating the Sublayout, change the
Ascx filevalue to
- On the out-of-the-box
/sitecore/content/Homeitem, open the Layout Details from the Presentation ribbon and Edit the Default layout.
- Click on the Sample Rendering and then Change. Select the Sublayout you just created, then click OK.
- Proceed to the Verification step below.
Note: this technique works equally well with Sitecore MVC. This example uses Web Forms only for easy compatibility with the default Sitecore site.
Log out of Sitecore or open a private browser window.
Navigate to your Sitecore instance's home page.
You should see the app embedded in the Sitecore sample home.
How it Works
client.jsof the app uses
react-domto render the app on a page element with the id
EmbeddedWizard.ascxSublayout simply adds a
divwith that 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.
- If you have a lot of apps and want to provide control to a content author, you could create your own "registry" of apps (with their DOM id's) and allow the content author to choose which app to embed.
- In your implementation, if you don't want to globally include the scripts and styles for your JSS app(s), you'll want to use some mechanism to include them dynamically based on presence of the rendering, such as the Assets module in Sitecore Habitat. This approach is described in the Helix design priciples.
- The sample uses the
react-stepzillamodule to provide a step-based UX.
- Each step is a separate JSS route to provide for easier management/editing via the Experience Editor.
Wizardcomponent "creatively" uses a
StepReferencecomponent to allow steps to be managed via the Experience Editor, but then when rendering for the front-end, uses the component data to construct the step data expected by
Stepcomponent loads the referenced route from the Layout Service as each step is displayed.
- This means that each step will register in analytics as it is displayed as well.
Stepuses the same placeholder name as
App, so that step contents can be rendered directly in the
Appas well (i.e. in the Experience Editor).
Things you can try
- Add new questions to steps via the Experience Editor.
- Insert a new step, add some questions to it, and then add step reference to the main Wizard route.