Grid Classes

This chapter provides an overview of Grid class and the GridColumn subobject and discusses the following topics:

Note. Use the grid classes to control the display of a grid control. If you want to manipulate an analytic grid, used with PeopleSoft Analytic Calculation Engine data, you must use the AnalyticGrid classes.

See Also

Analytic Grid Classes

Click to jump to parent topicUnderstanding Grid and GridColumn Classes

A grid looks and behaves like a spreadsheet embedded in a page: it has column headings, row headings, cells, and horizontal and vertical scroll bars. It can be used instead of a single-level scroll. It is analogous to a scroll region on a page. Each row in a grid corresponds to a set of controls in a scroll occurrence. Each cell in a grid corresponds to a field on a page.

The grid class enables you to instantiate only GridColumn objects, which in turn enables you to change grid column attributes without having to write PeopleCode that loops through every row of the grid.

Note. PeopleSoft builds a page grid one row at a time. Because the grid class applies to a complete grid, you can’t attach PeopleCode that uses the grid class to events that occur before the grid is built; the earliest event you can use is the page Activate Event.

See Also

GridColumn Class

Using Grids

Activate Event

Click to jump to parent topicShortcut Considerations

An expression of the form

&MYGRID.columnname.property

is converted to an object expression by using GetColumn(columnname). The following examples are equivalent.

Using columnname: 

&MYGRIDCOLUMN = &MYGRID.CHECKLIST_ITEMCODE;

Using the GetColumn method:

&MYGRIDCOLUMN = &MYGRID.GetColumn("CHECKLIST_ITEMCODE");

The following examples are equivalent.

Using columnname:

&MYGRID.CHECKLIST_ITEMCODE.Visible = False;

Using the GetColumn method:

&MYGRID.GetColumn("CHECKLIST_ITEMCODE").Visible = False;

Click to jump to parent topicThe Grid Class in PeopleCode

The PeopleCode grid object is a reference to a page runtime object for the grid. These particular page runtime objects aren’t present until the Component is started.

Note. PeopleSoft builds a page grid one row at a time. Because the Grid class applies to a complete grid, you can’t attach PeopleCode that uses the Grid class to events that occur before the grid is built; the earliest event you can use is the page Activate Event.

If you’re using the grid within a secondary page, the runtime object for the grid isn’t created until the secondary page is run. The grid object can’t be obtained until then, which means that the earliest PeopleCode event you can use to activate a grid that’s on a secondary page is the Activate event for the secondary page.

The attributes you set for displaying a page grid remain in effect only while the page is active. When you switch between pages in a component, you have to reapply those changes every time the page is displayed.

In addition, the Activate event associated with a page fires every time the page is displayed. Any PeopleCode associated with that Activate event runs, which may undo the changes you made when the page was last active. For example, if you hide a grid column in the Activate event, then display it as part of a user action, when the user tabs to another page in the component, then tabs back, the Activate event runs again, hiding the grid column again.

If a user at runtime hides a column of a grid, tabs to another page in the component, then tabs back to the first page, the page is refreshed and the grid column is displayed again.

When you place a grid on a page, the grid is automatically named the same as the name of the primary record of the scroll for the grid. This is the name you use with the GetGrid function. You can change this name on the Record tab of the Grid properties.

Note. There is no visible property for a grid, just a grid column. However, you can still hide an entire grid. Remember, many of the Rowset methods and properties work on a grid. If you want to hide an entire grid, get the rowset for that grid by using the HideAllRows Rowset class method.

Use the grid classes to access an ordinary grid. Use the analytic grid classes to access an analytic grid.

See Also

Analytic Grid Classes

Activate Event

HideAllRows

Click to jump to parent topicData Type for a Grid or Grid Column Object

Grids are declared using the Grid data type. For example, 

Local Grid &MYGRID;

Grid Columns are declared using the GridColumn data type. For example:

Local GridColumn &MYGRIDCOL;

Click to jump to parent topicScope of a Grid or Grid Column Object

Both the grid and grid column objects can be instantiated from PeopleCode only.

