7.3.1. Defining a New Custom Type

Engineering Knowledge Manager

Administration Guide | Chapter 7: Defining Custom Types | 7.3. Defining Custom Types Directly in EKM |

7.3. Defining Custom Types Directly in EKM |  | 7.3.2. Editing a Custom Type
Prev |  | Next

### 7.3.1. Defining a New Custom Type

There are three types of custom types you can define: an object type, a mixin, and an extension to a built-in type. Mixins are not types on their own, but can be embedded in an object type or extension to a built-in type.

To define a new custom type:

1. While in restricted configuration mode, select the `/Administration/Configuration/Custom Types` folder, then select (New) > EKM Type. This opens the New Custom Type dialog box.

   Figure 7.1: Defining a New Custom Type

2. This dialog box contains the following tabs for specifying various settings of the custom type:

   - General: On this tab, you specify:

     - Kind of custom type: You have 3 options to choose from: Object type, Mixin or Extension to a built-in type. Refer to Defining Custom Types Using XML for more details on these options. The other settings in the tab and the other tabs in this dialog box depend on which option you select.

     - Name: This is the name of the custom type. Note that the custom type name, also referred to as `typeName`, is not the same as the name of the custom type object; however, usually the object name is typeName.type.xml. Thus if you specify the name to be Project, the name of the object will be Project.type.xml.

     - Label: The name is usually an internal ID whereas the label is how the type is represented in the user interface. Do not use the label or name of any built-in type. If the type extends a built-in type, you may want to append a suffix such as `_c` to the label to make it unique.

       A label is not specified if you are creating a mixin or an extension to a built-in type.

     - Extends from: This is the base class from which the type extends. This is not specified if you are defining a mixin. Existing types are shown in a drop-down list. Non-localized type names are used because some type names have a common localized name. Also, the list may not contain a new type that you have just defined if you have not yet accepted or applied the workspace configuration. If you want to refer to a recently-created type in your new custom type definition, then you will need to apply the workspace configuration first, before you can define the new type.

   - Properties: On this tab you specify the properties of the custom type. This tab is not available if you are defining an extension to a built-in type. See Defining Properties for a Custom Type below for details. Note that if you want to extend an existing type by adding properties to it, you will need to first define a mixin that specifies the properties, and then add the mixin to your extended type definition.

   - Children: On this tab you specify any children of the type. This tab is not available if you are defining an extension to a built-in type. See Defining Children for a Custom Type below for details.

   - Mixins: On this tab you specify any mixins of the type. A mixin can be used to create sharable groups of children and properties that can be included in more than one type (new data types and extensions to built-in types). This tab is not available if you are defining a mixin. See Defining Mixins for a Custom Type below for details.

   - Type Attributes: On this tab you specify any type attributes of the type. This tab is not available if you are defining a mixin or an extension to a built-in type. See Defining Type Attributes for a Custom Type below for details.

   - Script: On this tab you can define macros that you can reference when defining type attributes, actions and views for a custom type. See Defining Scripts for a Custom Type for details.

   - Actions: On this tab you specify any actions for the type. This tab is not available if you are defining a mixin. See Creating Actions for a Custom Type below for details.

   - Views: On this tab you can define custom views for the type. These will appear as additional tabs in the view window when viewing an object of this type. See Creating Custom Views for a Type for details.

3. When you have specified all the settings, you can click Create & New to create the new type and open the same dialog box again for creating an additional type. If you do not want to create any additional types, you can click Create & Close to create the type and dismiss the dialog box.

#### 7.3.1.1. Defining Properties for a Custom Type

The Properties tab in the Edit Custom Type dialog box can be used to specify properties of a custom type as shown in Figure 7.2: Custom Type - Properties.

Figure 7.2: Custom Type - Properties

You can click Add to add a new property. You can then specify the settings for each property in the Property definition pane. The settings will depend on the type of the property, but will include the following:

- Name: This is the name of the property. When a new property is added it has a default name, such as `prop0`. You can change the name and click the Rename button to specify a different name.

- Label: This is how the property will be represented in the user interface.

- Type: Choose the property type: String, Integer (referred to as “Long” in XML), Real Number (referred to as “Double” in XML), Boolean, Date or Reference.

- Multi-line value: For `String` properties, enables you to specify two or more lines of text as the value of the string.

- Default: You can specify a default value for the property. The value should be compatible with the type, and whether or not it is multi-valued. Refer to Defining Properties Using XML for more details on how to provide correct values for various property types.

