Customizing Configurable Link Tables

Customization > Configurable Links > Configurable Link Tables > Customizing Configurable Link Tables

This section describes each of the components that went into creating a Configurable Link table and displaying it in the OOTB example. Customizing the Configurable Link tables is also covered here. Customization is described using the OOTB example as a reference. An important point to note is that the file extensions (Ex: .xml, .xconf) and the format within the files must be maintained.

1. Define Configurable Link types and valid relationships.

The first step to customizing Configurable Link tables is to define the Configurable Link subtypes and the relationship constraints for each link type. This is done in the ConfigurableLinkExamples.xml file. This file contains two sections:

◦ Configurable Link Subtypes: The first part defines the Configurable Link subtypes. The name and description for each link type must be defined here. The name field defined on BeginTypeDefView is the Configurable Link type and is what will be used to tie-in the registration of the display location of the table, the table header and the action title associated with the link type.

The BeginTypeDefView name, the PropertyValue description and a displayName must be defined with meaningful customized names to define a new Configurable Link type.

◦ Configurable Link Valid Relationships: The second part of this file contains the relationship constraints for the Configurable Link subtypes that have been defined - these are the valid relationships for each defined link type. Each constraint specifies the Role A and Role B objects to be associated with a specific link type. "Role A" is the object that constitutes the left-hand-side of the link, and "Role B" is the object that constitutes the right-hand-side. The linkType is the BeginTypeDefView that is defined in the Configurable Link Subtype definition. The roleAType and roleBType are the objects that take on the respective roles for the specific linkType.

2. Define Action Names for the Relationship Tables.

The next step is to set up a mechanism to display the relationship table corresponding to a configurable link. This is done by defining actions for each Configurable Link table. The file ConfigurableLinkExamples-actions.xml does this in the example provided.

This file contains the action definitions for all Configurable Links in the OOTB example. In the UI, the table names (i.e., actions) are displayed in a sub-menu in the Customize menu on information pages. Clicking on an action will display a table that shows the relationship contained by that Configurable Link. The table can display the relationship either from the Role A side or from the Role B side, depending on how the action is set up.

In the Windchill+ modular structure, create incremental actions to define a new custom action if you don't want to use OOTB actions. For example, customization/module1/main/resources/custom-actions/CustomPartClient-actions.xml.

◦ To display the relationship from the Role A side, the URL associated with the action must point to: /netmarkets/jsp/object/configurableLinkRoleATable.jsp

◦ To display the relationship from the Role B side, the URL associated with the action must point to: /netmarkets/jsp/object/configurableLinkRoleBTable.jsp

Example:

To define a new action, follow the syntax within the <action> </action> fragment. The name field for the action can be set to any meaningful name. The value used for this field will be used as the key to provide the display name for this action in the resource file. After setting the name of this action, follow the rules above to define if this specific action will display the relationship table from the Role A or the Role B side.

3. Determining the location to display the actions.

The actions created in step 2 above need to be defined in the appropriate area in order to display them. An action-model is used to provide this definition. In the OOTB example, the file ConfigurableLinkExamples-actionmodels.xml handles this aspect.

The relationship tables for Configurable Links should be defined in the Customize menu on information pages. steps 3a and 3b describe how to create a model, and then display it. The end result is that the Customize menu on information pages will have a new menu option. The menu option will be the actions that display the relationship tables for configurable links.

a. Defining a model

i. First, define the actionmodel in the incremental action file by giving it name configLinks in the OOTB example or CustomLinks if it’s a new actionmodel. The resourceBundle definition after the name is the location of the Java file using annotations that contains the display names.

Example location: customization/module1/main/resources/custom-actions/CustomPartClient-actionmodels.xml

Sample snippet:

ii. Now that the name has been defined, a brief description can be provided.

iii. Next, define all the actions (i.e., relationship tables) that are intended to be displayed under this actionmodel. In the example, all actions defined in step 2 are under this model.

iv. Finally, the model as a whole needs to be placed in the Customize menu on information pages of objects that intend to display it. In this example, it is intended to be displayed from the part and document info pages. That is done by incrementally adding this submodel to Customize menu on information pages for these 2 objects, and this is described below.

com.ptc.windchill.enterprise.part.psb.showConfigurableLinksTab

b. Displaying the model

The model third_level_nav_part contains the list of Customize menu on information pages that is available for parts. OOTB, this model is defined in PartClient-actionmodels.xml, and the menu options are "general", "relatedItems", "changes", "history", and "collaboration". To add the newly created configLinks model to the info page of a part, the third_level_nav_part definition needs to be incrementally updated to include this new model as well. An important point to keep in mind is that performing this step will override any previous customizations to third_level_nav_part. To retain any previous customizations in Windchill+ create this model in an incremental actionmodel file at customization/module1/main/resources/custom-actions/CustomPartClient-actionmodels.xml directory.

For example, create a new model CustomLinks and define actions for this model. Incrementally add this actionmodel as a submodel to the model third_level_nav_part.

Example code snippet:

The same steps in step 3b would have to be followed to display the new menu option for configurable link tables in the Customize menu on information pages of any other object (The document is also provided in the OOTB example).

4. Creating labels for the table header and action title

