Component Builder javascript Clientside

This module renders the component and populates it with data. It also supports efficient update of component for the new data.

What does it do?

• Renders component content and returns React/DOM element
• Populates attributes and text valeus with mapped data
• Repeats nodes mapped to collections
• Updates previously rendered component for new data
• Provides both react and javascript revisions of Clientside
• (optional) Fetches of component from the cloud

What does it NOT do?

• Does not fetch the data: It needs to be explicitly given as data attribute.
• Does not offer any event listening helpers: We recommend using bubbling events instead

Usage

React:

    import * as FEAAS '@sitecore-feaas/clientside';

    // provide html template directly
    <feaas-component template={`<p>Hello <var data-path="user.name" /></p>`} data={JSON.stringify({user: {name: "World"})}} />

    // fetch component from the cloud
    <feaas-component component="..." version="..." revision="production" cdn="..." data={JSON.stringify({user: {name: "World"}})} />

JS Dom

import * as FEAAS from '@sitecore-feaas/clientside'
// or <script src="//feaas-components.sitecore.cloud/clientside/latest.min.js"></script>
// will define FEAASComponent global variable

// Fetch component from the cloud, returns element immediately
// Use FEAAS.renderComponentPromise to await for fetch request
// Optionally accepts 2nd argument, element to render to
const element = FEAAS.renderComponent({
  library: '...',
  component: '...',
  version: '...',
  revision: 'production',
  cdn: '...',
  data: { user: { name: 'World' } }
})

// inject element into DOM
// will be empty until content is fetched, but will automatically re-render
document.body.appendChild(element)

// update element with new data
FEAAS.renderComponent(
  {
    data: { user: { name: 'Universe' } }
  },
  element
)

// ALTERNATIVELY: provide html template directly
const element = FEAAS.renderComponent(
  {
    template: `<p>Hello <var data-path="user.name" /></p>`,
    data: { user: { name: 'World' } }
  }
  //, element // optionally provide target element here a
)

// inject element into DOM
document.body.appendChild(element)

// update data in the element
FEAAS.renderComponent(
  {
    data: { user: { name: 'Universe' } }
  },
  element
)

Fetching styles

Components use styele guide, a stylesheet shared per tenant. In short, it has to be included on the page. Stylesheets are cached with immutable Cache-Control, meaning that the browser will never attempt to re-fetch them if it was cached once. That ensures the fastest rendering time on final website. The small price to pay is to use Clientside on the page, that will invalidate the stylesheet automatically.

Recommended: Linking stylesheet in HTML

Placing stylesheet into HTML is benefitial to get the fasted loading speed. This allow browser to start fetching the css before it has finished loading, parsing and executing js.

<!-- Use id=`feaas-stylesheet` for Clientside to deal with invalidation -->
<link rel='stylesheet' id='feaas-stylesheet' href='https://components.sitecore.cloud/styles/:tenant_id/published.css' />
<!-- Include Clientside on the page OR as npm import inside your own code  -->
<script src="//feaas-components.sitecore.cloud/clientside/latest.min.js"></script>

Linking stylesheet in Clientside app

Loading styles from javascript is as simple as calling loadStyles function. It is safe to use this method together with HTML inclusion, the stylesheet will not be loaded twice.

import * as FEAAS from '@sitecore-feaas/clientside'

// Load stylesheet (will automatically add it )
<feaas-stylesheet='library_id'></feaas-stylesheet>

Entrypoints

There are three different entrypoints for clientside: UI, React and Headless 1. The main entrypoint @sitecore-feaas/clientside targets the UI package which references frontend from components monorepo. This includes both the core functionality and some ui components like the pickers and the embedded editor 2. The @sitecore-feaas/clientside/react entrypoint targets the React package which is similar to the main entrypoint but also includes some components that use React as a dependency like external react components. 3. The @sitecore-feaas/clientside/headless entrypoint targets the Headless package which includes just the core functionality of clientside without any dependencies on frontend or react.

NOTE 1: React library is not included in any clientside package, we assume that it is already installed in the container that uses the @sitecore-feaas/clientside/react entrypoint. We mark React library as external in scripts/build.js

NOTE 2: UI has its own tsconfig that includes references to both /frontend and /clientside. Clientside main tsconfig excludes /ui avoiding circular imports

Bring your own code components

You can use Components clientside SDK to register and render your own code components to your FEAAS components. Registration steps:

• Install and import the Components React SDK to your App

npm install @sitecore-feaas/clientside

import * as FEAAS from "@sitecore-feaas/clientside/react"

• Register your component via

registerComponent(component, options)

component is the actual react component, options (optional) is a JSON Schema representation of your component options containing the components props and other options. If not provided, the component will be registered as a prop-less component. An example of schema is provided below:

const options = {
  name: 'My example component',
  description: 'Description of my example component',
  required: ['firstName'],
  thumbnail: 'https://mss-p-006-delivery.stylelabs.cloud/api/public/content/3997aaa0d8be4eb789f3b1541bd95c58',
  group: 'Examples',
  properties: {
    firstName: {
      type: 'string',
      title: 'First name',
      required: true
    },
    lastName: {
      type: 'string',
      title: 'Last name'
    },
    telephone: {
      type: 'string',
      title: 'Telephone',
      minLength: 10
    }
  }
}

Options may contain any of the bellow items:

Name
Type: string
Required: no
Description: Name of your Component as it will be shown to the user. If not provided, will be function name in title case.

Description
Type: string
Required: no
Description: Describe your Component and anything a user should know when using it.

Thumbnail
Type: url
Required: no
Description: A URL of a thumbnail image to be displayed in the Builder. Should have some dimension guidelines.

Group
Type: string
Required: no
Description: Used to group related Components together in the UI. E.g. Typography

Properties
Type: JSONSchema object
Required: no
Description: Inputs (Props) to be provided by the user when embedding this Component.

Required
Type: String Array
Required: no
Description: Array of keys from Inputs (Props) that should be required

We use React JSONSchema Form to generate a form for the component properties. You can read more about React JSONSchema Form here: https://react-jsonschema-form.readthedocs.io