Kinetic Request / Kinetic Survey

  Version 5.0.3

Kinetic Request / Kinetic Survey
Search:
 
Filters

Javascript API documentation for Kinetic Request & Kinetic Survey

Many of the functions contained here are called automatically when creating events within one of the Author consoles. However, there are situations where a customer may want to write custom javascript to perform a task beyond the capabilities of the events/actions provided. The information in these documents should assist developers in those scenarios.

Choose a module, class, or file from the list on the left for more information.

Minified Files

Minimized versions of all the files are also provided. The javascript files have also been minimized by removing all comments and whitespace characters to make the file sizes smaller for faster load times. In addition to each individually minified file, two combined files exist: kd_complete.js, and kd_core.js.

The complete file (kd_complete.js) contains all the javascript resouce files bundled up into one file for ease of use. The three core files (kd_actions.js, kd_utils.js, and kd_client.js) have been bundled together into a single minified file called kd_core.js.

The fully documented version, and the minified version of each file referenced here are installed on your web server(s) when installing Kinetic Request and/or Kinetic Survey. They can typically be found at {webserver}/kinetic/resources/js/.

For troubleshooting purposes, the original files may be loaded by adding the '&debugjs=true' parameter to the end of the URL.

Custom Code

Custom javascript functions can be attached to a service item in a few different ways. If the function will only be used on a single service item, then the code is usually placed in the CustomHeaderContent field on the advanced tab of the specific template/service item, or in an external javascript file that added as an attachment to the service item on the advanced tab. If the function will be used by more than one service item, it is best placed in an external javascript file, and the javascript file can be included by the the display JSP page.

Examples - (click title to view/hide code)

Simple Data Request

A simple data request (SDR) consists of a client-side Ajax request, and a server-side database query to the AR Server. The event that creates this SDR is responsible for building up both the client-side code and the server-side database query.

For the client-side, the javascript portion of the code consists of an HttpXmlRequest or ActiveXObject object, and a callback object that defines parameters for the database query and how to render the query once it completes.

A simple data request is typically created using a Custom event action. It may be triggered in many ways, such as on page load, click of a link or button, or change of a field value.

This example checks if there are any broadcast messages for the user, and if so, display a javascript alert message indicating this, and then the broadcast messages are inserted into a div element on the page.

Code Example

/*
 * This code builds up an Ajax object, a callback object, and the functions to 
 * handle success or failure.
 */
 

/*
 * The argument passed to the callback handler functions consists of an object 
 * that represents the response to the Ajax request.  It contains five properties
 * of significance:
 *   status       - the status code returned from the server (usually 200 for success)
 *   statusText   - the text value of the status code (usually 'OK' for success)
 *   responseText - the resulting text/html after rendering the results through the JSP
 *   responseXML  - if no JSP was specified then the raw XML results, else null
 *   argument     - an array of ids for the elements specified in the third parameter of 
 *                  the KD.utils.Callback object.  If an array was specified in the
 *                  callback, the array would be available at o.argument[0]
 */

 
 
/*
 * The success callback function for the simple data request.  This function is 
 * called when the SDR completes successfully.  In this example, this function will
 * display a message to the user, and add the contents of the response to the 
 * element's innerHTML property.
 *
 * @method hSuccess
 * @param {Object} o the response object
 * @return void
 */
function hSuccess (o) {
    // the result is stored in the response object o
    if (o && o.responseText != '') {
        // alert the user
        alert('You have new messages');
        // add the messages to the broadcast messages element
        KD.utils.Action._addInnerHTML(o);
    }
}

/*
 * The failure callback function for the simple data request.  This function is 
 * called when the SDR fails due to a server error or a timeout.  In this example, 
 * this function will clear the value of the broadcast messages.
 * @method hFailure
 * @param {Object} o the response object
 * @return void
 */
function hFailure (o) {
    var elId = o.argument[0][0];
    var el = document.getElementById(elId);
    if (el) {
        // clear the messages from the broadcast div container
        el.innerHTML = '';
    }
}

/* 
 * Define the callback object  --  See KD.utils.Callback
 * on a successful request, call the hSuccess handler function.
 * on a failed request, call the hFailure handler function.
 * for Simple Data Requests, the third parameter defines the element ids to 
 * pass into the 'arguments' property of the response object.
 * the last parameter indicates that a loading image should be displayed while 
 * this request is active
 */
var cb = new KD.utils.Callback(hSuccess, hFailure, ['broadcasts'], true);


