Folder Options in Forms -Part2

Steps to create Folder Form

Step – 1 Create Folder Objects

• Reference Folder Object

Every folder form must contain the folder objects (such as the windows that are used for saving folders and changing prompts) included in the STANDARD_FOLDER object group. If this object group does not already exist in your form, reference it from APPSTAND. $AU_TOP/au/11.5.0/forms/US/APPSTAND.fmb

• Attached the Folder library

Every folder form must have the library APPFLDR.pll attached. The library file is $APPL_TOP/au/11.5.0/resource/APPFLDR.pll.

• Create the Content/Fixed Canvas

Create a content canvas, as you would for any window. Assign it the property class CANVAS, and assign it to the appropriate window. This canvas will hold the block scroll bar, the record indicator, and the folder_open and folder_title objects. This canvas will also hold any fields that would not be part of the folder block, such as required primary key fields.

Note: The name of the content canvas cannot be a substring of the name of the stacked canvas, as this will cause errors. For example, if the content canvas is called ORDERS, then the stacked canvas cannot be called ORDERS_FOLDER, but ORDERS_MAIN and ORDERS_FOLDER would be acceptable.

• Create the Stack Canvas

Create a stacked canvas; it holds prompt fields and displayed fields of the folder block, as well as the ORDER_BY# buttons.

Determine the appropriate Y position for the top of the folder block (this corresponds to the Y position for the top of the Folder Open button and the Folder Title). This value is referred to as Y_OFFSET, and is used to calculate the correct positions for items and canvasses. Typically Y_OFFSET should be .25 inches (that is, the top of the Folder Open button should be one character down from the top of the window) if the folder is the first block in the window.

Set the following properties for the stacked canvas:

Sequence : After the content canvas.

Property Class : CANVAS_STACKED
Displayed :True for the stacked canvas that will be shown
immediately upon entering the block; False for any
others.

Window : Same as for the content canvas.

View Height :.5” + (.25” * number of rows to be displayed)

Display X Pos : .5” (May be adjusted later)

Display Y pos : Y offset + .25

View Horiz
Scroll Bar : True


Step – 2 Create Folder block item
• Folder Block Item

Create a block to hold the fields of the folder, as you would any other block. The block scroll bar must be on the content canvas.

Suggestion: Although the scroll bar must be on the content canvas, most of the fields belong on the stacked canvas. If you are using the default block functionality, this can be achieved most easily by specifying the stacked canvas when creating the default block, and then changing the Scroll Bar Canvas property after the block has been created. One or more fields may be on the content canvas. These fields must always be the leftmost fields in the block, and will not respond to folder events (e.g. Move Right, Widen, Hide). Identify which, if any, fields will be on the content canvas, and move them there. Sequence these fields before any of the fields that will be on stacked canvasses.

Adjust the Display X Position for the stacked canvas view so that it is .1” to the right of the fields on the content canvas. For each item to be displayed as part of the folder, set the properties as follows:

TYPE: Text Item, Check box or List only.

X Position: Positioned at runtime

Y Position: If on content canvas, Y_OFFSET + .5”; otherwise, .25”

Width: Set at runtime

Canvas: The content or stacked canvas

Displayed: If part of the default display, True; otherwise False. Fields on the content canvas must be Displayed.

Note: The position and width of any field on the content canvas must be set accurately in the Designer. Also, the width of a check box should be set accurately to 0.3”. Check boxes with width 0.2” are acceptable, but do not save space since APPFLDR always allocates at least 0.3” for a check box.

• Folder Switcher Item

Create a switcher field for the block. In a combination block, this should be called ’SWITCHER’, and in any other folder block, it should be called ’FOLDER_SWITCHER’. It must be sequenced first in the block, and must use the SWITCHER property class. Place it on the content/fixed canvas. This field must not have a corresponding field in the prompt block. Attached the following trigger to the switcher item:-

Trigger: WHEN–NEW–ITEM–INSTANCE (Execution Style: Override)
On field SWITCHER:

app_folder_move_cursor(’1’);

• Create Current Record Indicator/Drilldown Record Indicator

Create a record indicator for the block. It must be called either CURRENT_RECORD_INDICATOR or DRILLDOWN_RECORD_INDICATOR. Do not include a corresponding field in the prompt block. The folder code disables certain functions automatically, but it is developer responsibility to write the code to manage the indicator. The WHEN–NEW–ITEM–INSTANCE trigger for CURRENT_RECORD_INDICATOR must call
app_folder_move_cursor(’1’).

Step – 3 Create Block Level Trigger
• Trigger: WHEN–NEW–BLOCK–INSTANCE (Execution Style: Before)

app_folder.event(’WHEN–NEW–BLOCK–INSTANCE’);

This trigger instantiates the folder block(if necessary), attempting to load the user’s default if on exists.

• Trigger: KEY-NEXT-ITEM

app_folder.event (’KEY–NEXT–ITEM’);

This trigger navigates to the next folder–sequenced item. Moves to next record if needed. Fire in Enter Query mode must be TRUE.

