Ενσωμάτωση

Embedding is a simple way to include the app in your website. Add the following code to your website:

<iframe
  id="butterfly"
  src="https://web.butterfly.linwood.dev/embed"
  width="100%"
  height="500px"
  allowtransparency="true"
></iframe>

Επιλογές

Επιλογή	Τύπος	Προεπιλογή	Περιγραφή
αποθήκευση	Boolean (true, false)	true	Enable save. If disabled, only an exit button will be shown
editable	Boolean (true, false)	true	Enable editing. If disabled, the document will be read-only
fullScreen	String (enabled, layoutOnly, startInLayout, forced, disabled)	enabled	Configure full-screen behavior. Embeds never enter browser or system full screen automatically
γλώσσα	Συμβολοσειρά (…, σύστημα, χρήστης)	user	Language of the document. If system, the language will be detected from the browser. If user, the language will set to the users preference
fileName	String		Display this file name in the embed title. It is visual only and does not change the document metadata

Full-screen modes

Τιμή	Initial layout	Toggle	Browser/system full screen
enabled	Κανονικό	Ναι	When enabled by the user
layoutOnly	Κανονικό	Ναι	Ποτέ
startInLayout	Πλήρης οθόνη	Ναι	Ποτέ
forced	Πλήρης οθόνη	Όχι	Ποτέ
disabled	Κανονικό	Όχι	Ποτέ

Messaging

The embed uses browser postMessage events. Send messages to the iframe with iframe.contentWindow.postMessage({ type, message }, origin). Butterfly sends messages back to the parent window with the same shape: { type: string, message?: unknown }.

See the embedding example for a live page that sends messages to the iframe and listens for messages from it.

<iframe
  id="butterfly"
  src="https://web.butterfly.linwood.dev/embed?save=true&editable=true&fileName=Example.bfly"
  width="100%"
  height="500"
></iframe>

<script>
  const butterflyOrigin = 'https://web.butterfly.linwood.dev';
  const butterfly = document.querySelector('#butterfly');

  function sendToButterfly(type, message) {
    butterfly.contentWindow.postMessage({ type, message }, butterflyOrigin);
  }

  window.addEventListener('message', (event) => {
    if (
      event.origin !== butterflyOrigin ||
      event.source !== butterfly.contentWindow
    ) {
      return;
    }

    const { type, message } = event.data ?? {};

    if (type === 'save') {
      const documentBytes = Array.from(message);
      console.log('Save requested by the embed', documentBytes);
    }

    if (type === 'exit') {
      const documentBytes = Array.from(message);
      console.log('Exit requested by the embed', documentBytes);
    }

    if (type === 'change') {
      console.log('Document changed', message);
    }

    if (type === 'getData') {
      console.log('Current document bytes', message);
    }

    if (type === 'getThumbnail') {
      // null means that the document has no captured thumbnail.
      console.log('Captured thumbnail', message);
    }

    if (type === 'render') {
      const image = new Image();
      image.src = `data:image/png;base64,${message}`;
      document.body.append(image);
    }

    if (type === 'renderSVG') {
      const preview = document.createElement('div');
      preview.innerHTML = message;
      document.body.append(preview);
    }
  });

  butterfly.addEventListener('load', () => {
    sendToButterfly('getData');

    // Omit camera and size fields to render the current visible canvas view.
    sendToButterfly('render', {
      renderBackground: true,
    });

    // Set the camera explicitly to render from the document origin instead.
    sendToButterfly('render', {
      x: 0,
      y: 0,
      width: 600,
      height: 400,
      scale: 1,
      rotation: 0,
      padding: { top: 0, right: 0, bottom: 0, left: 0 },
      renderBackground: true,
    });
  });
</script>

To load document bytes into the embed, send an array of byte values:

sendToButterfly('setData', documentBytes);

The view is separate from the document bytes. To save and restore the same camera view, request getViewState and store its response with the bytes. Pass both to setData when loading the document:

// Use the message from the getViewState response, or a stored viewChange event.
sendToButterfly('setData', {
  data: documentBytes,
  viewState: savedViewState,
});

