Basic Customization > User Interface Customization > Incorporating Pickers in JSP Clients > Configuring Pickers
  
Configuring Pickers
Solution
Write a custom JSP page and use the Item Picker tag to display the picker. Configure the search criteria fields to be included in the picker using the PickerAttributes.xml file. Configure the object types and containers to be searched using parameters on the itemPicker tag.
Prerequisite knowledge
To achieve this objective, you need to have an understanding of the following:
• Basic development involving HTML forms, JSP, XML.
• Picker common components
• Table common component
• View creation
Solution Elements
Element
Type
Description
pickerAttributes.xml
XML
Runtime location:<Windchill>\codebase\pickerAttributes.xml
SearchResultsTable.properties.xconf
Xconf
Runtime location:<Windchill> \codebase\com\ptc\netmarkets\search\SearchResultsTable.properties.xconf
This file can be used to configure table view definition.
Procedure - Launching the picker and defining the object types to be searched
The picker can be launched from your JSP by calling the itemPicker tag:
<wctags:itemPicker id="customized_item_picker" objectType="WCTYPE|
wt.part.WTPart|org.r_and_d.mypart" componentId="customizedItemPickerForSoftPart "/>
The objectType parameter indicates that the search should be limited to objects of type org.r_and_d_mypart.
The value of the id parameter should be an identifier that is unique for the given page.
The value of the componentId parameter is a key that will be used to look up the search criteria to be presented in the picker. This is described in the next section.
Procedure - Customizing the Picker Search Criteria
The search criteria for a picker can be customized using the file pickerAttributes.xml. First define a new component id for the picker using the componentID parameter on the picker tag, as shown above, and then define the object attributes to be used as search criteria in the xml file as shown below.
<ComponentID id="customizedItemPickerForSoftPart">
<ObjectType id="WCTYPE|wt.part.WTPart|org.r_and_d.mypart">
<SearchCriteriaAttributes>
<Attributes>
<Name>name</Name>
<DisplayName>NAME_LABEL</DisplayName>
<IsSearchable>true</IsSearchable>
</Attributes>
</SearchCriteriaAttributes>
</ObjectType>
</ComponentID>
If the componentID attribute is not specified or if you do not define search criteria in pickerAttributes.xml, by default pickerSearch componentId is used to display the search criteria. The pickerAttributes.xml files can be modified by customers and is the only file to be modified in this regard. This file contains only search criteria and not the object types. Prefix WCTYPE is allowed in this xml file. It is required in case of subtypes. For hard types only object type is required.
In this example, the component id is the component id defined for our picker on the picker tag (see the “Procedure - Launching the picker and defining the object types to be searched” section above). We have defined a single attribute to be searchable, which is the attribute nameon the object type org.r_and_d.mypart.
${domain} is specific to EPM document. It is generic and not internal to developers.
This xml file contains search criteria input fields and not types.
If you were searching for more than one object type, you will have to add entries for other object types after first object type under same component id.
In case of multiple type searches, generic (persistable object type) criteria will be displayed.
Common Customization Points are listed in following tables:
Parameter
Default Value
Possible Values
Req?
Description
Id
Anything that is unique in a page
Yes
An ID is associated with every picker in Scope of the calling application. This ID has to be unique for all pickers, irrespective of type on one page.
The id should not contain "." (Dot) in the name.
componentId
pickerSearch
Any valid component id specified in pickerAttributes.xml
No
componentId determines the attributes that should appear in search criteria panel for the given picker.
pickerCallback
Generated at runtime if user has not specified this parameter
Name of the callback function
No
Name of the customized callback javascript function that a user would have to implement. It’s recommended that you should specify pickerCallback function in custom.js file
defaultValue
“” (blank)
Any values
No
Default value for textbox rendered by the picker.
Label
Context Picker
Any value
No
Label of the picker.
displayAttribute
Name
Any attribute
No
Name of the attribute that should be the displayed in the picker textbox after selecting result from the item picker.
containerRef
“” (blank)
Any container
No
Value of the containerRef in which a user wants to restrict the search.
baseWhereClause
“” (blank)
Any valid I*E where clause query
No
Additional where clause if you want to filter search results on some specific criteria regardless of user input. This where clause will get “ANDed” with the internal where clause.
pickerTitle
Contexts
Any value
No
Default value of the hidden textbox associated with the picker.
pickedDataFetcher
<WebApp>/netmarkets/jsp/search/pickedData.jsp
URL location of the fetcher file
No
URL of the data fetcher file that will be used by the AJAX call to process the selected results.
Editable
True
true/false
No
This attribute defines whether you want to have find icon along with the textbox.
readOnlyPickerTextBox
False
true/false
No
This attribute defines whether the picker text box should be editable or not.
Inline
False
true/false
No
You should specify this parameter with value as true when you want to launch picker as a table level action or inline.
pickedAttributes
Name
Any comma separated list of valid attributes
No
This parameter contains a comma separated list of the attributes that a user wants a picker to fetch. This is applicable only if inline is “true”.
pickerType
search
search/picker
No
This parameter defines the picker type i.e. “search” picker or “picker” picker. In search picker, you will see search criteria in the picker and then you have to click the search button to see the results however in case of “picker” picker you will directly see the results table without any search criteria.
pickerTextBoxLength
25
Any numeric value
No
This parameter defines the length of the picker text box.
searchResultsViewId
“”(blank)
Any valid view id
No
This parameter allows user to define custom view id for the picker search results table.
Procedure - Defining the containers to be searched
To confine the search to objects in certain containers, use the containerRefparameter on the picker tag. The value of this parameter should be a comma-separated list of one or more WTContainerRef objects, in string format, for the containers you want to search.
The WTContainerRefs for the containers can be fetched by querying for the containers and getting the WTContainerRef for each from the WTContainer object.
If no containerRef parameter is provided, all containers will be searched.
<wctags: itemPicker id=" customized_item_picker”
objectType="WCTYPE|wt.part.WTPart|org.r_and_d.mypart"
containerRef=" OR: wt.pdmlink.PDMLinkProduct:33707”
componentId="customizedItemPickerForSoftPart" />
Procedure - Customizing the search result table view
Search result tables use the table common component and hence the column display can be configured by creating a new table view.
You will first need to create a new JCAConfigurableTable Java class defining your table view.
Then create a service property entry in a *.properties.xconf file that can be used to look up your table view class based on an identifier you choose called the “selector.” For example, if your table view class was CustomizedPartView, your service property entry might look like this:
<Service context="default"
name="com.ptc.core.htmlcomp.tableview.ConfigurableTable">
<Option
serviceClass="com.ptc.netmarkets.search.views.CustomizedPartView" requestor="java.lang.Object"
selector="wt.part.WTPart.customizedSearchView "/>
</Service>
Finally, pass the selector as below to the picker tag, as shown below, and the search results table will be rendered with this view.
<wctags: itemPicker id=" customized_item_picker"
objectType="WCTYPE|wt.part.WTPart|org.r_and_d.mypart"
containerRef="<OR: wt.pdmlink.PDMLinkProduct:33707”
componentId="customizedItemPickerForSoftPart"
searchResultsViewId="wt.part.WTPart.customizedSearchView"/>
Sample Code
<html>
<body>
<table>
<tr>
<%-- launching user picker--%>
<wctags:userPicker id="testUserPicker" label="MyUserPicker"
readOnlyPickerTextBox="false" editable="true" showSuggestion="true"
suggestMinChars="5" />
</tr>

