fs-tpp-api/README.md

FirstSpirit Third-Party-Preview API

# FirstSpirit Third-Party-Preview API

Enable editing of FirstSpirit content in a third party app.

Integrate Single-Page-Applications in FirstSpirit ContentCreator.

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 two alternative APIs, [``snap``](https://docs.e-spirit.com/tpp/snap/) and [``fs-tpp-api``](https://docs.e-spirit.com/tpp/api/).
The first is a rewrite of the latter, informed by
experience we gained with our customers and partners during the ramp up phase. We will support the older API
for some time to save the investments of our customers and partners. Be aware that at some point we may decide to
add features to the ``snap`` api only.

The demo application we deliver together with the backend module since v1.2 is based solely on the _snap API_.

There is a third API which can be used to fetch content from the CaaS backend.

## API Documentation
* [snap](https://docs.e-spirit.com/tpp/snap/)
* [fs-tpp-api](https://docs.e-spirit.com/tpp/fs-tpp-api/) (legacy)

## Release Notes

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

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

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

#### via CDN (browser, recommended)
```
<script src="https://unpkg.com/fs-tpp-api@VERSION/snap.js"></script>
```

Please replace `VERSION` in the above url with the correct module version (see above), e.g. 
`https://unpkg.com/fs-tpp-api@1.2.15/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://unpkg.com for a full documentation of the url format. 

#### via 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.

Usage:

```
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 TPP 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 TPP affect the DOM tree?*

TPP adds UI elements to your DOM tree.
This is done by appending DIV nodes as children of ```document.body```.
TPP also listens 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`)