Category:JavaScript Reference

JavaScript is a computer programming language. It is one of the most widely used languages due to its use in web development. Refer to the Internet (e.g., searching using Google) for more details, examples, online courses, etc.

Introduction to JavaScript and its use in Q

The best way to start is to use the Online Training tutorials, shown at the top-right corner of this page.

The page JavaScript Tips outlines some of the general principles of JavaScript, focusing on aspects that are different to the various syntax languages widely used in market research (e.g., SPSS, Uncle).

The page Writing ‘Real’ Code introduces some more powerful aspects of JavaScript (see also the links at the end of that page).

JavaScript functions

When creating JavaScript Variables it is often sufficient to write simple mathematical expressions, such as var1 + var2. However, from time-to-time, it is useful to use functions, which take one or more inputs and compute an output.

Standard JavaScript functions

In Q, the only widely used standard JavaScript function is isNaN(). This is a function that takes a single input and determines whether the input is numeric. For example, isNaN(123) returns a value of false, whereas a true is returned by isNaN("Dog") and also by isNaN(NaN). Note that in Q NaN indicates a missing value, so isNaN() is a way of working out if a variable in Q contains missing values or not, and it is common to combine this with the Not Logical Operator (i.e., !isNaN(NaN) will return a value of false).

Functions for getting input from users

When using JavaScript to write QScripts, it is often useful to create dialog boxes. JavaScript comes with some standard functions for doing this. If you create and run a QScript that contains alert('Hello World!'), a dialog box will appear which says 'Hello World' with an OK button. The function confirm() essentially creates the same dialog box as alert(), but it remembers whether the user clicked OK or Cancel, so it can be used in an if statement. The function prompt() instead asks the user to enter text into a box.

Q also provides additional functions for obtaining inputs from users:

• QScript Selection Functions create dialog boxes for use in QScripts.
• User Input for Rules contains functions for creating user interfaces for Rules. Conceptually these are a little more tricky to use, so please first read Objects and methods.

Writing your own functions

You can also create your own functions in JavaScript. For example, if you include the following in your code:

function isNumber(x) {
    return isFinite(x) && !isNaN(parseFloat(x));
}

you can then, later in the code, use this function (e.g., isNumber(123)). ^{[note 1]}

Examples

Many different JavaScript functions are provided on this wiki as examples. These are collected in four sections on this Wiki. The first contains general-purpose examples. The rest contain examples specific to different applications of JavaScript within Q:

• JavaScript Examples Library
• JavaScript Variables Examples Library
• QScript Examples Library
• Table JavaScript and Plot JavaScript Examples Library

These examples can all be cut and pasted into your own code. However, if doing this make sure that you also copy and paste any functions that are used within these functions. Many of these examples are also included in the Online JavaScript Libraries and it is often easier to instead use these libraries. If a function is on a page which shows Category:Online JavaScript Libraries at the bottom, then the name of the page is its name in the library.

Libraries

A library is a collection of related functions. In order to use a function that is a part of library, you need to tell Q that you wish to use that library. There are two different ways to do this For the most commonly used libraries, you add a prefix to the function. For example, the following expression:

Q.AsNumeric('dog1')

returns a value of 1 (i.e., it removes the non-numeric aspect of dog1), where Q. tells Q to find the function called AsNumeric in the Q library. Other libraries are not built into Q, but must be explicitly loaded using includeWeb('library name') at the beginning of your code (see Online JavaScript Libraries).

Math

Commonly used mathematics functions are in the Math. library. For example, Math.max(11, 5, 49) returns 49. See JavaScript Mathematical Functions.

jstat

The jstat statistical library contains a large number of statistical functions. For example, jStat.normal.inv(0.975, 0, 1) returns a value of approximately 1.96. Note that from time-to-time usage of this library will lead to computation of slightly different results to those in Q, due to rounding errors.

Q

Q comes with its own library of special-purpose functions. For example, Q.EncodeDate(2001, 12, 30) returns a value of 1009670400000, which is the number of of milliseconds since 1/1/1970 (this is how Date questions are stored in Q).

Online JavaScript Libraries

In addition to Q's JavaScript Library, less-commonly-used functions are available and can be 'called' (i.e., made available) using includeWeb. For example, if the following is saved and run as a QScript:

includeWeb("JavaScript Utilities");
alert(isNumber("dog"))

it will create a dialog box showing false.

Libraries called in this way are downloaded from the internet when they are used, which means there will be a small delay before they are run and they will not work when offline. You can work around this by copying and pasting the code from the internet into your own code.

You can find a full list of these libraries at Online JavaScript Libraries. Most of these are designed for use with QScript.

Note that these online libraries only work for Table JavaScript and Plot JavaScript and QScript. If you require these libraries for use in writing JavaScript for a variable, you will need to copy and paste the relevant code into your variable(s).

Objects and methods

JavaScript is an object-oriented programming language. Many of the 'things' in Q are objects. For example, each table that you create in Q is an object. Each question in Q is an object. A data file is also an object. And, even a string of text, such as "My big fat dog" is an object.

A method is a function that can be used to do something to an object.

The following code, has an object called project and uses the method addDataFile to add a data file to the project:

project.addDataFile("phone.sav", null, { auto_tidy_labels: true,
                    auto_detect_questions: false,
                    strip_labels_html: true });

This next example, again refers to the object called project, and extracts the first data file in that object (i.e., this is what project.dataFiles[0] means). It then uses the method getQuestionByName to extract a question called Age from this data file. The next line, extracts a part of the question object, called the dataReduction, which stores how categories are merged on tables, and uses the method hide to hide the Don't know category.

var age = project.dataFiles[0].getQuestionByName('Age');
age.dataReduction.hide("Don't know");

The most straightforward way to get across these concepts and how they work in practice is to work your way through Worked Examples, which the examples above are extracted from.

Notes

Template:Reflist
Cite error: <ref> tags exist for a group named 'note', but no corresponding <references group='note'/> tag was found