/* 
 * Define the parameter key/value pairs that will be passed to the SDR 
 * qualification.
 * the SDR will look for any parameter keys in its query, and substitute 
 * the key with with the parameter value before sending the query.  This 
 * allows you to define dynamic qualifications and pass values from the client-side
 * to customize the query results.
 * 
 * This example shows two key/value pairs being passed to the SDR qualification.
 */
var params = 'clientManager.userName=' + clientManager.userName;
params += '&status=Active';


/* 
 * Execute the Ajax request  --  See KD.utils.Action.makeAsyncRequest
 *
 * the first parameter is just a name for the request, it can be any value
 * the second parameter is the instanceId of the Simple Data Request in the database
 *     this tells the application what simple data request definition to use for 
 *     the query.
 * the third parameter is the KD.utils.Callback object that defines the success and
 *     failure handlers, along with the element ids that are passed to the handler,
 *     and whether to display a loading image to indicate an Ajax request is in
 *     progress.
 * the fourth parameter passes the parameter string built up above.  If no parameters 
 *     are needed in the query, just pass the empty string ''.
 * the fifth parameter defines the JSP page to use to format the results that 
 *     are returned.
 * the sixth parameter tells the application whether it should try to retrieve all
 *     records as a list (true) or as full entries (false).  If this paramter is true, 
 *     all fields that need to be used in the JSP must be included in the 
 *     'FieldsAvailable' field in the SDR.
 * the seventh parameter instructs the request to made asynchronously (false), 
 *     or synchronously (true).  Be careful when using synchronous requests, as 
 *     the browser will be unresponsive until the request completes.
 */
KD.utils.Action.makeAsyncRequest(
    'getClientName',
    clientAction.actionId,
    cb,
    params,
    '../../themes/my_theme/partials/result',
    false,
    false
);

URL Parameters

This example shows how to retrieve the value of a URL parameter, and set the value of a question with the value. This code would likely be placed in the custom code field of a Custom event action.

Code Example

/*
 * Use the convenience method KD.utils.Util.getParameter to retrieve the value
 * of the parameter by name.
 */
var email = KD.utils.Util.getParameter('email');

/*
 * Once the value is obtained, set the value of a question on the page with 
 * the parameter value.  No need to check if the value is null here, because
 * KD.utils.Action.setQuestionValue handles this for us.
 */
KD.utils.Action.setQuestionValue('Email', decodeURIComponent(email));

Compare Date Question with Current Date

The following javascript is meant to compare the value of a date question to the current date. This is an example of an event that is not provided "out of the box" with Kinetic Request / Kinetic Survey, but may be useful to implement.

Comments in the code show the purpose for the different parts of javascript used. This code would be called on a beforeSubmit event on the Page where the date questions are located. The action would be custom, and you will need to insert the question menu label for the specific date questions as the parameters of the function.

Code Example

// This function is called in the beforeSubmit event on the page the holds the related date question
function dateCheck(questionLabel){
    // The questionLabel parameter is the 'Menu Label' for the date question to check
    // It is on the on the answers tab of the question

    // nowDate holds the current date
    var nowDate = new Date();

    // The array builds up the values needed by the KD.utils.Action.setQuestionValue function if it is called
    var nowDateArray = new Array();
    nowDateArray[0] = nowDate.getFullYear();
    nowDateArray[1] = nowDate.getMonth() + 1;
    nowDateArray[2] = nowDate.getDate();

    // KD.utils.getQuestionValue returns the value hidden date question from the template
    var qstnDate = KD.utils.getQuestionValue(questionLabel);

    // The hidden date field stores the date as a character string.
    // The following steps get the individual values, turn them into integers,
    // and make them into a readable date format
    var qstnDateString = qstnDate.split('-');
    var qstnDateInt = new Array();
    qstnDateInt[0] = parseInt(qstnDateString[0],10);
    qstnDateInt[1] = parseInt(qstnDateString[1],10);
    qstnDateInt[2] = parseInt(qstnDateString[2],10);

    var qstnDateFinal = new Date();
    qstnDateFinal.setFullYear(qstnDateInt[0], (qstnDateInt[1] - 1), qstnDateInt[2]);

    // Finally, the two dates are compared
    if (nowDate > qstnDateFinal)
    {
        // personalized message to the user that date is not acceptable
        alert(questionLabel + 'must be set after the current date');
        KD.utils.Action.setQuestionValue(questionLabel, nowDateArray);
        // a return value of false will stop the submit process
        return false;
    }
}

Compare Two Date Questions

