Embedded applications

There are many situations in which you may prefer to use an application rather than a part.

It is a useful way to bridge the gap between editorial pages and applications. For instance, you may include the first step of the webshop flow on a product page or add a contact form directly onto the customer service page.

Apps that are embedded in Content Studio

• need to contain end-points or other functionalities that don't apply across teams
• work for your purpose only, and don't need to be shared with others
• do not contain editorial functionality in Content Studio
• are developed and maintained by your team (you build it, you run it)

If you're unsure whether any particular issue is best solved by a custom part or a shared part, please get in touch with us.

Your team's React application may be implemented among regular parts on any page in Content Studio by using either the App Loader part or The Form Loader part.

App loader

The App Loader requires an URL to the asset-manifest.json file of the React application and uses this to extract the js and css needed to render the app. The asset-manifest.json file can be generated by Webpack using webpack-manifest-plugin. 

See an example from the Swedish webshop

The part that loads your app needs three things:

1. The URL to an assets-manifest.json file that is hosted on our CDN. The JSON file must specify an object that contains two arrays of URLs to all assets – files and entrypoints. These must be uploaded to the CDN along with the manifest.
2. The class which the app mounts its DOM on. Use a unique class name (not "container" or "form"), as this is used to fetch the correct app.
3. Keys (optional), so that the editor may change the texts using a key/value input field.

Additional data (key-values)

You can add key-value pairs by using the additional data in the App loader part. These key-value pairs can be requested from the URL in the data-url attribute on the App loaders wrapping div (where the class="your-app-class" is rendered in the DOM). You will receive the data as json.

1. The application is designed
2. The React application is created with a manifest file hosted on Builders CDN
3. An editor inserts an App Loader part, which fetches the React applications through a JSON file's URL and its unique class name.

Design

Before you build something new, consider whether something existing could fill the need – either an app or a part. Maybe it could work with an improvement that would benefit others too?

When building from scratch, use Core components as much as possible – it will shorten time to market considerably. 

Most updates will need development, so see if you can do anything to keep the part "low-maintenance" with basic content that won't necessarily need changes with time.

• Parts in the CMS are always full width (but you may of course use the grid to divide content)
• As it will take up the whole width of the screen, your app should not take up too much vertical space
• Consider whether you should combine your new functionality with others to save space: Could your webshop entry be combined with a H1 header?

Develop

Create a manifest file that is hosted on our CDN.

Vite

If you use a Vite app, you need to apply the following in your vite.config file: 

build: {

   manifest: true

}

This will make the build generate a file called manifest.json. Use the App Loader part in XP to add your Custom Part built with Vite to a page, and provide the link to the build folder in CDN and the id for the app to mount on.

Create React App

CRA will by default generate a asset-manfiest.json file in the build folder.

The JSON file must specify an object that contains two arrays of URLs to all assets – files and entry points. These must be uploaded to the CDN along with the manifest.

The class which the app mounts its DOM on must have a unique class name (not "container" or "form"), as this is used to fetch the correct app.

The editors need the manifest URL, the class name and keys that allow them to change texts using key/value inputs.

If you want to use a webpack app that is not CRA or VIte, read about generating manifest file here: builders platform documentation

If editors should be able to edit texts in the app, consider using keys and values in Content Studio.

Implement in Content Studio

Insert a new part to the page, and choose App loader. Insert the manifest URL and class name provided by the developer. If you wish to update the texts in the app later, you may add keys and values.

When adding forms to your page, you may select the Form loader instead. This allows you to display any form on any page.