7.4.3. Defining Actions Using XML

Engineering Knowledge Manager

Administration Guide | Chapter 7: Defining Custom Types | 7.4. Defining Custom Types Using XML |

7.4.2. Defining Properties Using XML |  | 7.5. Custom Type Examples
Prev |  | Next

### 7.4.3. Defining Actions Using XML

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

Example 7.6: Custom Actions

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

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.