Each shape object represents a shape component in an Image Template file. This includes simple shape objects as well as data items within a map. There can be any number of shape objects in an Image Template file. Each shape object has its own name, data, and formatting options.
The examples in this section assume that the shape object has the default name of shape. However, shape objects are not usually named shape. Substitute the appropriate object name in place of shape.
This is especially true of map data items: the shape names are typically a combination of the map name and the name of the data item they represent. In order to access shapes in maps, specify the map name, followed by an underscore and the data item name. For example, if a map is named World, and contains a background shape or data item named Mexico, access the Mexico shape using World_Mexico, like this:
World_Mexico.hide()
Shape objects have the following methods:
|
method |
|
addDescription |
|
|---|---|---|---|
|
Syntax |
|
shape.addDescription(description) |
|
|
Description
|
|
Sets a shape's description field. Use this command to provide additional information about a shape. This field is accessed using the %_DESCRIPTION macro. |
|
|
Parameters |
|
shape.addDescription accepts the following parameters:
|
|
|
|
|
description |
String |
|
|
|
The description of the shape. |
|
|
method |
|
addHoverText |
|
|---|---|---|---|
|
Syntax |
|
shape.addHoverText(text) |
|
|
Description
|
|
Specifies hover text for the current shape. Hover text appears when a user mouses over the shape. For more information, see Hover Text in the Corda Builder™ User Guide. |
|
|
Parameters |
|
shape.addHoverText accepts the following parameters: |
|
|
|
|
text |
String |
|
|
|
The text that appears as a user mouses over the shape. |
|
|
method |
|
addITXML |
|
|---|---|---|---|
|
Syntax |
|
shape.addITXML(itxml) |
|
|
Description
|
|
Inserts the specified ITXML properties into this object. If a property has already been defined (e.g., in the Image Template file), this statement overrides it. If no Image Template file is currently open, this command creates a new Image Template file and inserts the specified object into the empty Image Template file. The ITXML in this file is appended to the ITXML from the Image Template file and from any previous addITXML commands. Adding an image object that has the same name as an existing image object in the Image Template file replaces the existing image object with the new image object. The shape.addITXML statement is useful for accessing features of Corda Server™ not available through the PCScript API. It allows you to add to or modify this object's definition within the actual Image Template file. For example, PCScript does not allow you to dynamically define text for this shape. However, you can use shape.addITXML to add the necessary ITXML to the shape object. Example 1below illustrates how to do this. Examples 2 and 3 show how this statement affects the shape object's definition in the Image Template file. Note that this only applies to properties of the <cit:shape> object. To modify attributes of the <cit:shape> tag (e.g., common="top:20;"), use the shape.setITXMLAttributes method. |
|
|
Parameters |
|
shape.addITXML accepts the following parameters: |
|
|
|
|
itxml |
String |
|
|
|
A string of ITXML that contains valid properties for the <cit:shape> tag. For more information, see ITXML. |
|
|
Examples |
|
Example 1: shape.addITXML Method Call shape.AddITXML(<cit:label text="Label Text"/>) Example 2: Shape Definition before Calling addITXML in Example 1 <cit:shape name="shape"> ... </cit:shape> Example 3: Shape Definition after Calling addITXML in Example 1 <cit:shape name="shape"> <cit:label text="Label Text"/> ... </cit:shape> |
|
|
method |
|
ddEnable |
|
|---|---|---|---|
|
Syntax |
|
shape.ddEnable(URL [, target]) |
|
|
Description
|
|
Adds a drilldown effect to this shape. Drilldown effects include linking to a different Web page or executing a Javascript* function. The drilldown effect occurs whenever a user clicks a specific data item. For more information about drilldown effects, see Building Drilldown. |
|
|
Parameters |
|
shape.ddEnable accepts the following parameters: |
|
|
|
|
URL |
{ URL | Javascript function } |
|
|
|
The Web page or Javascript function that a shape drills down to. If the URL parameter is a Web page, the link is relative to the location of the Web page that contains the Corda® image. Prefix the URL with http:// to specify an absolute path. If the URL parameter is a Javascript function, it must be prefixed with Javascript: . The function must also be declared within the Web page that contains the Corda image. For more information about drilling down to Javascript functions, see Drilldown to Javascript Functions. |
|
|
|
|
target |
String |
|
|
|
(Optional) The target window or frame that the shape drills down to. Do not use this parameter when drilling down to a Javascript function. |
|
|
Example |
|
shape.ddEnable Method Calls shape.ddEnable(http://www.myserver.com/box.html) shape.ddEnable(Javascript:dostuff(true)) |
|
|
method |
|
hide |
|---|---|---|
|
Syntax |
|
shape.hide() |
|
Description |
|
Hides this shape. Use the shape.show command to make the shape object visible again after using this command. |
|
method |
|
setITXMLAttributes |
|
|---|---|---|---|
|
Syntax |
|
shape.setITXMLAttributes(attributes) |
|
|
Description |
|
Inserts the specified attribute assignments into this shape object's ITXML tag. If an attribute has already been assigned (e.g., in the Image Template file), this statement overrides its assignment. The shape.setITXMLAttributes statement is useful for accessing features of Corda Server not available through the PCScript API. It allows you to add to or modify this object's definition within the actual Image Template file. For example, PCScript does not let you dynamically redefine the size and position of this object. However, you can use shape.setITXMLAttributes to change the ITXML that defines these settings. Example 1below illustrates how to do this. Examples 2 and 3 show how this statement affects the shape object's definition in the Image Template file. Note that this only applies to attributes listed in this object's <cit:shape> tag. To modify properties of the <cit:shape> tag (e.g., <cit:shape-settings>), use the shape.addITXML method. |
|
|
Parameters |
|
map.setITXMLAttributes accepts the following parameters: |
|
|
|
|
attributes |
String |
|
|
|
A string of ITXML attribute assignments, each separated by a blank space. This string is essentially what follows shape in a <cit:shape> tag. For example, to set the top attribute to 100, this string reads common="top:100;". This string can contain any number of attribute assignments. For more information about ITXML, see ITXML. |
|
|
Examples |
|
Example 1: shape.setITXMLAttributes Method Call shape.SetITXMLAttributes(common="top:20;left:20;width:300;height:300")
Example 2: Shape Definition before Calling setITXMLAttributes in Example 1 <cit:shape name="shape" common="top:8;left:91;width:270;height:340"> ... </cit:shape> Example 3: Shape Definition after Calling setITXMLAttributes in Example 1 <cit:shape name="shape" common="top:20left:20;width:300;height:300"> ... </cit:shape> |
|
|
method |
|
setLabel |
|
|---|---|---|---|
|
Syntax |
|
shape.setLabel(text) |
|
|
Description |
|
Specifies text for the shape label. |
|
|
Parameters |
|
shape.setLabel accepts the following parameters: |
|
|
|
|
text |
String |
|
|
|
The text you want to assign to this shape. This text appears in the shape's label. |
|
|
method |
|
setValue |
|
|---|---|---|---|
|
Syntax |
|
shape.setValue() |
|
|
Description |
|
Sets the data value of this shape. This value might appear in the shape's label. In maps, it is used to determine the value range to which the shape belongs. |
|
|
Parameters |
|
shape.setValue accepts the following parameters: |
|
|
|
|
value |
int |
|
|
|
The data value of this shape. |
|
|
method |
|
show |
|---|---|---|
|
Syntax |
|
shape.show() |
|
Description |
|
Shows the current shape. By default, all objects are visible. Use this command to make the shape object visible again after using the shape.hide command. |