<tr>
<%-- launching organization picker--%>
<wctags: organizationPicker id="orgPicker" label="MyOrgPicker"
readOnlyPickerTextBox="false" editable="true" showSuggestion="true"
suggestMinChars="3"/>
</tr>

<tr>
<%-- launching context picker--%>
<wctags: contextPicker id="contextPicker" label="MyContextPicker"
pickerTitle="ContextPicker" />
</tr>

<tr>
<%-- launching Item picker--%>
<wctags:itemPicker id="itemPicker" label="MyItemPicker"
pickerTitle="ItemPicker"/>
</tr>

<tr>
<%-- launching Item picker with exclude sub types and access
controller --%>
<wctags:itemPicker id="CustomizedItemPicker" label="CustomizedItemPicker"
pickerTitle="CustomizedItemPicker"excludeSubTypes="WCTYPE|wt.doc.WTDocument|
org.rnd.Minutes,WCTYPE|wt.doc.WTDocument|org.rnd.General"
customAccessController="com.ptc.windchill.
enterprise.search.server.LatestVersionAccessController"/>
</tr>

<tr>
<%-- launching Item Masterpicker--%>
<wctags:itemMasterPicker id="itemMasterPicker"
label="MyItemMasterPicker"/>
</tr>

<tr>
<%-- launching Item Masterpicker--%>
<wctags:genericPicker id="genericPicker"objectType="wt.part.WTPart"label
="Part Picker using generic" />
</tr>

<tr>
<%-- launching Item Masterpicker--%>
<wctags:genericPicker id="viewPicker" objectType="wt.vc.views.View" label="
View Picker
using generic" pickerType="tree" />
</tr>

<tr>
<%-- launching Recently Visited Context Picker- Single Select--%>
<wctags:contextPicker id="containerTypeListSingleSelect" label="
Recently Visited Context Picker-
Single Select" pickerTitle="ContextPicker" showRecentlyUsed="true"
displayAttribute="containerInfo.name"/>
</tr>

<tr>
<%-- launching Recently Visited Context Picker- Multi Select--%>
<wctags:contextPicker id="containerTypeListMultiSelect" label="Recently
Visited Context Picker- Multi Select" pickerTitle="ContextPicker"
showRecentlyUsed="true" displayAttribute="containerInfo.name"
showMultiSelectRecentlyUsed="true"/>
</tr>
</table>
</body>
</html>