FirstSpirit Omnichannel Manager API

This library enables the use of FirstSpirit editorial functions in any frontend application like
Single Page Applications and Progressive Web Apps.

This API is built to be used with the FirstSpirit Omnichannel Manager (short: OCM).

Learn more about FirstSpirit.

API

This module provides the frontend API snap since v1.2 onwards.
To get a better idea how things work together see the documentation links above and refer to our demo application
(_Snap Shop_).

The demo application includes a readme which describes how to set it up
and how the development process works. There is another API for fetching content from the CaaS backend which is also
included in the demo application (caas.js, see also below).

API Documentation

There is an online version of the API documentation. If you have to stick to
an older version you find the matching version of the documentation in the deliverables you obtained from our
technical support team.

Release Notes

See here: Release Notes.

Usage in your application

Determine the version of the OCM module in your FirstSpirit setup. Always include the exact matching version in
your frontend. We do not recommend using LATEST as version identifier.

At least for development time it is recommended to expose the snapAPI so that it can be accessed from the browser
console to ease trouble shooting.

$3

Include the snap.js somewhere in your markup.

#### CDN (browser, recommended)
``

`

Please replace VERSION in the above url with the correct module version (see above), e.g.
https://cdnjs.cloudflare.com/ajax/libs/fs-tpp-api/2.1.1/snap.js.
You can also use a tag name after the @ (you can find a list of valid tags at the
npm package site).
See https://cdnjs.com/api for a full documentation of the url format.

This is just an example, you may use other CDNs.

#### NPM (server-side builds)
`


install

npm i fs-tpp-api@VERSION -s

further usage

const TPP_SNAP = require('fs-tpp-api/snap');
`

$3

In the editorial mode it is mandantory to initialize the API by registering a callback to the
onInit handler. In the callback code you should at least
register handlers for these two callbacks:

0. onRerenderView - called every time the (changed)
editorial content has to be rendered.
0. onRequestPreviewElement - called every time
the routing of the application has to adapt to a request from the editorial ui (aka ContentCreator), e.g. when a search
result entry has been clicked.

$3


Use the data-preview-id attribute on DOM nodes providing the FirstSpirit preview contents.
Set the attribute value to the identifier attribute provided in the standard FirstSpirit JSON. If the JSON is crafted
manually you can create the value in your template code using the
previewId template function:
`
$CMS_VALUE(previewId())$
`

$3

...or how does OCM integrate with the FirstSpirit ContentCreator?

In the ContentCreator the third party app is embedded in an iframe. The script is also part of the third party app.
It communicates with the ContentCreator by means of
window.postMessage.

$3

...or how does OCM affect the DOM tree?

The implementation adds UI elements to your DOM tree.
This is done by appending DIV nodes as children of `document.body`.
We also listen to mouse events fired on annotated elements.
A MutationObserver is also used.




$3


Include caas.js from the demo project in your markup to simplfy reading editorial content from the CAAS backend in
your application.

Usage example:

`
const options = {
host: "example.com"
apikey: "my-apikey"
project: "myCaasProject"
}
let response = await caas.get(options, "tutorials")
let data = response.data
`

$3

We support the following browsers:
* Chrome >= 59
* Firefox >= 61
* Edge >= 15
* Safari >= 10.1
* IE 11 (please import snap.ie11.js`)