How to create an embedded viewer solution

A how-to guide to create a viewer solution that can be embedded in a website.
Tags:

Introduction

This guide explains how to build a viewer solution that can be embedded in and communicate with a website (e.g. the solution receives user inputs from a website). It’s part of a three step process to embed a Packhunt viewer solution into your website, so make sure you follow them step by step.

Prerequisites

1. Configure the viewer solution

Configure a solution that only shows a Viewer in the user interface.

  • Create a root-frame
  • Add a Model block for the geometry
  • Add a Viewer block with the necessary materials for visualising the geometry
  • Subscribe the Viewer to the Model results
  • If deployed, there’s nothing to see nor test yet. Testing will be explained later in the guide.
kind: Solution
... 
frames:
  root-frame: 
    kind: Frame
    contents:
      my-geometry-model: ...
      my-viewer: ...

2. Add an Embed block

Add an Embed block to the root frame to communicate with the host website (e.g. receive inputs from the website).

  • Add an Embed block to your root-frame content
  • Specify the allowedOrigins as provided in the app endpoint request.
...
  root-frame:
    kind: Frame
    contents:
      my-geometry-model: ...
      my-viewer: ...
      my-embed:
        kind: Embed
        allowedOrigins:
        - http://localhost:1234
        - https://my-website-test.com
        - https://my-website.com

3. Configure allowed messages

Configure messages sent from the website to the solution.

  • Specify an allowedMessage to set all inputs (coming from the website). Add all inputs as properties to the Embed block. By default they’re all required.
my-embed:
  kind: Embed
  allowedOrigins: ...
  allowedMessages: 
    set-inputs:
      description: "Set all inputs ..."
      properties:
        my-input-a:
          type: Number
          description: "This is ..."
        my-input-b:
          type: String
          description: "This is ..."
        ...
  • Subscribe the Model to the Emed block input message(s).
my-geometry-model:
  kind: Model
  modelFile: ...
  subscribe:
    - kind: Embed
      source: my-embed
      frame: root-frame
      messageId: set-inputs
      action: set
  • (Optional) Specify an allowedMessage to set partial inputs. Add all the model inputs as properties to the message, but set them all to required: false. Then subscribe the Model to the Embed block with action: update.

4. Test the solution without the website

Test the solution (so far) by sending user inputs to the solution via the route.

  • Subscribe the Embed block to the Route.
  • In the setMessage property specify the name of the allowedMessage to which to send the route parameters.
  • In the urlParameters specify the message properties that will be set in the route.
my-embed:
  kind: Embed
  ...
  subscribe:
  - kind: Route
    urlParameters: [my-input-a, my-input-b]
    setMessage: set-inputs
  • Deploy the solution.
  • Open the solution and add the url parameters to the route.
    E.g. https://app.packhunt.io/my-project-slug?my-input-a=test&my-input-b=123
  • Adjust the values in the route to test if the solution is working as expected.

5. Configure available events

Configure events sent from the solution to the website. Note that the outgoing messages can only be tested with a website.

  • Specify outgoing availableEvents with properties that match the model outputs.
  • Set the property to nullable: true if the content can be null.
my-embed:
  kind: Embed
  ...
  availableEvents:
    my-geometry-model-warnings:
      description: "User warnings from the geometry model."
      properties:
        my-warning-a: 
          type: String
          description: "This warning is ..."
          nullable: true
        my-warning-b: ...
    ...
  • Subscribe the Embed block to the model outputs.
my-embed:
  kind: Embed
  ...
  availableEvents:
    my-geometry-model-warnings: ...
    ... 
  subscribe: 
    ...
    - kind: Model
      frame: root-frame
      source: my-geometry-model
      eventID: my-geometry-model-warnings

Next

Once the viewer solution is ready you can continue with the next embedding guide - Setup your website.