This example shows how you can add a database lookup to a field on an existing screen. It also shows how the lookup pattern can be used to generate all the code needed for the lookup component itself.

Contents

1. Getting Started
   1. Sample Application
   2. Code Generation Setup
2. Writing The Lookup
3. Adding the Lookup To A Field
4. Testing the Lookup
5. Appendix

Prerequisites

Thorough understanding and setup of the Pattern Generator for Finder and Viewer as defined in "How to use the Pattern Generator".

Terms Used

Lookup Client: Screen from where the lookup will be launched.
Lookup Criteria: First screen that comes up on launching the lookup.
Lookup Results: Screen that comes on hitting the [search] button on Lookup Criteria.
Lookup Viewer: Screen that comes on hitting the [Viewer] button on "Lookup Results".
Lookup Creator: Screen that comes on hitting the [Creator] button on "Lookup Results".
Lookup Updator: Screen that comes on hitting the [Updator] button on "Lookup Results".
Lookup Deletor: Button that would delete the record from the database.

For the object for which to create the lookup, the domain classes should have been created. If one would need a viewer on the "Lookup Results" screen, the viewer for that object should have been generated as well.

1. Sample Application

   Let us assume for purchasing (requesting) a part from an online warehouse, one would need a Part Lookup. This will filter the parts for the User based on the criteria entered. The user should be able to select a part from the "Lookup Results" screen and populate the Part field of request screen.

2. Code Generation Setup

   Create the folder source/java/resources/tools/patternengine/object_lookup_1_0.

• Create source/java/resources/tools/patternengine/object_lookup_1_0/PartLookup.xml using the sample file: PartLookup.xml. Please refer to the Appendix for understanding the XML structure of the sample file.

