Creating Component Interface Definitions
This section discusses how to create and work with component interface definitions.
This section discusses key concepts for creating component interface definitions.
Component Structure
You must know the structure of the component for which you are constructing a component interface because each component interface refers to a single component. You can use an existing component within an application or create a new one for the sole purpose of constructing a component interface. Many parts of the component interface, such as the keys, are created based on settings in the referenced component.
Criteria for Setting Automatic Default Properties
To be able to set automatic defaults for fields in the new component interface, the system needs the properties to be of a specific field or page control type.
The fields should be of the following types:
Character
Long character
Number
Signed number
Date
Time
Datetime
The field should be one of the following page control types:
Edit box
Drop-down list box
Check box
Radio button
The field cannot be invisible and should not be the same as the key field of the immediate parent.
Collections must have at least one child property that satisfies the field or page control criteria for providing the field by default. Collections with no properties are not added.
For a field on a secondary page to be selected for the default properties process, it must satisfy all the criteria for field type and page control and must be at the same level as the host page.
Additionally, the component tree that a component interface uses to order the properties lists the fields in the record based on their order in the record definition and not the order of the fields on the page. If the component tree lists the fields of a record based on the page, the properties of the component interface will reflect that order.
This section discusses how to create a new component interface.
Image: PeopleSoft Application Designer
This example shows a new component interface with no properties yet defined.
To create a new component interface:
Select from the PeopleSoft Application Designer menu.
Select Component Interface from the New dialog box.
Select the component on which to base this component interface.
After you select the appropriate component, you see a message asking whether you want the fields that are exposed in the selected component to become the default properties of the component interface.
Note: Not all fields on the component interface can have automatic defaults created for them.
Click Yes to confirm the default property definitions or No if you don’t want any properties initially created.
If you elect to have the property definitions automatically provided by the system by default, then all properties that appear on the pages of the underlying component are added to the component interface. Even though the system adds the default properties, you may need to move other properties into the component view for the component to work.
An untitled component interface appears, showing the Get keys and Find keys. Create keys are produced only if the underlying component can run in Add mode (the example preceding this procedure does not have Create keys, because the search record of the underlying component cannot run in Add mode). PeopleSoft Application Designer generates the keys for you as you drag definitions.
The standard methods Cancel, Find, Get, and Save are automatically created. The Create method is not automatically created unless the component supports the Add mode.
Note: You can begin adding properties to a new component interface at any point. However, you cannot add any user-defined methods to the component interface until you have saved the component interface.
Save the component interface.
After you have saved the component interface, you can further define user-defined methods.
Like every other definition in PeopleTools, component interfaces must have unique names. The naming of component interfaces should be consistent and systematic. Also, the name should not be changed after the component interface is part of a production system—other applications depend on a consistent name with which to reference the component interface.
If you are changing the structure of a component interface such that an existing program can no longer access it correctly, create a new component interface rather than updating the existing one. No version property is on a component interface, so if you must create a new version of a delivered component interface, adhere to a standard naming guideline to avoid confusion. A suggested naming guideline is:
LOCATION (original component interface).
LOCATION_V2 (version two of the component interface).
This applies to component interfaces built from components that are already attached to one or more menus.
Image: Properties – General tab
Use the Properties – General tab to associate a component interface with a menu.
To associate a component interface with a menu:
Select from the PeopleSoft Application Designer menu to open an existing component interface.
Select from the PeopleSoft Application Designer menu.
The Definition Properties dialog box appears.
Select the appropriate menu name on the General tab for this component interface.
Note: Associate a menu with a component interface only when PeopleCode is in the component that uses the %Menu system variable.
You expose fields from a component in the component interface by dragging a record field or a scroll from the component view into the component interface view. However, some forethought is required before exposing a component as a component interface. You need to have a thorough understanding of the underlying component so that you expose fields that are required in the external system. For example, if the component has a field called SSN, you need to be sure that the SSN field is required before exposing it to the external system. Expose only those properties that are necessary.
The component view displays fields that are available in the component buffer at runtime. For example, if a record containing 10 fields has only 3 fields included on a page, then the component view will list only those 3 fields.
The first time that you drag a scroll from the component view to the component interface view, the system uses the following rules to determine what properties to expose:
Keys are exposed only at the highest-level collection in which they first appear.
In some cases, this is not appropriate. When an effective-dated component that has the same level-zero and level-one record is exposed through a component interface, it should be exposed the same way in which it appears on a page in the component. In this case, only one key field typically appears at level zero and the effective-date keys appear at level one. The component interface wrapper should expose the page in the same fashion—removing keys that do not appear in the level-zero scroll from the component interface top-level collection and manually adding keys that appear in level-one scroll to the second-level collection.
Typically, you do not want to expose Get keys or Create keys as properties, because these are set before a Get or Create operation and might be inadvertently changed.
Make sure that you do not delete all the properties within the collection; that would result in an empty collection. If such empty collections exist, remove them; otherwise, they appear with X in the component interface view.
If your page does not support Add mode, then you should not expose the level-zero record of the component, because it contains data that is not specific to the component interface that you are creating.
Do not expose fields that are not visible in the component view.
The component optimization code might eliminate unused fields from its buffers, which results in an error when that field is accessed by the component interface.