fs-tpp-api/README.md

FirstSpirit Third-Party-Preview API

# FirstSpirit Omni-Channel-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 OmnichannelManager](https://docs.e-spirit.com/tpp/).

[Learn more about FirstSpirit.](https://www.e-spirit.com)


# API

This module provides the frontend API [`snap`](https://docs.e-spirit.com/tpp/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_).  


We also support an older version of the API ([`fs-tpp-api`](https://docs.e-spirit.com/tpp/api/)). Be
aware that we add new features to the `snap` api only.

The demo application is based on the _snap API_. 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](https://docs.e-spirit.com/tpp/snap/). If you have to stick to
an older version the matching version of the documentation is included in the deliverables you obtained from our 
technical support team.


## Release Notes

See here: [Release Notes](https://docs.e-spirit.com/tpp/releasenotes/).

## 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 `snap`API so that it can be accessed from the browser
console to ease trouble shooting.

### snap.js
Include the `snap.js` somewhere in your markup.

#### CDN (browser, recommended)
```
<script src="https://cdn.jsdelivr.net/npm/fs-tpp-api@VERSION/snap.js"></script>
```

Please replace `VERSION` in the above url with the correct module version (see above), e.g. 
`https://cdn.jsdelivr.net/npm/fs-tpp-api@1.2.21/snap.js`.
You can also use a tag name after the `@` (you can find a list of valid tags at the
[npm package site](https://www.npmjs.com/package/fs-tpp-api?activeTab=versions)). 
See https://cdn.jsdelivr.net for a full documentation of the url format. 

#### NPM (server-side builds)
```
# install
npm i fs-tpp-api@VERSION -s

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

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

Usage example:

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

### Preview content notation
Use the `data-preview-id` attribute on DOM nodes providing the FirstSpirit preview contents. The _PreviewId_ is provided
in the template code as [`$CMS_VALUE(previewId())$`](https://docs.e-spirit.com/tpp/#vorlagen-code).


### IFrame handling
*...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](https://developer.mozilla.org/docs/Web/API/Window/postMessage).   
 

### DOM handling
*...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](https://developer.mozilla.org/de/docs/Web/API/MutationObserver) is also used.


### Browser support

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