TPP_SNAP

Global FirstSpiritPreview instance.

TPP_SNAP
Example
<!--
  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 {@link 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>
Static Members
isConnected
isLegacyCC
onInit(handler)
onContentChange(handler)
onRerenderView(handler)
onNavigationChange(handler)
onRequestPreviewElement(handler)
registerButton(button, index)
overrideDefaultButton(defaultButtonName, buttonOverrides)
findPreviewNodes(previewId)
execute(identifier, params, result)
getPreviewElement()
setPreviewElement(previewId)
getPreviewLanguage()
showEditDialog(previewId)
showMetaDataDialog(previewId)
getElementStatus(previewId, refresh)
renderElement(previewId)
deleteElement(previewId, showConfirmDialog)
startWorkflow(previewId, workflow)
processWorkflow(previewId, transition)
createPage(path, uid, template, options?)
createSection(previewId, options?)
moveSection(source, target, options?)
createDataset(template, options?)
toggleBookmark(previewId)
cropImage(previewId, resolution, result)
languages()
previewUrl()
showTranslationDialog(previewId, source, target)
triggerChange(previewId, content)
triggerRerenderView()
mppGetParameter(name)
mppGetTimeParameter()
mppIsParameterized()
mppSetParameter(name, value)
mppSetTimeParameter(date)

onInit~Handler

onInit~Handler(success: boolean, isLegacyCC: boolean)

Type: Function

Since: 1.2.0
Parameters
success (boolean) the TPP handshake was successful or not
isLegacyCC (boolean) if the TPP handshake was successful, whether the connected ContentCreator uses the legacy design

onContentChange~Handler

onContentChange~Handler($node: HTMLElement, previewId: string, content: any): any

Type: Function

Since: 1.2.0
Parameters
$node (HTMLElement) a DOM node which contains the [data-preview-id] attribute
previewId (string) the current PreviewId
content (any) the changed content, could be a string, or an object (if the FirstSpirit Template generates JSON) or null, if this PreviewElement was deleted.
Returns
any: if the handler doesn't return anything, onRerenderView~Handler will be triggered.

onRerenderView~Handler

onRerenderView~Handler()

Type: Function

onNavigationChange~Handler

onNavigationChange~Handler(previewId: (string | null))

Type: Function

Since: 1.2.0
Parameters
previewId ((string | null)) of a newly created page, otherwise null

onRequestPreviewElement~Handler

onRequestPreviewElement~Handler(previewId: string)

Type: Function

Since: 1.2.0
Parameters
previewId (string) the current PreviewId

ButtonScope

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

ButtonScope
Parameters
$node (HTMLElement) the DOM node where the decoration appears
$button (HTMLElement) the DOM node of the button (not available in Button#isVisible~Callback )
previewId (string) the PreviewId
status (Status) the current Status object of PreviewId
language (string) the current language

Button#isVisible~Callback

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.

Button#isVisible~Callback(scope: ButtonScope): Promise<boolean>

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
Returns
Promise<boolean>:

Button#isEnabled~Callback

Button#isEnabled~Callback(scope: ButtonScope): Promise<boolean>

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
Returns
Promise<boolean>:

Button#getIcon~Callback

Button#getIcon~Callback(scope: ButtonScope)

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
Example
// 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'),
  ...
});

Button#getLabel~Callback

Button#getLabel~Callback(scope: ButtonScope)

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
Example
// 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',
  ...
});

Button#getItems~Callback

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

Button#getItems~Callback(scope: ButtonScope)

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
Example
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),
  ...
});

Button#beforeExecute~Callback

Button#beforeExecute~Callback(scope: ButtonScope, item: any)

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
item (any) see Button#getItems~Callback

Button#execute~Callback

Button#execute~Callback(scope: ButtonScope, item: any): Promise<void>

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
item (any) see Button#getItems~Callback
Returns
Promise<void>:

Button#afterExecute~Callback

Button#afterExecute~Callback(scope: ButtonScope, item: any, error: Error?)

Type: Function

Since: 1.2.0
Parameters
scope (ButtonScope)
item (any) see Button#getItems~Callback
error (Error?) if an uncatched error appears

Button

Button
Parameters
button (object)
Name Description
button.label string (default '') simple labeling, used by the default of Button#getLabel~Callback
button.css string? simple css class definition, used by the default of Button#getIcon~Callback
button.icon string? simple icon url, used by the default of Button#getIcon~Callback
button.isVisible Button#isVisible~Callback? whether this button should be rendered or not; the default is (scope) => true
button.isEnabled Button#isEnabled~Callback? whether this button should be enabled or not; the default is (scope) => false
button.getIcon Button#getIcon~Callback? use scope.$button to define the appearance of the button
button.getLabel Button#getLabel~Callback? the tooltip ( [title] ) for this button
button.getItems Button#getItems~Callback? if this is not an empty list, a dropdown will be rendered; the default is (scope) => []
button.beforeExecute Button#beforeExecute~Callback? will be called before Button#execute~Callback
button.execute Button#execute~Callback? will be called, when the button (or an item) is clicked
button.afterExecute Button#afterExecute~Callback? will be called after Button#execute~Callback

CustomStatus

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

CustomStatus

Extends Status

Since: 1.2.0
Example
// <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');
  },
})

Status

The status is not a stable API, yet.

Status
Parameters
previewId (string) the raw PreviewId
custom ((string | null)) is null, if the status is delivered by FirstSpirit. Otherwise this contains information from the markup.

matches

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

matches