Instance method

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.

Take a look at the Instance method sample app for a demonstration of this feature.

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.

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

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

You can close modals with this method.

client.instance.close();

• 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

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.

try {
  let data = await client.instance.context();
    console.log(data); // context
} catch (error) {
    console.error(error);
}

{
  instanceId: "1",
  location: "ticket_requester_info"
}

To know the usage of context method with an example, see Send data from a parent location to a modal.

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.

ticket_sidebar_template.html or modal.html

try {
  let data = await client.instance.get();
} catch (error) {
    console.error(error);
}

Output

[
  {instanceId: "1", location: "ticket_requester_info"},
  {instanceId: "2", location: "ticket_sidebar"},
  {instanceId: "4", location: "modal", parentId: "1"}
]

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 scenario as shown below.

try {
  await client.instance.send({
      message: {
          name: "James",
          email: "James@freshdesk.com"
      },
      receiver: ["instanceID1", "instanceID2"]
  });
} catch (error) {
    console.error(error);
}

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

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.

ticket_sidebar_template.html or modal.html

client.instance.receive(
  function(event) {
    let data = event.helper.getData();
    console.log(data);
    /* data contains {senderId: "1", message: { message: {name: "James", email: "James@freshdesk.com"}} */
    }
);

data returns the following attributes.

In this example, when a user enters information (Name and Email) and clicks the Show Modal button, the values are sent to the modal.

First, add an additional parameter data in showModal() so that information is available in the modal.

ticket_sidebar_template.html

try {
await client.interface.trigger("showModal", {
  title: "Information Form",
  template: "modal.html",
  data: {
    name: "James",
    email: "James@freshdesk.com"
  }
});
} catch (error) {
  console.error(error);
}

The data can then be retrieved using the context() method.

modal.html

try {
let context = await client.instance.context();
console.log("Modal instance method context", context);
  /* Output: Modal instance method context
  {
    instanceId: "4",
    location: "modal",
    parentId: "1",
    modalData: {name: "James", email: "James@freshdesk.com"} }"
  */
document.querySelector("#name").val(context.modalData.name);
document.querySelector("#email").val(context.modalData.name);
} catch (error) {
  console.error(error);
}

Here, modalData contains data that was passed using showModal.

Data can be transferred from a modal to its parent location ticket_requester_info using the send() and receive() methods. In the following example, when a user enters the information (Name and Email) and clicks the Send button in the modal, the user input is populated in ticket_requester_info(parent location).

modal.html

client.instance.send({
  message: {name: "James", email: "james.dean@freshdesk.com"}
});
/* message can be a string, object, or array */

ticket_sidebar_template.html

client.instance.receive(
function(event) {
  let data = event.helper.getData();
    console.log(data);
      /* Output:
      {
       senderId: "4",
       message: {name: "James", email: "james.dean@freshdesk.com"}
      }
      */
  }
);

Data can be transferred from location to another location by using send() and receive() methods instance methods. In the following example, when a user enters information (Name and Email) and clicks the Send button in the ticket_requester_info location, the data is passed to the ticket_sidebar location as shown.

ticket_requester_template.html

let data = await client.instance.get();
console.log("Modal instance method context", context);
  /* Output: Modal instance method context
  {
    instanceId: "1",
    location: "ticket_requester_info",
   },
   {
    instanceId: "1",
    location: "ticket_requester_info",
   }"
  */
let sidebarApp = data.find(x => x.location === "ticket_sidebar");
await client.instance.send({
  message: {
    name: "James",
          email: "james.dean@freshdesk.com"
      },
      receiver: sidebarApp.instanceId
  });
  /* 2 - instance ID of the receiver */
/* message can be a string, object, or array */

ticket_sidebar_template.html

client.instance.receive(
function(event) {
  let data = event.helper.getData();
  console.log(data);
  /* Output:
    {
      senderId: "1",
      message: { name: "James", email: "james.dean@freshdesk.com"}
    }
  */
}
);