Labels are created using annotations in a Java file. In the OOTB example, this is done in the configurableLinkExamplesResource.java file.

This file ties the registration of the Customize menu on information pages to the link type that is implemented for the table, the table header and the action title. The tie-up for the link type is done in the moreurlinfo field. The value for this field has the configurableLinkType set to the value of the BeginTypeDefView name defined in Step 1. The display text for the action title is set by defining the respective values for the action names created in step 2.

This file must be compiled, and the compiled (.class) version of this file must be placed in <Windchill>/codebase/com/ptc/windchill/enterprise/object

For steps 5 through 8, the OOTB example code is located in files with the prefix ConfigurableLinkExamples. However, you should make any customization changes by a creating file with the ConfigurableLinkCustomizations file prefix.

ConfigurableLinkCustomizations-service.properties.xconf: The source location for custom service xconf file will be <WT_HOME>/custom/module1/xconf.

5. Registering the Relationship Tables with a Validator

Once the actions have been defined, it is necessary to register each newly created action with the common validator in order to ensure that the logic behind the hide/display rules for the action title and relationship table work correctly. In the OOTB example, this is done in the ConfigurableLinkExamples-service.properties.xconf file.

Depending on the table being registered - Role A (parent) or Role B (child) (i.e., depending on the selector), the corresponding validator - ConfigurableLinkParentTableActionValidator or ConfigurableLinkChildTableActionValidator should be used respectively as the serviceClass.

6. Registering the Relationship Tables with Table Titles

In order to see Table Titles on your custom configurable link tables, you need to register each table with ConfigurableLinkDynamicUrlDelegate in ConfigurableLinkCustomizations-service.properties.xconf.

In the OOTB example, this is done in the ConfigurableLinkExamples-service.properties.xconf file.

7. Registering the Relationship Tables with Table Views

In order to use custom Table Views with your custom Configurable Link tables, you need to register each table with the appropriate table views class in ConfigurableLinkCustomizations-service.properties.xconf. If the base type of the Configurable Link is ConfigurableReferenceLink, then you would register your Configurable Link with ConfigurableReferenceLinkTableViews. Likewise links of base type ConfigurableDescribeLink should be registered to ConfigurableDescribeLinkTableViews and those with base types of ConfigurableMasterLink should be registered to ConfigurableMastersLinkTableViews. The selectors that are used should be the internal name defined for the Configurable Links, followed by either _childTable or _parentTable depending on if it is a Role A or Role B table.

For example, CustomReferenceLink's selectors would be com.ptc.CustomReferenceLink_childTable and com.ptc.CustomReferenceLink_parentTable.

In the OOTB example, this is done in the ConfigurableLinkExamples-service.properties.xconf file.

8. Registering the Relationship Tables with the Action Command Delegate

This is a required step for all Configurable Link tables that have toolbar actions. In order to make the Configurable Link toolbar actions work properly, register every configurable link table with ConfigurableLinkTableToolbarActionCommandDelegate. Use the same selector from Step 7 (ex. com.ptc.CustomReferenceLink_childTable). These entries should be made in ConfigurableLinkCustomizations-service.properties.conf.

In the OOTB example, this is done in the ConfigurableLinkExamples-service.properties.xconf file.

9. Registering the actions and actionmodels files

The next step is to add the newly created actions and actionmodels files (from steps 2 and 3 respectively) as incremental actions and actionmodel files in CCD modular structure. For more information, see Package Structure for Customization Artifacts.

An important point to keep in mind is that the newly created actions and actionmodels files (as part of the customization) now contain overrides to models that were originally defined OOTB. If this step of adding these new files is not performed, then the original definition of these models will be used by the application.

In the OOTB example as described above, the third_level_nav_part model has been overridden to include the configLinks submodel. It is important to perform Step 9 in such a way that these new files are added to the global definition after the OOTB definition. In this example, ConfigurableLinksExample-actionmodels.xml must be added after PartClient-actionmodels.xml and DocumentManagement-actionmodels.xml. This is because the OOTB example overrides the definition of the third_level_nav_part and third_level_nav_doc models. All the actions and actionmodels files are placed in wt.properties (step 10) and the last definition of a specific model is what will take effect.

If the newly created actions and actionmodels files are removed from wt.properties, or are not registered as required here in Step 8, or placed before the OOTB model definitions, then the OOTB behavior will be observed for the specific Customize menu options on information pages.

10. Collecting the registration in Steps 5 through 9 together.

For convenience in the installation process, the xconf settings (containing registrations such as those in steps 5 and 6) specific to a module are placed together in one file. In the OOTB example, these files are:

◦ ConfigurableLinkExamples-service.properties.xconf

◦ ConfigurableLinkExamples-wt.properties.xconf

This file references the files created in steps 5 through 9 above and puts them together in one location for the xconfmanager to pick up and propagate the changes. The xconfmanager places all actions and actionmodels files in wt.properties, and this is used eventually by the action service.

The above steps create a customized Configurable Link table. In order to install this, follow the instructions in Installing or Enabling OOTB Configurable Links using CCD Utility Example.

For installing Configurable Links with new custom subtyped Configurable Links, see Installing or Enabling Configurable Links with New Custom Subtyped Configurable Links Example.

Was this helpful?