Map objects represent each map in an Image Template file. There can be any number of map objects in an Image Template file. Each map object has its own name, data, and formatting options.
Map objects are unique because they can contain layers of shape objects. Manipulate each shape object using the shape object API. To identify a shape to manipulate, precede the shape's name with that of the map it belongs to, followed by an underscore (_). For example, if the map is named World and contains a shape named Texas, you access that shape using the World_Texas object.
However, because the map object lets you change the data of all of properties, you do not typically need to access map shapes individually.
Note: The examples in this section assume that the map object has the default name of map. However, be aware that map objects are not usually named map; instead, they are named something like US or World. Substitute the appropriate object name in place of map.
Map objects have the following methods:
|
method |
|
addITXML |
|
|---|---|---|---|
|
Syntax |
|
map.addITXML(itxml) |
|
|
Description
|
|
Inserts the specified ITXML properties into the map 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 map.addITXML command is useful for accessing Corda Server™ features 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 the default shape for data items within this map. However, you can use map.addITXML to change the ITXML that defines this default setting. Example 1 below illustrates how to do this. Examples 2 and 3 show how this statement affects the map object's definition in the Image Template file. Note that this only applies to properties of the <cit:map> object. To modify attributes of the <cit:map> tag (e.g., common=”top:20;”), use the map.setITXMLAttributes method. |
|
|
Parameters |
|
map.addITXML accepts the following parameters: |
|
|
|
|
itxml |
String |
|
|
|
A string of ITXML that contains valid properties for the <cit:map> tag. For more information, see ITXML. |
|
|
Examples |
|
Example 1: map.addITXML Method Call map.addITXML(<cit:default-shape><cit:shape-settings type="round"/></cit:default-shape>)
Example 2: Map Definition before Calling addITXML in Example 1 <cit:map name="map"> <cit:default-shape> <cit:shape-settings type="rectangle"> </cit:shape-settings> </cit:default-shape> ... </cit:map> Example 3: Map Definition after Calling addITXML in Example 1 <cit:map name="map"> <cit:default-shape> <cit:shape-settings type="round"> </cit:shape-settings> </cit:default-shape> ... </cit:map> |
|
|
method |
|
addLine |
|
|---|---|---|---|
|
Syntax |
|
map.addLine(srclat, srclong, destlat, destlong, [color, width, style, hover, drilldown, target]) |
|
|
Description
|
|
Places a line between two latitude-longitude coordinates. Specify the color, width, and style of the line, as well as hover text and drilldown effects. This command only works on maps that contain latitude-longitude information (see Adding Longitude/Latitude-Based Items to a Map). |
|
|
Parameters |
|
map.addLine accepts the following parameters: |
|
|
|
|
srclat |
coord |
|
|
|
The latitude of the starting point for the line. To learn how to format latitude coordinates, see Acceptable Formats for Coordinates. |
|
|
|
|
srclong |
coord |
|
|
|
The longitude of the starting point for the line. To learn how to format longitude coordinates, see Acceptable Formats for Coordinates. |
|
|
|
|
destlat |
coord |
|
|
|
The latitude of the starting point for the line. |
|
|
|
|
destlong |
coord |
|
|
|
The longitude of the starting point for the line. |
|
|
|
|
color |
color |
|
|
|
(Optional) The six-digit hexadecimal color code (RRGGBB) for the line. |
|
|
|
|
width |
int |
|
|
|
(Optional) The width of the line in pixels. |
|
|
|
|
style |
{ plain | dashed | dotted | dashdot } |
|
|
|
(Optional) Specifies the style of the line. The default value is plain. |
|
|
|
|
hover |
String |
|
|
|
(Optional) The text that you want to appear when a user mouses over this line. |
|
|
|
|
drilldown |
{ URL | Javascript function } |
|
|
|
(Optional) The Web page or Javascript* function that the line links to when a user clicks it. If the drilldown 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 drilldown 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 |
|
|
|
|
(Optional) The target window or frame that the line drills down to. Do not use this parameter when drilling down to a Javascript function. |
|
|
Example |
|
Using addLine ID.addLine(43.55,-114,43.8,-112.05) ID.addLine(43.5644,-116.223,43.8339,-111.805,#0000ff,5,dotted) ID.addLine(43.613,-111.3,43.82,-115.805,#ff00ff,2,,This is a line,http://myserver.com,hoverwindow)
|
|
|
method |
|
addPoint |
|
|---|---|---|---|
|
Syntax |
|
map.addPoint(name, lat, long, value) |
|
|
Description
|
|
Places a new data point on the map at the specified latitude-longitude coordinates. This command only works on maps that contain latitude-longitude information (see Adding Longitude/Latitude-Based Items to a Map). |
|
|
Parameters |
|
map.addPoint accepts the following parameters: |
|
|
|
|
name |
String |
|
|
|
The name of the data point. |
|
|
|
|
lat |
coord |
|
|
|
The latitude coordinate of the data point. To learn how to format latitude coordinates, see Acceptable Formats for Coordinates. |
|
|
|
|
long |
coord |
|
|
|
The longitude coordinate of the data point. To learn how to format longitude coordinates, see Acceptable Formats for Coordinates. |
|
|
|
|
value |
float |
|
|
|
The value of the data point. |
|
|
Example |
|
Using addPoint US.addPoint(Four Corners, 36° 59' N, 109° 02' W,33) US.addPoint(Four Corners, 36.9992,-109.045239,33) |
|
|
method |
|
hide |
|---|---|---|
|
Syntax |
|
map.hide() |
|
Description
|
|
Hides this map. Use the map.show command to make the map object visible again after using this command. |
|
method |
|
loadMapFile |
|
|---|---|---|---|
|
Syntax |
|
map.loadMapFile(layerName, FileName [, HTMLTable [, encoding]]) |
|
|
Description
|
|
Instructs Corda Server to import data from a tab-delimited data file, comma-separated value file, XML database file, or table in an HTML file. This file or Web page must be accessible to the machine running Corda Server. When using this command, you must specify which layer of the map you want to target. The data is applied to that layer only. If the data file names an object that is not in the specified layer, that object is ignored. For more information on map layers, see Map Layers in the Corda Builder™ User Guide. Corda Server automatically detects the format of the file you specify. For more information on these data formats, see Connecting to Data Files. To specify which columns hold the data item names or values, use map.setMapDataColumns in conjunction with map.loadMapFile. For example, suppose you've saved a data file named <document_root>\datasales.csv. Load data from that file into the background shape layer of the map object named world using the following PCScript method call: world.loadMapFile(areas, data/sales.csv) Similarly, to replace the shape values in a map object named georgia with data from a table named data2 on the Web page http://www.myserver.com/stats.html, send the following PCScript to Corda Server: georgia.loadMapFile(points, http://www.myserver.com/stats.html,data2) Important: The path.xml file must grant Corda Server permission to read files from the location that you specify. Otherwise, it is unable to load the data. For more information, see Setting Path Permissions in the Corda 7 Install and Administration manual. Note: This command provides the same functionality as the loadMapData Corda Embedder method. |
|
|
Parameters |
|
map.loadMapFile accepts the following parameters: |
|
|
|
|
FileName |
String |
|
|
|
The path and filename (relative to <document_root>) of the file or Web page that the data is retrieved from. Specify the path using either path or URL notation. Make sure that path.xml permits Corda Server to read from this path (see Setting Path Permissions in the Corda 7 Install and Administration manual). |
|
|
|
|
layerName |
String |
|
|
|
The layer of the map that you want to send data to. |
|
|
|
|
HTMLTable |
{ int | title } |
|
|
|
The title or number of the table that is loaded from the Web page. If this parameter is a title, be sure that the title corresponds to the value of the title attribute of the <table> tag. If it is a number, Corda Server imports data from the n th table in the Web page, where n is the number you specify. Example 2 below illustrates how this parameter is used. The first line of code imports data from the table titled pricing on the Web page stats.html. The second line of code imports data from the 11th table on the Web page morestats.html. This parameter must always be set when importing data from HTML tables. |
|
|
|
|
encoding |
String |
|
|
|
(Optional) Specifies the character encoding of the file you are loading. Valid character sets include euc-jp, utf-8, shift_jis, and unicode. If you have no idea what character encoding is, you most likely can ignore this parameter. For information about using international and double-byte characters, see International Fonts and Character Support in the Corda 7 Install and Administration manual. |
|
|
Examples |
|
Example 1: Loading a Comma-Separated Value File map.loadMapFile(areas,data/020115.csv) Example 2: Loading an HTML Table from a Web Page map.loadMapFile(datapoints,http://www.myserver.com/stats.html,pricing) map.loadMapFile(datapoints,\\database\morestats.html,11) |
|
|
method |
|
setDrilldown |
|
|---|---|---|---|
|
Syntax |
|
map.setDrilldown(layerName; shapeName, URL [, target]) |
|
|
Description
|
|
Specifies drilldown effects for the specified map layer within the current map. Drilldown effects are special events that can happen when a user clicks on a data item (e.g., linking to a new page, running a Javascript function). For more information, see Building Drilldown. map.setDrilldown takes as its arguments any number of drilldown effects. Each drilldown effect is separated by a semi-colon (;). A drilldown effect consists of two values: the name of the data item (e.g., Austin or Seat41A) and the URL or Javascript function to which the data point drills down to. An optional third value lets you define a target for the drilldown effect. If a drilldown effect has already been defined for a data item within the Image Template file, this command overrides that effect. Because data items often contain commas, you might have to change the parameter delimiter so that Corda Server does not get confused. For example, an item named Las Vegas, NV causes Corda Server to identify two different parametersLas Vegas and NVinstead of a single item. Changing the delimiter to a vertical bar ( | ), for example, properly passes the data item. This can be done using the main.paramDelimiter command, as illustrated in the example below. |
|
|
Parameters |
|
map.setDrilldown accepts the following parameters: |
|
|
|
|
layerName |
String |
|
|
|
The name of the map layer that you want to add a drilldown effect to. This name is defined in the Image Template file. Reference the map layer using the name attribute in <cit:layer>, which is accessible from Object Properties. For more information on map layers, see Map Layers in the Corda Builder User Guide. Note: If layerName is incorrect or omitted, then each map layer, starting at the topmost, is searched for a matching shape. |
|
|
|
|
shapeName |
String |
|
|
|
The name of the data items that you want to add a drilldown effect to. This name is defined in the Image Template file. Reference a data item using one of three possible names: the object name, the long name or the code name. For example, in the U.S. map, refer to Texas using either TX (the object name), Texas (the long name), or 48 (the code name). Note: On maps with a large number of data items, you may want to use map.setLookup to tell Corda Server which type of name you are using to help speed up image generation time. |
|
|
|
|
URL |
{ URL | Javascript function } |
|
|
|
The Web page or Javascript function that the data point links to when a user clicks it. 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 data item drills down to. Do not use this parameter when drilling down to a Javascript function. |
|
|
Example |
|
map.setDrilldown Method Call New York.setDrilldown(Background; New York City, Javascript:jumpto('NY')) main.paramDelimiter(|)US.setDrilldown(Background; Austin, TX|http://slc.org; Las Vegas, NV|http://myserver.com/getmaps?LV)main.paramDelimiter(,)
|
|
|
method |
|
setHover |
|
|---|---|---|---|
|
Syntax |
|
map.setHover(layerName; shapeName, text; [shapeName, text;]*) |
|
|
Description
|
|
Specifies hover text for data items within the current map. Hover text appears when a user mouses over a data item. For more information, see Hover Text in the Corda Builder User Guide. map.setHover takes as its arguments any number of hover text assignments. Each hover text assignment is separated by a semi-colon (;). A hover text assignment consists of two values: the name of the data item (e.g., Austin or Seat41A) and the hover text for that data item. If hover text has already been defined for a data item within the Image Template file, this command overrides that text. Because data items often contain commas, you might have to change the parameter delimiter so that Corda Server does not get confused. For example, an item named Las Vegas, NV causes Corda Server to identify two different parameters—Las Vegas and NV—instead of a single item. Changing the delimiter to a vertical bar ( | ), for example, properly passes the data item. This can be done using the main.paramDelimiter command, as illustrated in the example below. |
|
|
Parameters |
|
map.setHover accepts the following parameters: |
|
|
|
|
layerName |
String |
|
|
|
The name of the map layer that you want to add hover text to. This name is defined in the Image Template file. Reference the map layer using the name attribute in <cit:layer>, which is accessible from Object Properties. For more information on map layers, see Map Layers in the Corda Builder User Guide. Note: If layerName is incorrect or omitted, then each map layer, starting at the topmost, is searched for a matching shape. |
|
|
|
|
shapeName |
String |
|
|
|
The name of the data item that you want to add hover text to. This name is defined in the Image Template file. Reference a data item using one of three possible names: the object name, the long name or the code name. For example, in the U.S. map, refer to Texas using either TX (the object name), Texas (the long name), or 48 (the code name). Note: On maps with a large number of data items, you may want to use map.setLookup to tell Corda Server which type of name you are using to help speed up image generation time. |
|
|
|
|
text |
String |
|
|
|
The text you want to appear as a user mouses over the data item. |
|
|
Example |
|
map.setHover Method Call New York.setHover(Background; New York City, I Luv New York) main.paramDelimiter(|)US.setHover(Background; Salt Lake City, UT|Site of 2002 Olympics; 04| Abnormal Precipitation; Las Vegas, NV|Viva Las Vegas!)main.paramDelimiter(,)
|
|
|
method |
|
setITXMLAttributes |
|
|---|---|---|---|
|
Syntax |
|
map.setITXMLAttributes(attributes) |
|
|
Description
|
|
Inserts the specified attribute assignments into this map object's ITXML tag. If an attribute has already been assigned (e.g., in the Image Template file), this statement overrides its assignment. The map.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, by using the map.setITXMLAttributes method, you can change the ITXML that defines this setting. Example 1 below illustrates how to do this. Examples 2 and 3 show how this statement affects the map object's definition in the Image Template file. Note that this applies only to attributes listed in this object's <cit:map> tag. To modify properties of the <cit:map> tag (e.g., <cit:map-settings>, use the map.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 map in a <cit:map> 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: map.setITXMLAttributes Method Call map.SetITXMLAttributes(common="top:20;left:20;width:300;height:300")
Example 2: Map Definition before Calling setITXMLAttributes in Example 1 <cit:map name="map" common="top:8;left:91;width:270;height:340"> ... </cit:map> Example 3: Map Definition after Calling setITXMLAttributes in Example 1 <cit:map name="map" common="top:20left:20;width:300;height:300"> ... </cit:map> |
|
|
method |
|
setLabel |
|
|---|---|---|---|
|
Syntax |
|
map.setLabel(layerName; shapeName, text) |
|
|
Description
|
|
Specifies text labels for data items within the current map. map.setLabel takes as its arguments any number of label assignments. Each label assignment is separated by a semi-colon. A label assignment consists of two values: the name of the data item (e.g., Austin or Seat41A) and the label for that data item. If a label has already been defined for the data item within the Image Template file, this command overrides that label. Because data items often contain commas, you might have to change the parameter delimiter so that Corda Server does not get confused. For example, an item named Las Vegas, NV causes Corda Server to identify two different parametersLas Vegas and NVinstead of a single item. Changing the delimiter to a vertical bar ( | ), for example, properly passes the data item. This can be done using the main.paramDelimiter command, as illustrated in the example below. |
|
|
Parameters |
|
map.setLabel accepts the following parameters: |
|
|
|
|
layerName |
String |
|
|
|
The name of the map layer that you want to specify a label for. This name is defined in the Image Template file. Reference the map layer using the name attribute in <cit:layer>, which is accessible from Object Properties. For more information on map layers, see Map Layers in the Corda Builder User Guide. Note: If layerName is incorrect or omitted, then each map layer, starting at the topmost, is searched for a matching shape. |
|
|
|
|
shapeName |
String |
|
|
|
The name of the data item you want to add a text label to. This name is defined in the Image Template file. Reference a data item using one of three possible names: the object name, the long name or the code name. For example, in the U.S. map, refer to Texas using either TX (the object name), Texas (the long name), or 48 (the code name). Note: On maps with a large number of data items, you may want to use map.setLookup to tell Corda Server which type of name you are using to help speed up image generation time. |
|
|
|
|
text |
String |
|
|
|
The text you want to appear in the label. |
|
|
Example |
|
map.setLabel Method Call New York.setLabel(Backround; New York City, NYC) main.paramDelimiter(|)US.setLabel(Background; Austin, TX|Texas State Capitol; 04| Iowa; Las Vegas, NV|LAS)main.paramDelimiter(,)
|
|
|
method |
|
setLookup |
|
|---|---|---|---|
|
Syntax |
|
map.setLookup(layerName; value) |
|
|
Description
|
|
Specifies the name type that Corda Server uses to match names listed in PCScript statements to data items within the Image Template file. A data item can be referenced using one of three possible names: the object name, the long name or the code name. For example, in the U.S. map, refer to Texas using either TX (the object name), Texas (the long name), or 48 (the code name). When Corda Server attempts to match a name to a data item, it first tries to find a match in the code name list. If it can't find a matching data item, it looks in the object names list. If it still can't find a matching data item, it looks up the name in the list of long names. If you index data using object names or long names when the map has a large number of data items, the time it takes Corda Server to generate the image is less than optimal. This is because Corda Server needlessly searches through a map's entire code name list before searching through the lists of object and long names. To optimize performance, use the map.setLookup method to specify which type of name Corda Server expects to find in PCScript statements. Corda Server then searches for the matching data item only in the specified name list. |
|
|
Parameters |
|
map.setLookup accepts the following parameters: |
|
|
|
|
layerName |
String |
|
|
|
The name of the map layer that you want to specify a lookup for. This name is defined in the Image Template file. Reference the map layer using the name attribute in <cit:layer>, which is accessible from Object Properties. For more information on map layers, see Map Layers in the Corda Builder User Guide. Note: If layerName is incorrect or omitted, then each map layer, starting at the topmost, is searched for a matching shape. |
|
|
|
|
value |
{ name | longname | code } |
|
|
|
Specifies the type of name on which Corda Server indexes its searches for data items. Available options are name (the object name), longname (the object's long name), and code (the object's code name). |
|
|
Example |
|
map.setLookup Method Call map.setLookup(Points; code) map.setValues(753,81; 862,17; 811, 92) map.setLookup(Background; longname) map.setLabel(Austin,78753) |
|
|
method |
|
setMapDataColumns |
|
|---|---|---|---|
|
Syntax |
|
map.setMapDataColumns(namecolumn, valuecolumn) |
|
|
Description |
|
Specifies which columns of an imported data table are used for data item names and data item values, respectively. This command applies to any data imported by a map.loadMapFile statement. |
|
|
Parameters |
|
map.setMapDataColumns accepts the following parameters: |
|
|
|
|
namecolumn |
int |
|
|
|
The column number of the data import that holds the data item names. By default, this is the first column. |
|
|
|
|
valuecolumn |
int |
|
|
|
The column number of the data import that holds the data item values. By default, this is the second column. |
|
|
Example |
|
map.setMapDataColumns Method Call map.setMapDataColumns(1,3) map.loadMapFile(areas,\\database\morestats.html,11) |
|
|
method |
|
setValues |
|
|---|---|---|---|
|
Syntax |
|
map.setValues(layerName; shapeName, value [; name, value]) |
|
|
Description
|
|
Lets you specify data for data items in a map. map.setValues takes as its arguments any number of data items. Each data item is separated by a semi-colon (;). A data item consists of two values: the name of the data item (e.g., Austin or Seat41A) and the value assigned to that data item. In order for data to be mapped, the data item must be defined within the current map object. For more information about adding data items to a map object, see Adding Point Layer Data Items in the Corda Builder User Guide. Because data items often contain commas, you might have to change the parameter delimiter so that Corda Server does not get confused. For example, an item named Las Vegas, NV causes Corda Server to identify two different parameters—Las Vegas and NV—instead of a single item. Changing the delimiter to a vertical bar ( | ), for example, properly passes the data item. This can be done using the main.paramDelimiter command, as illustrated in the example below. |
|
|
Parameters |
|
map.setValues accepts the following parameters: |
|
|
|
|
layerName |
String |
|
|
|
The name of the map layer that you want to add values to. This name is defined in the Image Template file. Reference the map layer using the name attribute in <cit:layer>, which is accessible from Object Properties. For more information on map layers, see Map Layers in the Corda Builder User Guide. Note: If layerName is incorrect or omitted, then each map layer, starting at the topmost, is searched for a matching shape. |
|
|
|
|
shapeName |
String |
|
|
|
The name of the data item whose value you want to modify. This name is defined in the Image Template file. Reference a data item using one of three possible names: the object name, the long name or the code name. For example, in the U.S. map, refer to Texas using either TX (the object name), Texas (the long name), or 48 (the code name). Note: On maps with a large number of data items, you may want to use map.setLookup to tell Corda Server which type of name you are using to help speed up image generation time. |
|
|
|
|
value |
int |
|
|
|
The value you want to assign this data item. |
|
|
Example |
|
map.setValues Method Call New York.setValues(Background; New York City, 76) main.paramDelimiter(|)US.setValues(Background; Austin, TX|89; 04|112; Las Vegas, NV|28)main.paramDelimiter(,)
|
|
|
method |
|
show |
|---|---|---|
|
Syntax |
|
map.show() |
|
Description
|
|
Shows the current map. By default, all objects are visible. Use this command to make the map object visible again after using the map.hide command. |