The fs-tpp-api/snap.js must be used in the markup of the third party app. There is no specific position defined, but if you want to use the API of window.TPP_SNAP, your own script must be loaded after the inclusion fs-tpp-api/snap.js, of course. You could define the optional [data-firstspirit-origin] attribute to ensure that the first(!) postMessage (aka. TPP handshake) is only committed to the real ContentCreator frame.

<script src="path/to/fs-tpp-api/snap.js" data-firstspirit-origin="http://firstspirit:8000"></script>

All you have to do is use the [data-preview-id] in your markup. This library automatically decorates those containers with the known borders and buttons. Content changes will force a refresh of the current page, so there is no need to implement in JS!

But of course you are able to do this by using the framework! That's what the docs are for...

As an example, a FirstSpirit Template delivers some HTML Markup, which you would like to update in-place in case of changes. You could use the [data-on-tpp-change] attribute which is a representation of the onContentChange~Handler. Or you use it directly, like this:

TPP_SNAP.onContentChange(($node, previewId, content) => {
  if ($node.matches('.content') && content !== null) {
    $node.innerHTML = content;
    return false;
  }
})

You can register multiple handlers. Further processing of the event is stopped after the first handler returns a value !== undefined.

<div class="content"
  data-preview-id="<previewId>"
  data-on-tpp-change="if (content !== null) { this.innerHTML = content; return false; }">
</div>

Preview Element

To change the current preview element, you should use the method TPP_SNAP.setPreviewElement. This also ensures that the ContentCreator keeps track of the route change and the shown workflows are those of the current element:

TPP_SNAP.setPreviewElement(pageRefPreviewId);

Note that for navigating to another page, you should use the preview ID for its PageRef instead for the page itself.

For being able to open pages from within the ContentCreator (e.g. to use the search function) you have to specify your own listener to handle this request. The method to use for this purpose is TPP_SNAP.onRequestPreviewElement. A handler registered with onRequestPreviewElement should implement the frontend specific way to route to the requested page using the given preview id.

TPP_SNAP.onRequestPreviewElement(async (previewId) => {
  // The following previewIdToPath function is just a placeholder! The mapping from previewId to route has
  // to be defined project-dependent!
  let path = previewIdToPath(previewId);

  // The routing mechanism depends on the frontend as well, thus the "route" function also has to
  // be understood as a placeholder!
  if (path) return route(path);
  // ... error handling (e.g. 404) ...
}

Nested Components

Nested components of input components such as FS_CATALOG or FS_INDEX can be edited as well. To enable the editing of such a component make sure to provide a custom preview id for both the nested component as well as the parent component using the syntax #PARENT_COMPONENT_NAME and #NESTED_COMPONENT_INDEX as the following example shows.

<div data-preview-id="8326527a-60ff-49a0-bc66-91671d660249">
    <ul data-preview-id="#pt_catalog">
        <li data-preview-id="#0">This is content from the first entry.</li>
        <li data-preview-id="#1">The second component does have different content.</li>
        <li data-preview-id="#2">And of course, this is also different.</li>
    </ul>
</div>

Notice that the presence of the preview id of the data provider that contains the FS_CATALOG component is needed. As long as the HTML complies with this structure the individual nested components will automatically provide buttons for interaction.

NOTE: This feature also works for multiple nested components (e.g. a Catalog$Card that is part of of a Index$Record). It must be noted that in such a scenario, the path to a nested component must always alternate between a component name and an index. Additionally the last part of the path must always be an index of a nested component.

NOTE: Currently only FS_INDEX components that use the DatasetDataAccessPlugin are supported.

Inline Editing

Some input components support inline editing when enabled. All input components named in the FirstSpirit Online Documentation are supported. To enable inline editing for such components a custom preview id needs to be provided as a data attribute on the related DOM node using the syntax #INPUT_COMPONENT_NAME.

The following example includes a DOM node that corresponds to a CMS_INPUT_TEXT component with the name pt_headline.

<div data-preview-id="8326527a-60ff-49a0-bc66-91671d660249">
    <span data-preview-id="#pt_headline">
        Our various services for sales, marketing and installation branches.
    </span>
</div>

Notice that the presence of the preview id of a data provider that contains the editable input component is needed. As long as the HTML complies with this structure the component will automatically become inline editable.

CaaS Mode

The CaaS mode is mainly useful for scenarios where your web app uses the CaaS as the source for FirstSpirit content and your app can't render changed content dynamically (e.g. using the respective event handlers).

Whenever a re-rendering of the current page or the preview of an element was requested, this mode waits for the changed content to be present in the CaaS and then triggers the related handlers (onRerenderView~Handler or onRequestPreviewElement~Handler).

To enable the CaaS mode use the TPP_SNAP.enableCaasMode function.

TPP_SNAP.onInit(async (success) => {
  if(success) {
    const { previewCollectionUrl, apiKey } = {
      previewCollectionUrl: "https://caas-host/my-tenant-id/f948bb48-4f6b-4a8a-b521-338c9d352f2b.preview.content",
      apiKey: "9afa9e21-d02f-4836-9e55-111fcf6521a3"
    }
    TPP_SNAP.enableCaasMode(previewCollectionUrl, apiKey)
  }
})

NOTE: When using the CaaS mode in combination with dynamically rendering changed content (e.g. using the onContentChange~Handler) make sure to avoid handling any content changes that should lead to a re-rendering of the current page.

NOTE: The CaaS mode requires a minimum version for the CaaS platform and CaaS Connect module, see TPP_SNAP.enableCaasMode for more information.

Default Buttons

TPP_SNAP.onInit(async (success) => console.log(`FirstSpirit Preview is ${success ? 'now' : 'NOT'} available!`))

TPP_SNAP.onContentChange(($node, previewId, content) => $node.innerHTML = content))