- Options: If the user can only select the value of the property from a limited set of options, you can specify the options separated by comma.

- Hidden: Specifies that the property will not appear in the Properties display when a user is viewing or editing object properties (on the Details tab or in the Edit Properties dialog box). This means that users cannot specify the property's value, even if the Extracted option is disabled (see below). Hidden properties are set via scripting.

- Display order: This value is set when you want the property to appear in a particular order in the Properties display or in a dialog box when user input is required. Dialog boxes include: Edit Properties, Edit Type, New Folder, and New Object. This value can be any valid integer. Properties with lower order are displayed first. If unspecified, the default value is `0`, which will display the property alphabetically by name. The Display order setting is not available for Hidden properties, because such properties are not visible in the Properties display.

- Extracted: If this check box is selected it means that the property value is automatically extracted. Otherwise it is specified by the user, or a script.

- Required: If this check box is selected it means that the user is required to enter the value of this property.

- Multivalued: If this check box is selected it means that the property is multi-valued or a list.

- Base type: This setting is available if the property type is Reference and is used to specify the base type of the object reference. You may need to apply the workspace configuration in order to see a recently created custom type in this list.

- Minimum and Maximum: These settings are available if the property type is Integer or Real Number.

- Quantity and Unit: These settings are available if the property type is Real Number and are used to specify the unit information. Refer to Defining Properties Using XML for more details.

You can also click an existing property in the Properties column to either change its settings or remove it by clicking Remove.

#### 7.3.1.2. Defining Children for a Custom Type

The Children tab enables you to specify the children of a custom type as shown in Figure 7.3: Custom Type - Children.

Figure 7.3: Custom Type - Children

You can add a new child by clicking the Add Child button. This will add a new row to the children table. For each child you can specify the following:

- Name: This is the name of the child. It can be empty if the child is a list.

- Type: This is the type of the child. You may need to apply the workspace configuration in order to see a recently created custom type in the drop-down list.

- Is List: Specifies whether or not the child is a list.

#### 7.3.1.3. Defining Mixins for a Custom Type

Mixins can be defined when you want to create a sharable group of children and properties that can be included in more than one custom type (new data type/extension to a built-in type). The Mixins tab enables you to specify the mixins for a custom type, as shown in Figure 7.4: Custom Type - Mixins.

Figure 7.4: Custom Type - Mixins

You can add a new mixin by clicking Add Mixin. This will add a new row to the Mixin table. You can select the particular mixin that you want to add to the custom type from the drop-down list. You may need to apply the workspace configuration to see a recently-created mixin in this list. You can remove an existing mixin by clicking the Remove button in the row.

#### 7.3.1.4. Defining Type Attributes for a Custom Type

The Type Attributes tab enables you to specify type attributes for a new object type.

Figure 7.5: Custom Type - Type Attributes

The Type Attributes that are shown in the dialog box depend on the base type from which the custom type extends. The list of type attributes shown in Figure 7.5: Custom Type - Type Attributes are the default settings for a new object type that extends from `CaeModelFile`. Settings are described below.

icon

  This attribute can be used to specify the path of the icon file associated with this file type. You can place icon files in the resources folder (typically `EKM_HOME/conf/resources`) and specify the value of this type attribute as `/custom/`<path of icon file in resources folder>``.

  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 without supplying a macro.

propertyUpdateMacro

  This attribute can be used to specify a macro that will enable dependencies to be created across properties, so that if one property is changed, other properties that depend on it will change as well. The macro that you specify must be defined in the Script entry box on the Actions tab. See Example: Specifying a Macro that Creates Dependencies Across Properties for an example.

  A dependent property can change if:

  - the property value is changed

  - the property is enabled or disabled

  - the property options are changed for drop-down lists or list boxes

  The property dependencies will be visible in the following dialog boxes in EKM:

  - Edit Properties (Set Properties step)

  - Upload

  - New Folder

  The macro that you define on the Script tab should have two arguments. The first argument is of type `ModelObjectInterface` and for the Edit Properties dialog box, it is the object whose properties are being changed. For the Upload and New Folder dialog boxes, it represents the parent folder where the object will be added or uploaded. The second argument is a map of the `Property` object. An overview of the methods contained in the `Property` object is provided below. For more details, refer to the scripting interface API.

  - `getValue`: Returns the current value of the property.

  - `setValue`: Sets the value of the property.

    If you need to modify variable values using an action macro, you can either have the macro return a map containing the name of the property and its updated value, or directly set values using the setValue method in the macro.

  - `isDisabled`: Returns true if the property is disabled and false otherwise.

  - `setDisabled`: Disables or enables the property.

  - `getOptions`: Returns the list of options for properties shown in a drop-down list or list box.

  - `setOptions`: Sets the options for properties shown in a drop-down list or list box. The specified options must be a subset of options specified in the type definition for that property.

