Customizing Configurable Link Tables
This section describes each of the components that went in to creating a Configurable Link Table and displaying it in the OOTB example. Customizing the configurable link tables are 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.
◦ 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
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 rbinfo 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 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
a. First, define the action model by giving it a name - "configLinks" in the OOTB example. The resourceBundle definition after the name is the location of the java file using annotations that contains the display names.
b. Now that the name has been defined, a brief description can be provided.
c. Next, define all the actions (i.e., relationship tables) that are intedned to be displayed under this action model. In the example, all actions defined in step 2 are under this model.
d. Finally, the model as a whole needs to be placed in the 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 overriding the pre-existing definition for the Customize menu on information pages for these 2 objects, and this is described below.
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". In order to add the newly created configLinks model to the info page of a part, the "third_level_nav_part" definition has been overridden 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". In order to retain any previous customizations, copy the definition of the model being overridden ("third_level_nav_part" in this case) as it exists on the system into the newly created actionmodels file ("ConfigurableLinkExamples-actionmodels.xml" in this case). Then add the newly defined model ("configLinks" in this case) to the overridden model ("third_level_nav_part") using the "submodel" tag.
The same steps in step 3b would have to be followed to display the new menu option for configurable link tables in the in the Customize menu on information pages of any other object (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 in 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 creating files with the �ConfigurableLinkCustomizations� file prefix.
• ConfigurableLinkCustomizations.xconf
• ConfigurableLinkCustomizations-wt.properties.xconf
• ConfigurableLinkCustomizations-service.properties.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. The source and target locations for this file are:
◦ Source: com/ptc/windchill/enterprise
◦ Target: <Windchill>/codebase/com/ptc/windchill/enterprise
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) to the application wide list of actions/actionmodels files that are picked up by the actions service. This is done in the OOTB example by the ConfigurableLinkExamples-wt.properties.xconf file.
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, this file is ConfigurableLinkExamples.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 under the section Installing the Configurable Links Example in
Installing the Configurable Links Example topic.
