Custom Module Creation Process

Any module in the Report has two components in its script:
  1. Tcl script that runs the functionality of the module.
  2. XML script that populates in the property area in the user interface


Figure 1. Module Creation Workflow

For any module to work successfully, the Tcl and XML files need to be connected and contribute their individual responsibilities properly.

For this process overview, two files will be used: CurveMaxima.xml and CurveMaxima.tcl. They are located here:

<installation_directory>/tutorials/hwdesktop/mv_hv_hg/publish_reports/CurveMaxima.xml

<installation_directory>/tutorials/hwdesktop/mv_hv_hg/publish_reports/CurveMaxima.tcl

Module Creation Process Overview

The module creation process consists of the following steps:
  1. Data preparation.

    The custom script performs the necessary processes on the model or graphs and prepares it for data capture. Values and information are captured, which can be used later for Report titles, image captions, and to populate text fields and tables.

  2. Defining the objects and placeholders.

    The Report API layer is used to create slides based on slide layouts or Word chapters. These objects contain images, text, and tables.

  3. Populate data.

    The data prepared in step 1 is used to populate objects in step 2. The property selection for individual items is set during the item creation (step 2) or this data population step.

  4. Connect to the user interface.
    Decide the input parameters that will be required to run this module. Options include:
    • Where the data exists (page and window selection, single or multiple).
    • The format to present the data. For example, specific slide layout styles.
    • The amount of content to add. For example, a module could have two modes: short and descriptive.
    Select all input parameters from the property area of the module in the user interface. The XML file for populating the interface must recognize which function in the module script a given property belongs to.
  5. Register the module.

    Register the directory of the module scripts in one of the recommended ways.

For this example, the custom module Curve Maxima will be used. This file can be found in <installation_directory>/tutorials/hwdesktop/mv_hv_hg/publish_reports/CurveMaxima.xml

Module Objective
From a given HyperGraph window, identify the names and IDs of all curves, the maximum Y value, and the curve's X location in a tabular format. Capture an image that highlights the maximum points from all curves. This needs to flexible for any Word or PPT format.

Data Preparation

A set of lines (Tcl) that prepares the data is required. For this module's objective, the HyperGraph window needs to be defined to get a clean capture. This includes all curves visible and only the maximum value notes created. Also, the values of the maximum Y and its equivalent X need to be found for each curve ID and label.

The CurveMaxima.tcl file can be found in <installation_directory>/tutorials/hwdesktop/mv_hv_hg/publish_reports/CurveMaxima.tcl

Lines 123 to 148 achieve this in the sample script CurveMaxima.tcl.


Figure 2. Data Preparation

Define Objects and Placeholders

Use report APIs to create slides with images, text, and tables for PowerPoint (PPT) and for Word, report and chapters with images, text, and tables.

  1. After creating the objects, apply APIs are used to display these items in the Report tab.
  2. For PPT, the Create Slide operation requires you to choose a slide layout. The slide layout contains information on the object's images, text, and tables to be created. Thus, it is not required to create these items again; only their IDs are required to use them for data population later.
  3. For Word, the object's images, text, and tables need to be created separately in the proper sequence. The chapter creation is optional, but creating a chapter creates an automatic entry in the table of contents. Also, while creating a chapter, you can specify the IDs of the objects to be included in the chapter.


    Figure 3. Report Object Creation

Populate Data

The objects created above can be populated with data obtained using the user logic. The IDs of the report objects are required in this step.

  1. In the module example below, lines 107-121 illustrate the text box data caption "Max values from curves", while the table headers are set to visible and their content is set.


    Figure 4. Populate Text and Table Information
  2. In the same loop where the curve data is obtained and notes are created, the table cells can also be populated. This is done from lines 149 to 154.
  3. After creating notes and hiding the content that is not required in the image, the image can be populated. The report image objects are capable of directly taking the image of the selected page/window. Alternatively, it can be sourced from an external image file that may have been saved during a previous capture operation.
  4. Image objects need a special execute operation. After execution, the temporary notations on the screen must be removed and the previously visible entities need to be restored. This is done from lines 156 to 167.


    Figure 5. Populate table cells and images
  5. The entire code block from the Tcl script must be placed in the execute block of the sample module Tcl template or can be replaced in CurveMaxima.tcl.
  6. In addition to the execute block, other blocks exist in the Tcl sample file. Pre-execute and post-execute blocks can contain the code responsible for both the presets before module execution and restoring the session to its original form after module execution. For example, the entity overview module always deletes all notes created for capturing images.


    Figure 6. Pre-execute and Post-execute

Connect to the User Interface

In the Tcl script, the initialize block receives the ID and the position to be assigned to the module. Also, it takes the values set in the property area of the module in the user interface.



Figure 7. Initialization Block

This initialize block is connected to the XML file and shares information from property area of the module.



Figure 8. Module Property Area


Figure 9. Module XML Script for the Interface

You can edit the template CurveMaxima.xml to change the hierarchy in the property area. It can also be edited to change the selection styles from combo box to multi-selector. Basic functions, such as getting default pages and window IDs, and special instructions regarding when the Report is in PPT or Word mode, can be written in the Tcl script and referred to in the XML file.



Figure 10. Functions for the User Interface

Register the Module

After finishing these steps, please place the XML and Tcl file in the appropriate location, preferably in the same folder. It's recommended to test this module in a HyperWorks session. For this, the module needs to be registered. This can be done in one of the following ways:

  1. Use the environment variable ARD_CUSTOM_PATH.


    Figure 11. Register Module with Environment Variable
    Note: Keep the forward slash in the directory path.
  2. Use Report API. 
    ::ardi::frwk addcustompath -directory [list {C:\Custom_Module\CurveMaxima}]
::ardi::frwk start -mode interactive
  3. After running this, close and open the Report tab. For the selected Report format, the custom module is listed along with the standard modules.


    Figure 12. Custom and Standard Modules