1. Wrapping code in a component

Wrap a web component in a Sitecore component

There are two ways to wrap a web component in a Sitecore component: 

  • A single-use web component can be created directly in the builder by loading a publicly hosted JavaScript file defining and powering the web component directly into the builder.

    Single-use web components are automatically rendered in the Component builder preview. Also, several web components on the same canvas that use the same source will load the source only once.

  • Reusable web components can be defined in the rendering host, using the registerComponent function call in your code.

    The benefit of this approach is that the web component will be available both in the page builder and Components as any other component with its own thumbnail. As a part of registerComponent flow, it is possible to define in the code of the component a property schema that will become available as configuration settings in the right hand pane of the page builder. This gives content author and marketers an easy-to-use UI to configure the component once it is inserted in a webpage.

Add a single-use web component

To create a web component: 

  1. In the Component builder, open the component you want to add a web component to.

  2. Click the element where you want to add the single-use web component.

  3. At the bottom of the right-hand pane, click Create web component.

  4. In the Web component dialog, enter the name of this component.

  5. In the JavaScript source URL field, enter the URL for the JavaScript source.

    Note

    The file needs to be publicly accessible, so it can be loaded into the builder.

    We recommend that this file only contains the necessary code to power the web component.

    This code needs to include a call to define the web component using the HTML5 standard, using customElements. For example: customElements.define("my-custom-element", MyCustomElement);. In this case the name of a component is my-custom-element, so this is what you need to put into the component name field.

  6. Click Create.

The web component will initialize and display in the builder. The content generated by the component is not accessible for direct editing or manipulation. If the component does not use shadow DOM (document object model that scopes CSS styles to a specific DOM subtree and isolates that subtree from the rest of the document), the content of the web component inherits the styles provided by Style Guides.

Add a reusable web component

After registering an external web component, you can add it to the Component builder canvas as you do when adding other components.

To add a reusable web component inside a Sitecore component:

  1. In the Component builder, open a component or create a new one.

  2. There are two ways to add a web component inside your component:

    • If you're adding the web component to the entire section, click anywhere in the component area to display the context toolbar. Then, click Add element.

    • If you want to draw a specific container, click and drag to create a container, then click the container. In the context toolbar, click Add element.

  3. Click the Component element and in the context toolbar, click Append inside the element.

  4. On the right-hand side, click the web component you previously registered. You can find it in the collection that was defined in the code by the group parameter. If you have not already defined a collection for your web component, you can find it in the Default collection.

  5. Optionally, click Attributes in the right-hand pane to configure attributes in JSON format for your instance of the web component.

  6. You won't be able to see a visual preview of the component in the canvas components, nor in Pages; however, you can open a preview of the component with all its element and layout in a separate browser tab by clicking Preview external components.

If you have suggestions for improving this article, let us know!