• Trigger: KEY-PREV-ITEM

app_folder.event(’KEY–PREV–ITEM’);

This trigger navigates to the prior folder–sequenced item. Moves to
prior record if needed. Fire in Enter Query mode must be TRUE.

• Trigger: PRE–BLOCK (Execution Style: Before)

app_folder.event(’PRE–BLOCK’);

This trigger establishes values for the folder block (when more than one is defined). It re-enables the folder menu upon entering the block.

• Trigger: POST–BLOCK (Execution Style: Before)

app_folder.event(’POST–BLOCK’);

This call disables the folder menu.

• Trigger: PRE–QUERY (Execution Style: Before)

app_folder.event(’PRE–QUERY’);

This call builds the order by clause for the query.

• Trigger: POS–QUERY (Execution Style: Before)

app_folder.event(’POST–QUERY’);

If the folder block is the master of a master–detail relationship, this trigger is required. It extracts the WHERE clause from SYSTEM.LAST_QUERY. Without this trigger, the detail block’s query can be extracted instead, which can lead to saving an invalid query with the folder.

• Trigger: User–named trigger FOLDER_RETURN_ACTION

<>

This trigger is fired each time the folder does certain operations that you may need to further process. ’global.folder_action’ contains the name of the process, and ’global.folder_field’ holds the name of the relevant field, if any, stripped of the block name. Specific callbacks may populate other global variables. The FOLDER_RETURN_ACTION trigger is optional. You should code it if you need to perform logic on any of the supported events.

Example:-
Following is code written in FOLDER_RETURN_ACTION trigger to allow update for ‘COL1’, ‘COL2’ and ‘COL3’ in the folder block:-

DECLARE
field_name VARCHAR2(30);
BEGIN
IF (:global.folder_action = ’SHOW–FIELD’) THEN
field_name:= NAME_IN(’global.folder_field’);
IF (field_name IN (’COL1’, ’COL2’, ’COL3’)) THEN
app_item_property.set_property (
’’||’.’||field_name,
ALTERABLE,
PROPERTY_ON);
END IF;
END IF;
END;

Step – 4 Create Prompt Block
Create a one record block to hold the fields that act as prompts for the folder block. For every item in the folder block that may be displayed, the prompt block must contain an item of the same name (except for the record indicator and the switcher). The initial settings of the prompts drive the layout of the Default Screen, including item width and tabbing sequence.

Typically one would name the prompt block _PROMPT, for example, ORDERS_PROMPT.

Each ’prompt’ field must have the following characteristics:

Property Class: DYNAMIC_PROMPT
Sequence: Must match the name of an item in the folder block. Sequence the first
set of fields to be displayed properly, starting at 1. This drives the
folder TAB order.
X Position: Positioned at runtime.
Y Position: .05.

Width: Dictates the width of the corresponding field. Make sure the width is adequate to display the text for the prompt fully. The width only needs to
account for English text – no translation expansion space is needed. Specifying the width as 0.1” causes it to adjust automatically based on the text it contains. For checkboxes, specify a width of 0.1”

Alignment: Usually Start, but follows alignment of data in corresponding folder
block field. Prompts for check boxes are always Center aligned.

Canvas: Stacked canvas.

Default: The text for the prompt. The translation tool translates this
automatically.

Displayed: True only for those fields you want displayed on the default screen;
otherwise, False.


Create Special Fields in Prompt Block

The following special fields must exist in the prompt block:-

Field: FOLDER_OPEN
PROPERTY CLASS: FOLDER_OPEN
X POSITION: 0.1”
Y POSITION: Y_OFFSET
CANVAS: content canvas

Field: FOLDER_TITLE
PROPERTY CLASS: DYNAMIC_TITLE
X POSITION: 0.4”
WIDTH: 4”
Y POSITION: Y_OFFSET +.05
CANVAS: content canvas

Field: FOLDER_DUMMY
PROPERTY CLASS: FOLDER_DUMMY
CANVAS: TOOLBAR

Field: ORDER_BY1,ORDER_BY2,ORDER_BY3
PROPERTY CLASS: FOLDER_ORDERBY
X POSITION: Set at runtime.
Y POSITION: For content canvas Y_OFFSET+.5+(.25*Rows)
For stack canvas .25+(.25*Rows)
CANVAS: If it’s a fixed field specify content canvas otherwise specify stack
canvas.

Step – 5 Code Form Level Trigger
The following form–level triggers must exist in order for a folder block to operate correctly:

• Trigger: WHEN–WINDOW–RESIZED:

IF :system.event_window IN (’<>’) THEN
app_folder.event(’WHEN–WINDOW–RESIZED’);
END IF;


• Trigger: KEY–CLRFRM:

app_folder.event(’KEY–CLRFRM’);

This call must be made anywhere a clear_form is issued. This cause the folder code to repaint the prompts and folder titles as if they were normal boilerplate.

• Trigger: WHEN–NEW–FORM–INSTANCE:

app_folder.define_folder_block('OBJECT NAME',
’’,
’’,
’’
’’,
[’’]);

