Variables, Constants, and Settings in Scripts

There are four basic types of variables you can use in script.

script variables

These are the usual in-script variables. They follow the normal rules and usage of your scripting language.

mapset/module variables

These are variables that are stored in the mapset or module associated with the script.

fooValue = mapset.getVariables().get("foo");
mapset.getVariables().put("foo", fooValue);
fooValue = module.getVariables().get("foo");
module.getVariables().put("foo", fooValue);

These are good for storing things while the program is open, but doesn’t save them between sessions. They are also useful for sharing objects between scripts or between different runs of the same script.

script constants

Constants are really just a special case of script variable. They are generally used when there is some behavior or value that doesn’t need to be configurable but might have to get modified occasionally during development or troubleshooting - for example, to turn on debugging code or to set the length of a data record.

// constants
PATH_LENGTH = 53;
DEBUG = false;

mapset/module settings

When it’s time to reuse the same code for multiple customers and you need to change something on a per-customer basis, use config variables.

Create a settings.xml file in either: * config/FOO/mapsets/MAPSET/settings.xml, or * config/FOO/modules/MODULE/settings.xml.

They work the same way, just with module or mapset as desired:

pathLength = mapset.getSettings().get("pathLength");

or

pathLength = module.getSettings().get("pathLength");

Each time you call getSettings() the platform checks to see if the file has changed and reloads it as needed. Thus, you don’t have to restart the platform every time you modify settings.xml.

Here’s an example of the XML. Note the integer type - important to avoid needing to use ConversionLib.

<?xml version='1.0'?>
<cog>
  <Naming>
    <Integer name='pathLength'>
      53
    </Integer>
  </Naming>
</cog>

The “Parse” button on the Workbench text editor will check for XML issues.

predefined variables

To facilitate scripting, some variables are set before the script is run. These provide the necessary context for activities like dynamic map translation or actions.

All scripts predefine:

  • log - the script’s logger, an instance of com.partnersoft.core.Log; and
  • script - the com.partnersoft.scripting.Script representing this script.

Module scripts

All scripts in modules also have the following variables set:

  • settings - a Naming (com.partnersoft.data.Naming) of values from settings.xml in the module’s config, and
  • module - the Module (com.partnersoft.system.Module) the script lives in.

Mapset scripts

All scripts in mapsets have the following variables set:

  • app - the Map Viewer’s MapApp (com.partnersoft.maps.app.MapApp),
  • mapset - the MapSet (com.partnersoft.maps.model.MapSet),
  • settings - the Naming (com.partnersoft.data.Naming) of values from settings.xml, and
  • module - if the mapset is in a module, an instance of Module (com.partnersoft.system.Module.

Action Scripts

Mapset Action scripts also have this variable set:

  • selected - the currently selected MapDataItem (com.partnersoft.maps.model.MapDataItem)

Translator Frontend Scripts

Mapset translator frontend scripts also have this variable set:

  • translator - an instance of DynamicMapTranslator (com.partnersoft.maps.translator.DynamicMapTranslator)

Workbench scripts

All scripts used by the Workbench (actions, hotkeys, etc.) have the log, script, and module variables, and also have these variables set:

  • workbench - the com.partnersoft.workbench.app.WorkbenchApp instance,
  • file - the currently selected VfsFile (com.partnersoft.io.vfs.VfsFile)
  • directory - the currently selected VfsDirectory (com.partnersoft.io.vfs.VfsDirectory)