This item was originally publised in May, 2002.

NOTE: This hook is presented only as an example of how to customize your use of IBM® Rational® ClearQuest®. It has not been formally tested, and is not supported by IBM.

Description

A dependent choicelist typically requires 2 fields: a root field and a dependent field. The root field determines the valid choices for the dependent field. For example, in the HOOKS database, there is a "CQ_Ver" field that captures what version of ClearQuest a particular hook was written for. In version 1.0, ClearQuest only supported Action and Field hooks, and so the possible selections for the "Hook_Type" is limited to "Action" and "Field" while CQ_Ver is set to "1.0". In ClearQuest 1.1, support for Record and Global hooks was added, so when CQ_Ver is set to "1.1", we want to offer these selections also.

Back to top

Script Language

VB Script

Back to top

Code

To make the choicelist for the Hook_Type field change based on the currently selected value in the CQ_Ver field, the following choicelist hook was written:

Choicelist hook for field "Hook_type":

Sub Hook_type_ChoiceList(fieldname, choices)
 ' fieldname As String
 ' choices As Object
 'entityDef = Hook

   select case GetFieldValue("CQ_Ver").GetValue
			case "1.0"
			   choices.AddItem "Action"
			   choices.AddItem "Field"
			case "1.1"
			   choices.AddItem "Action"
			   choices.AddItem "Field"
			   choices.AddItem "Record"
			   choices.AddItem "Global"
 			case else
				
		end select

End Sub

In the scenario where a user first selects CQ_Ver "1.1" and Hook_Type "Global", and then changes CQ_Ver to "1.0", the Hook_Type value can be invalid. To prevent this, sometimes it is desirable to clear the content of a dependent field whenever its root field is changed. The following ValueChanged hook for the CQ_Ver field shows this:

ValueChanged hook for field "CQ_Ver":

Sub CQ_Ver_ValueChanged(fieldname)
' fieldname As String
 REM This hook will be run each time the field's value
 REM changes.  This hook is run before
 REM the new value is validated
 REM so be aware the new value may not be valid.
  
  SetFieldValue "Hook_type", ""
  
End Sub

It is also possible that a dependent field could itself be a root field for yet another dependent field. This scenario creates a 3-level hierarchy of dependent fields. In the HOOKS database again, the "Hook_name" field is dependent on the "Hook_type" field, and the example below shows these dependent choices:

Choicelist hook for field "Hook_name":

Sub Hook_name_ChoiceList(fieldname, choices)
  ' fieldname As String
  ' choices As Object
  'entityDef = Hook
    select case GetFieldValue("Hook_type").GetValue
	 case "Field"
		choices.AddItem("Choice_List")
		choices.AddItem("Default_Value")
		choices.AddItem("Permission")
		choices.AddItem("Validation")
		choices.AddItem("Value_Changed")
	case "Action"
		choices.AddItem("Access_Control")
		choices.AddItem("Commit")
		choices.AddItem("Initialization")
		choices.AddItem("Notification")
		choices.AddItem("Validation")
	case "Global"
		 choices.AddItem("Global Hook")
	case "Record"
	 	choices.AddItem("Record Hook")
	case else
		 	
end select
End Sub

Again, because it is desirable to reset dependent fields when their root fields change, we use the following ValueChanged hook on the Hook_type field to reset the content of the Hook_name field:

ValueChanged hook for field "Hook_type":

Sub Hook_type_ValueChanged(fieldname)
 ' fieldname As String
  REM This hook will be run each time the
     field's value
  REM changes.  This hook is run before
  REM the new value is validated
  REM so be aware the new value may not be valid.
  
  SetFieldValue "Hook_name", ""
  
End Sub

If the CQ_Ver field is changed, the CQ_Ver ValueChanged hook will fire. Since it resets (i.e. changes) the Hook_type field, the ValueChanged hook of the Hook_type field will subsequently fire, with the end result being that all dependent fields in the hierarchy are reset.

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Description
• Script Language
• Code
• About the author
• Comments

Next steps from IBM

• Try: Rational ClearQuest
• Demo: Create customized queries with IBM Rational ClearQuest
• Webcast: Tips on achieving global IT efficiency through collaboration, automation, and project insight
• Briefing: Jazz and Rational Team Concert
• Buy: Rational ClearQuest

My developerWorks community

Dig deeper into Rational on developerWorks

Try Rational System Architect

See how this fully integrated collection of models and documents can help you better align your IT systems and infrastructure to simplify business processes

Special offers