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 |
|
oldStep newStep activityType |
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) |
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 |
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);