A grid is a control on a page. You generally use these objects only in PeopleCode programs that are associated with an online process, not in an Application Engine program, a message subscription, a Component Interface, and so on.

In addition, PeopleSoft builds a page grid one row at a time. Because the Grid class applies to a complete grid, you can’t attach PeopleCode that uses the Grid class to events that occur before the grid is built; the earliest event you can use is the page Activate Event.

Click to jump to parent topicGrid Class Built-in Function

GetGrid

Click to jump to parent topicGrid Class Methods

In this section, we discuss each Grid class method.

Click to jump to top of pageClick to jump to parent topicEnableColumns

Syntax

EnableColumns(&Array)

Description

Use this method to enable or disable one or more columns in a grid. When a column is enabled, it is editable; when it’s disabled, it is un-editable.

The EnableColumns method of the Grid class can provide a noticeable performance improvement over multiple calls to set the Enabled property of the GridColumn class. Each call manipulating a grid (either using a Grid class method or setting a GridColumn property) has a significant, and similar performance overhead. Therefore, one key to increasing the performance of PeopleCode programs manipulating grids is to reduce the number of these calls. Performance testing data suggests that if your program is changing three or more columns, use one of the Grid class methods, such as the EnableColumns method, instead of setting the column properties directly. The single call to the Grid class method offsets the small overhead of creating and populating the required array.

Parameters

&Array

Specify a two-dimensional array containing the column name and a value (Y/N) indicating whether the column is enabled.

Returns

None.

Example

&AREnable = CreateArrayRept(CreateArrayRept("", 2), 0);
&AREnable.Push(CreateArray("JOB_DETAIL", "Y"));
&AREnable.Push(CreateArray("JOB_TIME", "Y"));
&myGrid.EnableColumns(&AREnable);

See Also

Enabled.

Click to jump to top of pageClick to jump to parent topicGetColumn

Syntax

GetColumn(columnname)

Description

The GetColumn method instantiates a grid column object from the Grid class, and populates it with a grid column from the grid object executing this method. Specify the grid column name in the page field properties for that field, consisting of any combination of uppercase letters, digits and "#", "$", "@", and "_".

To specify a grid column name:

  1. Open the page in Application Designer, select the grid and access the page field properties.

  2. Select the Columns tab on the grid properties.

  3. Either double-click on the grid column you want to name, or select the column and click the Properties button.

  4. On the General tab, type the grid column name in the Page Field Name field.

Note. Although it’s possible to base multiple grid columns on the same record field, the Page Field Name you enter for each grid column must be unique, not just for that grid, but for that page. If you have two grids on a page, every page field name must be unique to the page.

Parameters

columnname

Specify a string containing the value of the Page Field Name on the General tab of the grid column’s properties. You must have previously entered a value for the Page Field Name for the grid column you want to work with.

Returns

A GridColumn object populated with the grid column specified as the parameter to this method.

Example

local Grid &MYGRID;
local GridColumn &MYGRIDCOLUMN;

&MYGRID = GetGrid(PAGE.EMPLOYEE_CHECKLIST, "EMPL_GRID");
&MYGRIDCOLUMN = &MYGRID.GetColumn("CHECKLIST_ITEMCODE");

The following function loops through rows on a grid. The function finds each row that is selected. It does this through the Selected property of the Row class of PeopleCode. Data is then moved from the selected row to a new row, on a different grid, in the same page. The way in which this function is written, data is moved from &SCROLL_SHELF to &SCROLL_CART. These are two different rowset objects, of two different grids, on the same page. Note that the two grids in this example are on the same occurs level.

/* Moving data between grids on the same occurs level */
/* of the same page */

Local Rowset &SCROLL_CART, &SCROLL_SHELF;

Function move_rows(&SCROLL_CART As Rowset, &SCROLL_SHELF As Rowset);

   &I = 1;