• Execute the ant script source/java/resources/tools/patternengine/executeObjectLookup_1_0.xml. (Note: running the pattern engine this way generates the code for all patterns in the lookup folder. If you don't want this to happen, either modify the ant script or call the pattern generator directly)

• With the above example, new files will be generated in source/java/com/example/applications/app1/modules/catalog/components/partlookup

• You can now compile and test this code. You may have to add entries to the ApplicationResources.properties to support any tokens you have used in the pattern. It also assumes that your ant build process will pick up the struts and components xml fragments and include them in the build.

• You can now deploy the WAR file and validate that the lookup component works using the URL 'http://localhost:8080/App1/startComponent.do?component=Catalog.PartLookup'

• Go to the "Lookup Client" screen (namely: source/html/app1/request/createrequest/jsp/createRequest.jsp) for adding the lookup widget/ hyperlink.

• Under the "Portlet:Form action" tag, look for the target field which will be a "Portlet:EditBox"
  (in this example it will be <Portlet:EditBox field="part"/>),

• Add the entry

  <Portlet:Lookup component = "Catalog.PartLookup" dynamicParameters = "part=part" staticParameters = "prime=ABC" targetFields = "part=part" >Part Lookup</Portlet:Lookup>

  where:

  • "component" is <Module>.<Component> of the sample file;

  • "dynamicParameters" are the value of fields that should be passed dynamically from the "Lookup Client" screen to the "Lookup Criteria" screen;

  • "staticParameters" are the hard coded values that should be passed to the "Lookup Criteria" screen;

  • "targetFields" are the value of key fields that should be passed dynamically from the "Lookup Results" screen to the "Lookup Viewer", "Lookup Creator", "Lookup Updator" and "Lookup Deletor" screens;

  • "bypassCriteriaScreen" is a boolean which determines whether the "Lookup Results" screen should be brought directly from the "Lookup Client" (when "true"). Not specifying this value assumes the default action of bringing the "Lookup Criteria" screen first.

• Execute the 'deploy-Tomcat4' task of the ant script build/build.xml

On the "Lookup Client" screen (namely: createRequest), the "Part Lookup" hyperlink gets displayed to the right of the EditBox for the Part field. Hitting the "Part Lookup" hyperlink will take the user to "Lookup Criteria" screen.

The user can populate data in the corresponding fields on "Lookup Criteria" screen and hit the [Search] button.

The [Clear] button would clear the screen and any staticParameters or dynamicParameters.

Hitting the [Search] button on "Lookup Criteria" screen would take the user to "Lookup Results" screen.

The user can hit the [ModifySearch] to specify a different criteria. That will take the user back to the "Lookup Criteria" screen with prior data entered.

The user can hit the [Select] button to select the value of Part field. This value will be populated on the "Lookup Client" and the "Lookup Results" will close automatically.

The user can hit the [View] button to get part details for that record.

The user can hit the [Create] button to create a new part.

The user can hit the [Update] button to update an existing part.

The user can hit the [Delete] button to delete an existing part.

<?xml version="1.0" encoding="US-ASCII"?>
<!-- This dtd is used for validating the Meta files for generating the various object lookup files -->
<!ELEMENT Root (PatternTemplate,Application,Module,Component,BasePackage,DomainObject,
                DomainPackage,CriteriaTitle?,ResultsTitle?,CriteriaFields,ResultsFields,
                OrderByFieldCombos?,MaxRecords?,Creator?,Viewer?,Updator?,Deletor?,KeyFields)>
<!ELEMENT PatternTemplate (#PCDATA)>
<!ELEMENT Application (#PCDATA)>
<!ELEMENT Module (#PCDATA)>
<!ELEMENT Component (#PCDATA)>
<!ELEMENT BasePackage (#PCDATA)>
<!ELEMENT DomainObject (#PCDATA)>
<!ELEMENT DomainPackage (#PCDATA)>
<!ELEMENT MaxRecords (#PCDATA)>
<!ELEMENT CriteriaTitle (#PCDATA)>
<!ELEMENT ResultsTitle (#PCDATA)>
<!ELEMENT CriteriaFields (CriteriaField+)>
<!ELEMENT CriteriaField (Name,DataType,Display,Label?,DomainField,AltDomainObject?)>
<!ELEMENT Name (#PCDATA)>
<!ELEMENT DataType (#PCDATA)>
<!ELEMENT Label (#PCDATA)>
<!ELEMENT DomainField (#PCDATA)>
<!ELEMENT AltDomainObject (Object,Package,CriteriaJoinFields)>
<!ELEMENT Object (#PCDATA)>
<!ELEMENT Package (#PCDATA)>
<!ELEMENT CriteriaJoinFields (CriteriaJoinBetween+)>
<!ELEMENT CriteriaJoinBetween (DomainObjectField,AltDomainObjectField)>
<!ELEMENT DomainObjectField (#PCDATA)>
<!ELEMENT AltDomainObjectField (#PCDATA)>
<!ELEMENT ResultsFields (ResultsField+)>
<!ELEMENT ResultsField (Name,DataType,Display,Label,Width,DomainField,Source?)>
<!ELEMENT Display (#PCDATA)>
<!ELEMENT Width (#PCDATA)>
<!ELEMENT Source (Object,Package,ResultsJoinFields)>
<!ELEMENT ResultsJoinFields (ResultsJoinBetween+)>
<!ELEMENT ResultsJoinBetween (DomainObjectField,SourceField)>
<!ELEMENT SourceField (#PCDATA)>
<!ELEMENT OrderByFieldCombos (OrderByFieldCombo+)>
<!ELEMENT OrderByFieldCombo (OrderByField+)>
<!ELEMENT OrderByField (DomainFieldName,Label?)>
<!ELEMENT DomainFieldName (#PCDATA)>
<!ELEMENT Creator (ComponentName,ClassName,Package)>
<!ELEMENT Viewer (ComponentName,ClassName,Package)>
<!ELEMENT Updator (ComponentName,ClassName,Package)>
<!ELEMENT Deletor (ComponentName,ClassName,Package)>
<!ELEMENT ComponentName (#PCDATA)>
<!ELEMENT ClassName (#PCDATA)>
<!ELEMENT KeyFields (KeyField+)>
<!ELEMENT KeyField (ResultsFieldName,DataType,FieldNameInTargetComponent)>
<!ELEMENT ResultsFieldName (#PCDATA)>
<!ELEMENT FieldNameInTargetComponent (#PCDATA)>

Under the <Root> tag:

• The <PatternTemplate> tag specifies the placeholder for object lookup template in Jaffa.
• The <Application> tag specifies the sample application for which the lookup is being generated.
• The <Module> tag specifies the module to which the lookup belongs.
• The <Component> tag specifies the name of the lookup component.
• The <BasePackage> tag specifies the place where the code should be generated for the lookup component.
• The <DomainObject> tag specifies the name by which the persistence layer recognizes the object.
• The <DomainPackage> tag specifies the place where the code exists for recognizing the domain object.
• The <CriteriaTitle> tag specifies the title for the "Lookup Criteria" screen.
• The <ResultsTitle> tag specifies the title for the "Lookup Results" screen.
• The value specified in <CriteriaTitle> and <ResultsTitle> tags get referred in ApplicationResources.properties file. This file translates the value to the actual label displayed on the screen.
• The <CriteriaFields> tag specifies the fields on the "Lookup Criteria" screen.
• The <ResultsFields> tag specifies the fields on the "Lookup Results" screen.
• The <MaxRecords> tag specifies the maximum number of records that would be displayed on the "Lookup Results" screen. If additional records qualify the criteria, the User would not have their visibility. A future enhancement would be to indicate if additional records qualify the criteria.
• The <Viewer> tag specifies the details for the [Viewer] button on the "Lookup Results" screen.
• The <Creator> tag specifies the details for the [Creator] button on the "Lookup Results" screen.
• The <Updator> tag specifies the details for the [Updator] button on the "Lookup Results" screen.
• The <Deletor> tag specifies the details for the [Deletor] button on the "Lookup Results" screen.
• The <KeyFields> tag specifies the key fields for [Viewer], [Creator], [Updator], and [Deletor]. The key fields represent the primary key fields for the lookup table.

Under the <CriteriaFields> tag:

• The <CriteriaField> tag specifies the various fields on the "Lookup Criteria" screen.
• There could be one or more <CriteriaField> tags.

Under the <CriteriaField> tag:

• The <Name> tag specifies the unique name by which the field would be recognized.
• The <DataType> tag specifies the data type of the field created by the Domain Creator.
• The <Display> tag specifies whether the field will be created on the JSP or not. It holds a boolean value. The field could still act as a hidden parameter for the "Lookup Results" screen.
• The <DomainField> tag specifies the name by which the field gets referred in the <DomainObject> under <DomainPackage>. This gets referred in ApplicationResources.properties file. This file translates the value to the actual label displayed on the screen.

Under the <ResultsFields> tag:

• The <ResultField> tag specifies the various fields on the "Lookup Results" screen.
• There could be one or more <ResultField> tags.

Under the <ResultField> tag:

• The <Name> tag specifies the unique name by which the field would be recognized.
• The <DataType> tag specifies the data type of the field created by the Domain Creator.
• The <Display> tag specifies whether the field will be created on the JSP or not. It holds a boolean value. The field could still act as a hidden parameter for the [Viewer], [Creator], [Updator], and [Deletor] screens.
• The <Label> tag specifies the column heading of the table on the "Lookup Results" screen.
• The <Width> tag currently does not have any functionality behind it. In the future, it can be enhanced to display the specified number of characters on the "Lookup Results" in the table cell. This will be useful for large fields where the User would be interested in the first few characters.
• The <DomainField> tag specifies the name by which the field gets referred in the <DomainObject> under <DomainPackage>.

Under the <Viewer>, <Creator>, <Updator> and <Deletor> tags:

• The <ComponentName> tag specifies the sub module to which the [Viewer] belongs.
• The <ClassName> tag specifies the name of the class that gets generated for the [Viewer].
• The <Package> tag specifies the location where the class gets generated.

Under the <KeyFields> tag:

• The <KeyField> tag specifies the field of the primary key.
• There could be one or more <KeyField> tags (for a composite primary key).

Under the <KeyField> tag:

• The <ResultsFieldName> tag specifies the name of the field on the "Lookup Results" screen.
• The <DataType> tag specifies the data type of the field created by the Domain Creator.
• The <FieldNameInTargetComponent> tag specifies the name of the field as it appears under the <ClassName> tag for the <Viewer>. The value should be the same as the value in <Name> tag of <CriteriaField> under <CriteriaFields> under <Root> of source/java/resources/tools/patternengine/object_viewer_1_0/<ClassName>.xml.