PeopleCode Events

This section discusses:

Activate event.
FieldChange event.
FieldDefault event.
FieldEdit event.
FieldFormula event.
ItemSelected event.
PostBuild event.
PreBuild event.
PrePopup event.
o!Delete event.
o!Init event.
o!Insert event.
o!Select event.
SaveEdit event.
SavePostChange event.
SavePreChange event.
SearchInit event.
SearchSave event.
"or#$o! event.
Note. The term PeopleCode type is still fre%uentl& used' (ut it does not )t into the
PeopleTools o(*ect+(ased' event+driven metaphor. The term PeopleCode event should
no! (e used instead. ,o!ever' it-s often convenient to %ualif& a class of PeopleCode
programs triggered (& a speci)c event !ith the event name. for e/ample' PeopleCode
programs associated !ith the o!Init events are collectivel& referred to as RowInit
PeopleCode.
Dinesh Kumar
Activate Event
The Activate event is initiated each time that a page is activated' including !hen a page
is )rst displa&ed (& a user' or if a user presses Ta( (et!een di0erent pages in a
component. Each page has its o!n Activate event.
The Activate event segregates PeopleCode that is related to a speci)c page from the rest
of the application-s PeopleCode. Place PeopleCode related to page displa& or page
processing' such as ena(ling a )eld or hiding a scroll area' in this event. Also' &ou can
use this event for securit& validation: if an user does not have clearance to vie! a page
in a component' &ou !ould put the code for hiding the page in this event.
Note. PeopleSoft (uilds a page grid one ro! at a time. Because the 1rid class applies to
a complete grid' &ou cannot attach PeopleCode that uses the 1rid class to events that
occur (efore the grid is (uilt. the earliest event &ou can use is the Activate event. The
Activate event is not associated !ith a speci)c ro! and record at the point of e/ecution.
This means &ou cannot use functions such as 1etecord' 1eto!' and so on' !hich rel&
on conte/t' !ithout specif&ing more conte/t.
Activate PeopleCode can onl& (e associated !ith pages.
This event is valid onl& for pages that are de)ned as standard or secondar&. This event is
not supported for su(pages.
FieldChange Event
2se FieldChange PeopleCode to recalculate page )eld values' change the appearance of
page controls' or perform other processing that results from a )eld change other than
data validation. To validate the contents of the )eld' use the FieldEdit event.
The FieldChange event applies to the )eld and ro! that *ust changed.
FieldChange PeopleCode is often paired !ith o!Init PeopleCode. In these
o!Init3FieldChange pairs' the o!Init PeopleCode chec#s values in the component and
initiali4es the state or value of page controls accordingl&. FieldChange PeopleCode then
rechec#s the values in the component during page e/ecution and resets the state or
value of page controls.
To ta#e a simple e/ample' suppose &ou have a derived3!or# )eld called P5D2CT' the
value of !hich is al!a&s the product of page )eld A and page )eld B. "hen the
component is initiali4ed' &ou !ould use o!Init PeopleCode to initiali4e P5D2CT e%ual
to A 6 B !hen the component starts up or !hen a ne! ro! is inserted. 7ou could then
attach FieldChange PeopleCode programs to (oth A and B !hich also set P5D2CT e%ual
to A 6 B. "henever a user changes the value of either A or B' P5D2CT is recalculated.
FieldChange PeopleCode can (e associated !ith record )elds and component record
)elds.
Dinesh Kumar
FieldDefault Event
The FieldDefault PeopleCode event ena(les &ou to programmaticall& set )elds to default
values !hen the& are initiall& displa&ed. This event is initiated on all page )elds as part
of man& di0erent processes. ho!ever' it triggers PeopleCode programs onl& !hen the
follo!ing conditions are all true:
The page )eld is still (lan# after appl&ing an& default value speci)ed in the record
)eld properties.
This is true if there is no default speci)ed' if a null value is speci)ed' or if a 8 is
speci)ed for a numeric )eld.
The )eld has a FieldDefault PeopleCode program.
In practice' FieldDefault PeopleCode normall& sets )elds (& default !hen ne! data is
(eing added to the component. that is' in Add mode and !hen a ne! ro! is inserted into
a scroll area.
If a )eld value is changed' !hether through PeopleCode or (& a user' the IsChanged
propert& for the ro! is set to True. The e/ception to this is !hen a change is done in the
FieldDefault or FieldFormula events. If a value is set in FieldDefault or FieldFormula' the
ro! is not mar#ed as changed.
At save time' all ne!l& inserted and changed ro!s are !ritten to the data(ase. All ne!l&
inserted (ut not changed ro!s are not !ritten to the data(ase.
7ou must attach FieldDefault PeopleCode to the )eld !here the default value is (eing
populated.
Note. An error or !arning issued from FieldDefault PeopleCode causes a runtime error.
FieldDefault PeopleCode can (e associated !ith record )elds and component record
)elds.
FieldEdit Event
2se FieldEdit PeopleCode to validate the contents of a )eld' supplementing standard
s&stem edits. If the data does not pass the validation' the PeopleCode program should
displa& a message using the Error statement' !hich redispla&s the page' displa&ing an
error message and turning the )eld red.
To permit the )eld edit (ut alert the user to a possi(le pro(lem' use a "arning statement
instead of an Error statement. A "arning statement displa&s a !arning dialog (o/ !ith
59 and E/plain (uttons. It permits )eld contents to (e changed and continues processing
as usual after the user clic#s 59.
Dinesh Kumar
If the validation must chec# for consistenc& across page )elds' then use SaveEdit
PeopleCode instead of FieldEdit.
The FieldEdit event applies to the )eld and ro! that *ust changed.
FieldEdit PeopleCode can (e associated !ith record )elds and component record )elds.
FieldFormula Event
The FieldFormula event is not currentl& used. Because FieldFormula PeopleCode initiates
in man& di0erent conte/ts and triggers PeopleCode on ever& )eld on ever& ro! in the
component (u0er' it can seriousl& degrade application performance. 2se o!Init and
FieldChange events rather than FieldFormula.
If a )eld value is changed' !hether through PeopleCode or (& a user' the IsChanged
propert& for the ro! is usuall& set to True. ,o!ever' if a value is set in FieldDefault or
FieldFormula' the ro! is not mar#ed as changed.
At save time' all ne!l& inserted and changed ro!s are !ritten to the data(ase. All ne!l&
inserted (ut not changed ro!s are not !ritten to the data(ase.
Note. InPeopleSoft Pure Internet Architecture' if a user changes a )eld' (ut there is
nothing to cause a trip to the server on that )eld' default processing and FieldFormula
PeopleCode do not run. The& onl& run !hen another event causes a trip to the server.
As a matter of convention' FieldFormula is no! often used in F2:C;IB< =function li(rar&>
record de)nitions to store shared functions. ,o!ever' &ou can store shared functions in
an& PeopleCode event.
FieldFormula PeopleCode is onl& associated !ith record )elds.
ItemSelected Event
The ItemSelected event is initiated !henever a user selects a menu item from a pop+up
menu. In pop+up menus' ItemSelected PeopleCode e/ecutes in the conte/t of the page
)eld from !here the pop+up menu is attached' !hich means that &ou can freel&
reference and change page )elds' *ust as &ou could from a (utton.
Note. This event' and all its associated PeopleCode' does not initiate if run from a
component interface.
ItemSelected PeopleCode is onl& associated !ith pop+up menu items.
PostBuild Event
The PostBuild event is initiated after all the other component (uild events have (een
initiated. This event is often used to hide or unhide pages. It-s also used to set
component varia(les.
Dinesh Kumar
PostBuild PeopleCode is onl& associated !ith components.
PreBuild Event
The PreBuild event is initiated (efore the rest of the component (uild events. This event
is often used to hide or unhide pages. It-s also used to set component varia(les.
Note. If a PreBuild PeopleCode program issues an error or !arning' the user is returned
to the search page. If the search record has no #e&s' a (lan# component page appears.
Also use the PreBuild event to validate data entered in a search page after a prompt list
is displa&ed. For e/ample' after a user selects #e& values on a search' the PreBuild
PeopleCode program runs' catches the error condition' and issues an error message. The
user receives and ac#no!ledges the error message. The component is canceled
=(ecause of the error>' and the user is returned to the search page. PreBuild PeopleCode
is onl& associated !ith components.
PrePopup Event
The PrePopup event is initiated *ust (efore the displa& of a pop+up menu.
7ou can use PrePopup PeopleCode to control the appearance of the pop+up menu.
Note. This event' and all its associated PeopleCode' does not initiate if run from a
component interface.
PrePopup PeopleCode can (e associated !ith record )elds and component record )elds.
RoDelete Event
The o!Delete event is initiated !henever a user attempts to delete a ro! of data from
a page scroll area. 2se o!Delete PeopleCode to prevent the deletion of a ro! =using an
Error or "arning statement> or to perform an& other processing contingent on ro!
deletion. For e/ample' &ou could have a page )eld called Total on scroll area level 4ero
!hose value is the sum of all the E/tension page )elds on scroll area level one. If the
user deleted a ro! on scroll area level one' &ou could use o!Delete PeopleCode to
recalculate the value of the Total )eld.
The o!Delete event triggers PeopleCode on an& )eld on the ro! of data that is (eing
$agged as deleted.
Note. o!Delete does not trigger programs on derived3!or# records.
o!Delete PeopleCode can (e associated !ith record )elds and component records.
Deleting All o!s from a Scroll Area
Dinesh Kumar
"hen the last ro! of a scroll area is deleted' a ne!' dumm& ro! is automaticall& added.
As part of the o!Insert event' o!Init PeopleCode is run on this dumm& ro!. If a )eld is
changed (& o!Init =even if it-s left (lan#>' the ro! is no longer ne!' and therefore is not
reused (& an& of the ScrollSelect functions or the Select method. In this case' &ou ma&
!ant to move &our initiali4ation code from the o!Init event to FieldDefault.
RoInit Event
The o!Init event is initiated the )rst time that the Component Processor encounters a
ro! of data. I2se it to set the initial state of component controls. This occurs during
component (uild processing and ro! insert processing. It also occurs after a Select or
SelectAll o!set method' or a ScrollSelect or related function' is e/ecuted.
Note. 1enerall&' if none of the )elds in the ne! ro! are changed after the ro! has (een
inserted =either (& a user pressing Alt?@ or programmaticall&>' !hen the page is saved'
the ne! ro! is not inserted into the data(ase. ,o!ever' if the Change5nInit ro!set class
propert& is set to False' &ou can set values for )elds a ne! ro! in o!Insert or o!Init
PeopleCode' and the ro! !onAt (e saved.
o!Init is not )eld+speci)c: it triggers PeopleCode on all )elds and on all ro!s in the
component (u0er.
Do not use Error or "arning statements in o!Init PeopleCode: these cause a runtime
error.
o!Init PeopleCode is often paired !ith FieldChange PeopleCode. In these
o!Init3FieldChange pairs' the o!Init PeopleCode chec#s values in the component and
initiali4es the state or value of page controls accordingl&. FieldChange PeopleCode then
rechec#s the values in the component during page e/ecution and resets the state or
value of page controls.
To ta#e a simple e/ample' suppose &ou have a derived3!or# )eld called P5D2CT' the
value of !hich is al!a&s the product of page )eld A and page )eld B. "hen the
component is initiali4ed' use o!Init PeopleCode to initiali4e P5D2CT e%ual to A 6 B
!hen the component starts up or !hen a ne! ro! is inserted. 7ou could then attach
FieldChange PeopleCode programs to (oth A and B' !hich also sets P5D2CT e%ual to A
6 B. "henever a user changes the value of either A or B' P5D2CT is recalculated.
o!Init PeopleCode can (e associated !ith record )elds and component records.
o!Init E/ceptions
In certain rare circumstances' the Component Processor does not run o!Init
PeopleCode for some record )elds. The Component Processor runs o!Init PeopleCode
!hen it loads the record from the data(ase. ,o!ever' in some cases' the record can (e
initiali4ed entirel& from the #e&s for the component. "hen this happens' o!Init
PeopleCode is not run.
Dinesh Kumar
For o!Init to not run' the follo!ing must all (e true:
The record is at level 4ero.
Ever& record )eld that is present in the data (u0ers is also present in the #e&s for
the component.
The Component Processor determines if the )eld is re%uired (& the component. In
practice' this usuall& means that the )eld is associated !ith a page )eld' possi(l&
hidden' for some page of the component. It could also mean that the )eld is
referenced (& some PeopleCode program that is attached to an event on some
other )eld of the component.
Ever& record )eld that is present in the data (u0ers is displa&+onl&.
o!Init not running is not considered to (e an error. The purpose of o!Init PeopleCode
is to complete initiali4ation of data on the ro! after it has (een read from the data(ase.
Because the data in this special circumstance is coming from the #e&list' it has alread&
(een initiali4ed correctl& (& !hatever processing produced the #e&list. Bore general
initiali4ation of the component should (e done in PostBuild PeopleCode' not o!Init.
RoInsert Event
"hen a user adds a ro! of data' the Component Processor generates a o!Insert event.
7ou should use o!Insert PeopleCode for processing speci)c to the insertion of ne!
ro!s. Do not put PeopleCode in o!Insert that alread& e/ists in o!Init' (ecause a
o!Init event al!a&s initiates after the o!Insert event' !hich !ill cause &our code to (e
run t!ice.
Note. 1enerall&' if none of the )elds in the ne! ro! are changed after the ro! has (een
inserted =either (& a user pressing Alt?@ or programmaticall&>' !hen the page is saved'
the ne! ro! is not inserted into the data(ase. ,o!ever' if the Change5nInit ro!set class
propert& is set to False' &ou can set values for )elds a ne! ro! in o!Insert or o!Init
PeopleCode' and the ro! !onAt (e saved.
The o!Insert event triggers PeopleCode on an& )eld on the inserted ro! of data.
Do not use a !arning or error in o!Insert.
7ou can prevent a user from inserting ro!s into a scroll area (& selecting the :o o!
Insert chec# (o/ in the scroll (ar-s page )eld properties' as sho!n in the follo!ing
illustration. ,o!ever' &ou cannot prevent ro! insertion conditionall&.
Setting ro! insert properties in page )eld properties for a scrool (ar
Note. o!Insert does not trigger PeopleCode on derived3!or# )elds.
o!Insert PeopleCode can (e associated !ith record )elds and component records.
Dinesh Kumar
RoSelect Event
The o!Select event is initiated at the (eginning of the component (uild process in an&
of the update action modes =2pdate' 2pdate3Displa& All' Correction>. o!Select
PeopleCode is used to )lter out ro!s of data as the& are (eing read into the component
(u0er. This event also occurs after a ScrollSelect or related function is e/ecuted.
A Discardo! function in o!Select PeopleCode causes the Component Processor to s#ip
the current ro! of data and continue to process other ro!s. A StopFetching statement
causes the Component Processor to accept the current ro! of data' and then stop
reading additional ro!s. If (oth statements are e/ecuted' the program s#ips the current
ro! of data' and then stops reading additional ro!s.
PeopleSoft applications rarel& use o!Select' (ecause itAs ineCcient to )lter out ro!s of
data after the&Ave alread& (een selected. Instead' screen out ro!s of data using search
record vie!s and e0ective+dated ta(les' !hich )lter out the ro!s (efore the&Are selected.
7ou could also use a ScrollSelect or related function to programmaticall& select ro!s of
data into the component (u0er.
In previous versions of PeopleTools' the "arning and Error statements !ere used instead
of Discardo! and StopFetching. "arning and Error statements still !or# as (efore in
o!Select' (ut their use is discouraged.
Note. In o!Select PeopleCode' &ou can refer to record )elds onl& on the record that is
currentl& (eing processed. This event' and all its associated PeopleCode' does not initiate
if run from a component interface.
o!Select PeopleCode can (e associated !ith record )elds and component records.
SaveEdit Event
The SaveEdit event is intiated !henever a user attempts to save the component. 7ou can
use SaveEdit PeopleCode to validate the consistenc& of data in component )elds.
"henever a validation involves more than one component )eld' &ou should use SaveEdit
PeopleCode. If a validation involves onl& one page )eld' use FieldEdit PeopleCode.
SaveEdit is not )eld+speci)c: it triggers associated PeopleCode on ever& ro! of data in
the component (u0ers' e/cept ro!s $agged as deleted.
An Error statement in SaveEdit PeopleCode displa&s a message and redispla&s the
component !ithout saving data. A "arning statement ena(les the user to clic# 59 and
save the data' or to clic# Cancel and return to the component !ithout saving.
2se the SetCursorPos function to set the cursor position to a speci)c page )eld follo!ing
a !arning or error in SaveEdit' to sho! the user the )eld =or at least one of the )elds>
Dinesh Kumar
that is causing the pro(lem. Ba#e sure to call SetCursorPos (efore the error or !arning'
(ecause these ma& terminate the PeopleCode program.
SaveEdit PeopleCode can (e associated !ith record )elds and components.
SavePostChange Event
After the Component Processor updates the data(ase' it initiates the SavePostChange
event. 7ou can use SavePostChange PeopleCode to update ta(les not in &our component
using the SD;E/ec (uilt+in function.
An error or !arning in SavePostChange PeopleCode causes a runtime error. Avoid errors
and !arnings in this event.
The s&stem issues a SD; Commit statement after SavePostChange PeopleCode
completes successfull&.
If &ou are e/ecuting "or#$o! PeopleCode' #eep in mind that if the "or#$o! PeopleCode
fails' SavePostChange PeopleCode is not e/ecuted. If &our component has (oth "or#$o!
and SavePostChange PeopleCode' consider moving the SavePostChange PeopleCode to
SavePreChange or "or#$o!.
If &ou are doing messaging' &our Pu(lish PeopleCode should go into this event.
SavePostChange does not e/ecute if there is an error during the save. For e/ample' if
there is a data con$ict error (ecause another user updated the same data at the same
time' SavePostChange does not e/ecute.
Important! :ever issue a SD; Commit or oll(ac# statement manuall& from !ithin a
SD;E/ec function. ;et the Component Processor issue these SD; commands.
SavePostChange PeopleCode can (e associated !ith record )elds' components' and
component records.
SavePreChange Event
The SavePreChange event is initiated after SaveEdit completes !ithout errors.
SavePreChange PeopleCode provides one )nal opportunit& to manipulate data (efore the
s&stem updates the data(ase. for instance' &ou could use SavePreChange PeopleCode to
set se%uential high+level #e&s. If SavePreChange runs successfull&' a "or#$o! event is
generated' and then the Component Processor issues appropriate Insert' 2pdate' or
Delete SD; statements.
SavePreChange PeopleCode is not )eld+speci)c: it triggers PeopleCode on all )elds and
on all ro!s of data in the component (u0er.
SavePreChange PeopleCode can (e associated !ith record )elds' components' and
component records.
Dinesh Kumar
SearchInit Event
The SearchInit event is generated *ust (efore a search' add' or data+entr& dialog (o/ is
displa&ed. SearchInit triggers associated PeopleCode in the search #e& )elds of the
search record. This ena(les &ou to control processing (efore a user enters values for
search #e&s in the dialog (o/. In some cases' &ou ma& !ant to set the value of the
search dialog )elds programmaticall&. For e/ample' the follo!ing program in SearchInit
PeopleCode on the component search #e& record )eld EBP;ID sets the search #e& page
)eld to the user-s emplo&ee ID' ma#es the page )eld unavaila(le for entr&' and ena(les
the user to modif& the user-s o!n data in the component:
EBP;ID E FEmplo&eeId.
1ra& =EBP;ID>.
Allo!EmplIdChg=true>.
7ou can activate s&stem defaults and s&stem edits in the search page (& calling
SetSeachDefault and SetSearchEdit in SearchInit PeopleCode. 7ou can also control the
(ehavior of the search page' either forcing it to appear even if all the re%uired #e&s have
(een provided' or (& s#ipping it if possi(le' !ith the SetSeachDialogBehavior function.
7ou can also force search processing to al!a&s occur (& selecting the Force Search
Processing chec# (o/ in the component properties in PeopleSoft Application Designer.
Note. This event' and all its associated PeopleCode' do not inititiate if run from a
component interface.
SearchInit PeopleCode can (e associated !ith record )elds and component search
records.
SearchInit PeopleCode Function estrictions
7ou canAt use the follo!ing functions in SearchInit PeopleCode:
DoBodal
DoBodalComponent
Transfer
TransferPage
SearchSave Event
SearchSave PeopleCode is e/ecuted for all search #e& )elds on a search' add' or data+
entr& dialog (o/ after a user clic#s Search. This ena(les &ou to control processing after
search #e& values are entered' (ut (efore the search (ased on these #e&s is e/ecuted. A
t&pical use of this feature is to provide cross+)eld edits for selecting a minimum set of
Dinesh Kumar
#e& information. This event is also used to force a user to enter a value in at least one
)eld' even if it-s a partial value' to help narro! a search for ta(les !ith man& ro!s.
Note. SearchSave is not initiated !hen values are selected from the search list. To
validate data entered in the search page' use the Component PreBuild event.
7ou can use Error and "arning statements in SearchSave PeopleCode to send the user
(ac# to the search page if the user entr& does not pass validations implemented in the
PeopleCode.
Note. This event' and all its associated PeopleCode' is not initiated if run from a
component interface.
SearchSave PeopleCode can (e associated !ith record )elds and component search
records.
Note. Do not use the FBenu s&stem varia(le in this event. 7ou ma& get une/pected
results.
"or#$o Event
"or#$o! PeopleCode e/ecutes immediatel& after the SavePreChange event and (efore
the data(ase update that precedes the SavePostChange event. The "or#$o! event
segregates PeopleCode related to !or#$o! from the rest of the application-s PeopleCode.
5nl& PeopleCode related to !or#$o! =such as TriggerBusinessEvent> should (e in
!or#$o! programs. 7our program should deal !ith the "or#$o! event onl& after an&
SavePreChange processing is complete.
"or#$o! PeopleCode is not )eld+speci)c: it triggers PeopleCode on all )elds and on all
ro!s of data in the component (u0er.
"or#Flo! PeopleCode can (e associated !ith record )elds and components.
Dinesh Kumar