Using Variables

A variable is a placeholder in your script that you use to store a value. A variable always has a name that you can use to represent its value. You can use the name of a variable to store something or retrieve it. Variable names, also known as identifiers, must begin with an underscore “_”, or letter that you can follow with letters, underscores, and digits. Here are some sample variable names:

myVariable? 
Number_Of_Inspections? 
Test12?

In this document, we always begin our variable names with a lower case letter, and capitalize the first letter of each subsequent word in the variable name. We recommend, but do not require, this method of variable naming. Let us look at an example of putting a value into a variable.

myVariable = 12; 
aa.print(myVariable);

This script displays this output:

The first line of this script puts the value 12 into myVariable. The second line uses the print method of the aa object that we investigated earlier, but instead of putting a string of characters in between the left and right parentheses of the print method, we have put the name of our variable. This usage tells the print method to display whatever value myVariable contains. We can also put strings of characters into variables. Here is a script that uses a string as the value of myVariable:

myVariable = “Hello World.”; 
aa.print(myVariable);

This script displays this output:

Hello World.

Another technique that we can use is to assign the value of one variable to the value of a different variable. Here is an example:

firstVariable = 101; 
secondVariable = firstVariable; 
aa.print(secondVariable);

This script displays this output:

In this script, we assign the value 101 to firstVariable, and then assign the value of firstVariable to the value of secondVariable. Finally, the script prints out the value of secondVariable. When you use firstVariable on the right side of an equals sign, we call this evaluating a variable. To evaluate a variable is to retrieve its value. We are also evaluating a variable when we pass secondVariable to the print method of the aa object. One might ask, what happens if we try to evaluate the value of a variable to which you did not assign a value. For example,

firstVariable = 101; 
aa.print(secondVariable);

This script displays this output:

An error occurred while running your script. 
ErrorType: org.mozilla.javascript.EcmaError 
Error Detail: 
?undefined: "secondVariable" is not defined. (script; line 1)

In this example, we removed the second line of the script. This means there is no line in the script that assigns a value to secondVariable, but on the last line of the script, we try to print out the value of this variable. You receive an error if the script tries to evaluate a variable without an assigned value. When we try to execute this script we see an error message in the output box. The error message tells us that secondVariable is not defined.

There are many potential causes for errors. Civic Platform error messages provide meaningful information to help you solve problems with your scripts. Script writers frequently misspell variable names, so It is a good idea to look carefully at your scripts, check for misspellings, missing semi-colons, and missing parentheses.

Topics:

Numbers
Strings
True and False
Arrays
The Special Value “null”
Objects

Numbers

There are many kinds of numbers you can assign to a variable. We do not provide an exhaustive list here, but we do go over some of the common kinds of numbers that we deal with. Numbers can be positive, negative, zero, integers, decimals, and have exponents and other characteristics. Here are some sample numbers:

The last two sample numbers have an exponent. You probably do not need to use the exponential form of a number, but if your script ever encounters a very large or very small number, then tries to print that value, it may appear in the exponential form. The number after the E is the number of places to the right that you should move the decimal point to get the non-exponential form of the number. If the number after the exponent is negative, it represents the number of places to the left that you need to move the decimal point to get the non-exponential form. If you find that you need to use a kind of number not mentioned here, we encourage you to look up more information on numbers in a JavaScript reference text.

Precision of Numbers

The precision of a number is the number of decimal digits in that number. You can use mathematical expressions (see Mathematical Expressions) or functions (see Using Functions) in your scripts to get various numbers. Because Civic Platform applies the Java class BigDecimal to control the precision of results for mathematical functions, but not for mathematical expressions. If your expected result is a number with decimal part, use mathematical functions instead of expressions to ensure the precision of the result.

With mathematical functions including add, subtract, multiply, divide and round, the default DEF_DIV_SCALE value is 2. You can customize DEF_DIV_SCALE.

For example:

aa.print(123.3 / 100); // The precision in the expression is out of control. 
aa.util.multiply(4.015, 100); // result: 401.5 
var DEF_DIV_SCALE=3 
aa.util.divide(123.3, 100) //default scale=2, result: 1.23 
aa.util.divide(123.3, 100, DEF_DIV_SCALE) // result: 1.233 
aa.util.round(12.1542, 1) // result: 12.2 
aa.util.round(12.1542, 2) // result: 12.15

Strings

Strings comprise a number of characters in between a pair of double or single quotes. Here are some examples:

“Hello World.” 
“This string is surrounded by double quotes.” 
‘This string is surrounded by single quotes.’ 
‘Ok’ 
‘A’ 
‘!’

These examples show that a string can be one or many characters long, surrounded by single or double quotes. The following example shows that a string can consist of digits.:

