Field Class Methods

In this section, we discuss the Field class methods in alphabetical order.

Syntax

AddDropDownItem(CodeString, DescriptionString)

Description

The AddDropDownItem method adds an item to the dropdown list in the control for the field. The first time this method is called, it overrides the prompt table or translate table used to populate the list. Those items no longer appear in the list. Only the items added using this method display.

Subsequent calls to this method adds additional items to the dropdown list. The items added with the first call to the method also display.

If there is an existing value and the dropdown list is changed with these functions, the selection shows as (Invalid value) unless the new list contains an entry with the same code as the existing value.

Considerations Using AddDropDownItem

If the data for the dropdown is language sensitive, the values for the dropdown should come from the message catalog or from a database field that has a related language record, and should not be hard-coded.

A good place for your PeopleCode program to populate a dropdown list is in the RowInit event. This event executes before the page is shown for the first time, so it prevents unnecessary SQL.

Parameters

Field or Control

Definition

CodeString

Specify the value used to set the field value if this item is selected. Codes longer than the size of the field are truncated.

DescriptionString

Specify the value the end-user sees in the dropdown list.

Returns

None.

Example

Using a hardcoded list is not appropriate for this function because translations do not work. The data must come from the Translate Table (or other record) directly so that the data is translated correctly.

Local Rowset &Xlat;

&FLD = GetRecord(Record.JOB).GetField(Field.ACTION);
&FLD.ClearDropDownList();

Evaluate %Component
When Component.JOB_DATA_CONCUR
   &Xlat = CreateRowset(Record.PSXLATITEM);
   &Xlat.Fill("WHERE FILL.FIELDNAME = 'ACTION' AND Fill.FIELDVALUE in ('ADL','HIR') and EFFDT = (select max(EFFDT) from PSXLATITEM B where B.FIELDNAME = 'ACTION' and B.FIELDVALUE in ('ADL','HIR') and EFFDT <= JOB.EFFDT)");
   
   &Xlat_cnt = &Xlat.ActiveRowCount;
   For &I = 1 To &Xlat_cnt
      &CodeIn = &Xlat.GetRow(&I).GetRecord(1).FIELDVALUE.Value;
      &DescIn = &Xlat.GetRow(&I).GetRecord(1).XLATLONGNAME.Value;
      
      &FLD.AddDropDownItem(&CodeIn, &DescIn);
   End-For;
   
   Break;
When-Other
End-Evaluate;

Syntax

AddFFClass(style_names)

Description

Use the AddFFClass method to update the value of the FreeFormStyleName property. This method appends free form style classes to any existing styles defined by the FreeFormStyleName property for this field.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

style_names

Specifies the style names as a string value.

Returns

None.

Example

&fld1.AddFFClass("active color_red");

Syntax

ClearDropDownList()

Description