TPP_SNAP.onRerenderView(() => app.rerender());

TPP_SNAP.onRequestPreviewElement(async (previewId) => {
  // error handling omitted for brevity
  const json = await TPP_SNAP.renderElement(previewId);
  window.history.pushState(json.uid, json.displayName, json.uid);
  await TPP_SNAP.setPreviewElement(previewId);
})

// register a debug button, as the first button, on any decorated element
TPP_SNAP.registerButton({
  css: 'tpp-icon-debug',
  execute: async (scope) => console.log(scope),
}, 0);

// override what the default 'crop' button does
TPP_SNAP.overrideDefaultButton('crop', {
  execute: async ({ previewId }) => actions.cropImage(previewId, 'my-cropped-resolution'),
});

// https://docs.e-spirit.com/odfs/template-develo/contentcreator/functional-scop/index.html#klassen_navigationbearbeiten
TPP_SNAP.execute('class:EditMenu', { node: 43 }).then(() => location.reload());

// display the default button
TPP_SNAP.overrideDefaultButton('metadata', {
  isVisible: ({ status }) => !status.custom && (['PageRef', 'Page', 'Section', 'Media'].includes(status.elementType))
})

Type: Function

Type: Function

Type: Function

Type: Function

Type: Function

The ButtonScope is an object which is used by all button callbacks.

Be careful with your Promise here: the rendering of all buttons only happens after all Button#isVisible calls. That's why ButtonScope.$button doesn't exists in ButtonScope this time.

Type: Function

Type: Function

Type: Function

// the default callback is defined as:
TPP_SNAP.registerButton({
  icon = null,
  css = null,
  getIcon = async ({ $button }) =>
    (css !== null && !$button.classList.add(css))
    || (icon !== null && ($button.style.backgroundImage = `url(${icon})`))
    || $button.classList.add('tpp-icon-action'),
  ...
});

Type: Function

// the default callback is defined as:
TPP_SNAP.registerButton({
  label = '',
  getLabel = () => label,
  ...
});

// localize
TPP_SNAP.registerButton({
  getLabel: ({ language }) => language.toLowerCase() === 'de' ? 'Deutsche Bezeichnung' : 'English Label',
  ...
});

An Item could be anything, but it needs a property called label, which appears in the dropdown.

Type: Function

TPP_SNAP.registerButton({
  label = '',
  getItems = () => {
    return [
      { label: 'Option 1', value: 1 },
      { label: 'Option 2', value: 2 },
      { label: 'Option 3', value: 3 },
    ];
  },
  execute = (scope, item) => console.log(item.value),
  ...
});

Type: Function

Type: Function

Type: Function

An error that represents a duplication of a page (e.g. thrown by createPage in case a duplicate UID was detected). It encapsulates the preview ID of the duplicated element.

Type: Error

Extends Error

This error can be handled by applying .catch((e) => {...}) on the returned promise. Via DuplicatePageError~getPreviewId method one can also retrieve the preview ID of the element that was duplicated.

TPP_SNAP.createPage("path/to/homepage", "homepage", "homepage", {
    forceUid: true
}).catch(e => {
   console.log(e.message);
   console.log(e.previewId);
});

A custom PreviewId starts with custom: and can be used in a URN Schema way to create custom buttons.

Extends Status

// <div data-preview-id="custom:create-page:my/firstspirit/path:myPageName"></div>

TPP_SNAP.registerButton({
  css: 'tpp-icon-create-page',
  label: 'addMyPageName',
  isVisible: ({ status }) => status.custom !== null && status.parts[0] === 'create-page',
  execute: ({ status }) => {
    const [, path, name] = status.parts;
    TPP_SNAP.createPage(path, name, 'page_template_uid');
  },
})

The status is not a stable API, yet.

Performs a request targeting a specific nested component in the context of a previewId, while avoiding duplicate parallel requests targeting the same component at the same time.

The procedure making the request in the context of a specific nested component.

Type: Function

Manual polyfill. The elements provided by MutationObserver do not seem to be enhanced by babel-polyfills.