What are events?

When using widgets or apps, several things might happen. For example, when the app is “clicked” in Deskpro a message is sent to the app to say that the app is now shown to the user. These messages, or events, are useful when designing widgets and can tell your code to do certain things, like act upon data passed at a particular time. Here’s a brief overview of events passed to widgets:

• READY – when the widget is loaded in Deskpro, but not necessarily seen by the user

• SHOW – when the widget is shown to the user, like when the user clicks on the widget

• CHANGE – when data passed to the widget changes, e.g. when the ticket user is changed

Already you can see how these events might be useful. For example, when the app is READY you might want to load data from an API before the app is actually shown to the user – like a preload behaviour.

Contexts

When each of these events are sent to the widget, some information about where the widget is placed in Deskpro is passed along with the event. E.g. if the widget is in the ticket sidebar, details of the ticket are passed; like the ticket ID or primary user. This data is called a “context”.

An Example

Ok, so lets look at a simple example of using the READY event to make something happen in your widget. Create a new widget assigned to the "Ticket" target. In the "head" part of the "Code" tab when creating a widget, enter the script tag to import jQuery from a CDN.

<script src="https://code.jquery.com/jquery-3.6.0.min.js" integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script>
 copy

Then, in the "body" section of your widget's code, enter the following:

<div class="container">
	The primary ticket user is: <strong id="user"></strong>
</div>
	
<script>
	Deskpro.client.onReady(function (context) {
	  $("#user").text(context.data.ticket.primaryUser.displayName);
	});
</script>
 copy

Let's break down this example. The code in the "head" is an import of the jQuery library. We'll use this in our widget. The code in the "body" of our widget does two main things:

1. We wait for the READY event by using the onReady hook of the Deskpro apps client

2. When we receive a READY event, i.e. when the widget is first loaded, we are passed the context containing information about the ticket. We take the primary ticket user's display name and inject it, using jQuery, into the HTML above

Now, head over to Deskpro's agent interface and select any ticket. Clicking on our widget's icon in the ticket actions sidebar you should see our app show the name of the ticket's primary user.

As mentioned earlier, there are other events we can listen for and hook into. These can be seen in the example below:

<script>
	Deskpro.client.onReady(function (context) {
	  // Do something on READY
	});
	
	Deskpro.client.onShow(function (context) {
	  // Do something on SHOW
	});
	
	Deskpro.client.onChange(function (context) {
	  // Do something on CHANGE
	});
</script>
 copy