/* loop to find whether row is selected */
   Repeat
   If &SCROLL_SHELF.GetRow(&I).Selected = True Then

      If All(&SCROLL_CART(1).GetRecord(1).QEPC_ITEM.Value) Then

         &SCROLL_CART.InsertRow(&SCROLL_CART.ActiveRowCount);
      End-If;

   /* if it is selected move data to other grid   */

      &SCROLL_SHELF.GetRow(&I).GetRecord(1).CopyFieldsTo(&SCROLL_CART.GetRow⇒
(&SCROLL_CART.ActiveRowCount).GetRecord(1));

/* delete row from current grid so data disappears  */

      &SCROLL_SHELF.DeleteRow(&I);
      &I = &I - 1;
   End-If;

   &I = &I + 1;
   Until &I = &SCROLL_SHELF.ActiveRowCount + 1;

/* end of loop ****************************************/

End-Function;

/********* end of function *****************************/

/* Creating the rowset object */

&SCROLL_CART = GetLevel0()(1).GetRowset(SCROLL.QEPC_CART);
&SCROLL_SHELF = GetLevel0()(1).GetRowset(SCROLL.QEPC_SHELF);

/* calling the function   */

move_rows(&SCROLL_CART, &SCROLL_SHELF);

See Also

GetGrid.

Click to jump to top of pageClick to jump to parent topicLabelColumns

Syntax

LabelColumns(&Array)

Description

Use this method to set the display label for one or more columns in a grid.

The LabelColumns method of the Grid class can provide a noticeable performance improvement over multiple calls to set the Label property of the GridColumn class. Each call manipulating a grid (either using a Grid class method or setting a GridColumn property) has a significant, and similar performance overhead. Therefore, one key to increasing the performance of PeopleCode programs manipulating grids is to reduce the number of these calls. Performance testing data suggests that if your program is changing three or more columns, use one of the Grid class methods, such as the LabelColumns method, instead of setting the column properties directly. The single call to the Grid class method offsets the small overhead of creating and populating the required array.

Parameters

&Array

Specify a two-dimensional array containing the column name and a value for the column label.

Returns

None.

Example

&ARLabel= CreateArrayRept(CreateArrayRept("", 2), 0);
&ARLabel.Push(CreateArray("JOB_DETAIL", "Job Detail"));
&ARLabel.Push(CreateArray("JOB_TIME", "Job Time"));
&myGrid.LabelColumns(&ARLabel);

See Also

Label.

Click to jump to top of pageClick to jump to parent topicSetProperties

Syntax

SetProperties(&Array)

Description

Use this method to set multiple properties (column enabled, column visibility, and column label) for one or more columns in a grid.

The SetProperties method of the Grid class can provide a noticeable performance improvement over multiple calls to set individual properties of the GridColumn class. Each call manipulating a grid (either using a Grid class method or setting a GridColumn property) has a significant, and similar performance overhead. Therefore, one key to increasing the performance of PeopleCode programs manipulating grids is to reduce the number of these calls. Performance testing data suggests that if your program is changing three or more columns, use one of the Grid class methods, such as the SetProperties method, instead of setting the column properties directly. The single call to the Grid class method offsets the small overhead of creating and populating the required array.

Parameters

&Array

Specify a four-dimensional array containing the column name, a value (Y/N) indicating whether the column is enabled, a value (Y/N) indicating whether the column is visible, and a value for the column label.

Returns

None.

Example

&ARProp= CreateArrayRept(CreateArrayRept("", 4), 0);
&ARProp.Push(CreateArray("JOB_DETAIL", "Y", "Y", "Job Detail"));
&ARProp.Push(CreateArray("JOB_TIME", "Y", "Y", "Job Time"));
&mygrid.SetProperties(&ARProp);

See Also

Enabled, Label, Visible.

Click to jump to top of pageClick to jump to parent topicShowColumns

Syntax

ShowColumns(&Array)

Description

Use this method to set the visibility for one or more columns in a grid.

The ShowColumns method of the Grid class can provide a noticeable performance improvement over multiple calls to set the Visible property of the GridColumn class. Each call manipulating a grid (either using a Grid class method or setting a GridColumn property) has a significant, and similar performance overhead. Therefore, one key to increasing the performance of PeopleCode programs manipulating grids is to reduce the number of these calls. Performance testing data suggests that if your program is changing three or more columns, use one of the Grid class methods, such as the ShowColumns method, instead of setting the column properties directly. The single call to the Grid class method offsets the small overhead of creating and populating the required array.

