A single app can be present in multiple locations on the same page. In addition, a location may open up one or more modals. The locations and modals can be thought of as separate instances of the app and can be resized, closed, and communicate with each other. The app framework provides instance methods to enable these use cases.

Resizing an Instance
You can manually set the height of an app instance with client.instance.resize(), the maximum height being 700px. This works for modals and dialogs as well.

1
client.instance.resize({ height: "500px" });

If the instance occupies more space than this, scroll bars appear.

Closing an Instance
You can close modals and dialogs with this method.

1
client.instance.close();

Communication Between Instances

• Send data from a parent location to a modal - When a modal is opened, the location can send data to pre-populate form fields.
• Send data from a modal to a parent location - When a user fills a form in a modal window, some of this data may need to be returned to the parent.
• Send data from one location to another location - In the case of an app that is present in two locations on the same page, a button click in one location can be used to trigger an action in the second location.

The above use cases can be achieved with the following methods.

• Context
• Get
• Send
• Receive

Context

This method is used to fetch information about the current instance. For example, modals contain information about the parent location which triggered them and any data that was passed to them.

parent_location_template.html

1
2
3
4
5
client.instance.context().then(
  function(context)  {
       console.log(context);
  }
);

Output

1
2
3
4
{
  instanceId: "1",
  location: "conversation_card"
}

modal.html

1
2
3
4
5
client.instance.context().then(
 function(context)  {
   console.log(context);
 }
);

Output

1
2
3
4
5
6
{
  instanceId: "4",
  location: "modal",
  parentId: "1",
  modalData: "This conversation is initiated by Rachel"
}

Get

This method is used to fetch context information of all instances that are active at the time of the get() call. It can be used in conjunction with the send() method to send data to a specific instance.

modal.html

1
2
3
4
5
client.instance.get().then(
  function(data)  {
    console.log(data);
  }
);

Output

1
2
3
4
5
[
  {instanceId: "1", location: "conversation_card"},
  {instanceId: "2", location: "notification_card"},
  {instanceId: "4", location: "modal", parentId: "1"}
]

Send

This method can be used to send data to one or many instances. The receive() method should be used in the destination instance(s) to receive data. The syntax varies according to the following scenario.

• From one location/modal to one or more locations.
  
  modal.html Copied Copy

  1
  2
  3
  4
  5
  client.instance.send({
    message: {name: "James",
              email: "James@freshworks.com"},
    receiver: ["instanceID1", "instanceID2"]
  });

  
  

  Attribute	Description
  message	Data that is sent from a location/modal. message can be a string, object, or array.
  receiver	InstanceId(s) of the receiver locations.



• From a modal to its parent location.
  modal.html Copied Copy

  1
  2
  3
  4
  client.instance.send({
    message: {name: "James",
              email: "James@freshworks.com"}
  });

  
  

  Attribute	Description
  message	Data that is sent from a location/modal. message can be a string, object, or array.

The destination instances must be active when data is sent. You can retrieve all active instances using the get() method.

Receive

This method is used to receive data that is sent by another instance of the same app using the send() method. Anytime data is sent to the instance, the callback method is executed.

modal.html

1
2
3
4
5
6
7
client.instance.receive(
  function(event)  {
    var data = event.helper.getData();
    console.log(data);
    /* data contains {senderId: "1", message: { message: {name: "James", email: "James@freshworks.com"}} */
  }
);