In some cases you may want to define actions to be associated with your custom types. These custom actions will be displayed as additional menus in the action menus of the custom type object in EKM. Actions may simply execute some commands when they are clicked or they may open up a dialog box to enable users to specify inputs before commands are executed.
The listing in Example 7.6: Custom Actions shows
a type definition that also defines some
custom actions. The XML code related to the action definition is contained
within <actions> and </actions>. This example shows how two action menus Append Description and Set Description are added to the Project custom type. These action menus are
added to a new and common parent menu called Custom Actions. So, in addition to the other built-in action menus (such as Delete, Edit, Help, and so on) you will now see another menu called Custom
Actions that will contain two submenus: Append
Description and Set Description. When
the Append Description menu is clicked, it does
not open a dialog box but simply appends the current time stamp to
the Project’s description. When the Set Description menu is clicked, it opens a dialog box that displays the current
description, and enables you to enter a new description. The description
entered is then applied to the Project when the dialog box is submitted.
The user interface files for the dialog box are stored in a folder
named set-project-description within the resources
folder (which is typically EKM_HOME/conf/resources unless its location has been changed in the ekm.xml file).
<type name="Project" extends="Container" version="1.0.0">
<properties>
<property name="componentType" label="Component Type"
type="String" required="true">
<enumeration>Type A</enumeration>
<enumeration>Type B</enumeration>
<enumeration>Type C</enumeration>
</property>
<property name="disciplines" label="Disciplines"
type="String" required="true" multivalued="true">
<enumeration>Stress</enumeration>
<enumeration>Flow</enumeration>
<enumeration>Thermal</enumeration>
<enumeration>Electromagnetic</enumeration>
</property>
<property name="partId" label="Part Id" type="Long" required="true">
<constraint name="min" value="0" />
<constraint name="max" value="100" />
</property>
<property name="exportControlled" label="Export Controlled?"
type="Boolean" required="true"/>
<property name="dateOfIssue" label="Date Of Issue"
type="Date" required="true"/>
</properties>
<children>
<child name="Requirements" occurs="required" type="Folder"/>
<child name="Common Files" occurs="required" type="Folder"/>
<child name="" occurs="list" type="Folder"/>
<child name="Reports" occurs="required" type="Folder"/>
</children>
<actions>
<script>
appendDescription(object, dialog) {
description = object.getProperty("description");
ekm.startTransaction();
time = Calendar.getInstance().getTime().toString();
object.setProperty("description", description+", added at: "+time);
ekm.commitTransaction();
}
setDescription(dialog) {
ekm.startTransaction();
object = dialog.getObject();
object.setProperty("description", dialog.getVars().get("description").getValue());
ekm.commitTransaction();
}
setDescriptionDialog(object, dialog) {
dialog.addStep("Set Description",
"/custom/set-project-description/set-description.xhtml",
"setDescription");
description = object.getProperty("description");
dialog.addVar("description", dialog.VARIABLE_TYPE_STRING,
description, false);
}
# 'Show on multi-selection' enabled, custom action will be displayed when multiple objects of the
same type are selected.
# Custom action menu will also be displayed for a single object selection.
def setDescriptionOnObjects(object, dialog) {
import time
ekm.startTransaction()
time = time.asctime(time.localtime(time.time()))
try:
# pythonic approach is to assume an iterable, then fail gracefully if it does not work
on the given object.
# Duck-typing avoids tests using type() or isinstance()
# iterate assuming list for multiple objects
for object in objects :
description = object.getProperty("description")
object.setProperty("description", description+", added at: "+time + " on multiple objects")
except TypeError:
# not a list of objects, then it must be a single object
object = objects
description = object.getProperty("description")
object.setProperty("description", description+", added at: "+time + " on single object")
ekm.commitTransaction()
}
</script>
<action name="Custom Actions/Append Description" icon="/custom/icons/tips.gif"
macro="appendDescription" permissions="modify" />
<action name="Custom Actions/Set Description" icon="/custom/icons/ansysIconSmall.gif"
macro="setDescriptionDialog" permissions="modify" />
<action name="Custom Actions/Set Description On Objects" icon="/custom/icons/ansysIconSmall.gif"
macro="setDescriptionOnObjects " permissions="modify" multiSelectEnabled="true" />
</actions></type>
As shown in the code in Example 7.6: Custom Actions, all actions related to a type must be
defined within the actions element. This
element contains a script element and any
number of action elements. The script element is used to define macros that are associated
with the action. See the chapter on Defining Macros and Custom Dialog Boxes in the EKM User's Guide for details on scripting and macro
definition. The action element defines each
action associated with the type and has the following attributes:
name: Specifies the name
of the action menu and any parent menus. The parent menus are separated
by a slash /. Parent menus will be created
if they do not already exist. The name of
the parent menu can also be an existing menu (such as Edit) and in this case, the new menu will be added to the existing parent
menu. You can specify the name of the parent menu only in a single
language. This means that if you have users in multiple locales, it
will be better to place the custom actions in a new parent menu, rather
than an existing one.
macro: Specifies the name
of the macro that will be called when the menu is clicked. See the
chapter on Defining Macros and Custom
Dialog Boxes in the EKM User's Guide for details on macro definition and the EKM scripting interface.
Typically, the macro will be defined in the script element before the action definition, but
you can also define it in the common library of macros that are loaded
by EKM at startup. The macro must take the following two arguments:
an instance of ModelObjectInterface that specifies the object on which the action will be performed
an instance of DialogInterface that specifies the dialog box that will be opened. If the action
does not require a dialog box to be opened, then you can ignore this
argument in the macro body. The macro named appendDescription in the above listing is an example of this type of macro. If the
action requires a dialog box to be displayed, the macro body should
define the steps that are part of the dialog box, using the addStep() method of the DialogInterface. The macro named setDescriptionDialog in
the listing is an example of this type of macro.
permissions: Specifies the
permissions that a user must have in order to view this action on
the action menu. The permitted permission values are:
access: Specifies who can access
(or view) the object.
create: Specifies who can add
a child to a folder object.
delete: Specifies who can delete
the object.
modify: Specifies who can modify
the object.
lifecycle: Specifies who can
perform lifecycle operations such as promote and demote.
download: Specifies who can
download a file or folder object.
fullControl: Specifies who
has full control over the object. Full control means that all permissions
are available, including the ability to change permissions.
icon: Specifies the path
to the image file that will be used to represent the icon. The convention
used for the path is: /custom/<relative location of
the file in EKM_HOME/conf/resources folder>, which is
the location of the EKM_HOME/conf/resources folder. For example, suppose you have added an icon called myicon.gif to your EKM_HOME/conf/resources/icons folder. The path you would specify for icon would then be: /custom/icons/myicon.gif.
To specify icons for a parent menu that is not associated
with any action, you can add a new action and just provide an icon
and not supply a macro. In the Project example shown above, you can
create a new action named Custom Actions and
supply it with an icon. Once configured, the icon will be displayed
along with the label for the new menu category.
multiSelectEnabled: To display
an action when multiple objects of this type are selected, set this
attribute to true. Otherwise, if set to false, the action will only be displayed when a single
object is selected. If you enable this option, make sure that the
corresponding macro script handles single and multiple objects, as
shown in the sample script.