Parameters

&Array

Specify a two-dimensional array containing the column name and a value (Y/N) indicating whether the column is visible.

Returns

None.

Example

&ARShow= CreateArrayRept(CreateArrayRept("", 2), 0);
&ARShow.Push(CreateArray("JOB_DETAIL", "Y"));
&ARShow.Push(CreateArray("JOB_TIME", "Y"));
&myGrid.ShowColumns(&ARShow);

See Also

Visible.

Click to jump to parent topicGrid Class Properties

In this section, the Grid class properties are described in alphabetical order.

Click to jump to top of pageClick to jump to parent topicgridcolumn

Description

If a grid column name is used as a property, it accesses the grid column with that name. This means the following code:

&Mycolumn = &MyGrid.gridcolumnname;

acts the same as 

&Mycolumn = &MyGrid.GetColumn(columnname);

This property is read-only.

Click to jump to top of pageClick to jump to parent topicLabel

Description

This property returns a string specifying the label that appears as the title of the grid.

Note. You can't use this property to set labels longer than 100 characters. If you try to set a label of more than 100 characters, the label is truncated to 100 characters. Always put any changes to labels in the Activate event. This way the label is set every time the page is accessed.

This property is read-write.

Click to jump to top of pageClick to jump to parent topicPersistMenuOption

Description

Use this property to set or return a Boolean value specifying the persistent search property for this grid. This corresponds to the "Persist In Menu" option for the grid that can be set in Application Designer. When this property is True, the most recent transaction search is stored and the search results are accessible through the drop-down navigation menu structure.

This property is read-write.

Example

&MyGrid = GetGrid(Page.GRIDCHECK, "GRIDNO");
&MyGrid.PersistMenuOption = True;

MessageBox(0, "", 0, 0, "Persist In Menu = " | &MyGrid.PersistMenuOption);

See Also

Setting Grid Use Properties.

Click to jump to top of pageClick to jump to parent topicSummaryText

Description

Use this property to set or return a string representing the summary text for the grid.

Summary text enables you to provide a brief description of the functionality and content of the grid area. This property is pertinent for users who access the application in accessibility mode using screen readers.

This property is read-write.

Example

&MyGrid = GetGrid(Page.PSXLATMAINT, "PSXITMMNT_VW");
&MyGrid.SummaryText = "This is the new summary text through PeopleCode";

See Also

Setting Grid Label Properties

Click to jump to parent topicGridColumn Class

Grid columns are page fields that comprise a grid, which is itself a page field. Similarly, a group of GridColumn objects comprises a Grid object. The GridColumn class enables you to change grid column attributes without having to write PeopleCode that loops through every row of the grid.

This class has no methods or built-in functions, only properties.

Note. To use a GridColumn object, you must instantiate it from a grid object. This requires you to first instantiate a Grid object using the GetGrid built-in function.

You create an analytic grid column object from the analytic grid class. However, the analytic grid column class has the same properties as the grid column class. Any differences are noted in the documentation.

See GetGrid.

Click to jump to parent topicGridColumn Class Properties

In this section, we discuss each GridColumn class property.

Click to jump to top of pageClick to jump to parent topicEnabled

Description

This property specifies whether the fields in the column are enabled (that is, can be edited) or if they are "disabled", that is, un-editable. All columns are enabled by default.

Note. For an analytic grid column, the Enabled property only works with cubes, not dimensions.

This property is read-write.

Example

If Not &ValidID Then 
   &MYGRID = GetGrid(PAGE.EMPLOYEE_CHECKLIST, "EMPL_GRID");
   &MYGRIDCOLUMN = &MYGRID.GetColumn("CHECKLIST_ITEMCODE");
   &MYGRIDCOLUMN.Enabled ​= False;
End-If;

See Also

EnableColumns, SetProperties.

The EnableColumns and SetProperties methods of the Grid class can provide a noticeable performance improvement over multiple calls to set the Enabled property of the GridColumn class.

