12.1.2. Defining Dialog Box Steps and Variables

Engineering Knowledge Manager

Administration Guide | Chapter 12: Defining Custom Dialogs, Wizards and Applications | 12.1. Defining Custom Dialog Boxes |

12.1.1. Defining a Custom User Interface |  | 12.1.3. Example: Creating a Custom Interface for Fluent Batch Jobs
Prev |  | Next

### 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:

- The steps contained in the dialog box. Dialog boxes can either have a single step or have multiple steps (for example, in case of wizards). For each step you would need to specify the header of the step and the XHTML file that provides the interface for that step. For the last step you would also need to specify the execution macro that will be called when the dialog box is submitted. This macro is used to process the user inputs and then execute some commands.

- The variables used by the dialog box. Variables are used to store the inputs specified by the user in the dialog box. These variables can then be accessed by the execution macro to retrieve the user inputs and act upon them.

#### 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:

- The user interface resource files needed for custom applications and process templates are added as an archive (in .zip, .tar, or .tar.gz formats).

- The resources archive is made a child of the process template or custom application object in EKM.

- When a custom dialog box needs to be opened, the resource archive is extracted to a specific location. This location is:

  `path-to-custom-resources_folder`/_custom_resource_cache_/`id-of-the-object`

  where `id-of-the-object` refers to the internal ID of the object in EKM. It is used to store the resource files from different custom applications and process templates in a separate folder.

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:

- `VARIABLE_TYPE_LONG`: For integers

- `VARIABLE_TYPE_DOUBLE`: For real numbers

- `VARIABLE_TYPE_BOOLEAN:` For Boolean (true/false) values

- `VARIABLE_TYPE_STRING`: For strings

- `VARIABLE_TYPE_DATE`: For date and time

- `VARIABLE_TYPE_REFERENCE`: For reference to other objects in EKM

- `VARIABLE_TYPE_FILE`: For files that are uploaded to EKM

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);

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

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