extractImageOnUpload

  This attribute can either be `true` or `false` and specifies whether an image of the CAE model should be extracted after upload. Images are not extracted from all simulation files.

imageName

  This attribute can be used to specify the format of the image file that is extracted when an image extraction application is specified. For example, to extract an image in CAX format, you would specify `file.cax` as the value of this attribute. Note that a suitable extractor must be specified for the `imageApplication` attribute.

  Note that 3D images are automatically extracted from several built-in CAE file types by default. For certain Fluent, CFX and Mechanical APDL file types, 3D images are extracted and displayed in an interactive 3D viewer on the Image tab when viewing the CAE file in EKM. Specifying values for the `imageName` and `imageApplication` attributes will override this default. For more information about the default image extraction, see Automatic Extraction of Images on Upload in the EKM User’s Guide.

disableDataExtraction

  This attribute can either be `true` or `false`. It is used to specify whether or not data is extracted from a file of this type when it is uploaded to EKM, and whether or not data can be manually extracted from it after it has been uploaded.

  Note:

  - If you are enabling data extraction for a type, you must also make sure that the global Disable data extraction setting is disabled in your Preferences. See Specifying General Preferences in the EKM User’s Guide for details.

  - A type's `disableDataExtraction` attribute also controls whether or not metadata is extracted from a Workbench project archive (.wbpz file) when it contains that file type.

contentType

  This attribute can be used to specify the MIME type of the file.

initializeMacro

  This attribute can be used to specify a macro that will executed after the object is created. The macro that you specify should have one argument of type `ModelObjectInterface` that represents the newly-created object and must be defined on the Script tab. See Example: Executing a Macro When an Object Is Created for an example.

imageApplication

  This attribute is used to specify the application used for extracting an image from a file after upload. Images can be extracted in any web-compatible format such as GIF, JPEG, PNG, TIFF, as well as VCollab’s CAX format for 3D visualization. The application should take the name of the file as a command line parameter and generate the image file in the current working directory. The input file will also be available in the current working directory.

  For example, if the `imageName` attribute is set to `file.cax`, you could specify `extractCaxImage` as the value of the `imageApplication` attribute to use the built-in CAX extractor application, extractCaxImage.app.xml, to extract CAX files. For more information about configuring EKM to use VCollab, see Using VCollab for 3D Visualization in EKM.

extension

  This attribute can be used to specify the file extension for the format. EKM uses the extension to identify the appropriate type for a file. If your file format can have multiple extensions then you can specify them in a comma-delimited string.

extendBuiltInExtraction

  This attribute can be used to specify whether the metadata or report extractors that are specified will extend or replace any built-in extractors. When the value is set to `true` (default), the additional extractors that you specify for metadata extraction in the `metaDataApplication` setting and simulation details report extraction in `customReportApp` setting will extend the built-in extractors so that custom extraction occurs after the built-in extraction. When the value is `false`, the additional extractors will replace the built-in extractors so that built-in extraction does not occur at all. This attribute will be available only if you are defining a new object type. If you are defining an extension to a built-in type, then you will need to set this attribute in the WorkspaceConfig.xml file.

metaDataApplication

  This attribute can be used to specify an application for extracting metadata from a file after upload. The value for this type attribute should be a `key` for the application defined in the application.xml file. See Extracting Metadata from Custom File Formats for details. If this value is empty, the built-in extractor will be utilized if defined for that type.

typeValidatorClass

  This attribute can be used to specify a Java class used for determining a file’s type. This is used for automatic type assignments during uploads.

  The custom type validator class requires the `com.ansys.ingress.core.fs.FileType Validator` interface in the ekm-core-18.2.jar file for compilation. After compilation the `*.jar` file containing the custom type validator class should be placed in the `EKM_Home/plugins-deploy` folder. EKM will load the type validator class from this `*.jar` file when the server is restarted.

showContentViewAsDefault

  If set to `true`, the content view of the CAE file will be the default view in the interface.