Note: All parameters must be passed in UPPERCASE.

Example:
App_flolder.define_folder_block(‘PO_HEADER’
,’POHEADER’
,’POHEADER_PROMPT’
,’POHEADER_STK’
,POHEADER_MAIN’)

Choose the object name carefully; it must be unique across all products. Prefix it with the application short name, for example ’FND_ALERTS’. This object name identifies all folder definitions that users define and save for your folder, and it appears in the Administer Folders form as the Folder Set, so you should make the object name descriptive and readable.

’DISABLED FUNCTIONS’ can be a string combining any of the following. Specifying that a function is disabled prevents the user from performing it.

• OPEN
• TOOLS: Disables everything except OPEN. Note that if the profile FOLDERS:ALLOW_CUSTOMIZATION is ’N’, all tools are automatically disabled except Open.

• ORDERBY
• NEW
• SAVE: Disables Save and Save As.

• AUTOQUERY: Should be disabled for any detail block.

• PUBLIC
• DEFAULT
• DELETE
• SHOW
• HIDE
• MOVE
• WIDEN
• SHRINK
• AUTOSIZE
• PROMPT
• QUERY

Following example will disable ‘ORDER BY’ and ‘HIDE’ function in the folder form:

App_flolder.define_folder_block(‘PO_HEADER’
,’POHEADER’
,’POHEADER_PROMPT’
,’POHEADER_STK’
, POHEADER_MAIN’
,’ORDERBY HIDE’);

• User-named Trigger: FOLDER_ACTION

app_folder.event(:global.folder_action);

Do not insert additional code in this trigger. It is used to allow the menu and folder toolbar to communicate with the folder library that is attached to the form.

• User-named Trigger: FOLDER_RETURN_ACTION
NULL;

This trigger must exist at form–level to handle the case in which it has not been coded at block–level.



The FOLDER_RETURN_ACTION trigger supports the following events:

• SHOW_FIELD: The field in :global.folder_field has just been made visible. In updateable blocks, you may need to set some properties (such as Update Allowed, Required, etc.). Fields can become visible in Enter Query mode or normal mode. When a folder is opened, all fields currently displayed are hidden, even if they are in the new folder; thus this call is made for each field as it is redisplayed.

• ADD_FILED: Populates :global.folder_field. Called at the end of a user–initiated ’Show Field’ event that results in a field being displayed. The ’SHOW–FIELD’ callback is also triggered before this callback.

• HIDE_FIELD: Populates :global.folder_field. Called at the end of a user–initiated ’Hide Field’ event that results in a field being hidden.

• OPEN_FOLDER: Called at the end of an ’Open Folder’ event that results in a folder being loaded, but before the folder autoqueries. Populates global.folder_id.

• SET-WHERE-CLAUSE: Called during a ’Save Folder’ event, before setting the where clause that will be saved with the folder. Sets global.folder_action_allowed ’TRUE’. If the value of :global.folder_action_allowed is changed to anything but ‘TRUE’ by the FOLDER_RETURN_ACTION trigger, the WHERE clause saved with the folder is null.

• RESET-WHERE-CLAUSE: Called when the block WHERE clause is set back to the developer’s WHERE clause, because the user has selected Folder–>Reset query from the menu, or because the user has selected Folder–>New from the menu.

• SAVE-FOLDER: Called at the end of a ’Save Folder’ event, immediately before the Commit. Populates :global.folder_id.

• DELETE-FOLDER: Called during a ’Delete Folder’ event, immediately before the Commit. Populates :global.folder_id.

• CONFIRM-HIDE-FIELD: Called during a user–initiated ’Hide Field’ event, immediately after doing all other checks that the field can be cut (for example, it is not on the content or fixed canvas, it is not the only field on the stacked canvas, etc.). The variable ’global.folder_action_allowed’ is seeded with ’TRUE’. If this variable is changed to anything but ’TRUE’, the action is aborted and the user cannot hide the field. By default, if the user attempts to hide a required field, CONFIRM–HIDE-FIELD automatically prevents it, and users are allowed to hide non–required fields. You can override this behavior by changing the value of :global.folder_action_allowed to either ’TRUE’ (allow hiding) or ’FALSE’ (prevent hiding non–required fields) in the CONFIRM–HIDE–FIELD callback to the FOLDER_RETURN_ACTION trigger.

• AUTOQUERY: Called when a folder loads and automatically executes a query.

• CONFIRM-AUTOQUERY: Called when a folder that is designed to autoquery opens. ’GLOBAL.FOLDER_ACTION_ALLOWED’ is seeded with ’TRUE’. If this variable is changed to anything but ’TRUE’, the folder does not autoquery.

Example: Prevent Hiding a Field
Prevent the user from hiding the (non–required) ’PERIOD_NAME’ field:

Trigger: FOLDER_RETURN_ACTION (block–level):
IF(:global.folder_action = ’CONFIRM–HIDE–FIELD’) THEN
IF :global.folder_field = ’PERIOD_NAME’ THEN
:global.folder_action_allowed := ’FALSE’;
END IF;
END IF;