Click to jump to top of pageClick to jump to parent topicLabel

Description

This property specifies the display label for the GridColumn object , as distinct from the grid column’s Record Field Name or Page Field Name. This property overrides the equivalent settings on the Label tab of the grid column’s Page Field Properties.

Note. You can't use this property to set labels longer than 100 characters. If you try to set a label of more than 100 characters, the label is truncated to 100 characters. If you change the column label, then change the field label, you may overwrite the column label with the field label. The grid object is part of a page, not the data buffers, while the field is part of the data buffers. To avoid this problem, always put any changes to column labels in the Activate event. This way the label is set every time the page is accessed.

This property is read-write.

Example

&MYGRIDCOLUMN.Label = "Checklist Item";

See Also

LabelColumns, SetProperties.

The LabelColumns and SetProperties methods of the Grid class can provide a noticeable performance improvement over multiple calls to set the Label property of the GridColumn class.

Click to jump to top of pageClick to jump to parent topicName

Description

This property returns the name of the grid column, as a string. This value comes from the Page Field Name on the General tab in the Page Field Properties of the GridColumn object executing the property. This property was the value used to instantiate the GridColumn object.

This property is read-only.

Example

&PF_NAME = &MYGRIDCOLUMN.Name;

Click to jump to top of pageClick to jump to parent topicVisible

Description

This property specifies whether a grid column is visible or hidden. Set this property to False to hide the grid column, and to True to unhide the grid column. This property defaults to True.

The Visible property also hides grid columns that are displayed as tabs in the PeopleSoft Pure Internet Architecture.

If you specify "Show Column on Hide Rows" in Application Designer, the column headers and labels of a grid display at runtime, even when the rest of the column is hidden. You can't override this value using PeopleCode.

Note. For an analytic grid column, this property is only valid if the column is bound to a dimension on a slicer, and bound to a cube that is on the column axis.

This property is read-write.

Note. In previous releases of PeopleTools, the methodology for hiding a grid column was to use the Hide function in a loop to hide each cell in the column, one row at a time. This method of hiding grid columns still works. However, your application will experience deteriorated performance if you continue to use this method.

Example

&MYGRIDCOLUMN.Visible = False;

The following example checks for the value of a field in every row of the grid. If that value is "N" for every row, the column is hidden.

&RS = GetRowset(Scroll.EX_SHEET_LINE);
&HIDE = True;
While (&HIDE)

   For &I = 1 To &RS.ActiveRowCount;
      &OUT_OF_POLICY = &RS(&I).EX_SHEET_LINE.OUT_OF_POLICY.Value;
      &NO_RECEIPT_FLG = &RS(&I).EX_SHEET_LINE.NO_RECEIPT_FLG.Value;
      If &OUT_OF_POLICY = "Y" Then
         &OUT_OF_POLICY_HIDE = False;
         &HIDE = False;
      End-If;

      If &NO_RECEIPT_FLG = "Y" Then
         &NO_RECEIPT_HIDE = False;
         &HIDE = False;
      End-If;
   End-For;

   If &HIDE = True Then
      &HIDE = False;
   End-If;

End-While;

If Not (&OUT_OF_POLICY_HIDE) Then
   GetGrid(Page.EX_SHEET_LINE_APV1, "EX_SHEET_LINE").OUT_OF_POLICY.Visible = True;
Else
   GetGrid(Page.EX_SHEET_LINE_APV1, "EX_SHEET_LINE").OUT_OF_POLICY.Visible = False;
End-If;

If Not (&NO_RECEIPT_HIDE) Then
   GetGrid(Page.EX_SHEET_LINE_APV1, "EX_SHEET_LINE").NO_RECEIPT_FLG.Visible = True;
Else
   GetGrid(Page.EX_SHEET_LINE_APV1, "EX_SHEET_LINE").NO_RECEIPT_FLG.Visible =⇒
 False;
End-If;

See Also

ShowColumns, SetProperties.

The ShowColumns and SetProperties methods of the Grid class can provide a noticeable performance improvement over multiple calls to set the Visible property of the GridColumn class.