|
|
ION Script User's Guide: Variables, Expressions & Operators |
|
System variables are built-in ION Script variables used to hold useful information about ION Script applications. Each system variable can have multiple variables associated with it. You refer to these variables using the following general syntax:
$SystemVariable.VariableName
where $SystemVariable is $Browser, $Document, $Form, $FormURL, $ION, or $Mouse, and VariableName is the specific variable name for the specified system variable. Some system variables have only built in variables associated with them, such as $Mouse, which has $Mouse.x and $Mouse.y. Other system variables are assigned variables by the user, such as $Form, when the user defines an INPUT element.
| Note System variables are case-insensitive, except for any variables specified by the $Browser system variable. The $Browser system variable is used to specify actual CGI environment variables, such as HTTP_USER_AGENT. CGI environment variables are case-sensitive. |
The $Browser system variable can be used to access any CGI environment variable. CGI environment variables contain various information about the request, such as the server software being used, the hostname making the request, and whether the request was made using the GET or POST method.
One CGI environment variable in particular, HTTP_USER_AGENT, is useful in determining the type and version of the browser being used to request the page. Determining the browser version and type is useful when your application has content that cannot be rendered by all browsers. Browser vendors often incorporate proprietary "extensions" to HTML that add functionality to their product, but that are not supported by other browsers. It is generally recommended that you limit your use of browser-specific, proprietary features, but when used, you are strongly encouraged to provide alternate content that can be viewed by any browser. One technique for ensuring that users of different browsers will all see your content in the manner best suited to their browsers is to determine the browser type and version, and redirect users to the appropriate page for their browser. It is beyond the scope of this document to discuss these techniques in detail, but extensive information on the subject can be found in many HTML and JavaScript/VBScript references.
The CONTAINS operator can be used to check the $Browser.HTTP_USER_AGENT variable for a browser type or version. For example, the following code could be used to determine if the browser is Microsoft Internet Explorer:
<ION_SCRIPT> <ION_BODY> <ION_IF EXPR="$Browser.HTTP_USER_AGENT CONTAINS 'MSIE'"> You are using Internet Explorer. </ION_IF> </ION_BODY> </ION_SCRIPT>
See http://hoohoo.ncsa.uiuc.edu/cgi/env.html for a list of CGI environment variables.
| Warning Assigning $Browser.REMOTE_USER as a string variable to the VALUE attribute can be dangerous because it is frequently an undefined system variable. When VALUE is undefined, IDL reports an error. However, it is possible that code that uses $Browser.REMOTE_USER could be implemented and tested without error on one system and fail if ported to another system. |
The $Document system variables store the metadata defined in the header section. For example, if the header section of your ION Script page contains the tag
<TITLE>My Title</TITLE>
then $Document.TITLE contains the text "My Title".
The application name, defined with the <APPLICATION> tag.
The document author, defined with the <AUTHOR> tag.
The copyright statement, defined with the <COPYRIGHT> tag. To add a copyright statement to your ION Script page, you can use the COPYRIGHT and ION_VARIABLE tags as follows:
<ION_SCRIPT> <ION_HEADER> <COPYRIGHT>Copyright 2004 ITT Visual Information Solutions, </COPYRIGHT> </ION_HEADER> <ION_BODY> <ION_VARIABLE NAME="$Document.COPYRIGHT"/> </ION_BODY> </ION_SCRIPT>
You can control whether or not the © symbol appears before the copyright statement using the Format tab of the configuration utility. See Include © when displaying $Document.COPYRIGHT.
The date the document was created, defined with the <DATE> tag.
A variable of type STR that contains the name of the event that triggered the current page to be loaded. If no event triggered the page, its value is 'page'. Therefore, 'page' is an illegal name for an event. The following two ION Script pages demonstrate the use of $Document.EVENT.
page1.ion:
<ION_SCRIPT> <ION_HEADER> <EVENTS> <EVENT_DECL NAME="PASSEVENT" ACTION="page2.ion"/> </EVENTS> </ION_HEADER> <ION_BODY> <ION_FORM> <ION_BUTTON EVENT="PASSEVENT" LABEL="Load page via an event" TYPE="BUTTON" /><BR> </ION_FORM> <FORM ACTION="http://myserver/cgi-bin/ion-p"> <INPUT TYPE="HIDDEN" NAME="page" VALUE="ion://page2.ion"> <INPUT TYPE="SUBMIT" VALUE="Load page via an HTML form"> </FORM> </ION_BODY> </ION_SCRIPT>
page2.ion:
<ION_SCRIPT> <ION_BODY> <ION_IF EXPR="$Document.EVENT NE 'page' "> The <ION_VARIABLE NAME="$Document.EVENT"/> loaded this page <ION_ELSE/> This page was not loaded from an event </ION_IF> </ION_BODY> </ION_SCRIPT>
The date the document was last updated, defined with the <LASTUPDATE> tag.
The document title, defined with the <TITLE> tag.
$Form variables are variables that arrived in the page as the result of one of the following:
$Form variables are always treated as strings. Form variables are referred to using the following syntax:
$Form.Formvar
Formvar can be any of the following:
<INPUT NAME="MyVar" TYPE="TEXT" VALUE="Hello">
On the action page of this form, you would refer to the value of this form field as follows:
$Form.MyVar
| Note You cannot access the value of a $Form variable on the page in which the form field is defined. The value is not available until the form has been submitted. |
To use a $Form variable in a numeric expression (using ION_IF or ION_EVALUATE), you must declare a variable as an INT or DOUBLE using VARIABLE_DECL, and assign this variable the value $Form.NAME, where NAME is the NAME attribute of the form field or ION_LINK, or the name in a name/value pair passed in a URL. This converts the string variable — $Form variables are always string variables — to the type you desire. When writing the expression, you then use this new variable instead of using the $Form variable. For example:
<ION_FORM> <INPUT NAME="Age" TYPE="TEXT" VALUE="35"> </ION_FORM>
In the page that is called, you would define a variable as follows:
<VARIABLE_DECL NAME="AGE" VALUE="$Form.Age" TYPE="INT">
This variable needs to be defined only on pages that use the $Form variable in a numeric expression. You then use this new variable in place of the $Form variable in a numeric expression, such as in the following example:
<ION_IF EXPR="$AGE GT 30"> <!--$AGE is $Form.Age -->
The reason for this requirement is that $Form variables are always treated as strings. Since strings and numerics cannot be used together in a numeric expression (except to concatenate a numeric to a string using the + operator), creating a numeric variable equal to the form variable allows you to use the form variable in a numeric expression, such as an expression using a comparison operator.
The $FormURL system variable is equivalent to the $Form variable except that $FormURL returns the string in URL-encoded format. In a URL-encoded string, special characters such as carriage returns and tabs are replaced with codes representing that character. ION Script defines special characters as:
When URL encoded, these special characters are replaced by %hh, where hh is the hexadecimal ASCII value of the character. Carriage returns are replaced by %0D%0A.
| Example Code The IDL program strdecode.pro (located in the ion_script/examples directory) can be used to decode the URL-encoded string in an <IDL> block. |
$FormURL is useful in cases where the user might enter characters that would cause problems when passed in a string directly to IDL, such as carriage returns and quotation marks, as illustrated in the following example.
In this example, a text field is used to enter the x-axis label for a plot. Assume the user enters a label containing an apostrophe (single quotation mark), such as "Doug's Data". The value of $Form.LABEL is the string "Doug's Data". If $Form.LABEL is enclosed in single quotation marks in an <IDL> block, such as with the IDL command
label = '$Form.LABEL'
a syntax error would occur because this would be interpreted by IDL as
label = 'Doug's Data'
This would cause the string to be terminated prematurely in IDL. The $FormURL.LABEL variable is the string "Doug%27s%20Data". This can be decoded in an <IDL> block using the IDL program strdecode.pro as follows:
label = strdecode('$FormURL.LABEL')
Now, label is the string "Doug's Data".
FormURL1.ion:
<ION_SCRIPT> <ION_HEADER> <EVENTS> <EVENT_DECL NAME="PLOT" ACTION="ion://FormURL2.ion"/> </EVENTS> </ION_HEADER> <ION_BODY> <ION_FORM> X-axis Label: <INPUT TYPE="TEXT" NAME="xlabel"> <BR> <ION_BUTTON TYPE="BUTTON" EVENT="PLOT" LABEL="Show Plot"/> </ION_FORM> </ION_BODY> </ION_SCRIPT>
FormURL2.ion:
<ION_SCRIPT>
<ION_BODY>
<ION_IMAGE TYPE="DIRECT">
<IDL>
label = strdecode('$FormURL.xlabel')
plot, [0,1], xtitle=label
</IDL>
</ION_IMAGE>
</ION_BODY>
</ION_SCRIPT>
Another case in which $FormURL is useful is if your ION Script form contains a textarea to allow the user to enter (or paste in) data that is delimited with commas, tabs, spaces, and/or carriage returns. The strdecode.pro program can convert such data into the format you require.
In this example, a textarea is used to enter a two-dimensional array of data for a contour plot. By setting the ARRAY keyword in the call to strdecode, we allow the user to enter a two-dimensional array, where the elements of each row can be separated by spaces, tabs, or commas, and each row is terminated with a carriage return. Therefore, if the user enters data containing multiple rows and columns, this application preserves the format of the data. Note that strdecode creates a string array, therefore, this array must be converted to a numeric array in this example.
textarea1.ion:
<ION_SCRIPT> <ION_HEADER> <EVENTS> <EVENT_DECL NAME="DRAW" ACTION="ion://textarea2.ion"/> </EVENTS> </ION_HEADER> <ION_BODY> <ION_FORM> Enter contour data: <BR> <TEXTAREA NAME="data" ROWS="5"></TEXTAREA> <BR> <ION_BUTTON TYPE="BUTTON" EVENT="DRAW" LABEL="Draw Contour"/> </ION_FORM> </ION_BODY> </ION_SCRIPT>
textarea2.ion:
<ION_SCRIPT>
<ION_BODY>
<ION_IMAGE TYPE="DIRECT" BORDER="0">
<IDL>
; Decode the URL-encoded string into a 2D array
data = strdecode('$FormURL.data', /array)
; Convert to float array
data = float(data)
; Smooth the data
data = min_curve_surf(data)
; Draw the contour plot
contour, data
</IDL>
</ION_IMAGE>
</ION_BODY>
</ION_SCRIPT>
The IDL program strdecode.pro is provided as an example of how you can decode URL-encoded strings. The strdecode command uses the following syntax:
Result = STRDECODE(String [, /ARRAY] [, /NO_SPLIT])
The String argument is the $FormURL string to be decoded.
If ARRAY is set, spaces, commas, tabs, and carriage returns are treated as delimiters, and the scalar string is converted into a string array. If NO_SPLIT is set, a one-dimensional (vector) string array will be returned, otherwise the result will be a two-dimensional string array.
| Note For a two-dimensional array, the first input row is used to determine the number of columns. Rows that contain fewer columns will be filled with null strings, while extra columns will be ignored. |
If NO_SPLIT is set, carriage returns will not be used to split the string into a string array. Carriage returns will remain within the string as characters with the value STRING(13b).
Assume the following data is entered into a textarea (<CR> is a carriage return):
1,2<CR> 3,4<CR> 5,6<CR>
The following table illustrates how the different keyword combinations affect the value returned by strdecode. returns the following Result when decoding $FormURL.DATA using the various keyword combinations:
The $ION system variables are read-only values that contain information about ION Script.
$ION.IDLURL is a read-only string value specifying the URL used to call the ION Script image engine, ion-i.exe. This system variable is used as the value of the DATA attribute of the ION_OBJECT tag (when OBJTYPE is OBJECT), or the SRC attribute of the ION_OBJECT tag (when OBJTYPE is EMBED). Refer to ION_OBJECT for examples on using $ION.IDLURL.
$ION.temp is a read-only string value specifying the location in which ION Script writes temporary files before transferring them to the client. This location is specified on the "Files" tab of the ION Script Configuration Utility (Windows), or in the "Files" section of the .ionsrc file (UNIX). $ION.temp can be used to write files to the temporary directory when writing files from your ION Script application.
$ION.uniqueID is a read-only integer value representing the process number of the ion-p process. Because the process number is unique each time ion-p is executed, this number can be used to create unique filenames when writing files from IDL. This prevents files written by your ION Script application from being overwritten when multiple users are running your application.
| Example Code For an example in which $ION.temp and $ION.uniqueID are used to generate a filename, see the example application largeData.ion in the examples directory. |
$ION.version is a read-only string value specifying the version of ION Script you are currently using.
The $Mouse system variables store the x and y coordinates of the mouse cursor when the mouse is clicked on an ION_IMAGE, an ION_BUTTON of TYPE="IMAGE", or any HTML image created with <INPUT TYPE="IMAGE">.
$Mouse.x stores the x location of the cursor.
$Mouse.y stores the y location of the cursor. Note that when you click an image, the browser considers the origin (0, 0) to be the upper left corner of the image. In IDL, however, the origin of the image is the lower left corner. Therefore, when you want to pass the y location of the mouse click to IDL, you must subtract $Mouse.y from the height of the image. For example, to annotate a 300 x 300 image at the location of the mouse click using the XYOUTS procedure, you could use IDL code similar to the following:
XYOUTS, $Mouse.x, 300-$Mouse.y, '. You clicked here', /DEVICE
To see this behavior in an ION Script application, run the example mouse.ion in the ION63/ion_script/examples subdirectory of your ION Script installation. See ION_IMAGE for another example using $Mouse.
The default values of $Mouse.x and $Mouse.y are 0.0, therefore, you can check to see if the user has clicked the mouse with the statement
<ION_IF EXPR="$Mouse.x NE 0.0">
See Using the $Mouse System Variable for an example that employs this technique.
IDL Online Help (March 06, 2007)