The ClearDropDownList method clears all items added to the dropdown list using the AddDropDownItem method. In addition, this method causes the prompt table or translate table values defined for the list to come back into effect again (unless they're subsequently overridden again with AddDropDownItem.)

Parameters

None.

Returns

None.

Example

&FLD = GetRecord(Record.ABSENCE_HIST).GetField(Field.ABSENCE_TYPE);
&FLD.AddDropDownItem("CNF", "Conference");
&FLD.AddDropDownItem("VAC", "Vacation");
&FLD.AddDropDownItem("SCK", "Sick");
. . . .
&FLD.ClearDropDownList();

Syntax

GetAuxFlag(FlagNumber)

Description

Use the GetAuxFlag method to determine whether the Auxiliary Flag Mask specified by FlagNumber has been set for a field.

Currently, only one flag comes preset from PeopleSoft: a 1 indicates a ChartField.

Parameters

Field or Control

Definition

FlagNumber

Specify the flag number. 1 is a ChartField. Valid values are between 1 and 32.

Returns

A Boolean value: True, the flag is set, False if the flag hasn't been set.

Example

&field = GetField(Field.RC_TEST_PB);
&ret = &field.GetAuxFlag(1);
If (&ret = True) Then
   MessageBox(0, "Metadata Fn Status", 0, 0, "Aux Flag 1 is SET - ChartField");
Else
   MessageBox(0, "Metadata Fn Status", 0, 0, "Aux Flag 1 is NOT SET - Not a ChartField");
End-If;

Syntax

GetBaseName()

Description

Use the GetBaseName method to return the value of the Page Field Name field if it is defined on the the field's General tab. Otherwise, the method returns the name of the page field as RECORD_NAME_FIELD_NAME.

Note: This differs from the Name property, which returns the FIELD_NAME value only.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A String value.

Example

&nm = PTNUI_ADDT_WRK.GROUPBOX7.GetBaseName();

Syntax

GetDNDField()

Description

Use the GetDNDField method to return the field from which the drag started—that is, the source field.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A Field object.

Example

Local Field &field1 = GetDNDField();

Syntax

GetDNDRow()

Description

Use the GetDNDRow method to return the row from which the drag started—that is, the source row.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A Row object.

Example

Local Row &dragRow = GetDNDRow();
Local integer &fromRowNum = &dragRow.RowNumber;

Syntax

GetDNDRowset()

Description

Use the GetDNDRowset method to return the rowset from which the drag started—that is, the source rowset.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A Rowset object.

Example

Local Rowset &rs = GetDNDRowset();

Syntax

GetDNDTargetField()

Description

Use the GetDNDTargetField method to return the field on which the drop occurred—that is, the target field.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A Field object.

Example

Local Field &field2 = GetDNDTargetField();

Syntax

GetDNDTargetRow()

Description

Use the GetDNDTargetRow method to return the row on which the drop occurred—that is, the target row.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A Row object.

Example

Local Row &toRow = GetDNDTargetRow();
Local integer &toRowNum = &toRow.RowNumber;

Syntax

GetDNDTargetRowset()

Description

Use the GetDNDTargetRowset method to return the rowset on which the drop occurred—that is, the target rowset.

Important! Use this method within fluid applications only.

Parameters

None.

Returns

A Rowset value.

Example

Local Rowset &rs2 = GetDNDTargetRowset();

Syntax

GetLongLabel(LabelID)

Description

The GetLongLabel method returns the long name for a field given a label ID. If the given label ID isn’t found, a null string is returned. LabelID takes a string value.

Note: If a button is defined as an HTML button or hyperlink, and if it has an associated record field, the label associated with it is only the text of the button. The mouse-over text can only be changed by the lable if the button is defined as a button with an Image label.

Returns

A text string containing the long name of the field for the specified label ID.

Example

The following code sets the label for a field to one of two different texts, based on the page.

Local Field &FIELD;

&FIELD = GetField(RECORD.MYFIELD);
   If %Page = PAGE.PAGE1 Then
      &FIELD.Label = &FIELD.GetLongLabel("LABEL1");
   Else If %Page = PAGE.PAGE2 Then
      &FIELD.Label = &FIELD.GetLongLabel("LABEL2");
End-If;

If the Label ID is the same as the name of the field, you could use the following:

&LABELID = &FIELD.Name;
&FIELD.Label = &FIELD.GetLongLabel(&LABELID);

Syntax

GetRelated(recname.fieldname)  

Description

The GetRelated method returns a field object for a related field recname.fieldname that has the field executing the method as its control field.

This method is similar to the GetRelField built-in function, however, the built-in works only in the current context, while this method can be applied to a field from any position in the buffer structure.

Using GetRelated With a Control Field

PeopleCode events on the Control Field can be triggered by the Related Edit field. When this happens, there can be different behavior than with other types of fields:

  • If the events are called from FieldEdit of the Control Field, and that FieldEdit is triggered by a change in the Related Edit field, the functions return the previous value.

  • If the events are called from FieldChange of the Control Field, and that FieldChange is triggered by a change in the Related Edit field, the functions return the value entered into the Related Edit. This may be a partial value, that will subsequently be expanded to a complete value when the processing is complete.

Parameters

Field or Control

Definition

recname.fieldname

Specifies a field in the same row as the current field object, that has the field executing the method as its control field.

Returns

The field object for the field with the specified name that is related to the field executing the method.

Example

In the following example, the field object is instantiated, then the related display field object. The Value property for the related display is changed, it is disabled, and another variable is assigned its value.

Local Field &FIELD, &REL_FIELD;

&FIELD = GetField(OPC_9A2FIELDS.COMPANY);   
/* control field object  */
&REL_FIELD = &FIELD.GetRelated(COMPANY_TBL.DESCR);    
/* related display object */
&REL_FIELD.Value = "Change";
&REL_FIELD.Enabled = False;
&TMP = &REL_FIELD.Name;
&REL_FIELD.Value = &TMP;

If you were not going to use the &FIELD variable later, the first two lines of code in the previous example could be combined:

&REL_FIELD = GetField(OPC_9A2FIELDS.COMPANY).GetRelated(COMPANY_TBL.DESCR);

Suppose you had two control fields, EMPLID and MANAGER_ID, and both use the NAME field on the PERSONAL_DATA table as their related display. If you need to access both related display fields, you could do the following:

&NAME_EMPLID = GetField(PERSONAL_DATA.EMPLID).GetRelated(PERSONAL_DATA.NAME);
&NAME_MANAGER = GetField(PERSONAL_DATA.MANAGER_ID).GetRelated(PERSONAL_DATA.NAME);

Syntax

GetShortLabel(LabelID)

Description

The GetShortLabel method returns the short name for a field given a label ID. If the given label ID isn’t found, a null string is returned. LabelID takes a string value.

Note: If a button is defined as an HTML button or hyperlink, and if it has an associated record field, the label associated with it is only the text of the button. The mouse-over text can only be changed by the lable if the button is defined as a button with an Image label.

Returns

A text string containing the short name of the field for the specified label ID.

Example

The following code sets the label for a field to one of two different texts, based on the page.

Local Field &FIELD;

&FIELD = GetField(RECORD.MYFIELD);
   If %Page = PAGE.PAGE1 Then
      &FIELD.Label = &FIELD.GetShortLabel("LABEL1");
   Else If %Page = PAGE.PAGE2 Then
      &FIELD.Label = &FIELD.GetShortLabel("LABEL2");
End-If;

If the Label ID is the same as the name of the field, you could use the following:

&LABELID = &FIELD.Name;
&FIELD.Label = &FIELD.GetShortLabel(&LABELID);

Syntax

ReplaceFFClass(from_style, to_style, append)

Description

Use the ReplaceFFClass method to update the value of the FreeFormStyleName property. This method replaces the from_style with the to_style. If the from_style does not exist, the to_style is added to the style list, only if the optional append parameter is True.

Note: ReplaceFFStyle can only replace the styles set through PeopleCode using the AddFFClass method or the FreeFormStyleName property and the not those set through Application Designer.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

from_style

Specifies the style (or list of styles) to be replaced as a string value.

to_style

Specifies the replacement style (or list of styles) as a string value.

append

Specifies a Boolean value indicating whether the to_style value is to be appended when the form_style does not exist. The default value is False.

Returns

None.

Example

&field1.ReplaceFFClass("dateStyle", "emphasis");
&field2.ReplaceFFClass("hidden", "");

Syntax

SearchClear()

Description

The SearchClear method clears the field values if the field is a search key.

Considerations Using SearchClear and SetDefault

The SetDefault method causes a field to be set to its default value (if there is one) immediately after SearchInit PeopleCode finishes. SetDefault overrides SearchClear. If you call SearchClear for a record, then use SetDefault for a field, the field is set to its default value and the search key values for the rest of the record are cleared.

Parameters

None.

Returns

None.

Example

Local Field &FIELD;

&FIELD = GetField(PERSONAL_DATA.EMPLID);
&FIELD.SearchClear();

Syntax

SetCursorPos(Page.page_name | %Page)

Description

The SetCursorPos method enables you to set the focus to the page field corresponding to the current Field object (on the specified page). The current page may be specified as %Page.

Restrictions on Use with a Component Interface

This method is ignored (has no effect) when used by a PeopleCode program that’s been called by a component interface.

Parameters

Field or Control

Definition

Page.page_name

The name of the page, preceded by the keyword Page. The page_name page must be in the current component. You can also pass the %Page system variable in this parameter (without the Page reserved word).

Returns

None.

Example

The following pseudo-code enables you to set the focus to a related field:

GetField(ControlRec.ControlField).GetRelated(RelatedRec.RelatedField).SetCursorPos(Page.pagename);

The following example places the cursor in the current field if a SaveEdit validation fails. Note the use of the %Page system variable to get the page name. Note also that SetCursorPos is called before Error.

   If None(DERIVED_SECURTY.OPERPSWD) Then
      GetField(DERIVED_SECURTY.OPERPSWD).SetCursorPos(%Page);
      Error MsgGet(48, 268, "Message Not Found");
   End-If;

Syntax

SetDefault() 

Description

SetDefault sets the value of the field to a null value, or to a default, depending on the type of field.

  • If this method is used against data from the component buffers, the next time default processing occurs, it is set to its default value: either a default specified in its record field definition or one set programmatically by PeopleCode located in a FieldDefault event. If neither of these defaults exist, the Component Processor leaves the field blank.

  • If this method is used with a field that isn't part of the data buffer (for example, a field in a record object instantiated with CreateRecord) the field is automatically set to its default value if one is set for the field, not for the record field. Any FieldDefault PeopleCode will not be run on these types of fields. If you want to set the default values for all the fields in a record, use the SetDefault record class method.

Blank numbers correspond to zero on the database. Blank characters correspond to a space on the database. Blank dates and long characters correspond to NULL on the database. SetDefault gives each field data type its proper value.

Parameters

None.

Returns

None.

Example

&CHARACTER.SetDefault();

Syntax

SetDisplayMask(Mask_Char, Unmasked_Trailing_Chars)

Description

Use the SetDisplayMask method to mask all or some of the data displayed in certain PIA page controls. The method replaces each character of the displayed field text value with the chosen masking character. The method provides the ability to choose the number of trailing characters to remain unmasked. This method affects the same PIA displays that honor Custom Field Formatting. Once the mask is set, it is persisted within the component. If the value is changed, the masking character is re-applied on the next server trip. The method can be called via event mapping and can be used in combination with IsUserInRole() or IsUserInPermissionList() functions to control who can or should not see the unmasked information.

Parameters

Field or Control

Definition

Mask_Char

Specifies a single character value used for masking data (only first character is used if more than one character is entered).

Unmasked_Trailing_Chars

Specifies the number of trailing characters on the right to remain unmasked.

Returns

None.

Example

&field = GetField(Field.AE_BIND_VALUE);
&formatlength = &field.SetDisplayMask("*", 4);
&value = &field.FormattedValue;
&mymsg = "Field.AE_BIND_VALUE is " | &value;
MessageBox(0, "SetDisplayMask", 0, 0, &mymsg);

Syntax

SetGroupletActionUrl(URL)

Description

Use the SetGroupletActionUrl method to set the target content URL to which the user is transferred when the user taps the grouplet or tile.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

URL

Specifies the URL as a string value.

Returns

None.

Example

PT_AG_LAYOUT.PT_AG_GROUPBOX3.SetGroupletActionUrl("http://example.com:8080/psc/ps5/EMPLOYEE/HRMS/s/WEBLIB_PTAI.ISCRIPT1.FieldFormula.IScript_LoadSubpageButtons?PTAI_LIST_ID=PTIB_IBCFG1001&fmode=1");

Syntax

SetGroupletDisplayIn(display_in)

Description

Use the SetGroupletDisplayIn method to set the location where the target content for the grouplet or tile will be displayed.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

display_in

Specifies the display location as an Integer constant.

Use the following integer constants (integer values are provided for reference only):

Numeric Value

Constant Value

Description

0

%GroupletActionInCurrentWindow

Display the content in the current browser window.

1

%GroupletActionInNewWindow

Display in a new browser window.

2

%GroupletActionInModal

Display in a modeless modal window.

3

%GroupletActionNavBarGrouplet

Display in the NavBar (used by NavBar tiles only).

4

%GroupletActionNavrBarUrlInCurrentWindow

Display in the current browser window (used by NavBar tiles only).

6

%GroupletActionAGTargetFluid

Display the fluid component within the activity guide.

7

%GroupletActionMDTargetFluid

Display the fluid component within the master/detail target area.

8

%GroupletActionMDTargetClassic

Display the classic component within the master/detail target area.

9

%GroupletActionAGTargetClassic

Display the classic component within the activity guide.

Returns

None.

Example

PT_AG_LAYOUT.PT_AG_GROUPBOX3.SetGroupletDisplayIn(%GroupletActionInCurrentWindow);

Syntax

SetGroupletEventMsg (push_event)

Description

Use the SetGroupletEventMsg method to specify the name of a push notification event used to dynamically update the tile’s content.

Parameters

Field or Control

Definition

push_event

Specifies the push notification event name as a String value.

Returns

None.

Example

&rec.GROUPLET.SetGroupletEventMsg("MY_EVENT");

Syntax

SetGroupletID(field_ID)

Description

Use the SetGroupletID method to set the ID of the group box (the page field name) from which the content is rendered.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

field_ID

Specifies the page field name of the group box as a string value.

Returns

None.

Example

PT_AG_LAYOUT.PT_AG_GROUPBOX3.SetGroupletID("GROUPBOX5");

Syntax

SetGroupletImage(image_ID)

Description

Use the SetGroupletImage method to specify the image ID for the static image to be displayed on the grouplet or tile.

Note: If dynamic content is also configured for the grouplet, this "pre-load" image is displayed while the dynamic content for the tile is being retrieved and loaded.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

image_ID

Specifies the database ID for the image as a string value.

Returns

None.

Example

&rec.GROUPLET.SetGroupletImage(&rec.IMAGE_NAME.Value);

&RS_OPTN(1).PSSCWORDDEFN.SCNEGWORDFLG.SetGroupletImage("PROFILE_64");

Syntax

SetGroupletImageUrl(image_URL)

Description

Use the SetGroupletImageUrl method to specify a fully formed URL for the static image to be displayed on the grouplet or tile.

Note: If dynamic content is also configured for the grouplet, this "pre-load" image is displayed while the dynamic content for the tile is being retrieved and loaded.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

image_URL

Specifies the fully formed URL for the image as a String value.

Returns

None.

Example

&rec.GROUPLET.SetGroupletImageUrl(&remoteImageURL);

Syntax

SetGroupletMOptions(modal_options)

Description

Use the SetGroupletMOptions method to set the modal options for the grouplet or tile.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

modal_options

Specifies custom modal options as a String value. See Modal Options for more information.

Returns

None.

Example

/* Action Menu */
Local string &sMenuTitle = MsgGetText(124, 524, "Message Not Found: Action Menu");
PTLAYOUT.HEADER_ACTIONGROUP.SetGroupletMOptions("sTitle@" | &sMenuTitle | ";bAutoClose@1;bMask@1;bHeader@0;");

Syntax

SetGroupletTargetID(target_ID)

Description

Use the SetGroupletTargetID method to set the target ID attribute of the NavBar tile.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

target_ID

Specifies the target ID attribute as a String value.

Returns

None.

Example

&RS_OPTN(&I).QE_GROUPLET.QE_GRPDESCR.SetGroupletTargetID("TARGETGROUP$0"); /* NEW TARGET ID*/

Syntax

SetGroupletTimer(time_in_seconds)

Description

Use the SetGroupletTimer method to set the time in seconds after which the grouplet or tile will be refreshed with the source content.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

time_in_seconds

Specifies the time in seconds after which the tile is refreshed with the source content, as an integer value.

Returns

None.

Example

&rec.GROUPLET.SetGroupletTimer(100);

Syntax

SetGroupletType(type)

Description

Use the SetGroupletType method to set the type of grouplet.

A grouplet is the encapsulation of content from one source (for example, a component, an iScript, or external content) that is presented within the context of another fluid application page. Tiles, embedded related content, and related information are all examples of grouplets. In each of these scenarios, the grouplets are created by the system at runtime based solely on configuration details. However, you can use this and other methods and properties of the Field class to generate grouplets from group box fields programmatically.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

type

Specifies the type for the grouplet as an integer constant.

Use the following integer constants (integer values are provided for reference only):

Numeric Value

Constant Value

Description

0

%GroupletNone

Not a grouplet (also referred to as a tile). This is a regular group box with its content coming from the same page records.

1

%GroupletWithStyle

Grouplet with style. This producer tile includes its own style sheets, JavaScript, or both.

Important! Be aware that this setting can inject style settings or JavaScript code that conflicts with those defined for the page.

2

%GroupletNoStyle

Grouplet without style. This producer tile does not include style sheets or JavaScript.

Note: This is the recommended setting.

3

%GroupletIframe

Interactive grouplet.

4

%GroupletIframeExt

Interactive grouplet for external content.

5

%GroupletIframeAutoSize

Interactive grouplet with autosizing.

Note: Use this setting for homepage and dashboard tiles only.

6

%GroupletIframeExtAutoSize

Interactive grouplet for external content with autosizing.

Note: Use this setting for homepage and dashboard tiles only.

7

%GroupletIframeVAutoSize

Interactive grouplet with vertical autosizing. The system will autosize the grouplet height based on the content at initial load. The grouplet will be automatically resized by the system when:

  • The window is resized.

  • Any field change or server trip is invoked within the grouplet.

  • Any group boxes within the grouplet are expanded or collapsed.

  • When either side panel is opened or closed.

Important! While a grouplet can be defined as interactive, you should be aware of the limitations. See the section, “Limitations with Interactive Grouplets,” in Fluid Related Content for more information.

Returns

None.

Example

/* Use the following three methods to create a display-only grouplet.    */
&fld.SetGroupletType(%GroupletNoStyle);
/* Specifies the grouplet's source content */
&fld.SetGroupletUrl(&src_URL);
/* Specifies the group box's page field name. Not used with interactive  */
/* grouplets, which render the entire component.                         */
&fld.SetGroupletID("GRPLTC_NOINTER");

Syntax

SetGroupletUrl(URL)

Description

Use the SetGroupletUrl method to set the source URL from which the grouplet or tile content is rendered.

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

URL

Specifies the URL as a string value.

Returns

None.

Example

/* Specifies the grouplet's source content */
&fld.SetGroupletUrl(&src_URL);

Syntax

SetImageUrl(image_URL)

Description

Use the SetImageUrl method to specify a fully formed URL for the static image to be associated with page field of type image (that is, an image associated with a record field).

Important! Use this method within fluid applications only.

Parameters

Field or Control

Definition

image_URL

Specifies a fully formed URL for the image as a String value.

Returns

None.

Example

PTGP_GPLT_WRK.PTGP_CONTEXT_IMG.SetImageUrl(&thisImage.ImageUrl);
PTGP_GPLT_WRK.PTGP_CONTEXT_IMG.Label = &thisImage.AltText;