allowJobExecution

  If set to `true`, an Execute menu will be available for the CAE file, enabling users to execute batch and interactive jobs directly from the file.

reportApplication

  This attribute can be used to specify an application for extracting a `Simulation Details Report` from a file after upload or on-demand. See Extracting Reports from Custom File Formats for information on how to build an application for extracting the report.

customStatusFlagsMacro

  Use this attribute to specify the name of a macro that will display custom status flags and icons when an object of this type is displayed or queried in the list view.

  In Python, the macro should use `def testStatus(model):`, as shown in the example below:

      def testStatus(model):
          statuses  = [["testStatus", "/custom/testStatusFlag/status.gif"]]
          return statuses

  The status flag is a list with two values: a key and an icon. In the example above, if the key `testStatus` is defined in the custom.properties file, a localized tooltip will be displayed. Otherwise, the key will appear as the tooltip.

  In BeanShell, the macro should use `List testStatus(model)`, as shown in the example below:

      import java.util.List;
      import java.util.ArrayList;

      List testStatus(model) {
          List statuses = new ArrayList();
          List status = new ArrayList();
          status.add("testStatus");
          status.add("/custom/testStatusFlag/status.gif");
          statuses.add(status);
          return statuses;
      }

##### Example: Specifying a Custom Metadata and Report Extractor for a Built-in Type

The following sample XML code is used to define a custom report extractor (`customReportApp`) and a custom metadata extractor (`customMetaApp`) for new type that is an extension to the built-in `FluentCase` type. While the workspace is in restricted configuration mode, edit the content of the `WorkspaceConfig.xml` file in `/Administration/Configuration` (using Edit > Content), and add the following XML code:

    <typeSettings>
            <type name="FluentCase">
                <typeAttribute name="extendBuiltInExtraction" value="true"/>
                <typeAttribute name="metaDataApplication" value="customMetaApp"/>
                <typeAttribute name="reportApplication" value="customReportApp"/>
            </type>
        </typeSettings>

Then, apply and accept the workspace configuration. The applications need to be defined as External Applications under EKM Server (for example, `/Administration/Servers/Master/EKM Server`). Refer to Extracting Metadata from Custom File Formats for more information on defining applications for the metadata extraction.

##### Example: Specifying a Metadata and Report Extractor for a New Object Type

The following example defines a custom extractor for metadata and report generation for a new custom object type of type “NCT” that extends `CAEModelFile`. The file listings for the extractor Python files, external application XML files, custom object type, and custom mixin type are shown below.

1. Using a text editor, create the external applications that are needed by copying and pasting the contents of the external application files customMetaApp.app.xml and customReportApp.app.xml listed below into an empty file and saving the files with the names and extensions as noted.

2. Using a text editor, create the custom object type and custom mixin type files that are needed by copying and pasting the contents of the `NewCustomType.type` and `mix1.type` listed below into an empty file and saving the files with the names and extensions as noted. You can also create these files using the New > Custom Type action. To do this, you will have to refer to the settings in the XML files and specify the corresponding settings in the Edit Custom Type dialog box.

3. Edit the external application files and enter the correct path to your Python executable in `<execPath>`.

   Also, enter the path to the directory where the Python files (extract-additional-metadata.py and extract-additional-report.py listed below) are stored on your local drive in `<param>`.

   Example:

   <execPath>C:\Python25\python.exe</execPath>

   <param>C:\EKM\extract-additional-metadata.py</param>

4. While the workspace is in restricted configuration mode, upload the external application files to the `/Administration/Servers/Master/EKM Server` folder.

5. Upload `NewCustomType.type` and `mix1.type` files to the `/Administration/Configuration/Custom Types` folder.

6. Apply and Accept Workspace Configuration. You may have to migrate your workspace if there are data model conflicts that need to be resolved. To do this, sign out of EKM and sign into the EKM Administration site. Once migration is complete, sign back into EKM and Apply/Accept the Workspace Configuration.

7. Upload any Fluent case file. Change the type to `NCT` using Edit > Type.

8. Display the simulation details report and view the custom report additions by clicking on the Fluent case file.

9. Display the added custom metadata for the report by clicking the Details tab.

File Listing for `extract-additional-report.py`

    f = open('ekm-report.xml', 'w')

    s = """
    <ekmReport:section xmlns:ekmReport="http://www.ansys.com/ekm/report" name="Custom report">
          <table name="Project Information">
            <column name="condition"/>
            <column name="value"/>
            <row><value>Client</value><value>abc</value></row>
            <row><value>Company Name</value><value>ANSYS</value></row>
    		<row><value>Company Location</value><value>Globally</value></row>
            <row><value>Contact Person</value><value>Dana</value></row>
            <row><value>Contact Address</value><value>abc@def.com</value></row>
          </table>
          <table name="Solution Information">
            <column name="condition"/>
            <column name="value"/>
            <row><value>Solver</value><value>Mechanical APDL</value></row>
            <row><value>iterations</value><value>1500</value></row>
            <row><value>version</value><value>18.2</value></row>
            <row><value>tolerance</value><value>0.02</value></row>
            <row><value>physicalModels</value><value>Stress, Magnetostatic</value></row>
          </table>
    </ekmReport:section>
    """
    f.write(s)

    f.close()

File Listing for `extract-additional-metadata.py`

    import os
    scriptPath = os.getenv('PYTHON_EXEC_PATH')

    f = open('ekm-meta-data.xml', 'w')

    s = """<ekmMetaData:meta-data xmlns:ekmMetaData="http://www.ansys.com/ekm/metaData">
    <data name="p1" value="%s"/>
    <data name="p2" value="101"/>
    <data name="fluentVersion" value="6.4.17"/>
    </ekmMetaData:meta-data>
    """ % scriptPath
    f.write(s)

    f.close()

File Listing for `customMetaApp.app.xml`

    <?xml version="1.0" encoding="UTF-8"?>
    <ekmApplication:applications xmlns:ekmApplication="http://www.ansys.com/ekm/application"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <application>
        <key>customMetaApp</key>
        <execPath>C:\Python25\python.exe</execPath>
        <param>C:\EKM\extract-additional-metadata.py</param>
        <nativeOptions />
      </application>
    </ekmApplication:applications>

File Listing for `customReportApp.app.xml`

    <?xml version="1.0" encoding="UTF-8"?>
    <ekmApplication:applications xmlns:ekmApplication="http://www.ansys.com/ekm/application"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <application>
        <key>customReportApp</key>
        <execPath>C:\Python25\python.exe</execPath>
        <param>C:\EKM\extract-additional-report.py</param>
        <nativeOptions />
      </application>
    </ekmApplication:applications>

File Listing for `NewCustomType.type`

    <?xml version="1.0" encoding="UTF-8"?>
    <ekmTypes:types xmlns:ekmTypes="http://www.ansys.com/ekm/types"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <type name="New Custom Type" extends="CaeModelFile" label="NCT" version="0">
        <properties />
        <children />
        <mixins>
          <mixin>mix1</mixin>
        </mixins>
        <typeAttributes>
          <typeAttribute name="extension" value="cas" />
          <typeAttribute name="extendBuiltInExtraction" value="true" />
          <typeAttribute name="metaDataApplication" value="customMetaApp" />
          <typeAttribute name="extractImageOnUpload" value="true" />
          <typeAttribute name="imageName" value="file.cax" />
          <typeAttribute name="showContentViewAsDefault" value="false" />
          <typeAttribute name="contentType" value="text/plain" />
          <typeAttribute name="reportApplication" value="customReportApp" />
          <typeAttribute name="imageApplication" value="extractCaxImage" />
        </typeAttributes>
        <actions>
          <script />
        </actions>
      </type>

File Listing for `mix1.type`

    <?xml version="1.0" encoding="UTF-8"?>
    <ekmTypes:types xmlns:ekmTypes="http://www.ansys.com/ekm/types"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <mixin name="mix1" version="0">
        <properties>
          <property name="p2" type="Long" label="" multivalued="false"
            required="true" specifiedBy="extractor" displayOrder="1">
            <defaultValue>0</defaultValue>
            <constraint name="min" value="-9223372036854775808" />
            <constraint name="max" value="9223372036854775807" />
          </property>
          <property name="p1" type="String" label="" multivalued="false"
            required="true" specifiedBy="extractor" displayOrder="0">
            <defaultValue />
          </property>
        </properties>
        <children />
      </mixin>
    </ekmTypes:types>

#### 7.3.1.5. Defining Scripts for a Custom Type

The Script tab enables you to input a script using either Python or BeanShell. Macro names specified in the script can be referenced when defining type attributes, actions or views for the object type.

Figure 7.6: Edit Custom Type - Script

To define a script for a type:

1. On the Script tab of the Custom Type dialog box, select the Script Language that you want to use for the script that will be associated with the action, view, or type attribute.

2. Enter or paste the script into the Script text box.

##### Example: Specifying a Macro that Creates Dependencies Across Properties

The following macro named `updateProperties` creates dependencies across properties for a custom type. In the first line, the property `partId` is set to be disabled if the Boolean property `exportControlled` is `true`. After that it creates a list of options for the property `disciplines`. The options depend on the value of `componentType` property. You must specify the name of this macro in the `propertyUpdateMacro` setting in the Type Attributes tab. See Defining Type Attributes for a Custom Type for more details.

File listing for `updateProperties`:

    updateProperties(model, properties) {
       properties.get("partId").setDisabled(properties.get("exportControlled").getValue());
       l = new LinkedList();
       l.add("Flow");
       l.add("Electromagnetic");
       ct = properties.get("componentType").getValue();
       if (!ct.equals("Type B")) {
          l.add("Thermal");
          l.add("Stress");
       }
       properties.get("disciplines").setOptions(l);
    }

##### Example: Executing a Macro When an Object Is Created

The following macro named `initObject` sets the description property of an object when it is created. You must specify the name of this macro in the `initializeMacro` setting in the Type Attributes tab. See Defining Type Attributes for a Custom Type for more details.

    initObject(model) {
     ekm.startTransaction();
     model.setProperty("description", "Set from script during initialization");
     ekm.commitTransaction();
    }

##### Example: Launching a URL from a Macro

In order for a URL to be launched from a macro, the macro must create and return a URL string.

The example below shows you how to customize the file download action using a macro that returns a URL string. Sample files that illustrate this example can be found in the following folder:`EKM_HOME\examples\conf\customTypes\customDownload`.

In the following script, the repository file original.cdl is downloaded to the directory specified by the environment variable `EKM_TEMP`. The file is modified, and the new file is saved to a directory under `EKM_TEMP`. The macro returns a URL string that corresponds to the location of the modified file. When the macro is completed, the URL will be launched by the browser, and the modified EKM file will be downloaded to the user's desktop.

    def customDownload(object, dialog):
    	originalFile = ekm.getObjectByPath('/Data/Shared Data/original.cdl')
    	fis = originalFile.getContent()
    	reader = BufferedReader(InputStreamReader(fis))
    	uuid = UUID.randomUUID().toString()
    	outputFilePath = os.path.join(os.getenv('EKM_TEMP'), uuid)
    	os.mkdir(outputFilePath)
    	outputFilePath = os.path.join(outputFilePath, 'modifiedFile.txt')
    	outputFile = open(outputFilePath, 'w')
    	while True:
    		line = reader.readLine()
    		if line == None:
    			break
    		outputFile.write(line + '\n')
    	outputFile.write('Modified content appended')
    	outputFile.close()
    	outputFilePath = outputFilePath.replace( "\\", "/")
    	return ekm.getRemoteFileUri(outputFilePath)

#### 7.3.1.6. Creating Actions for a Custom Type

The Actions tab enables you to define actions for a custom type, and remove selected built-in actions from it. Actions that you add will be associated with the custom type and selectable from the right-click context menu as well as from the action toolbar. Built-in actions that you remove will not be available on the context menu and toolbar. When adding an action, you can also define an icon to represent the action which will be visible on the toolbar and in menu items.

Figure 7.7: Custom Type - Actions

Prior to defining an action you will need to specify a script on the Script tab that contains the macro to be executed when the action is performed. You will reference the macro name when defining the action.

To create an action for a custom type:

1. On the Actions tab of the Custom Type dialog box, click the Add Action button. A new row will be added for each new action that you add.

2. For each action in the table, specify the Name, Macro, Permissions, and (optional) Icon, in accordance with the settings described in Defining Actions Using XML. For menu groups, you may add a row containing just the Name and Icon of the group. There is no Macro associated with a menu group.

3. To display an action when multiple objects of this type are selected, enable the Show on multi-selection check box for that action. Otherwise, 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 following sample script:

       # Example macros for custom actions

       # 'Show on multi-selection' disabled, custom action menu will be displayed for a single object
          selection only.
       def appendDescription(object, dialog):
           import time
           description = object.getProperty("description")
           ekm.startTransaction()
           time = time.asctime(time.localtime(time.time()))
           object.setProperty("description", description+", added at: "+time)
           ekm.commitTransaction()

       # '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 setDescription(objects, 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()

