cmSurvey Functions

This article will provide a list of all the cmSurvey functions available. 

Background

The cmSurvey functions listed below can be used to help make some of your custom functionality work. These are available for use within the Custom JavaScript fields, and any <script> tag you add in your survey html.

cmSurvey Functions List

• disableBackButton: Disable/enable the back button without hiding it.
  • @param {boolean} disable

  • cmSurvey.disableBackButton(disable)

  • It also adds/removes the class cm-button-disabled to the back button.
  • Examples:
    • cmSurvey.disableBackButton(true); // Disables the back button.
    • cmSurvey.disableBackButton(false); // Enables the back button.
• disableNextButton: Disable/enable the next button without hiding it.
  • @param {boolean} disable

  • cmSurvey.disableNextButton(disable)
    

  • It also adds/removes the class cm-button-disabled to the back button.
  • Examples:
    • cmSurvey.disableNextButton(true); // Disables the next button.
    • cmSurvey.disableNextButton(false); // Enables the next button.
• hideBackButton: Hide/show the back button.
  • @param {boolean} hide

  • cmSurvey.hideBackButton(hide)

  • It also adds the class cm-hidden to the back button.
  • Examples:
    • cmSurvey.hideBackButton(true); // Hides the back button.
    • cmSurvey.hideBackButton(false); // Shows the back button.
• hideNextButton: Hide/show the next button.
  • @param {boolean} hide

  • cmSurvey.hideNextButton(hide)

  • It also adds the class cm-hidden to the next button.
  • Examples:
    • cmSurvey.hideNextButton(true); // Hides the next button.
    • cmSurvey.hideNextButton(false); // Shows the next button.
• onPageLoad: Execute code after the current page initially loads.
  • @param {function} callback

  • cmSurvey.onPageLoad(callback)

  • IMPORTANT NOTE: Don't use this function on the dedicated JavaScript question field, as these fields are already wrapped on their own onPageLoad event. If you do, then your listener will effectively be added after the event has already passed, and could potentially fire until the next page loads.
  • Examples:
    • cmSurvey.onPageLoad(function () { alert('Hi!'); }); // Will show an alert with the content "Hi!" when the current page loads.
• onLoad: Execute code after each page load. This function should be added to the header of the survey to ensure it's still executed if a respondent refreshes the survey or resumes into the survey.
  • @param {function} callback

  • cmSurvey.onLoad(callback)

  • Examples:
    • cmSurvey.onLoad(function () { alert('Please pay attention to this page'); }); // Will show an alert with the content "Please pay attention to this page' every time a new page is loaded (first page, and after a every successful submit).
• handleIframe: Add a listener for an iFrame message event. This is to communicate events from inside the iFrame to the survey. For instance, this can be used to track clicks inside of a prototype and store the data inside the survey. If the message is a stringified JSON, it will also deserialize it automatically into a JS object. From within the iframe, you have to use the JS postMessage function (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
  • @param {function} callback(event, data)

  • cmSurvey.handleIframe(callback)

  • Examples:
    • Send a plain text message:
      • Within the iFrame, the following code would throw the event:
        • window.parent.postMessage('headerClick', '*');   // Sends a 'headerClick' message to the parent window.
      • Within the survey, the following code would listen to the event:
        • cmSurvey.handleIframe(function (event, data) { if (event.data === 'headerClick') { /* Do something */ } }); // This code would "do something" if the "headerClick" message is received.
    • Send an object in the message:
      • Within the iFrame, the following code would throw the event:
        • window.parent.postMessage(JSON.stringify({source:'pageChange', page: 1}), '*');   // Sends a message to the parent window with an object that has two properties.
      • Within the survey, the following code would listen to the event:
        • cmSurvey.handleIframe(function (event, data) { if (event.data.source === 'pageChange') { /* Do something */ } }); // This code would "do something" if the object's source property is equal to "pageChange".
• popup: used to programmatically trigger popups created following the cm-popup spec (Click to enlarge example).
  • @param {string} popupName

  • cmSurvey.popup(popupName)

  • Examples:
    • cmSurvey.popup('b1'); // This would open the popup with the name 'b1' in the current page