Skip to content

iframe-interface.md

Latest commit

 

History

History
154 lines (108 loc) · 6.76 KB

iframe-interface.md

File metadata and controls

154 lines (108 loc) · 6.76 KB
Raw

IFrame Interface

NovaCrate can be embedded into other frontends using the HTML-5 <iframe> tag. Limitations apply.

Integration

To use NovaCrate in Iframe mode, you must host an instance of NovaCrate yourself. Iframe integration is disabled in the official instance for safety reasons. To enable Iframe integration in your own instance, set the environment variable IFRAME_TARGET_ORIGIN. Set this variable to the origin of the parent page as described in the postMessage documentation. Example with Docker:

  1. Clone the NovaCrate repository
  2. In docker-compose.build.yml: Remove the line comment and set the environment variable IFRAME_TARGET_ORIGIN to the origin of the parent page
  3. Build the image: docker compose -f docker-compose.yml -f docker-compose.build.yml build
  4. Run using your own docker compose or by adapting the default docker-compose.yml.

When your NovaCrate instance is running, add the following HTML snippet to the page where NovaCrate should be embedded:

<iframe src="https://your-novacrate-instance.org/editor/iframe/entities" width="1200" height="800" />
<!--                                                    ^^^^^^ This enables Iframe mode           -->

Note the additional iframe segment in the URL.

Iframe integration is only enabled when both the IFRAME_TARGET_ORIGIN environment variable and the iframe URL segment are present as described.

Note

Find more information on supported Environment Variables.

Limitations

Currently, the Iframe mode of NovaCrate is limited to metadata editing. All file and folder management capabilities that are present in standalone NovaCrate are disabled. If file management is a feature you need in Iframe mode, please get in contact.

The Iframe mode of NovaCrate is locked down to only the crate loaded into the editor by the parent page. Users will not have access to their other crates they have used on your NovaCrate instance. They will also not be able to access the main menu or create a new crate. Instead, a crate must be provided by the parent page initially. If this limitation is a problem for you, please get in contact.

Message Interface (v1)

Communication between the embedding page (parent page) and NovaCrate is done via the postMessage API. The following messages can be exchanged between the two pages.

Direction Type Description
Parent <- NovaCrate READY Sent when NovaCrate is ready Link
Parent <- NovaCrate CRATE_CHANGED Sent when user saves changes Link
Parent <- NovaCrate GET_CRATE_RESPONSE In response to GET_CRATE Link
Parent -> NovaCrate LOAD_CRATE To load a crate into NovaCrate Link
Parent -> NovaCrate UPDATE_CRATE To update the currently loaded crate Link
Parent -> NovaCrate GET_CRATE To get the currently loaded crate Link

Messages sent by NovaCrate

These messages will be sent by NovaCrate to the parent page.

READY

This message is sent when NovaCrate is ready to receive messages from the parent page.

type ReadyMessage = {
    source: "novacrate"
    type: "READY"
    novaCrateVersion: string
    messageInterfaceVersion: number // currently: 1
}
  • novaCrateVersion is the version of NovaCrate that is currently running in the iframe.
  • messageInterfaceVersion is the version of the message interface that is currently used. This number is incremented only for breaking changes. Please check if this version matches the expected version in your application. If your application sends messages that NovaCrate (no longer) understands, they will be silently ignored.

CRATE_CHANGED

This message is sent whenever the user saves their changes in NovaCrate. It contains the current state of the crate in the metadata field.

type CrateChangedMessage = {
    source: "novacrate"
    type: "CRATE_CHANGED"
    metadata: string
}
  • metadata is a JSON string representing the current state of the crate metadata. Corresponds to the content of the ro-crate-metadata.json file.

GET_CRATE_RESPONSE

This message is sent in response to a GET_CRATE message. It contains the current state of the crate in the metadata field.

type GetCrateResponseMessage = {
    source: "novacrate"
    type: "GET_CRATE_RESPONSE"
    metadata: string
}
  • metadata is a JSON string representing the current state of the crate metadata. Corresponds to the content of the ro-crate-metadata.json file.

Messages sent by parent page

These messages may be sent by the parent page to NovaCrate.

LOAD_CRATE

This message is used to load a crate into NovaCrate from the parent page. It should be sent immediately after the READY event was received by the parent page. In Iframe mode, NovaCrate is unresponsive until a crate is loaded through the LOAD_CRATE message.

type LoadCrateMessage = {
    target: "novacrate"
    type: "LOAD_CRATE"
    metadata: string
}
  • metadata is a JSON string representing the crate metadata to be loaded. Corresponds to the content of the ro-crate-metadata.json file.

UPDATE_CRATE

This message is used to update a crate that has already been loaded into NovaCrate. NovaCrate will automatically reload all entities from the updated crate, overwriting local changes in case of conflicts. In case an entity did not change in the update and the user has made changes, the changes are preserved.

type UpdateCrateMessage = {
    target: "novacrate"
    type: "UPDATE_CRATE"
    metadata: string
}
  • metadata is a JSON string representing the crate metadata to be loaded. Corresponds to the content of the ro-crate-metadata.json file.

GET_CRATE

This message can be sent by the parent page to request the current state of the crate from NovaCrate. In return, a GET_CRATE_RESPONSE message will be sent by NovaCrate. Note that NovaCrate automatically sends a CRATE_CHANGED message whenever the user saves their changes in NovaCrate.

type GetCrateMessage = {
    target: "novacrate"
    type: "GET_CRATE"
}

Example

A working example of the Iframe integration can be found here.