##### Example: Custom Action with Icon

The following example defines an icon for two actions added to a custom `Project` folder type.

1. Create two sample image files containing icons and name them tips.gif and ansysIconSmall.gif.

2. Create an icons folder in `EKM_HOME/resources/` if it does not exist. Copy the image files to this folder.

3. Begin workspace configuration.

4. Upload the Project.type.xml file that is provided in the examples folder in `EKM_HOME/examples/conf/customTypes` to the `Administration/Configuration/Custom Types` folder in the EKM repository.

5. Edit the custom type by selecting the custom type file (Project.type.xml), right-clicking, and selecting Edit > Custom Type.

6. In the Edit Custom Type dialog box, select the Actions tab.

7. Use Add Action to add two action rows.

8. In the Icon column, enter `/custom/icons/tips.gif` for the first row and `/custom/icons/ansysIconSmall.gif` for the second row.

9. Click OK.

10. Apply and accept the workspace configuration.

11. In the repository, create a new custom folder of type `Project` and give it a name.

12. Right-click the new custom folder that was added and verify that a new menu item named Custom Actions appears at the bottom of the context menu. When you right-click the menu item, verify that two submenu items named Append Description and Set Description are listed, along with their corresponding icons (tips.gif and ansysIconSmall.gif, respectively).

    Verify that the actions are also available in the Action toolbar.

##### Localizing Custom Action Labels

You can configure EKM to display custom action labels in the language that is selected for the EKM interface.

1. Shut down the EKM server. Refer to the chapter on Starting and Connecting to EKM in the Installation Guide for details.

2. On the EKM server, go to EKM_HOME/bundles and open the folder that corresponds to the chosen locale (de = German, en = English, fr = French, ja = Japanese). Open the custom.properties file in a text editor. If such a file does not exist, create a text file named custom with the extension properties.

3. In a text editor, specify the following entry in the custom.properties file:

   ``actionName`.menu=`localized text``

   where ``actionName`` is the name of the action in the custom type definition (without spaces), and ``localized text`` is the desired action label text.

   For example, if you defined a custom type with an action named Set Description, and wanted it to appear in German when the German locale is selected, you would enter the following in the EKM_HOME/bundles/de/custom.properties file:

   `SetDescription.menu=Beschreibung Definieren`

4. Save the custom.properties file, and then restart the EKM server.

##### Removing Built-in Actions from a Custom Types

When defining a custom type, the Actions tab displays a list of built-in actions that are available for that type. If you do not want a particular action to be included on an object’s context menu or toolbar, simply enable its check box to remove it:

The available built-in actions will vary depending on the object type:

- For containers and folders: Delete, Edit, New, Download, Upload, More

- For files: Delete, Edit, New, Download, More

- For all other types: Delete, Edit, New, More

#### 7.3.1.7. Creating Custom Views for a Type

When defining an object type, you can create custom views for the object. These views will be displayed as custom tabs in the view window when you open an object of the specified type.

Views can contain object properties, images, links to other EKM objects, or other components.

There are three aspects to defining a custom view:

- Defining the interface in an XHTML file

- Defining a macro that references the XHTML file

- Adding a view that references the macro

##### Step 1: Define the Interface

To define the components of the custom view, such as images or object links, you can use JSF, RichFaces, Tomahawk, HTML, JavaScript, or CSS. For information about these technologies, the structure of XHTML files, and defining interface components, refer to Defining a Custom User Interface.

##### Step 2: Define a Macro

Once you have defined the interface in an XHTML file, you must specify a macro that will be used to define the functionality of the custom view, and initialize it.

This macro should specify:

- The name of the XHTML file that defines the content of the custom view

- The variables used to initialize input and output interface components, and store inputs specified by the user in the input components

Variables can be accessed by the macro to retrieve user inputs and act upon them.

For an example of how a macro is defined, see Example: Creating a Custom Interface for Fluent Batch Jobs.

##### Step 3: Add a View

To define a custom view for an object type:

1. In the Custom Type dialog box, select the Views tab, then click Add View. A new row will be added for each new view that you add.

   Figure 7.8: Custom Type - Views

2. Specify a Name for the view. When you open an object of this type, this will be the label displayed on the view’s tab.

3. Specify the name of the Init Macro that you defined on the Script tab which references the XHTML file.

