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