12.1.2. Defining Dialog Box Steps and Variables

When you define a dialog box, you first need to define a macro that specifies the following:

Defining Steps

The following code snippet shows how dialog boxes can be defined in a macro. This file is provided in the examples folder in your EKM server installation: EKM_HOME/examples/custom-apps.

init(dialog) {
  dialog.addStep("Test Variables", "test-variables.xhtml", "action");
  
  dialog.addVar("file", dialog.VARIABLE_TYPE_FILE, null, false);
  
  referenceVar = dialog.addVar("reference", dialog.VARIABLE_TYPE_REFERENCE, "", false);
  referenceVar.setReferenceType("Folder");
  referenceVar.selectOnlyModifiableFolders(true);
  
  dialog.addVar("string", dialog.VARIABLE_TYPE_STRING, "Hello World", false);
  dialog.addVar("integer", dialog.VARIABLE_TYPE_LONG, 10, false);
  dialog.addVar("real", dialog.VARIABLE_TYPE_DOUBLE, 1.2345, false);
  dialog.addVar("date", dialog.VARIABLE_TYPE_DATE, Calendar.getInstance().getTime(), false);
  dialog.addVar("boolean", dialog.VARIABLE_TYPE_BOOLEAN, true, false);
  dialog.addVar("radio", dialog.VARIABLE_TYPE_STRING, "Radio 2", false);

  menuVar = dialog.addVar("menu", dialog.VARIABLE_TYPE_STRING, "Menu Option 2", false);
  menuOptions = new LinkedList();
  menuOptions.add("Menu Option 1");
  menuOptions.add("Menu Option 2");
  menuOptions.add("Menu Option 3");
  menuVar.setOptions(menuOptions);

  dialog.addVar("listBox", dialog.VARIABLE_TYPE_STRING, new String[] 
{"List Option 1", "List Option 2"}, true);
}

The name of the macro is init and it takes a single argument dialog box that is an instance of DialogInterface.

The first line of the macro adds a step to the dialog box as follows:

dialog.addStep("Test Variables", "test-variables.xhtml", "action");

The first argument is the header and will be shown in the title bar of the dialog box when it is opened in the web user interface.

The second argument is the path of the XHTML file that defines the user interface for this step. The path can be either relative or absolute. An absolute path is used primarily for defining action dialog boxes for custom types. The location of the XHTML files (and other resource files used in the user interface such as images, CSS files, JavaScript files, and so on) is dictated by the customResourcesPath setting in ekm.xml and is by default EKM_HOME/conf/resources. The XHTML file for the custom type dialog box can be placed in any sub folder in the custom resources folder. You can then use the path: /custom/<relative path of file in custom resources folder> to refer to the XHTML file in the custom resources folder. Process templates and custom applications can be added or modified dynamically to EKM by any user who may or may not have access to EKM server’s file system. EKM handles this issue in the following ways:

Because you do not know the ID of an object before it has been added to EKM, you cannot use the absolute path to specify XHTML files for custom applications and process template dialog boxes. You can, however, specify a relative path and behind the scenes EKM will create the full path before the dialog box is opened. User interface resources are contained in an archive, and the relative path will depend on the path of the XHTML file in the archive. If the file is at the top level of the archive, then you can simply specify the file name (for example, test-variables.xhtml). However, if the file is in a folder then you will need to specify the name of the parent folder too (for example, folder-name/test-variables.xhtml).

The third argument is the name of the action macro that will be called when the dialog box is submitted. For a multistep wizard, you need to specify only the execution macro in the last step.

The addStep() method returns an instance of DialogStepInterface.

Defining Variables

Once the steps have been specified you can then add the variables used in the dialog box. This is done using the addVar() method of the DialogInterface as shown in the following line:

dialog.addVar("string", dialog.VARIABLE_TYPE_STRING, "Hello World", false);

The first argument is the name of the variable, the second argument is the type of the variable, the third argument is the default value and the fourth argument specifies whether the variable is multi-valued or not. The following types can be specified:

The default value will depend on the type of the variable. For VARIABLE_TYPE_DATE, it must be an instance of java.util.Date class. You can set the default to the current time by calling Calendar.getInstance().getTime(). For VARIABLE_TYPE_FILE the default must be null. For multi-valued variables, the default value must be a list. For example:

dialog.addVar("listBox", dialog.VARIABLE_TYPE_STRING, new String[] 
{"List Option 1", "List Option 2"}, true);

In the above line, the variable listBox is a multi-valued variable whose default value is a list with two elements: List Option 1 and List Option 2.

The addVar() method returns the newly added variable, which is an instance of the VariableInterface. You can use this instance to specify some additional attributes that can’t be specified in the addVar() method. For example, for reference variables you can specify the type of objects to be selected using the setReferenceType() method of ReferenceVariableInterface as shown in the following snippet. Here we are setting the type to Folder, this means that users will only be able to select Folder objects for this variable:

referenceVar = dialog.addVar("reference", dialog.VARIABLE_TYPE_REFERENCE, "", false);
  referenceVar.setReferenceType("Folder");

Similarly you can specify the options for any variable using the setOptions() method as shown in the following snippet. Here we are setting 3 options: Menu Option 1, Menu Option 2, and Menu Option 3.

menuVar = dialog.addVar("menu", dialog.VARIABLE_TYPE_STRING, "Menu Option 2", false);
  menuOptions = new LinkedList();
  menuOptions.add("Menu Option 1");
  menuOptions.add("Menu Option 2");
  menuOptions.add("Menu Option 3");
  menuVar.setOptions(menuOptions);

Release 18.2 - © ANSYS, Inc. All rights reserved.