4. If you want a custom view to be the default view when an object of this type is opened, enable the Default radio button in that view’s row.

##### Example: Creating a Custom Folder View

The following example steps you through the creation of a custom folder view that includes a customized list display and a mechanism for filtering the list so that only files with a specified name are listed.

Figure 7.9: Custom Folder View

The sample files referenced in this example are located at /Data/Shared Data/Sample Files/conf/customTypes/customViews.

1. Define the components of the custom view in an XHTML file. For information about defining interface components, refer to Defining a Custom User Interface. For this example we used the filter.xhtml file located at Data\Shared Data\Sample Files\conf\customTypes\customViews. This file was created using HTML5-friendly markup. The contents of this file are shown below.

       <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD
       /xhtml1-transitional.dtd">
       <html xmlns="http://www.w3.org/1999/xhtml"
       	xmlns:f="http://java.sun.com/jsf/core"
       	xmlns:h="http://java.sun.com/jsf/html"
       	xmlns:t="http://myfaces.apache.org/tomahawk"
       	xmlns:ui="http://java.sun.com/jsf/facelets"
           xmlns:ing="http://www.ansys.com/ingress/spdm"
           xmlns:a4j="http://richfaces.org/a4j"
       	xmlns:rich="http://richfaces.org/rich"
       	xmlns:jsf="http://xmlns.jcp.org/jsf"
       	xmlns:p="http://xmlns.jcp.org/jsf/passthrough">

       <body>

       <ui:component>

       <style>
           .childTableColumn {
               text-align:left;
               width: 250px;
           }
       </style>

       <div style="width: 750px; margin-left:auto; margin-right: auto; margin-top:50px;">

       	<h2>Contents of #{custom.view.object.name}</h2>

       	<form jsf:id="filterForm" jsf:prependId="false">

       	<table style="margin-left: 4px;" id="filterForm:filterPanel">
       	<tbody>
       	<tr>
       	<td>Filter Names (start with)</td>
       	<td>
       	<input style="width: 150px" type="text" jsf:id="name" placeholder="Enter file name"
       	jsf:value="#{custom.view.vars.filter.value}"/>
       	</td>
       	<td>
       	<button jsf:action="#{custom.view.executeMacro('doFilter')}">Filter
       		<f:ajax event="click" render="childTable" execute="filterForm"/>
       	</button>
       	</td>
       	</tr>
       	</tbody>
       	</table>
       	</form>

       	<table cellspacing="5" style="margin-top: 20px;" jsf:id="childTable">
       	<thead>
       	<tr>
       	<th scope="col" class="childTableColumn">Name</th>
       	<th scope="col" class="childTableColumn">Type</th>
       	<th scope="col" class="childTableColumn">Modified By</th>
       	</tr>
       	</thead>
       	<tbody>

       	<ui:repeat id="items" value="#{custom.view.vars.result.value}" var="childName">
       	<tr>
       	<td class="childTableColumn">#{childName}</td>
       	<td class="childTableColumn">#{custom.view.object.getChild(childName).properties.type}</td>
       	<td class="childTableColumn">#{custom.view.object.getChild(childName).properties.modifiedBy}</td>
       	</tr>
           </ui:repeat>

       	</tbody>
       	</table>

       </div>

       </ui:component>
       </body>
       </html>

2. Copy the XHTML file to `EKM_HOME\conf\resources`.

3. Go to the Administration section and select Configure > Begin Workspace Configuration.

4. On the /Administration/Configuration page, open the Custom Types folder, then select (New) > EKM Type.

5. On the General tab of the New Custom Type dialog box, specify the following settings:

6. On the Script tab, define a macro that references the filter.xhtml file created in step 1, and defines the variables used for inputs and outputs:

7. On the Views tab, click Add View, then specify the Name of the custom view tab, and the name of the Init Macro that you defined on the Script tab which references the XHTML file. Enable the Default option to make this view the default view when viewing the custom folder.

8. Click Create & Close. A file named customFolder.type.xml is added to the Custom Types folder.

9. Accept the workspace configuration.

10. Go to a folder in the Data section and select (New) > Folder.

11. In the New Folder dialog box, give the new folder a name of your choice, then click the Type dropdown and select Custom Folder:

    Click OK to create the new folder.

12. Open the new folder. Notice that the view opens on a custom My Folder View tab that has a customized display:

    Once you have uploaded files to the folder, you can use the custom filter component to filter out files with a specified name.

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.