Articles in this section

See more

Customizing Behavior With Events

Avatar
Justin Heeren
  • Updated
Follow

Contents

Event Handling Code
Events Reference
Code Example

Note: This help doc is for S1 campaigns only; it does not apply to campaigns built on S2 templates.


Overview

If you have JavaScript and jQuery experience, you can customize the behavior of your Campaign by responding to custom events that ShortStack triggers.

Note: JavaScript/jQuery is an advanced topic. If you're not familiar with JavaScript or jQuery, it is strongly recommended that you go through this JavaScript tutorial as well as this jQuery tutorial before attempting to use the methods outlined below.

Event Handling Code

The general steps for handling events are:

  • Add a Code Widget to your Campaign.

  • Paste the following code into the widget:
  $(function(){
    $('#WIDGET_ID').bind('EVENT.NAME', function(event) {
      // code for handling the event goes here
    });
    // repeat $('#WIDGET_ID')... block for additional event handlers
  });
  • Replace WIDGET_ID with the CSS ID of the widget where the event comes from.

  • Replace EVENT.NAME with the actual name of the event you are handling (see Events Reference below).

  • If needed, add additional event handlers.

Events Reference

Event Name

Description

Parameters

changed.content 

The content inside the widget was changed (for example, the user clicked another page of results in the Voting Widget).

None

error.form

The form was sent to the server, and the server replied with one or more error messages (for example, the user already submitted an email address).

response
The response object returned from the server. Error messages will be in response.errors.

form
The form that was submitted.

exception.form

The form was sent to the server, but an exception occurred on the server.

xhr
The xhr object from the ajax call.

sending.form

This is triggered when a user submits a form in a Custom Form or Promotion Widget, but before the data is sent to our server.

options
Set options.submit_form to false to cancel the form submission.

success.form

User successfully submits a Custom Form or Promotion Widget.

response
The response object returned by the Ajax call that submitted the form.

form
A jQuery reference to the form being submitted.

success.invite

User successfully sends invitations from the Friend Invite Widget to one or more friends.

response
Response returned by FB.ui

options
Set options.show_alert to false to cancel the confirmation message (for example, because you plan to show a hidden widget as confirmation, instead).

liked

Like Button Widget clicked.

href
The URL that was Liked.

success.poll

User successfully votes in a poll.

choice
Zero-based index of the item voted for.

error.poll

Triggered if user tries to vote again in a poll with Restrict Voting enabled.

options
Set options.show_error to false to cancel the popup error message (for example, because you plan to show a hidden widget, instead). Set options.show_results to false to cancel the automatic display of the poll results.

cancel.share

User canceled Share without sending.

None

changed.video

User clicked on a video thumbnail in the Video Widget.

video_id
The video ID (from YouTube or Vimeo) chosen.

play.video

User began playing a video in the Video Widget.

video_id
The video ID (from YouTube or Vimeo) being played.

success.vote

User votes on an entry.

entry
A jQuery object for the li element that was voted on.

 

Code Example

The Voting Widget doesn’t offer an option to automatically share an item that is voted on. To add this feature, paste the code below into a Code Widget.

  $(function() { // <- This function gets executed when the document is loaded and ready
    // create a handler for the success.vote event
    $('.ss_voting').on('success.vote', function(event, entry) {
      // search for a share link within the entry that was voted on
      var share_link = $('.share_link', entry);
      // test if the share link exists
      if (share_link.length > 0) {
        // a link was found, so "click" it for the user to invoke the share prompt
        share_link.click();
      }
    });
  });

Related articles