Dynamic Element Specifications

Table of Contents

Previous Section

WOActiveImage

Synopsis

WOActiveImage {filename= imageFileName; [framework = frameworkBaseName|"app" ;] | src=aURL; | value=aMethod; action=aMethod | href=aURL; [imageMapFile=aString]; [name=aString;] [x=aNumber; y=aNumber;] [target=frameName;] [disabled=YES|NO;] ... };

Description

A WOActiveImage displays an image within the HTML page. If the WOActiveImage is disabled, it simply displays its image as a passive element in the page. If enabled, the image is active, that is, clicking the image generates a request.

WOActiveImages are intended to be used outside of an HTML form. WOActiveImage functions as a mapped, active image. When the user clicks such a WOActiveImage, the coordinates of the click are sent back to the server. Depending on where the user clicks, different actions can be invoked. An image map file associates actions with each of the defined areas of the image. If an image map file is not specified, the method specified by the action attribute is performed when the image is clicked, or if the href attribute is specified, the image acts as a hyperlink and takes you to that destination.

Within an HTML form, a WOActiveImage functions as a graphical submit button. However, it is better to use a WOImageButton instead of WOActiveImage to create a graphic submit button or a mapped image within a form.

filename: Path to the image relative to the WebServerResources directory.
framework: Framework that contains the image file. This attribute is only necessary if the image file is in a different location from the component. That is, if the component and the image file are both in the application or if the component and the image file are both in the same framework, this attribute isn't necessary. If the image file is in a framework and the component is in the application, specify the framework's name here (minus the .framework extension). If the image file should be in the application but the component is in a framework, specify the "app" keyword in place of the framework name.
src: URL containing the image data. Use this attribute for complete URLs; for relative URLs use filename instead.
value: Image data in the form of a WOElement object. This data can come from a database, a file, or memory.
action: Method to invoke when this element is clicked. If imageMapFile is specified, action is only invoked if the click is outside any mapped area. In other words, action defines the default action of the active image.
href: URL to direct the browser to as a default when the image is clicked and no hot zones are hit.
imageMapFile: Name of the image map file.
name: If name is specified then the hit point is specified as name.x=value; name.y=value; in the form. This is useful when you need to use this element to submit a form to an external URL that expects the hit point to be expressed in a certain format.
x, y: If specified, returns the coordinates of the user's click within the image.
target: Frame in a frameset that will receive the page returned as a result of the user's click.
disabled: If YES, a regular image element (<IMG>) is generated rather than an active image.

The Image Map File

If imageMapFile is specified, WebObjects searches for the file in the component bundle (Component.wo), and then in the application's WebServerResources directory (or in the framework's WebServerResources if there's a framework attribute) If it isn't found there, WebObjects searches the application directory (MyApplication.woa/).

Note: The image map file must be in the same location as the image. For example, if the image is in a framework, the image map file must be in that same framework.

Each line in the image map file has this format:

	shape action coordinate-list

shape: Either rect, circle, or poly. For rect shape, the coordinates x1,y1 specify the upper-left corner of the hot zone, and x2,y2 specify lower-right corner. For circle shape, the x1,y1 is the origin, and x2,y2 is a point on the circle. For the poly shape, each coordinate is a vertex. Up to 100 vertices are supported.
action: Name of the method to invoke.
coordinate-list: x1, y1 x2, y2 ...

Here's an example of an image map file:

	rect	home	0,0 135,56
	rect	buy	135,0 270,56

Examples

Image-mapped active image

Table of Contents Next Section