The following javascript is meant to compare the value of one date question to the value of a second date question. This is another example of an event that is not provided "out of the box" with Kinetic Request / Kinetic Survey, but may be useful to implement.

Comments in the code show the purpose for the different parts of javascript used. This code would be called on a beforeSubmit event on the Page where the date questions are located. The action would be custom, and you will need to insert the question menu label for the specific date questions as the parameters of the function.

Code Example

// this function is called in the beforeSubmit event on the page that holds the date questions.
function dateCheck(qstnLabelStart, qstnLabelEnd){
    // qstnLabelStart & qstnLabelEnd are the menu labels of the two date questions from the template

    // first, the current date is stored so it can be put back into the date fields if the error comes up
    var nowDate = new Date();

    var nowDateArray = new Array();
    nowDateArray[0] = nowDate.getFullYear();
    nowDateArray[1] = nowDate.getMonth() + 1;
    nowDateArray[2] = nowDate.getDate();

    // The KD.utils.Action.getQuestionValue function retrieves the value from the 
    // date questions on the template
    var qstnStartDate = KD.utils.Action.getQuestionValue(qstnLabelStart);
    var qstnEndDate = KD.utils.Action.getQuestionValue(qstnLabelEnd);

    // The hidden date field stores the date as a string, so the following steps grab the individual
    // values convert them to integers and make a date out of them.
    // This is repeated for both Start and End dates.
    
    // It would be wise to create a function that split the date fields,
    // and returned the array. 
    var qstnStartDateString = qstnStartDate.split('-');
    var qstnStartDateInt = new Array();
    qstnStartDateInt[0] = parseInt(qstnStartDateString[0],10);
    qstnStartDateInt[1] = parseInt(qstnStartDateString[1],10);
    qstnStartDateInt[2] = parseInt(qstnStartDateString[2],10);

    var qstnStartDateFinal = new Date();
    qstnStartDateFinal.setFullYear(qstnStartDateInt[0], (qstnStartDateInt[1] - 1), qstnStartDateInt[2]);

    var qstnEndDateString = qstnEndDate.split('-');
    var qstnEndDateInt = new Array();
    qstnEndDateInt[0] = parseInt(surveyEndDateString[0],10);
    qstnEndDateInt[1] = parseInt(surveyEndDateString[1],10);
    qstnEndDateInt[2] = parseInt(surveyEndDateString[2],10);

    var qstnEndDateFinal = new Date();
    qstnEndDateFinal.setFullYear(qstnEndDateInt[0], (qstnEndDateInt[1] - 1), qstnEndDateInt[2]);

    // Finally, the dates are compared
    if (qstnStartDateFinal > qstnEndDateFinal)
    {
        // A message warns the user of the error and the two fields are set back to the current date (default)
        alert('Selected End Date must be set to after the Start Date');
        KD.utils.Action.setQuestionValue(qstnLabelStart, nowDateArray);
        KD.utils.Action.setQuestionValue(qstnLabelEnd, nowDateArray);
        //the return value of false stops continued processing of the submit action
        return false;
    }
}

Set a Date Question



This example shows how to set the value of a date question to a specified number of days after the current date.

Comments in the code show the purpose for the different parts of javascript used. This code would be called on a load event on the Page element where the date question is located. The action would be custom, and you will need to pass two pieces of information to the function as parameters:

  • questionLabel - The menu label of the date question to set (string)
  • numDays - The number of days to add to the current date (integer or string)

Code Example

// This function is called in the load event on the page the holds the related date question
function dateAddDays(questionLabel, numDays){
    // The questionLabel parameter is the 'Menu Label' for the date question to set
    // It is on the on the answers tab of the question

    // Create a placeholder for the the current date
    var nowDate = new Date();
    
    // Make sure the numDays parameter converts to an integer, otherwise set to 0 and the 
    // current date will be used
    var numDays = parseInt(numDays, 10) || 0;
    
    // Add the number of days to the current date
    nowDate.setDate(nowDate.getDate() + numDays);
    
    // convert the date to an array
    var dateArr = [];
    dateArr[0] = nowDate.getFullYear();
    dateArr[1] = nowDate.getMonth() + 1;
    dateArr[2] = nowDate.getDate();
    
    // Set the question value with the calculated date array
    KD.utils.Action.setQuestionValue(questionLabel, dateArr);
}
An example of using this function to set the question value to 7 days after the current date:
dateAddDays('My Date Question Label', 7);

Copyright © 2011 Kinetic Data Inc. All rights reserved.