Widget Events

The widget triggers custom events during its lifecycle. Your code may listen for these events and perform custom actions when the events occur. Example actions might include logging to an analytics platform, modifying the content of the page, starting a video, etc.

Custom Events

The widget uses JavaScript's CustomEvent feature to dispatch its events. For most events, some additional information is included in the detail property of the event object. The widget events bubbles up through the ancestors of the widget container element. Thus it is possible and often convenient to listen for events at the topmost level of the document.

To avoid naming conflicts with custom events from your code and other libraries or plugins, all of the widget event types begin with the civicscience: prefix.

Using Vanilla JavaScript

Here is an example of listening for a widget event using vanilla JavaScript.

document.addEventListener("civicscience:questionAnswered", function (event) {
    // handle the event
    console.log("the user answered question %s", event.detail.id);
});

Question Events

The question events can be used to monitor a user answering poll questions in the widget.

civicscience:beforeFetchingQuestions

This event is triggered before the widget requests from the server a batch of questions to ask the user.

There are no detail properties associated with this event.

civicscience:beforeAskingQuestions

This event is triggered when the batch of questions to ask has been received from the server, just before the first question will be asked.

This event has one detail property:

• ids an array of question identifiers in the order that they will be asked

civicscience:questionAsked

This event is triggered each time a question appears in the widget to be asked to the user.

This event has three detail properties:

• id the identifier for the question being asked
• index the 0-based index of the asked question in the poll
• length the total number of questions in the poll

civicscience:questionAnswered

This event is triggered when the user submits an answer to a question.

This event has three detail properties:

• id the identifier for the question which was just answered
• index the 0-based index of the answered question in the poll
• length the total number of questions in the poll

civicscience:afterAskingQuestions

This event is triggered immediately after the last question in the poll has been answered by the user, before results are shown.

This event has one detail property:

• ids an array of question identifiers just answered in the poll, in the order they were answered

Results Events

The results events are useful for monitoring how a user is navigating among a series of results pages or "slides" in the widget at the end of a poll.

civicscience:beforeShowingResults

This event is triggered just before the first results slide appears in the widget.

This event has one detail property:

• length the total number of results slides

civicscience:resultDeparted

This event is triggered when the user clicks the back or next button to leave one results slide for another. It is not triggered when the user navigates beyond the last results slide to begin a new poll, in which case the civicscience:afterShowingResults event is triggered instead.

The civicscience:resultDeparted event has three detail properties:

• from the 0-based index of original results slide
• to the 0-based index of the destination results slide
• length the total number of results slides

civicscience:resultArrived

This event is triggered when the user arrives at one results slide from another by clicking a back or next button. It is not triggered when the first slide initially appears, in which case the civicscience:beforeShowingResults event is triggered instead.

The civicscience:resultArrived event has three detail properties:

• from the 0-based index of original results slide
• to the 0-based index of the destination results slide
• length the total number of results slides

Why are there two results navigation event types?

At a glance supporting both the civicscience:resultDeparted and civicscience:resultArrived events may seem redundant. For many widget configurations, they will indeed be triggered nearly simultaneously.

However for some widgets with animation effects there is a delay between the user clicking a navigation button on the original results slide and the appearance of the destination results slide. Providing two separate event types allows you to choose whether your event listener should react to results navigation before or after this delay.

civicscience:afterShowingResults

This event is triggered when the user navigates beyond the last results slide to begin a new poll in the same widget visit. Widgets which link to a "user site" on the last slide do not have this capability, and so those kinds of widgets will never trigger this event.

This event has one detail property:

• length the total number of results slides

Frame Events

The frame events can be used to monitor changes in the widget iframe.

civicscience:frameResize

This event is triggered when the content of the widget has caused the widget to increase/decrease in size to fit its content.

This event has one detail property:

• height the height the frame is attempting to change to

Event Summary

The table below summarizes the events triggered by the widget.