@sitecore-feaas/sdk v0.3.5

FEAAS SDK

SDK is a set of tools that are used to access libraries of components, and their stylesheet. Components app uses this SDK to power its frontend and backend apps, so everything that is possible to do in the app can be done programmatically in the script as well.

Initializing SDK

SDK is loaded from a module. It is then instantiated with options:

import { SDK, Style } from '@sitecore-feaas/sdk'

const sdk = new SDK({
  // API key to access the library (can be found in Library settings in web app)
  apiKey: 'my-api-key',

  // enable logging
  verbose: true,

  // Optional: Configuring the non-production environment
  backend: 'https://components.sitecloud.io/api',
  frontend: 'https://components.sitecloud.io',
  cdn: `https://feaas.blob.core.windows.net`
})

Loading library resources

// Optional: Set XM Cloud tenant context to sync datasources with
sdk.auth.tenant = tenant

// Access library
const library = await sdk.libraries.get({ id: 'my-library' })

// Fetch all dependent resources (components, stylesheets, datasources)
// Everything EXCLUDING component versions
await library.fetchAll()

// Can access components now:
for (const collection of library.collections) {
  console.log('- Collection', collection.name)
  for (const component of collection.components) {
    console.log('  |- Component', component.name)

    // Fetch versions on demand
    for (const version of await component.versions.fetch()) {
      console.log('    |- Version: ', version.name)
    }
  }
}

// Datasources (`sdk.datasources` is `library.datasources` combined with `tenant.datasources` )
if (sdk.auth.tenant) {
  for (const datasource of sdk.auth.tenant.datasources) {
    console.log('- Tenant datasource', datasource.name)
  }
}

for (const datasource of library.datasources) {
  console.log('- Custom datasource', datasource.name)
}

for (const rule of library.stylesheet.rules) {
  if (rule.type == 'theme') console.log('- Theme', rule.details.title)
}

Rendering thumbnail

Thumbnails are generated on demand and put on CDN. Thumbnail methods will try to fetch the image file from cdn, and if it's detected to be outdated, it will be regenerated/refetched in background. Thumbnails are rendered by @sitecore-feaas/clientside package.

import { Thumbnail } from '@sitecore-feaas/clientside'

// 1. Recommended: Using callback, will show cached version while revalidating cache
Thumbnail.get(component, version, (img, isCached) => {
  // img is a loaded HTMLImageElement, use it directly or access its `src`, `width`, `height` properties.
  document.body.appendChild(img)
})

// 2. Not recommended: Using promise will only resolve with up to date image;
const image = await Thumbnail.get(component, version)
document.body.appendChild(image)

Embedding components

Here's an example that embeds all components onto a html page:

// Ensure that components are loaded
await library.get()
await library.fetchAll()

// Include clientside code that powers web components
import '@sitecore-feaas/clientside'

for (const collection of library.collections) {
  console.log('- Collection', collection.name)
  for (const component of collection.components) {
    const element = document.createElement('feaas-component')
    element.setAttribute('src', component.getSourceURL())
    document.appendChild(element)
    console.log('  |- Component', component.name)
  }
}

Getting instance of SDK

SDK is instantiated by <feaas-context /> from clientside on pages that use it. It's possible to access the instance of SDK by listening to event or subscribing to promise. The

// Event will fire after library is loaded and initialized
document.addEventListener('feaasReady', (e : CustomEvent<SDK>) => {
  sdk.library // has all data ready
  ...
})

or

const feaasContext = document.querySelector('feaas-context')
feaasContext.whenSDKReady.then((sdk) => {
  sdk.library // has all data ready
})

CLI Utility

SDK provides a CLI utility that allows exporting and importing component libraries, including stylesheets and datasources creation. This can be useful to:

• clone libraries between existing XM projects
• serialize them into a file for automatic provisioning of a project, for testing and demo purposes
• moving libraries between XM ecosystem environments (beta to production)

Serializing library into JSON

To export a library, you'd need its API key that can be found on Settings page of the Components application.

# Ensure SDK is installed. Use -g if you want it in a global scope
$ npm install @sitecore-feaas/sdk

# Output possible CLI options for export command
$  npx feaas export --help
Usage: feaas export [options] <libraryId> <apiKey>

Export a library in to JSON

Options:
  --entities [types...]    Only export specific type (choices: "datasources", "stylesheets",
                           "collections", default: true)
  -s, --silent             Dont output logs
  -h, --hostname  [value]  Components API hostname (default: "https://components.sitecorecloud.io")
  -o, --output <value>     Output file
  --help                   display help for command

# Export library to `my-library-id.json` in current directory
$ npx feaas export library <library-id> <api-key>

By default export command will serialize the whole library, including components, stylesheets and datasources (can be altered using --entities) option. The output file by default is <library-id>.json (can be altered with --output) option. During exporting, the logs will be output into stdout (can be disabled with --silent). The utility may connect to non-production instances of Components when --hostname option is used (E.g. use --hostname https://components-beta.sitecorecloud.io for pre-production)

Loading contents of a library from JSON

Importing library contents from JSON file can be done with feaas import command. It will read specified file, and create entities in a library of choice. You would need to have API key of the target library for this to work.

# Output possible CLI options for import command
$ npx feaas import --help
Usage: feaas import [options] <path> [libraryId] [apiKey]

Import serialized JSON file in to a library

Arguments:
  path                     Path to JSON file containing serialize library
  libraryId                ID of a library to copy to (defaults to ID in JSON file)
  apiKey                   API key for the target library (defaults to API key in JSON file)

Options:
  -s, --silent             Dont output logs
  -h, --hostname  [value]  Components API hostname (default: "https://components.sitecorecloud.io")
  --entities [types...]    Only import specific type (choices: "datasources", "stylesheets",
                           "collections", default: true)
  --help                   display help for command

# Import library `filename.json` into librari with id `my-library-id` using `api-key`
$ npx feaas import library <filename> <my-library-id> <api-key>

By default import will attempt to restore all contents from JSON file, including collections, components, stylesheets and datasources (can be specified using --entities). The input file is is the only required option. Target library with its api key can be specified as 2nd and 3d parameters. Otherwise the utility will attempt to restore to the library that the JSON was exported from. Similarily, import can be done to a library that already has contents. The current behavior is:

• Components/Collections/Datasources that were in the target library, but not in exported library will not be altered or removed.
• Stylesheet of a target library will be overwritten by the stylesheets from JSON on each import
• Components/Collections will be created first time import is ran, will not be overwritten on re-runs (possibly a subject to change)
• Datasources will be overwriten if they were imported previously