ION_IMAGE

The ION_IMAGE tag pair inserts an IDL-generated graphic into an ION Script document. Both Direct and Object graphics images can be generated. An EVENT assigned to the ION_IMAGE makes the image an input that can be clicked on to load a new ION Script document. The location of the mouse click is passed on to the new document through the Mouse.x and Mouse.y system variables.

The IDL code that generates the image is embedded an <IDL>...</IDL> block inside the ION_IMAGE block. For a Direct Graphics image, the last image created using a Direct Graphics command is rendered to the output page. For an Object Graphics image, the last image rendered to the ION_SCRIPT_BUFFER object is output in the page.

For images with events, ION Script creates the image using the HTML <INPUT TYPE="IMAGE" NAME="EventName" ALT="LABEL">. For images without events, ION Script creates the image with the HTML <IMG NAME="IMG" ALT="LABEL">.

Syntax

<ION_IMAGE
TYPE={"DIRECT" | "OBJECT"}
[BORDER="width"]
[DEBUG={"TRUE" | "FALSE"}]
[EVENT="eventName"]
[HEIGHT="height"]
[IMG_TYPE={"PNG8" | "PNG24" | "JPEG24"}]
[LABEL="label"]
[SERVER="url"]
[TARGET="frame target"]
[WIDTH="width"]
[<IMG> attributes (if EVENT not present) or <INPUT> attributes (if
EVENT present)]>

Notes About Using ION_IMAGE

The IDL code inside the <IDL>...</IDL> block can consist of the actual IDL statements that generate an image, or can simply be a call to a .pro file that generates an image.

Unlike ION_DATA_OUT, ION_IMAGE does not support the POST method. This is because image data is always passed to ion-i via an encrypted URL. If IDL blocks in your ION_IMAGE tags are large enough to exceed the maximum allowable length of a URL, such as very large data sets or a very large amount of IDL code, then you can work around the limitation by first using ION_DATA_OUT to create an IDL .sav file, and then simply restoring the .sav file in the ION_IMAGE call. For an example of this technique, see the example application largeData.ion in the examples directory.

The IDL code in the <IDL> block of an ION_IMAGE tag is not processed until the entire ION Script page has been parsed into HTML. Therefore, ION_IMAGE cannot be used to create data that is later used in constructing the web page. For example, you cannot use ION_IMAGE to create a .sav file that is restored in the <IDL> block of an ION_IMAGE or ION_DATA_OUT tag on the same page. Similarly, you cannot use ION_IMAGE to create a file that is included in the same ION Script page with ION_INCLUDE. For these cases, you would need to create the data using an ION_DATA_OUT tag, in which case the IDL code is processed as soon as it is encountered.

Attributes

BORDER

The width of the border drawn around the image. A value of 0 causes the image to be displayed without a border. The default BORDER is 1, but this default can be changed on the "Images" tab of the ION Script Configuration utility (Windows), or in the "Images" section of the .ionsrc file (UNIX). This attribute can contain a variable.

DEBUG

Setting this attribute to TRUE causes ION Script to generate a text file that can be used to help debug your ION Script application. This debugging file contains the exact code sent to IDL, as well as any errors reported by IDL. The file is given the name specified by the "ION Debug Filename" setting on the "Debug" tab of the ION Script Configuration utility (Windows) or in the "Debug" section of the .ionsrc file (UNIX). For example, if the "ION Debug Filename" setting is "ion-out%d.txt", then a file called ion-out<PID>.txt is created, where <PID> is the unique process ID for the instance of ion-i that generated the output. The file is written to the directory specified by the "ION Debug Location" setting on the "Debug" tab of the ION Script Configuration utility (Windows) or in the "Debug" section of the .ionsrc file (UNIX). In order for this to work, the directory specified by the "ION Debug Location" must be writable. See Debug for more information. The default value for DEBUG is FALSE.

EVENT

The name of the EVENT_DECL to execute when the user clicks on the image. This name must be one of the names defined in the NAME attribute of an EVENT_DECL tag. This attribute can contain a variable.

HEIGHT

IMG_TYPE

The graphics file format of the image created by the ION Script Image Engine. Valid values are:

PNG8 — 8-bit PNG images

PNG24 — 24-bit PNG images (lossless compression)

JPEG24 — 24-bit JPEG images (lossy compression)

Note
GIF, JPEG, and PNG are also accepted for backwards compatibility. GIF and PNG are interpreted as PNG8, and JPEG is interpreted as JPEG24.

For IMG_TYPE="DIRECT", the default is PNG8. For IMG_TYPE="OBJECT", the default is JPEG24. These defaults can be changed using the configuration utility or the .ionsrc file. The value specified in this attribute overrides the default value specified in the configuration utility. For information on how to select the appropriate image format, see Graphics in ION Script.

LABEL

The default text displayed in place of an image for browsers that do not support images, and for browsers in which the automatic display of in-line images has been turned off. If not specified, the value specified in the "Label" field on the "Images" tab of the configuration utility (Windows), or in the "Images" section of the .ionsrc file (UNIX), is used as the default.

This label is also used in some cases as the tooltip that appears when you hold the mouse cursor over the image, depending on which browser type and version you are using. Because different browsers (and different versions of each) implement alternate text and tooltips differently, it helps to know how ION Script maps the label to HTML. This label value (or the LABEL attribute of ION_IMAGE, if specified) becomes the value of the ALT attribute of the HTML <IMG> tag for an ION_IMAGE without an EVENT, or the ALT attribute of the <INPUT TYPE="IMAGE"> tag for an ION_IMAGE with an EVENT. Because some browsers handle images created with the <IMG> tag differently than those created with the <INPUT> tag, the name of the EVENT may be displayed in place of the value specified for the label if the EVENT attribute of the ION_IMAGE tag has been specified for an image.

SERVER

The full path to the image engine, ion-i. This must be a valid, absolute URL using the HTTP or HTTPS protocol. This attribute, which is also an attribute of <ION_DATA_OUT> and <ION_OBJECT>, can be used for load control by specifying different servers for different tasks (provided you have a copy of ion-i on each server, and that you have the proper license). If this attribute is not specified, ION Script will use the server specified during installation. The default value for this attribute can be changed using the configuration utility. This attribute can contain a variable.

TARGET

The name of the window or frame in which to load the URL specified by the EVENT attribute when the user clicks the image. This attribute can be set to either the NAME attribute of an HTML <FRAME> or <IFRAME> tag, or to one of four predefined windows: _blank, _parent, _self, or _top. See Targeting Different Frames for a description of these predefined windows. See Overview of Fixed Framesets for an example of how to use the TARGET attribute.

TYPE

Specifies whether image is generated using IDL's Direct or Object graphics system. Set to DIRECT to use IDL Direct Graphics, or to OBJECT to use Object Graphics. This is a required attribute.

WIDTH

HTML Mapping

The ION_IMAGE tag is converted to HTML as either an <IMG> tag, or a <FORM> tag with a nested <INPUT> tag, depending on whether the EVENT attribute is present.

If EVENT is Not Present

where width and height are defined by the "Image Width" and "Image Height" values specified in the configuration utility or .ionsrc file, and url is made up of the "ION Image Server URL" and the data returned by the <IDL> block. In this case, all attributes of the HTML <IMG> tag can be used in the <ION_IMAGE> tag.

If EVENT is Present

where url is made up of the ION Image Server URL and the data returned by the <IDL> block. In this case, all attributes of the HTML <INPUT TYPE="IMAGE"> tag can be used in the <ION_IMAGE> tag.

Example

In this simple example, we create an image that, when clicked, takes the user to another ION Script page that reports the x and y location of the mouse cursor: