Event Callbacks for Embedded Forms

If you have embedded an activity form on your own website, you may wish to add additional logic to manipulate the form or change the user's experience using Javascript. For example, you could use a script to customize values in hidden fields, change CSS or other styling of fields, etc. Often that logic depends on certain events, like the widget to finish loading, or a supporter clicking the 'Submit' button. 

Engage published widgets look for a handful of Javascript invocation hooks. If a function with the specified name is defined on the page by a web developer, it will be invoked at the appropriate event.  If the function does not exist, nothing changes. Errors that occur in the function will be ignored and allow the page to still load correctly. 

Where an Activity ID is specified, that Activity ID will be the actual ID of the activity of the widget, in order to support cases where more than one form widget is embedded on a given HTML page.

Description of each callback hook

Callback hook	For what activity type	When it executes	Data returned
salsaWidgetFinished	all	When the form finishes loading	activityType activityId
salsaWidgetStepNav	all	stepForward For all forms: when the supporter hits "next" on multi-step forms For Targeted Actions: when the supporter proceeds through targeted action flow (From one channel to another: Call, Email or Form, Twitter; or to Confirmation page, No targets page) stepBackward For all forms: when the supporter hits "back" on multi-step forms	oldStep newStep activityType activityId activityName fundraiserName (for Fundraiser page in P2P only) teamName (for Team page in P2P only)
salsaWidgetPageSubmit	all	When the supporter successfully submits an activity form after clicking the 'Submit' button. This event does not fire if clicking 'Submit' triggers a validation error or otherwise fails. NOTE: For Targeted Action forms this hook shows up on every successful submit request-response (click on 'Take Action', 'Connect Me Now', 'Send Email', 'Done Tweeting' buttons). In order to distinguish the final submission you can use the salsaWidgetStepNav callback and look for when nextStep = "confirmation".	activityType activityId activityName fundraiserName (for Fundraiser page in P2P only) teamName (for Team page in P2P only)
salsaWidgetTAMessageFocus	Targeted Actions	When the supporter clicks into the field to edit a message to a target on a Targeted Action (when the option "Yes, they can change a letter" is enabled for that activity)	activityType activityId
salsaWidgetRecurringIntervalChange	Fundraising Form	When the supporter selects a frequency of gift on donation page (when recurring gift  and the ability to select recurring frequency are enabled on the form). It also should be triggered for the default recurring interval	activityType activityId frequency
salsaWidgetDonationAmountChange	Fundraising Form, Ticketed Events, P2P	When the supporter selects/switches the amount on the donation amounts element.  It also should be triggered for the default donation amount	activityType activityId donationAmount
salsaWidgetPaymentTypeChange	Fundraising Form, Ticketed Events, P2P	When the supporter chooses/switches payment method (Credit Card/eCheck/Paypal) on the payment element	activityType activityId paymentType

Example Javascript

Example Javascript for defining each callback is below. This Javascript should be included on whatever page you are embedding the Engage form widget. In addition to (or in place of) console.log in each function, add whatever logic you wish to execute whenever that callback is invoked.

window.addEventListener('load', function () {

  /* salsaWidgetFinished: fires when the embedded Engage widget finishes loading
    eventObj = {
        activityType : string,
        activityId : string,
    }
  */
  window.salsaWidgetFinished = function (activityId, eventObj) {
    console.log("salsaWidgetFinished fired for activityId: " + activityId);
    console.info(eventObj, "salsaWidgetFinished eventObj");
  }

  /* salsaWidgetPageSubmit: Fires when a user clicks the submit button for a form
    eventObj = {
      activityType : string,
      activityId : string,
      activityName : string,
      fundraiserName : string
    }
  */
  window.salsaWidgetPageSubmit = function (eventObj) {
    console.info(eventObj, "salsaWidgetPageSubmit eventObj");
  }

  /* salsaWidgetDonationAmountChange: Fires when a user selects the amount to donate
    eventObj = {
      activityType : string,
      activityId : string,
      donationAmount: string
    }
  */
  window.salsaWidgetDonationAmountChange = function (eventObj) {
    console.info(eventObj, "salsaWidgetDonationAmountChange eventObj");
  }


  /* salsaWidgetPaymentTypeChange: Fires when a user selects the amount to donate
  eventObj = {
    activityType : string,
      activityId : string,
      paymentType: string
  }
  */
  window.salsaWidgetPaymentTypeChange = function (eventObj) {
    console.info(eventObj, "salsaWidgetPaymentTypeChange eventObj");
  }


  /* salsaWidgetRecurringIntervalChange: Fires when a user selects the frequency for a recurring donation
    eventObj = {
      activityType : xxxWidgetxxx.activityType,
      activityId : xxxWidgetxxx.activityDefinitionId,
      frequency: event.target.value
    }
  */
  window.salsaWidgetRecurringIntervalChange = function (eventObj) {
    console.info(eventObj, "salsaWidgetRecurringIntervalChange eventObj");
  }

  /* salsaWidgetStepNav: fires when a user navigates between steps on a multi-step form
    eventObj = {
          oldStep: string,
          newStep: string,
          activityType: string,
          activityId: string,
          activityName: string,
          fundraiserName: string
      }
  */
  window.salsaWidgetStepNav = function (stepDirection, eventObj) {
    console.log("salsaWidgetStepNav fired in direction: " + stepDirection);
    console.info(eventObj, "salsaWidgetStepNav eventObj");
  }

  /* salsaWidgetTAMessageFocus: Fires when a user clicks into a Targeted Action message textarea
    eventObj = {
        activityType : string,
        activityId : string,
    }
  */
  window.salsaWidgetTAMessageFocus = function (eventObj) {
    console.info(eventObj, "salsaWidgetTAMessageFocus eventObj");
  }


}, false);