Configuring Custom Actions
DBM allows administrators to define their own actions. These actions can be executed by a click on a user-defined toolbar button, from the context menu (right-click menu) of selected table items, or from the "Entry" main menu. To configure a custom action, use the Digas Administrator tool (Admin.exe) or the DPE admin page.
Common Configuration
Each custom action is configured in a subfolder of the | DBM | Actions | key. The name of the subfolder is not relevant to execution of the action; however, when you assign a keyboard accelerator to the action, the accelerator is named after the folder, so folder names should be meaningful.
You can define custom actions at GLOBAL, LOCAL, use USER level of the Digas registry. You can even define some parts at GLOBAL, others at LOCAL and yet others at USER level. If you do that, each action must use the exact (except for upper/lower case) same folder name at each level.
- Use the DigaSystem Administrator tool or DPE Admin to add the configuration data to the Digas registry.
- Create the registry folder | DBM | Actions | if it does not exist.
- Inside this folder, create a folder for each custom action.
- Inside the action folder, create entries as described below.
Configuration entries depend on the type of action; this section descriped entries that are common to all types of action.
If this parameter is defined, the action is available only for the tables listed in the parameter's value. Otherwise, the current table doesn't play a role for the action's availability. The value is a list of table specifications, separated by commas, semicolons, or vertical bars. Each specification is either a table's alias name or has the type dsn\name (the backslash is essential). the alias, the dsn and the name parts can contain DOS-style wildcards.
Parameter Name | Comment |
|---|---|
| Action | Launch specifies that this action should launch an external program. Workflow specifies that a DPE workflow is scheduled for immediate execution. The default value is Launch. |
| ActionRight | If not empty, defines the name of an action right that the user must have to execute this action. If empty or undefined, no action right is required. |
| Enabled | Set to FALSE to hide the button for a specific workstation or user. The default value is TRUE. |
| Label | Defines the text that is displayed while the mouse hovers over the button, and the text that is displayed in various menus. The default is the name of the containing configuration folder. |
| VisibleForTables new since DBM 5.8.8216.0 | Defines that the action is visible only when specific tables are open. Contains a list of table specifications, separated by commas, semicolons, or vertical bars. Each specification is either an alias name, or it has the form dsn\name (the backslash is essential). Alias, dsn, and name parts can contain DOS-like wildcards. |
| DisplayIndex | The display index defines the order in which custom actions are displayed in the toolbar and in menus. Actions are displayed in order of ascending DisplayIndex values. Actions that have the same DisplayIndex appear in arbitrary order. The default value is 0. |
| Picture | Defines the graphic that appears on the toolbar button. This entry contains the full (absolute) path of the file. The file can be any of the following formats: EMF, PNG, BMP. If empty or not defined, a default image is used. |
| ApplySymbolColor | Set this entry to to TRUE when the Picture parameter points to an image that is white on transparent background. DBM will set the foreground color to the standard symbol color, so that the button appears like the standard DBM toolbar buttons. You should use this option whenever possible in order to get a consistent appearance of DBM's user interface, independent of the currently used color scheme. The default value is FALSE. |
SymbolColor | Define this parameter to colorize a white-on-transparent image. Note that ApplySymbolColor must be set to 1 for this parameter to work. The default color is the standard icon color from the color scheme. |
Launching an External Program
When you configure Action=Launch (this is the default Action value), DBM launches an external program when you click the button or select the menu entry. Optionally, DBM can move its application window on the screen so that the other part of the screen is available to the external program. In addition to the configuration entries mentioned under Common Configuration, the following entries are required.
| Parameter Name | Comment |
|---|---|
| Config | Either the name of a program that is known to the Digas System (i.e. a program that has an entry in the | Programs | folder), or the full path of the executable file. This parameter is mandatory. |
| DbmResize | If not empty, the DBM window will be resized and/or moved after the configured program has been launched. Possible values are:
The following options are valid for two-monitor setups only:
If this value is not configured, DBM does not move or resize its window. |
CommandLine | Contains the command line tail for the external program. You can use various placeholders which are replaced by actual values from the selected entry when the program is launched (see below for a list). |
IsVisibleFor0Entries | Set this parameter to 0 if the button should be disabled when nothing is selected in the table. The default value for Action=Launch is 1. (Note that, for Action=Workflow, the default is 0!) |
MultiSelection | Set this parameter to 0 if the button should be disabled when more than one entry is selected in the table. The default value for Action=Launch is 1. (Note that, for Action=Workflow, the default is 0!) |
VisibleForClasses | If this parameter contains a list of class names, then the action is available only if selected items belong to one of these classes. (For Action=Workflow, this can be configured via the Config parameter.) |
RequiresTable | If this parameter has the value 1 or true, then the action is available only when a table is open. (DBM starts without an open table unless this is explicitly configured.) |
If Config is empty, no button is created.
When the tool is configured with MultiSelection=1, and you have selected multiple entries when you click the button, then the tool is launched separately for each selected entry. All instances of the tool execute in parallel, and there is no guarantee as to which instance will finish first.
Command Line Placeholders
New feature since version 5.8.8210.0
The CommandLine parameter can contain placeholders which are replaced by actual value before the command line is passed to the external program. Placeholders fall into three categories:
- Digas variables, defined in the "Variables" section of the Digas registry. Specify Digas variables between percent signs like %DigasDir%.
- Windows environment variables. Like Digas variables, use percent signs: %COMPUTERNAME%. When a Windows environment variable has the same name as a Digas variable, the Digas variable overrides the environment variable.
- Placeholders that refer to the selected entry. Specify them between curly braced, like {TITLE}. These names must be written all uppercase. The most useful names are: {DSN}, {TABLE}, {NUMBER} (alias: {REFNO}), {TITLE}, {FILENAME}. To insert a left curly brace, use this syntax: {{}.
CommandLine="{MEDIUM/FILE#1/FILEREF}" passes the name of the main media file on the command line.
On the usage of quotation marks
Most programs use whitespace (space, tab, etc.) as parameter delimiter. This makes is difficult to pass file paths on the command line which contain whitespace, such as C:\Program Files\Windows NT, because programs will consider this to be several parameters, and complain they cannot find C:\Program. If this happens, try to enclose the parameter in double quotation marks, such as "C:\Program Files\Windows NT". If no whitespace is present, the quotation marks are simply ignored.
When you create a command line with a parameter that might contain whitespace, just add quotation marks, like this: CommandLine="{TITLE}".
Note that this is standard behaviour of Windows programs, but programs are not forced to behave according to the standard. If the program's documentation doesn't help, you must try whether quotation marks are required.
Placeholders of any category which cannot be resolved are replaced by an empty string.
Triggering a DPE Workflow
With Action=Workflow, you can request execution of a workflow from your DPE system. This can only work if you have a DPE system installed that connects to the same database and configuration values as DBM. Configuration is the same as under Common Configuration, with the following additions.
| Parameter Name | Comment |
|---|---|
| Config | The workflow configuration. See Configuration for Starting a Workflow for an Entry for details. This parameter is mandatory. |
| IsVisibleFor0Entries new since version 5.8.8209.0 | Set this parameter to 1 if the button should be enabled when nothing is selected in the table. The default value for Action=Workflow is 0. (Note that, for Action=Launch, the default is 1!) |
In DBM versions up to 5.8.8208.0, Action=Workflow custom actions are not available while no database entry is selected. They may be unavailable when multiple items are selected, or when selected items do not have the configured class; this is defined on the Config entry as documented in Configuration for Starting a Workflow for an Entry.
Configuring Sub Menus
When you have a large number of custom actions, it may help to group these actions into menus. The DBM custom actions configuration lets you create menus that contain a subset of available actions. This menu is represented by a toolbar button and by a submenu entry in the menus. Its name, graphical symbol, position etc. are configured with the entries listed under Common Configuration. The Action entry is ignored (it is not required). To flag this entry as submenu entry, create the Children folder in this configuration folder, such as | DBM | Actions | <MenuButton> | Children | <SubMenuButton> |. Inside the Children folder, add folders for SubMenuButton(s) that configure actions.