1 | # FirstSpirit Omni-Channel-Manager API
|
2 |
|
3 | This library enables the use of FirstSpirit editorial functions in any frontend application like
|
4 | Single Page Applications and Progressive Web Apps.
|
5 |
|
6 | This API is built to be used with the [FirstSpirit OmnichannelManager](https://docs.e-spirit.com/tpp/).
|
7 |
|
8 | [Learn more about FirstSpirit.](https://www.e-spirit.com)
|
9 |
|
10 |
|
11 | # API
|
12 |
|
13 | This module provides the frontend API [`snap`](https://docs.e-spirit.com/tpp/snap/) since v1.2 onwards.
|
14 | To get a better idea how things work together see the documentation links above and refer to our demo application
|
15 | (_Snap Shop_).
|
16 |
|
17 |
|
18 | We also support an older version of the API ([`fs-tpp-api`](https://docs.e-spirit.com/tpp/api/)). Be
|
19 | aware that we add new features to the `snap` api only.
|
20 |
|
21 | The demo application is based on the _snap API_. The demo application includes a readme which describes how to set it up
|
22 | and how the development process works. There is another API for fetching content from the CaaS backend which is also
|
23 | included in the demo application (`caas.js`, see also below).
|
24 |
|
25 | ## API Documentation
|
26 | There is an [online version of the API documentation](https://docs.e-spirit.com/tpp/snap/). If you have to stick to
|
27 | an older version the matching version of the documentation is included in the deliverables you obtained from our
|
28 | technical support team.
|
29 |
|
30 |
|
31 | ## Release Notes
|
32 |
|
33 | See here: [Release Notes](https://docs.e-spirit.com/tpp/releasenotes/).
|
34 |
|
35 | ## Usage in your application
|
36 | Determine the version of the OCM module in your FirstSpirit setup. Always include the exact matching version in
|
37 | your frontend. We do not recommend using LATEST as version identifier.
|
38 |
|
39 | At least for development time it is recommended to expose the `snap`API so that it can be accessed from the browser
|
40 | console to ease trouble shooting.
|
41 |
|
42 | ### snap.js
|
43 | Include the `snap.js` somewhere in your markup.
|
44 |
|
45 | #### CDN (browser, recommended)
|
46 | ```
|
47 | <script src="https://cdn.jsdelivr.net/npm/fs-tpp-api@VERSION/snap.js"></script>
|
48 | ```
|
49 |
|
50 | Please replace `VERSION` in the above url with the correct module version (see above), e.g.
|
51 | `https://cdn.jsdelivr.net/npm/fs-tpp-api@1.2.21/snap.js`.
|
52 | You can also use a tag name after the `@` (you can find a list of valid tags at the
|
53 | [npm package site](https://www.npmjs.com/package/fs-tpp-api?activeTab=versions)).
|
54 | See https://cdn.jsdelivr.net for a full documentation of the url format.
|
55 |
|
56 | #### NPM (server-side builds)
|
57 | ```
|
58 | # install
|
59 | npm i fs-tpp-api@VERSION -s
|
60 |
|
61 | # further usage
|
62 | const TPP_SNAP = require('fs-tpp-api/snap');
|
63 | ```
|
64 |
|
65 | ### caas.js
|
66 | Include `caas.js` from the demo project in your markup to simplfy reading editorial content from your application.
|
67 |
|
68 | Usage example:
|
69 |
|
70 | ```
|
71 | const options = {
|
72 | host: "example.com"
|
73 | apikey: "my-first-apikey"
|
74 | project: "myCaasProject"
|
75 | }
|
76 | let response = await caas.get(options, "tutorials")
|
77 | let data = response.data
|
78 | ```
|
79 |
|
80 | ### Preview content notation
|
81 | Use the `data-preview-id` attribute on DOM nodes providing the FirstSpirit preview contents. The _PreviewId_ is provided
|
82 | in the template code as [`$CMS_VALUE(previewId())$`](https://docs.e-spirit.com/tpp/#vorlagen-code).
|
83 |
|
84 |
|
85 | ### IFrame handling
|
86 | *...or how does OCM integrate with the FirstSpirit ContentCreator?*
|
87 |
|
88 | In the ContentCreator the third party app is embedded in an iframe. The script is also part of the third party app.
|
89 | It communicates with the ContentCreator by means of
|
90 | [window.postMessage](https://developer.mozilla.org/docs/Web/API/Window/postMessage).
|
91 |
|
92 |
|
93 | ### DOM handling
|
94 | *...or how does OCM affect the DOM tree?*
|
95 |
|
96 | The implementation adds UI elements to your DOM tree.
|
97 | This is done by appending DIV nodes as children of ```document.body```.
|
98 | We also listen to mouse events fired on annotated elements.
|
99 | A [MutationObserver](https://developer.mozilla.org/de/docs/Web/API/MutationObserver) is also used.
|
100 |
|
101 |
|
102 | ### Browser support
|
103 |
|
104 | We support the following browsers:
|
105 | * Chrome >= 59
|
106 | * Firefox >= 61
|
107 | * Edge >= 15
|
108 | * Safari >= 10.1
|
109 | * IE 11 (please import `snap.ie11.js`)
|
110 |
|
111 |
|
\ | No newline at end of file |