Sending both in one setData message applies the view after the replacement document loads. To move the current embed without replacing its document, use setViewState instead.

To replace the current document with a new blank document without reloading the iframe, send either of these messages:

sendToButterfly('reset');
// Equivalent:
sendToButterfly('setData', null);

Συμβάντα

Listen for events with window.addEventListener('message', ...).

αποθήκευση

The save event is emitted when the user clicks the save button.

Παράμετροι:

• message (Type List<int>): The data of the document.

έξοδος

The exit event is emitted when the user clicks the exit button.

Παράμετροι:

• message (Type List<int>): The data of the document.

change

The change event is emitted when the user changes the document.

Παράμετροι:

• message (Type List<int>): The data of the document.

viewChange

The viewChange event is emitted after the camera position, zoom, or rotation changes. Events are debounced while the view is moving.

Παράμετροι:

• message (Type Object): { x, y, zoom, rotation } for the current view.

Μέθοδοι

Call methods with iframe.contentWindow.postMessage(...). Methods that return data send another message back with the same type.

getData

The getData method returns the data of the document.

No parameters. Returns: List<int>

getViewState

The getViewState method returns the current camera view.

No parameters. Returns: { x: Number, y: Number, zoom: Number, rotation: Number }. x and y are document coordinates of the view origin, zoom is a scale between 0.1 and 10, and rotation is in radians.

setViewState

The setViewState method moves the current camera without changing the document.

Παράμετροι:

• viewState (Type Object): { x, y, zoom, rotation }. All fields are required and must be finite numbers. Zoom must be between 0.1 and 10.

getThumbnail

The getThumbnail method returns the document’s captured thumbnail without rendering the canvas.

Pass "png" or { format: "png" } to receive a Base64 encoded PNG. Pass "svg" or { format: "svg" } to receive an SVG containing the captured PNG. The SVG is a raster image wrapper, not a vector rendering. If the document has no captured thumbnail, the response is null. Use render or renderSVG to export the current canvas view instead.

Returns: String | null

setData

The setData method replaces the document, or creates a new blank document when passed null.

Παράμετροι:

• data (Type List<int> | { data: List<int>, viewState?: Object } | null): The document bytes, an object containing the bytes and an optional camera view, or null to reset it. Invalid view states return an error message and leave the current document in place.

reset

The reset method replaces the current document with a new blank document.

No parameters.

render

The render method renders the document to a png image.

All parameters are optional. With no camera or size parameters, Butterfly exports the current visible canvas view. To export from the document origin, set x: 0, y: 0, scale: 1, and rotation: 0 together with the desired output size.

Padding expands the output dimensions: the final width is width + left + right and the final height is height + top + bottom.

Παράμετροι:

Parameter	Τύπος	Προεπιλογή	Περιγραφή
x	Number	Current view x	Document x position of the exported view.
y	Number	Current view y	Document y position of the exported view.
width	Number	Current viewport width	Output width in pixels.
height	Number	Current viewport height	Output height in pixels.
scale	Number	Current zoom	Camera zoom used for the export.
rotation	Number	Current rotation	Camera rotation in radians.
padding	Object	All sides 0	Extra output pixels added with top, right, bottom, and left fields.
renderBackground	Boolean	true	Whether to include the document background.

Returns: String (Base64 encoded image)

renderSVG

The renderSVG method renders the document to a svg image.

It accepts the same optional view parameters as render. Omitting them exports the current visible canvas view; explicitly setting an identity camera exports from the document origin.

Παράμετροι:

Parameter	Τύπος	Προεπιλογή	Περιγραφή
x	Number	Current view x	Document x position of the exported view.
y	Number	Current view y	Document y position of the exported view.
width	Number	Current viewport width	Output width in pixels.
height	Number	Current viewport height	Output height in pixels.
scale	Number	Current zoom	Camera zoom used for the export.
rotation	Number	Current rotation	Camera rotation in radians.
padding	Object	All sides 0	Extra output pixels added with top, right, bottom, and left fields.
renderBackground	Boolean	true	Whether to include the document background.

Returns: String (SVG)