Nicely Pruned Marigolds

    fs-tpp-api

    2.4.1 • Public • Published

    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.

    snap.js

    Include the snap.js somewhere in your markup.

    CDN (browser, recommended)

    <script src="https://cdnjs.cloudflare.com/ajax/libs/fs-tpp-api/VERSION/snap.js"></script>
    

    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');
    

    Initialization

    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:

    1. onRerenderView - called every time the (changed) editorial content has to be rendered.
    2. 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.

    Preview content notation

    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())$
    

    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.

    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 is also used.

    caas.js

    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
    

    Browser support

    We support the following browsers:

    • Chrome >= 59
    • Firefox >= 61
    • Edge >= 15
    • Safari >= 10.1
    • IE 11 (please import snap.ie11.js)
    Tip: Click on a version number to view a previous version's package page

    Current Tags

    Version History

    Install

    npm i fs-tpp-api

    DownloadsWeekly Downloads

    548

    Version

    2.4.1

    License

    Apache-2.0

    Unpacked Size

    1.81 MB

    Total Files

    7

    Last publish

    Collaborators

    • jodeleit-es
    • marro-es