“12345”

Escape Characters

The next example shows a string with a special escape character inside:

“Four score and \n seven years ago.”

The escape character is the backslash “\” character that you follow with the “n” character. This special character means go to the next line down when printing out this string. This special character calls the new line character. Here is a sample script that prints out this example:

aa.print(“Four score and \n seven years ago.”);

This script displays this output:

Four score and 
 seven years ago.

All special characters begin with a backslash. Let us look at the most commonly used special characters:

Table 1. Common Special Characters in Scripting
Special Character	Definition
`\n`	New Line
`\t`	Tab
`\’`	Single quote
`\”`	Double quote
`\\`	Backslash

Because we use the single and double quotes to determine the ends of the string, we can only put them into a string by using the special character that represents them. Because we use the backslash to start a special character, we must use a double to put a backslash into a string. Other special characters allow you to insert characters from foreign languages, insert special symbols, and insert other character types. If you find that you need to use these other special characters, consult a standard JavaScript reference book.

True and False

Now we encounter a new kind of variable type that we have not seen before. We call this type of variable Boolean. These variables can only hold either true or false. Here is an example:

aTrueVariable = true; 
aFalseVariable = false;

In this example, we assign the true value to one variable and the false value to the other variable. Unlike string values, you do not enclose the true and false values in quotes. You can assign these two words to variables as special values. You typically use Boolean variables as parameters for methods of objects or for controlling what happens next in your script. We see some examples of how to use Boolean variables later in this document.

Arrays

An array is a special kind of variable that hold a list of values, and allows you to retrieve and store each of the values separately. Here is an example of creating and using an array:

myVar = new Array(); 
myVar[1] = "Hello"; 
myVar[2] = "World"; 
aa.print(myVar[1]); 
aa.print(myVar[2]);

This script displays this output:

Hello 
    World

The first line of the example tells Civic Platform that myVar is of the special Array type, that is, assign a new empty Array object to myVar. So we can say that myVar contains an array object. The second line of the script puts the string “Hello” in number one position of the array. The third line put the string “World” in the number two position of the array. The fourth line prints out the value stored in the number one position of the array. The fifth line prints out the value stored in the number two position of the array. You can store and retrieve values in any position of the array you like. There is also a position zero, and negatively numbered positions, but most of the time you only use the positively numbered positions.

You can find out how long an array is by using a property of all arrays. Here is an example:

myVar = new Array(); 
myVar[1] = "Hello"; 
myVar[2] = "World"; 
aa.print(myVar.length);

This script displays this output:

Note that we are printing out something called myVar.length on the last line of the script. Whenever we need to know the length of an array we can always put “.length” after it to get the length. Length is a property of our array. We learn about more arrays and how properties work in the section Objects, Methods, and Properties later in this document. You may ask, if we assigned something to position one and two then why is myVar.length returning three? The answer is that we count position zero in the length of the array. Let us modify this example slightly and see what happens:

myVar = new Array(); 
myVar[1] = "Hello"; 
myVar[4] = "World"; 
aa.print(myVar.length); 
aa.print(myVar[2]);

This script displays this output:

5 
undefined

We changed the third line to put a value in position four rather than in position two. The result is that the total length of the array is now five. There are empty elements in the array at positions 0, 2, and 3. On the last line of the script we tried to evaluate myVar[2] and received a special value called undefined that tells us that we never put anything into the array at that position.

The Special Value “null”

The word null in a script means nothing. Some methods of some objects allow you to pass null in as the value of a parameter, usually to indicate that you do not want to send in any meaningful value for that parameter. We see a little later that Civic Platform may return null to your script when you try to retrieve some information from Civic Platform, usually to indicate that no information is available. We see some of the specific places that use null later in this document.

Objects

A variable can also contain an object. An object is a self-contained module of data and its associated processing. Lets look at an example:

myVar = aa; 
myVar.print(“Hello World.”);

This script displays this output:

Hello World.

Here we can see that we assigned the aa object to the myVar variable on the first line of the script. This assignment means that myVar contains the aa object. We then used myVar to execute the print method of the aa object. Here is another example:

myVarOne = aa; 
myVarTwo = aa; 
myVarOne.print(“Hello”); 
myVarTwo.print(“World”);

This script displays this output:

Hello 
World

Notice that we assign the aa object to both of the variables in this script, and then call the print method on each one. This example shows us that what really happens when you assign an object to a variable is that the variable is only pointing at the object. The variable becomes like a handle to the object that you can use to manipulate it. You can have many variables that all point at the same object.

We look deeper into object in the section Object, Methods, and Properties later in this document. We learn more about variables as we learn about other aspect of writing scripts.