Textshine Bridge

Die Textshine Bridge ist ein API, um von einer Website aus die Textshine Browser Extension steuern zu können. Achtung: Die Textshine-Browser-Extension muss beim Nutzer installiert sein, ansonsten wird ein Error gethrowed. Der primäre Usecase ist aktuell, eine Korrektur aus einer CMS-Integration zu starten; in Zukunft könnten weitere Funktionen folgen.

Wir empfehlen dringlich, wenn möglich, die Bridge über npm einzubinden, da sie dadurch bei neuer Version komfortabel aktualisiert werden kann.

Installation

npm install textshine-browser-extension-bridge

Nutzung

Entweder direkter Import des SDKs (vermeidet global scope pollution):

// ESM-Import (preferred)
import { startCorrection } from 'textshine-browser-extension-bridge'
// ODER CommonJS-Import
const { startCorrection } = require('textshine-browser-extension-bridge');
// Nutzung
startCorrection(params: { type, data }, callback)

oder bei älteren Umgebungen das register script welches das API ins window objekt registriert (Achtung, funktioniert nicht bei SSR, weil es window-Existenz voraussetzt):

// ESM (preferred)
import 'textshine-browser-extension-bridge/register'

// or CommonJS
require('textshine-browser-extension-bridge/register');

window.textshineBridge.startCorrection(params: { type, data }, callback)

Sollte kein Buildprozess existieren, lässt sich auch die Datei node_modules/textshine-browser-extension-bridge/dist/browser/textshine-bridge.min.js kopieren und mittels Vanilla-HTML-Script-Tag einbetten.

API

toggleExtension()

Toggled (öffnet wenn geschlossen und schließt wenn offen) die extension und verhält sich exakt ident wie wenn ein User das Extension icon in der toolbar klickt. Ist nützlich wenn man in einer Integration den Korrekturbutton innerhalb des UI behalten möchte.

startCorrection(input, callback)

Jeder Aufruf übergibt eine Liste von Items (oder Gruppen von Items) und erhält dieselbe Struktur zurück – nur mit korrigierten src-Werten. Diese Liste und optionale Gruppierung ergibt das Layout des Review Editors in der Textshine Extension.

Es ist best practice das übermittelte HTML semantisch zu übergeben (zB dass eine headline tatsächlich eine <h1/2/3> ist und nicht nur ein <div> mit id), damit der Review Editor die Texte angenehmer formatiert ausspielen kann.

Signatur:

// Aktuell supporten wir nur html, bitte in Kontakt treten für weitere Formate
type TextshineBridgeCorrectionType = 'html'

// Das Kernstück: Ein Pane im ReviewEditor
type TextshineBridgeCorrectionItem = {
  // Frei wählbare, aber unique id
  id: string
  // Label ist optional und kann auch weggelassen werden (siehe screenshot)
  label?: string
  type: TextshineBridgeCorrectionType
  // Text im gewählten TextshineBridgeCorrectionType-Format
  src: string
}

// Mehrere Panes lassen sich gruppieren um für Übersicht zu sorgen (maximal eine Ebene)
type TextshineBridgeCorrectionItemGroup = {
  // frei wählbare, aber unique id
  id: string
  // Das Label steht vertikal links neben der Gruppierung und ist mandatory
  label: string
  items: TextshineBridgeCorrectionItem[]
}

type TextshineBridgeCorrectionPayload = (TextshineBridgeCorrectionItem | TextshineBridgeCorrectionItemGroup)[]

// Man bekommt das Resultat exakt gleich zurück wie die Quelle, dennoch empfehlen wir mit IDs zur Auflösung zu arbeiten
type TextshineBridgeCorrectionResult = TextshineBridgeCorrectionPayload

// Alle aktuellen Fehler-Codes. Diese Liste kann sich in Zukunft ändern.
type TextshineBridgeError = {
  code:
    | 'BROWSER_NOT_SUPPORTED'
    | 'VALIDATION_ERROR'
    | 'START_CORRECTION_FAILED'
    | 'EXPORT_FAILED'
    | 'UNEXPECTED_ERROR'
    | 'CORRECTION_CANCELED'
  message: string
  details?: unknown
}

type TextshineBridgeCallback = (
  error: TextshineBridgeError | null,
  result?: TextshineBridgeCorrectionResult
) => void

// Entweder mit NodeJS-Style error-first callback
function startCorrection(params: TextshineBridgeCorrectionPayload, callback: TextshineBridgeCallback): void

// oder als Promise mit try/catch error handling
function startCorrection(params: TextshineBridgeCorrectionPayload): Promise<TextshineBridgeCorrectionResult>