Subscriptions

Explanation on using subscriptions.
Tags:

A frame can contain various types of entities. In certain cases, these entities need to exchange data with other entities. This can be achieved through subscriptions.

If an entity needs some data from another entity then it can subscribe to that entity. The target entity can be on the same frame or another frame.

A typical example is where we have a control panel, a model, and a viewer. In this case, we need two subscriptions.

  • The data from the control panel inputs need to be passed to the model.
    • So the model subscribes to the control panel.
  • The data from the model (the geometry that is generated after it solves) needs to be passed to the viewer.
    • So the viewer subscribes to the model.

When configuring a subscription, you need to specify the target entity in the configuration. This is done by specifying three properties:

  • kind: The kind of entity being subscribed to.
  • frame: The name of the frame that contains the target.
  • source: The name of the entity in the contents of that frame.

The subscription may also allow you to configure other aspects that affect the data transfer. For example, when you subscribe a viewer to a model, you can assign materials.

The configuration code below shows a simple example with a control panel, a model, and a viewer.

kind: Solution
version: v0
router:
  kind: Router
  routes:
    - frame: my-home-frame
frames:

  my-home-frame:
    kind: Frame
    layout:
      kind: ColumnLayout
      widths: [auto, 300px]
      areas: [my-viewer, my-control-panel]
    contents:

      my-model:
        kind: Model
        modelFile: box-model.gh
        subscribe: # subscribe the model to the control panel
          - kind: ControlPanel
            frame: my-home-frame
            source: my-control-panel

      my-viewer:
        kind: Viewer
        subscribe: # subscribe the viewer to the model
          - kind: Model
            frame: my-home-frame
            source: my-model

      my-control-panel:
        kind: ControlPanel
        controls:
          height:
            kind: Slider
            label: Box height
            min: 2
            max: 10
            precision: 1
            value: 5

The type of data transfer depends on the types of entities involved at either end of the subscription. Below the different types of subscriptions are listed.

From To Behaviours Schema docs How-to guides
ControlPanel DataStore Update control panel with values from the data store controlPanelDataStoreSubscribe -
ControlPanel Model 1. Disable controls during model solve
2. Set control values after model solve (optional)		 controlPanelModelSubscribe How to display text outputs
How to display results in a table
DataStore ControlPanel Save control panel values in the data store dataStoreControlPanelSubscription How to create multi-step controls
DataStore PopupForm Save pop-up form values in the data store dataStorePopupFormSubscription -
Model ControlPanel 1. Set model inputs from control panel values
2. Trigger model solve		 modelControlPanelSubscribe How to add parametric inputs to your solution
Model DataStore 1. Set model inputs from data store values
2. Trigger model solve		 modelDataStoreSubscribe How to create multi-step controls
Model PopupForm 1. Set model inputs from pop-up form values
2. Trigger model solve		 modelPopupFormSubscribe How to add a pop-up form
NavPanel RouterOutlet Highlight active navigation button navPanelRouterOutletSubscribe How to add a navigation panel
PopupForm Button Open popup form on button clicked buttonSubscribeConfig How to add a pop-up form
PopupForm Model 1. Disable controls during model solve
2. Disable closing of the pop-up form
3. Show message after model solve (optional)		 modelSubscribeConfig How to add a pop-up form
Viewer ControlPanel Assign material properties (colour) by key viewerControlPanelSubscribe.md How to use material colours as inputs
Viewer Model 1. Retrieve geometry
2. Assign materials to geometry (optional)
3. Assign layers to geometry (optional)		 viewerModelSubscribe How to set material colours
How to hide/unhide geometries in the viewer
Image Model Display different images conditionally imageModelSubscribe How to display different images