PK
7ZEoa, mimetypeapplication/epub+zipPK 7ZE iTunesMetadata.pliste
This chapter contains the following topics:
A portal is an application that aggregates portlets into pages and provides authentication, authorization and administration tools. A portlet is a single piece of portal content; it is the window through which users interact with the application while using a portal. Portlets provide information and act as gateways to full-blown applications. Portlets cannot communicate to one another, only to an application.
The principle value of a portlet to a user is that, compared to launching an application and searching for data manually, a portlet can significantly shorten the number of clicks required to get from the portal to the desired information or transaction.
This section discusses the three portlet types:
Alerts
Menus
Shortcuts
These types of portlets are typical of "dashboard" portal configurations used for business intelligence. They show a single dimension of data, provide a description for that data, and have a threshold value, which is often user configurable. If the threshold is breached, some event usually occurs to alert the user to the condition.
As a rule of thumb, limit each portlet to a single data dimension. Users who want to monitor several dimensions should have several portlets available on their portal—one for each dimension to be monitored.
Often, these types of portlets also provide a link to a transactional application that enables the user to see more detail and then change the situation that has caused the alert. If you provide such a link, be sure to prepopulate the transactional application with the data driving the portlet display result. Ideally, the user should not need to perform any queries for the initial data view when the application launches.
These types of portlets contain task-based links and shortcuts to web locations and applications. The value of such portlets is that the links should be highly tailored to the job role. The links you create to applications should therefore preload as much data as possible, based on the user's role. The idea is to reduce the amount of repetitive data entry the user must perform before entering a frequently-used application.
For example, a sales representative might want a portlet with a menu comprising his or her top 10 accounts. By clicking an account, the user launches an application in a view that shows an overview of all account activity for the last three months.
These types of portlets facilitate information lookup. Typically, they accept a limited amount of information, one or two fields of data. Just as with menu portlets, you should build in as much as possible based on the job role of the user to reduce data entry and target the result set as much as possible.
Frequently, these types of portlets display the results in an application, not the portlet itself. However, the application is often one that facilitates filtering the results and is not necessarily a full-blown transactional application. Based on your context, you might want to make it easy for the user to launch such an application from the filtering view.
This section discusses:
Portlet form features.
Portlet personalization.
Portlet form events.
Edit portlet form design-time considerations.
Portlet forms are the form types you use to create portlets intended for use in the Oracle Portal or the Collaborative Portal.
Note: Portlet forms are supported in JD Edwards EnterpriseOne version 8.11 and might not function correctly in older versions of the software. |
Portlet forms have these general characteristics:
All regular controls can be placed on portlet forms.
Multiple tab controls are permitted.
Toolbar and form/row exits are not permitted on a portlet form.
You must add action buttons to a portlet form.
No default action buttons are defined by Form Design Aid (FDA).
Default actions can be placed anywhere on the portlet form.
Portlet forms do not contain scroll bars; you must display all controls within the form.
Portlet forms support the Fetch on Business View and Update on Business View form property options.
You can nest reusable and embedded subforms in portlet forms.
JD Edwards EnterpriseOne Tools provides two types of portlet forms: browse portlets and edit portlets. Browse portlets enable the display of and queries for information. Edit portlets enable user edit functions—adding, changing, and deleting table information.
If you include a form interconnection in a portlet, the portal containing it will automatically resize the portlet to its maximum size when the user triggers the interconnection. When the user closes the application, the portlet returns to its normal size.
One feature of portlet forms that is unique among FDA form types is portlet personalization. Users can toggle between standard mode (where they interact with the application) and personalization mode, where they can select different options that affect how the application runs while in standard mode.
For example, say that the application by default displays all accounts that are overdue by 30 days or more. Users might be able to choose instead to view accounts that are overdue by 60 days instead, or by accounts in a certain region that are overdue. Alternatively, they might have an option which displays the information in a summarized format instead of showing all the data you show by default. Personalization values are user specific.
You control what options users have. Every option you provide, be it as simple as a filtering function or as complex as invoking additional functionality, is a data dictionary (DD) item passed in with the data structure. The DD items appear when the user toggles to personalization mode, and the user can trigger them by choosing the options and then returning to standard mode. If you do not include any such items in the data structure, then personalization mode is disabled for that portlet.
Because the available options are based on the form's data structure, those values are passed in by runtime to the form if they have been set.
Runtime provides three events that are specific to portlet form types:
This event occurs when runtime initializes the portlet form and before it initializes any forms which the portlet might contain.
This event occurs immediately after initialization to apply previously-saved personalization data. It occurs again when the user clicks the Save button in personalization mode.
This event occurs when the portlet is unloaded by the container. Typically, this occurs as the user logs out or the session times out.
In addition to the portlet-specific events, portlets support the general events in this table:
Event | Browse Portlet | Edit Portlet |
---|---|---|
Grid Record is Fetched | Yes | Yes |
Write Grid Line-Before | Yes | Yes |
Last Grid Record Has Been Read | Yes | Yes |
Notified By Child | Yes | No |
Grid Record is Fetched | No | Yes |
Write Grid Line-Before | No | Yes |
Last Grid Record Has Been Read | No | Yes |
Add Record to DB - Before | No | Yes |
Add Record to DB - After | No | Yes |
Update Record to DB - Before | No | Yes |
In addition to standard form properties, you can control the transaction boundary for edit portlets. You can choose to process each action (that is, insert, update, or delete) on the form separately (Transaction Disabled), or you can process all of the actions at once (Portlet Only Transaction). Choose the latter if processing each action separately would cause data integrity issues. Transaction processing for edit portlets is identical to that for subforms.
This section provides an overview of generating portlets and discusses how to deploy an FDA-created portlet.
Before you complete the tasks in this section:
Create or obtain a portlet application that was created in FDA.
Generate the application using eGenerator.
Generating an application based on portlet form types is similar to generating an application based on other form types, the difference being that you must also generate a portlet descriptor file, portlet.xml, that tells the portal which applications are available for the portlet (the WebClient_Portal.war file). This is an overview of the high-level tasks you must complete to create and view a portlet using FDA:
Create an application in FDA using the portlet form types.
Generate the application (that is, the portlet) with eGenerator.
Generate the portlet.xml file into WebClient_Portal.war file with eGenerator.
Install the .war file in Collaborative Portal.
To view it, add the portlet to a page in the portal.
This section discusses how to deploy an FDA-created portlet so that you can install it in Collaborative Portal.
To deploy an FDA-created portlet:
Launch eGenerator and select Generate, Portlet Deployment.
Select the .war file to generate.
Typically, the .war file for the local version of Collaborative Portal resides in C:\B9\system\Generator\WebClient_Portal.war.
eGenerator reads the local specifications for JD Edwards EnterpriseOne and lists all portlets it discovers.
Clear the check box next to any portlet that you do not want to generate, and click the Start button.
If multiple versions of an application exist, each version is listed.
Select the version you want to generate.
eGenerator creates a new portlet descriptor file and bundles it into a new WebClient_Portal.war file.
This section provides an overview of updating an FDA-created portlet after initial installation and discusses how to:
Add a new portlet application.
Delete an existing portlet application.
When you modify an existing FDA-created portlet in FDA, you need only regenerate the JD Edwards EnterpriseOne application to promote the application to the Collaborative Portal. However, if you are removing existing portlets or are adding new FDA-created portlets to Collaborative Portal, you must use eGenerator to update the portlet descriptor, portlet.xml, in the WebClient_Portal.war.
To add a new FDA-created portlet:
Launch eGenerator and select Generate, Portlet Deployment.
Select the .war file to update.
Select the same war file that you deployed previously.
Clear the check box next to any portlets that you do not want to generate, and click the Start button.
You should always select all portlets you want to be deployed to Collaborative Portal because after installation, the new WebClient_Portal.war replaces any previous version that exists on Collaborative Portal server.
eGenerator modifies the portlet descriptor file, portlet.xml, in the .war file.
This chapter contains the following topics:
With the saved query control, you provide users with the means to persist query criteria for use against the business view (BV) of the form. The control provides flexibility in the query filters and logic. You can constrain users to choosing a query from a preset list, enable them to input and save query parameters themselves, or give them any other combination of access.
The saved query control is a regular form control and can be added to a form as such, either from the Insert menu or tool bar. Because you must query on a BV, do not place a saved query control on a form type that does not permit BVs (that is, message forms) or on forms where the BV fetch is disabled. All filtering occurs on the BV columns that you select. A single BV column may be used as a filter more than once on the same form. You can display the query results in a grid or parent child control.
The query control appears by default with two parts: a titled drop-down field and two links (Save Query and Edit Queries). With the control properties, you can opt to display the links to the left of the combo box or beneath it. You can also choose to hide the links. Saved queries reside in the system as user overrides. You can use Cross-Reference and Object Management Workbench (OMW) to find and manipulate them as such. Because they are user overrides, saved queries are translatable.
In brief, these are the steps you perform to implement a saved query control:
Start with a form that has one or more BVs attached to it.
Place the saved query control on the form and configure it.
Place control on the form intended to display query results (that is, a grid or a parent/child control).
If you want a BV column to act as a filter, add an edit control for it and then configure it to be filterable by choosing a comparison operator to use.
If you want to enable users to select their own comparison type, add an edit control for each one and configure it with the Runtime Select comparison type.
If you want to provide users with a defined list of queries, run the application and make and save the queries (which are saved as user overrides).
Then, find and copy the user overrides into the *PUBLIC list.
This table identifies design-time property values you can set that can impact the saved query control significantly:
The saved query control is initialized as part of the form initialization process. To initialize the control, runtime checks the user override table for all saved query records that match the current application/form/version combination, user ID, current role or roles (*ALL), and *PUBLIC. If any records are found, runtime populates the drop-down field with the saved query names in alphabetical order.
In some cases, runtime might find duplicate query records between roles. For example, if a single user's query was copied so that it could be accessed by *PUBLIC, then runtime would discover that the query criteria are identical. In this case, runtime returns only the proprietary record (the user's query rather than the *PUBLIC version of the query). In all other instances, runtime returns one of the saved queries without preference as to which one it returns. Notice in this example that the entire saved query record was a duplicate. The saved query control enables duplicate saved query names; runtime can distinguish between queries with the same name with different criteria (non-duplicates) and queries with the same name with identical criteria (duplicates).
After initialization, runtime interacts with the saved query control only when the user works with queries. If the user selects a query from the drop-down list, runtime first clears all of the fields that have been flagged with the property value, Allow in Saved Query (including hidden columns and filter fields). Then runtime populates the fields as dictated by the saved query. Special values that require calculation such as user ID, today's date, and so forth, are calculated at the time that they are applied into the field. The act of populating the fields does not instigate a fetch; instead, the user must click Find to instruct the engine to fetch data based on the retrieved saved query.
When a user creates or modifies a saved query, runtime does not write those records to the user override table until form close. On the other hand, when a user deletes a saved query, runtime purges that record from the table immediately.
This chapter contains the following topics:
An edit control is a text field on a form. All form types can contain edit controls except message forms. Two types of edit controls are available. The first type is commonly referred to as a database field. It is associated with an item in the business view (BV) and through that connection to a specific data dictionary (DD) item. Database fields represent a field in a database record. The second type of edit control is commonly referred to as a DD field, and it also has a connection to a specific DD item.
Within the realm of database fields an additional distinction between filter fields and nonfilter fields exists. Database fields are nonfilter fields by default. Filter fields are used to alter the selection criteria of a database fetch. A filter can have a comparison type of equal, not equal, less than, less than or equal to, greater than, or greater than or equal to. A filter can be marked such that a wildcard (*) displays when the filter is not included in the selection.
The storage for the value of the edit control is based on the type of its associated DD item (such as numeric, string, character). An edit control is affected by the properties of the associated DD item. For example, if an edit control is associated with a DD item of type string with a length of thirty, the edit control will not permit more than thirty characters to be typed into the field.
Edit controls are generic input fields and have no associated text. You must associate edit controls with data items.
If you associate an edit control with a data item from the BV associated with the form, then the value entered by a user at runtime updates the table. If you associate an edit control with a data item not associated with the BV, then the value entered at runtime is for display only. However, you can make a field read-only for BV data items by enabling the Read Only property. You can also associate an edit control with a DD item with a user-defined code (UDC).
Edit controls have a Type Ahead feature. When a user enters a character in the field, the system searches a history list for a match. If a match exists, it appears in the field and is highlighted. This feature is particularly useful for data entry work because it can reduce the amount of typing required. A user can enable or disable Type Ahead editing in JD Edwards EnterpriseOne. Additionally, the Type Ahead capabilities of the browser (such as Internet Explorer) must be enabled as well. Type Ahead is disabled for double-byte languages and multiline edit controls.
As you add controls to the form, you can indicate how the runtime engine filters the incoming records from the database. For example, if the find/browse form has two controls on which you want to filter, the resulting SQL statement that you generate will have an AND
condition for each condition. For example, if you have Search Type and Alpha Description as the controls on the form, the filter criteria for Search Description should be >=
and the Search Type control should be =
. If a user types D and puts a V in the Search Type field, this is the resulting SQL statement:
SELECT * FROM F0101 WHERE (ABAT1 = V AND ABDC LIKE D%) ORDER BY ABAN8 ASC
You might also want to apply filters to edit controls when records need to fall between two values. In this case, you use a range filter. For example, in distribution, a status is assigned to each line of the order. One status is the current status and the other status is the next status. In this example, you filter records that are greater than or equal to the present status and less than or equal to the next status. You drop one value, filter the value, and then drop the next value.
A consideration when using the Required Field flag with edit fields is that, if the required field indicator should be displayed in the application, you must check the Required Field property for the edit field and then connect static text to it. Be sure to size the connected static text box appropriately to allow for the "required" indicator to be appended to the end of the text, and also to allow for translations. If you do not connect static text to the edit field, runtime does not display the required field indicator in the application.
To connect static text to the edit field, select the edit field and the label. Then select Edit, Reconnect. To disconnect the static text from the edit field, select them and then select Edit, Disconnect.
These events can fire on an edit control:
Control is Entered
Visual Assist Button Clicked
Post Visual Assistant Clicked
Control is Exited
Control is Exited/Changed-Inline
Control is Exited/Changed-Asynch
This section discusses how the runtime engine processes the edit control.
The control can acquire focus either through a user action, such as by pressing the Tab key or clicking it with the mouse, or through a system command. When the control acquires focus, runtime fires the Control is Entered event.
When the user leaves the control (such as by pressing the Tab key), the system validates the control and saves the value to memory. A number of events are fired during this process.
Data validation consists of ensuring that the value meets any established criteria for the DD item upon which it is based, including size, type, and so forth. Additionally, runtime compares the current value of the control with the value of the control before it started the exit process. If the value has changed, then it fires two additional events.
This section discusses system functions for edit controls, which reside in the Control folder.
Use this system function to set the background color for the edit control.
Parameters
Input, required. The FC to affect.
Input, required. The color to which to set the control. Double-click <Pick Color> to select a specific color. Otherwise, set the parameter to <Pick Color> or the default color (<Reset Color>).
Use this system function to set the font and font characteristics (for example, typeface and color) for an edit control.
Parameters
Input, required. The FC to affect.
Input, required. The font and font characteristics to apply. Double-click <Pick Font> to select specific settings. Otherwise, set the parameter to <Pick Font> or the system default settings (<Reset Font>).
This chapter contains the following topics:
A grid control is similar to a spreadsheet. Use grids to display data and to enable users to enter information. Unlike an edit control, grid controls can show multiple data items and multiple table rows at once. You also can use grid controls to enable users to edit table records. In end-user documentation, grid controls are referred to as detail areas.
A grid can either be a browse grid or an update grid. You can use a browse grid for viewing only, and you cannot select individual cells. The find/browse, search & select, power browse, and portlet browse forms have browse grids, as do browse subforms.
You can use an update grid to add, delete, or update records. Cells in an update grid can be selected individually. The header detail, headerless detail, power edit, and portlet edit forms have update grids, as do update subforms.
Grid controls of both types contain columns. The columns are specified at design time and are one of these types:
Database column or
Data dictionary (DD) column.
A database column is associated with an item in the business view (BV) and through that connection to a DD item. Database columns represent a field in a database record.
Although only one type of column is referred to as a DD column, both types have a connection to a specific DD item. The difference is that a database column has the additional connection to a BV field. A grid column is affected by the properties of the associated dictionary item. For example, if a grid column is associated with a dictionary item of type string with a length of 30, that grid column will not permit more than 30 characters to be typed into the cell.
Grid controls can also have a query-by-example (QBE) line. The QBE columns have a one-to-one correspondence with the grid columns. You use a QBE value to change the selection criteria of a database fetch. Only database columns enable entry in the QBE columns because the purpose of the QBE is to affect the selection and only database columns are in the BV. A QBE column can have one of these comparison types:
Equal.
Not equal.
Less than.
Less than or equal to.
Greater than.
Greater than or equal to.
The comparison type is equal unless you specify otherwise. You can specify the comparison type in the QBE column or by using system functions. You can use wildcards (* or %) for an inexact search on a string field.
Grid values can be retrieved on a cell-by-cell basis or on a row-by-row basis. Internal storage for the grid columns exists in the runtime engine. The way the grid column value is stored is based on the type of the associated dictionary item (for example, math numeric, string, character), and it is distinct from the screen representation of the value. Only one row of data can be acted upon at any given time. Each event executes in the context of a specific row.
Grid columns can have a heading row and might also have a QBE row to facilitate user searches. Additionally, you can specify rows or columns to display information that you acquire or calculate during runtime. Typically, the rest of the rows contain data. Generally, this data comes from database tables.
Usually, when you make the grid control, you place data items in the grid. The data items can come from the BV attached to the form, or they can be based on DD items. Either way, each data item becomes a column. Just as the grid control itself has a variety of property settings, you can set property values for each column in the grid as well.
You have a great deal of control, both at design time and at runtime, over how the grid appears, what it displays, and how it functions.
This section discusses how to:
Design the grid.
Add columns to the grid control.
Display grid data as icons.
Set property values for the grid control.
Show multiple currencies per column.
This task outlines the overall process for creating a grid.
To design the grid:
Create a form.
Find/Browse, header detail, headerless detail, and search & select forms have a grid control on them automatically.
Power edit, power browse, reusable and embedded edit subforms, reusable and embedded browse subforms, edit portlet, and browse portlet forms will accept a grid control.
On the form level, attach a BV for the engine to use to populate the grid or use values assigned in ER and system functions to insert grid rows.
Drop a grid control onto the form.
Configure the control.
If you are working with a header detail form, you can attach a different BV to the control.
Add columns to the control.
Configure each column.
Add logic.
To add columns to a grid control:
Perform one of these tasks:
To add a data item to the grid from the BV associated with the form, double-click a data item in the Business View Columns Browser.
To add a data item to the grid that is not in the BV associated with the form, search for a data item in the Data Dictionary Browser, and then double-click it.
Each time you double-click an item, Form Design Aid (FDA) adds it as a column to the grid control.
Repeat step one until you have added all of the columns you need.
Double-click the grid control.
On Grid Properties, click the Columns tab and arrange the column order by selecting a column and then using the Up and Down buttons to shift its position in the list.
Click the Sort Order tab and set the order in which the system will sort returned records by performing these steps:
Select a data item in the Unsorted Columns list and click the right arrow. Repeat for each data item on which you want to sort.
The data item moves to the Sorted Columns list.
To toggle between displaying by ascending and descending order, click the data item in the Sorted Columns list.
The letter A next to the data item indicates that the system will display records in ascending order. The letter D next to the data item indicates that the system will display records in descending order.
Arrange the column sort order by choosing a column in the Sorted Columns list and then using the Up and Down buttons to shift its position in the list.
You can display grid cell data as icons to provide quicker, more meaningful visual feedback on certain types of data, such as status flags or other data where the internal value of a flag is not directly meaningful to a user. The ability to display grid data as icons enables you to associate values or ranges of values with an icon image, and then display that image in a grid, instead of the underlying data value.
You can optionally make icons clickable so that a behavior is associated with them. You can also optionally create tooltip popups to display supplementary information about the data. These tooltips are displayed when the user hovers the mouse pointer over the icon image.
An icon can have several states. It can be clickable or non-clickable, and it can be enabled or disabled. It can also display a slightly different image when the mouse hovers over it. The appearance of the icon should be different in each case. This enables the user to understand quickly the current interactivity state of a grid cell.
Icons are therefore represented physically by a group of related graphic images, each of which corresponds to one of the different icon states. The naming convention enables these graphic images to be an interrelated set grouped under a single icon. The base or normal image represents the icon under normal, non-clickable conditions. Standard suffixes identify the other, related images for that same icon.
This table shows the icon naming convention:
State | Filename Suffix | Example |
---|---|---|
Normal (non-clickable) | None | status_ok.gif |
Clickable | _cl | status_ok_cl.gif |
Clickable – mouseover | _mo | status_ok_mo.gif |
Clickable – disabled | _di | status_ok_di.gif |
The graphic image types can be in gif, bmp, jpg and png formats. For each new icon you want to use, you must create four images (one for each state), and then store those images in your current H4A (or OH4A) installation, within the deployed webclient.war structure, in the WEB-INF/img/res/gridcolbmps directory.
To use an icon to represent an underlying data value or range of values in a column, you use a client-side NER. Client-side NER offers some key advantages when representing data values as icons:
Reusability. The NER can be used from any icon column. An example is that you use a NER to capture the decision process associated with each icon data item and then use the same NER in all columns displaying that same data item.
Consistency. The same type of data is represented with the same set of icons on multiple grids, over multiple applications.
Flexibility. When you need a one-off or non-standard icon representation, you can create special NERs. Alternately, you can use data structures to pass more information than the current value of that single data column to the icon decision-making process. This enables more flexible icon representation.
Displaying data as icons has the disadvantage of hiding detailed and possibly necessary information about the icon from the user.
Tooltips enable you to augment the icon with detailed information. When the user's mouse pointer hovers over an icon, the extended information about that grid cell is displayed. The information that displays is specific to the form and the grid column, but can include any or all of:
Icon-specific text for the currently displayed icon.
This text can, for example, provide short, explanatory context information to the user about why the icon is displayed, or its meaning when it is selected for display. This tooltip is labeled Show Icon Tootip in the dialog box.
DD Name for the column.
This tooltip is labeled Show DD Name Tooltip in the dialog box.
The underlying data value.
This tooltip is labeled Show Value Tooltip in the dialog box.
DD Alias for the column.
This tooltip is labeled Show DD Alias Tooltip in the dialog box.
Use these steps to display grid data as icons:
Identify data values or ranges of values that you want to represent as icons, and then decide which icons to use to represent them. Ensure that all required images for all icons are in the designated location.
Create the icon-setting (client-only) NER to define the value-to-icon relationships:
Define a data structure that enables enough information to be passed to the NER to make all icon-setting decisions.
Use ER to define all necessary data value conditions.
Provide at least one call to the Set Grid Cell Icon system function. Each call to this system function enables you to select the icon's base (normal) image using the Image Picker and then to optionally set icon-specific tooltip text to apply under that specific data
Associate the NER function that sets the icon with the grid columns:
From the Column Properties dialog, set Display Style to Icon.
Update the ER for the Grid Cell Display Changed event by adding a call to the NER function that sets the icon.
Optionally, to make an icon clickable, select Clickable, and then update the ER for the Grid Column Clicked event
Use design-time settings in FDA to affect grid display (including showing multiple currencies per column), loading and processing, and how a user can enter data.
In the next subsections, it is assumed that you access all property values from the Property Browser in FDA.
You control grid appearance through a combination of property values that you set at design time and system function values you program to occur during runtime. Consider carefully the design-time settings you make because you may not be able to change them during runtime.
In addition to these property settings, use these system functions to affect grid appearance:
Set Grid Color
Set Grid Font
Set Grid Row Format
FDA provides some options to automate fetches. You can choose to load the grid based on the fetch logic when the user launches an application if the grid resides on a find/browse or headerless detail form. Use automatic loading options with care; in some cases, enabling these features can have a significantly negative impact on performance.
Especially in HTML environments, the page-at-a-time processing feature can enhance performance. This option enables you to populate the grid at the rate of one page at a time (the runtime engine only loads enough data to fill the grid, and then loads enough data to fill the grid again if the user clicks Next). Page-at-a-time processing is enabled by default, and the JD Edwards standard is to leave it enabled for all form types.
These properties affect how the user interacts with the grid.
When a column has the Support Multiple Currencies option enabled, the runtime engine assumes that each cell contains its own currency setting, and it formats each cell based on that cell's currency decimal setting. The runtime engine will not apply the currency settings to other grid rows, however. Therefore, the application needs to apply currency to each grid row individually. For example, the Amount column in row 1 might have a JPY currency type and be formatted with no decimals, while the Amount column in row 2 might have a USD currency type and be formatted with two decimals.
When a column has the Support Multiple Currencies option disabled, the runtime engine assumes that all of the cells in that column share the same currency setting, and so it applies that currency setting to other grid rows. Therefore, if you specify the currency setting in one row, the system overwrites the currency setting for all the other rows in the grid to match. This feature offers a performance benefit for those grids that contain only one currency because the application needs to specify a currency setting to one grid row only to affect the entire grid.
These currency rules apply:
When assigning values using conventions such as target = source, if the source object does not have any currency information (currency code = null or empty string), then the target object keeps its own currency.
When a GB object is cleared, the currency code and currency decimal information for that column is not cleared.
This section discusses the events that runtime fires while processing a grid control.
Depending on the type and mode of the form, runtime fires a variety of events in response to events regarding the grid control.
If you set up a custom fetch routine, you will want to make use of Get Custom Grid Row. To perform a custom fetch, attach logic to this event to fetch a single row. To indicate that there are more records to fetch, use the system function, Continue Custom Data Fetch (set it to True).
When runtime loads the grid control, it fires Add Last Entry Row to Grid when (and if) it adds an entry row as the last line in the grid.
The pattern for adding and updating records is to fire an event immediately before and after commit. Then, runtime fires another event after all the records have been processed. This is a list of applicable events:
Add Grid Rec to DB - Before
Add Grid Rec to DB - After
All Grid Recs Added to DB
Update Grid Rec to DB - Before
Update Grid Rec to DB - After
All Grid Recs Updated to DB
The pattern for deleting a row is similar except that runtime notifies you before and after the user action as well as the commits:
Delete Grid Rec Verify - Before
Delete Grid Rec Verify - After
Delete Grid Rec from DB - Before
Delete Grid Rec from DB - After
All Grid Recs Deleted from DB
Runtime notifies you of these user actions:
Column Selection Changed
This event applies to check box grid columns only. Column Selection Changed fires if the user selects or clears an editable check box grid cell. It does not fire if the grid cell is modified by event rules.
Grid Column Clicked
This event fires only if the grid column was configured as being clickable during design time.
Visual Assist Button Clicked and Post Visual Assist Clicked
If you want to override the default UDC form that appears automatically in response to clicking the Visual Assist, these are the events to which to add the logic.
Double Click on Row Header
Finally, runtime signals as the user works through the grid, starting when the grid gets focus and ending when the grid loses focus.
Set Focus on Grid
This event fires whether the user or runtime changes the focus.
Grid Cell Display Changed
This event applies only to icon grid columns (those for which the Display Style property has been set to Icon.) The event fires and the cell's display icon setting changes whenever the value of the data in the cell changes. The value can change by fetching data, adding or updating records in a grid, setting the output parameter of a system or business function call, or by explicit ER assignment. It can therefore fire at many different times during the grid population, navigation and editing life cycle, including within other grid events.
This event should reference a client-side NER, which internally calls the Set Grid Cell Icon system function, which sets the new icon or tooltip to display for the column. You should make only a simple, single reference to the system function. If you do not call this system function, the cell displays a blank image.
Column Selection Changed
This event fires only if the column is a check box column (that is, the column Display Style-Default or Checkbox property has been set to Checkbox).
Row is Entered
Row is Selected (Web Only)
Row is Exited
Row Exit & Changed - Inline
This event fires after Row is Exited if the grid is an update grid and the row has been changed since the last time the row was exited.
Row is Exited & Changed - Asynch
This event fires after Row Exit & Changed - Inline if the grid is losing focus, or if another row is entered. Row is Exited & Changed - Asynch is equivalent to validating the contents of the row. It is often used for the Edit Line master business function.
Kill Focus on Grid
This event fires whether the user or runtime changes the focus.
This section discusses runtime processing for the grid control.
This subsection discusses how runtime processes the grid control.
Typically, runtime processes the grid control at these points in a standard workflow:
On control initialization (triggered by form initialization).
On grid population request (triggered conditionally by control initialization, Next, and Previous, and always by Find).
On row or control exit.
This flowchart illustrates the initialization process for a grid control:
Grid population occurs immediately after the initialization process if the option, Automatically Find On Entry is selected. The grid population process is also triggered when the user clicks the Find button or if you apply logic on an event to do so. If the fetch requires access to the form's BV only, then you can probably enable the engine to perform the fetch on its own. However, if you want to access other tables, you must set up and execute a custom fetch programmatically.
This flowchart illustrates the steps that occur when find is initiated:
This flowchart illustrates how the system performs an engine fetch:
This flowchart illustrates how the system creates the SQL statement:
Custom fetches are executed based exclusively on the ER associated with the Get Custom Grid Row event. The ER provides instructions for how to load a row, and runtime repeats the ER until you tell it to stop or it reaches the end of a page if page-at-a-time processing is enabled. To tell the engine to continue looping or not, include a call to Continue Custom Fetch in the ER. Set Continue Custom Fetch to True to run another loop; set it to False to exit the custom fetch loop. (Not calling Continue Custom Fetch is equivalent to setting it to false.)
Grid controls are used to display information. In some instances, information display is all the grid does, in which case, no more grid control processing occurs.
Grids can also be used to enable users to delete, edit, and add data as well. To enable any of these functions, the grid (and therefore the form) must be in Add or Update mode (Update mode is the default mode; add mode occurs either when the user clicks Add or a fetch fails to retrieve data). Furthermore for add and update capabilities, the grid must not be disabled; that is, the Disable Input option was not set at design time. Finally, to add data, the user must have an entry row (that is, a blank row) as well. Runtime automatically adds an entry row to update grids in the add and update modes as long as the No Adds on Update Grid option was not set at design time.
When the user tabs out of an entry row, runtime performs these functions in this order:
Clear the GC hash table.
Fire Last Entry Row to Grid.
Get the value from the GC and copy the contents into a new entry row.
This three-part flowchart illustrates how runtime processes the act of writing data from the grid and committing the change to the database:
This flowchart illustrates 21 CFR 11 validation:
This two-part flowchart illustrates grid data validation:
This subsection discusses the effect of different runtime processing environments and modes: HTML (low or high interactivity) or Windows.
This table contrasts the differences:
Grid Type | Interactivity | Effect |
---|---|---|
Non-editable | Low | Refresh the entire form (including grid control) on Find, Next, and Previous. Display only one page of data in the grid. |
Non-editable | High | Refresh only the grid (not the entire form) on Find. Append additional rows and expand the page size on Next. The interface provides a vertical scroll bar. |
Non-editable | Windows | Refresh only the grid (not the entire form) on Find. |
Editable | Low | Display only one page of data in the grid. Post and refresh behavior depends on whether the Multi-Line Edit option is enabled:
|
Editable | High | Expand the page and add a vertical scroll bar to display all rows. Post asynchronously and refresh the grid control at every user action (row exit, column exit, and so forth). Add a new entry row upon user keying into and exiting any cell in the entry row. |
Editable | Windows | Expand the page and add a vertical scroll bar to display all rows. Process every user action immediately. Add a new entry row upon user keying into any cell in the entry row. |
For high interactive editable grid, post asynchronously for each cell change.
This section discusses the system functions you can use to affect how the grid control works during runtime.
Grid system functions enable you to manipulate the appearance of the grid and what goes into or comes out of it during runtime. In the latter case, the system applies the command either to the model version of the grid or to the display version. The model version of the grid contains all rows and columns, whereas the display version might have hidden rows or columns. This is an important distinction to make when you are performing actions based on row or column number. For example, assume a grid contains three rows, but the second one is hidden. If you insert a row beneath row number two in the model grid, the insert row becomes row three, and row three becomes row four. However, if you insert a row beneath row number two in the display grid, the row is inserted at the bottom of the grid, because the actual row number two is hidden.
Another distinction to make is whether the system function expects the first grid row number to be zero or one. All system function descriptions where these factors might be an issue include whether they affect the model or display version of the grid and whether they are zero- or one-based.
Some grid-related system functions enable you to alter the appearance of the grid. Use Set Grid Color to change the background color of a cell, row, column, or the entire control. Use Set Grid Font to change the type, style, size, effects, and color of the font in a cell, row, column, or the entire control. Alternatively you can use Set Grid Row Format to use HTML formatting commands to control the appearance of the grid, not only for color and font, but for other factors as well. Use Set Grid Cell Icon within a client-side, icon-setting NER to set an icon for a grid cell. Use Set Grid Cell Icon Visibility within normal form-based ER to control an icon's visibility dynamically.
To enable or prevent a user from customizing the grid, use Display Customize Grid Option.
Use Hide Grid Column and Show Grid Column to hide and display columns in the grid. Although a user cannot affect a hidden column, you can still work with and change values in it programmatically.
If the column is based on a DD item, use Set Data Dictionary Overrides to change the DD attributes of the column, or Set Data Dictionary Item to substitute another DD item altogether. To change the heading for the column, use Set Grid Column Heading.
Use Hide Grid Row and Show Grid Row to hide and display rows in the grid. As with columns, you can still affect hidden grid rows programmatically.
You can also control the bitmap icon that appears next to a given row with Set Grid Row Bitmap.
You can enable or prevent users from changing an existing cell, row, column, or the entire control. Use Enable Grid to enable user edits (assuming that the current mode permits such actions) and Disable Grid to prevent them. Although users cannot alter a disabled grid object, you can change it programmatically.
You can enable or prevent users from importing from Excel or from importing or exporting to Excel or Word with Display Import from Excel Option, Display Export to Excel Option, and Display Export to Word Option.
You can determine if a grid cell has been updated since the last check with Was Grid Cell Value Entered.
Use Get Max Grid Rows to count the number of rows currently loaded into the grid control. Use Get Selected Grid Row Count to count the number of rows in the current selection. The selected area need not consist of contiguous rows.
Use Set QBE Column Compare Style to set the comparison value (=, >, <=, and so forth) for a QBE column. Clear QBE Column clears an entry in a QBE column.
Runtime always fetches all records for all columns defined by the BV. However, you can impact how runtime builds the WHERE
and ORDER BY
clauses of the SQL SELECT
statement it executes to perform a fetch. (Use the various Hide system functions to filter what the user sees even more, if necessary.) Use Set Selection to input the specific values you want to use in the WHERE
clause. For example, assume that you want a list of accounts that are greater than 1000 USD. The SQL WHERE
statement might look like this (literal values are used to simplify the examples):
WHERE F0902.GBAN01 > 1000
The Set Selection statement that builds this code would look like this:
Set Selection(FC Grid, F0902, GBAN01, <Greater Than>, '1000', <None>)
That is: (grid control, table, alias, comparison type, comparison value, and/or).
The values you input with Set Selection persist until form close. Consequently, subsequent calls to Set Selection enable you to build a complex WHERE
clause. For example, say you wanted a list of document types for Foundation. In the F0005 table, system code and object type are in two different columns, so you must call Set Selection twice. First:
Set Selection(FC Grid, F0005, DRSY, <Equal To>, '00', <None>)
Then:
Set Selection(FC Grid, F0005, DRRT, <Equal To>, 'DT', <AND>)
By setting the and/or parameter to <AND>, the system knows to append the WHERE
clause with the values from a subsequent call to Set Selection with an