Implement Folders in a Custom Form in

Oracle Apps R11i

Folder Functionality in Oracle Applications

Folders allows for a user to include/exclude/resize/move/rename/order fields in a multi-row
block, such that it is more suitable for specific user needs, also being able to save and load those
definitions for later use. Many standard forms include this functionality and is a handy tool that
users can easily manipulate. As they are used to it, when new forms are developed, they expect
to have the tool also available. To our bad luck, the Developer's Guide says nothing about it, nor
have I found a white paper or official guide. What follows is an explanation on the steps we need
to follow to include Folders functionality in custom Forms.

Please have in mind the following, copied from the Oracle Applications Developer´s Guide:
APPFLDR contains all of the packages that enable folder blocks.
Warning: Oracle Applications does not support use of the
APPFLDR library for custom development.

Image 1

Acknowledgments

The information was gathered from Oracle Metalink, mainly from the post "Enabling Folder
Functionality in Custom Forms " on Oracle Forums by Subhash Chand. Some research was done
along Balbina Silva and Camerino Tesillos for a client's requirement. Validation of the steps was
done by Ivan Ortega aka "Chilpacoco". The use of a fixed section on folders was done on my
own, and is included in this article.

Feedback for specific versions of 11i would be great to have a list of what releases this works on.
By now, I've used it on 11.5.10.2 and 11.5.9, with the only difference being that on the way to
use the VERIFY functionality.
Corrections and enhancements on grammar/spelling/phrasing is welcomed as I'm not a native
english speaker.

Sample data used

A new form was created based on the HR_LOOKUPS view to validate the steps. It's up and
running and can be downloaded from here. All the images from this point were taken from the
process of building that form. Originally only Lookup Type, Lookup Code, Meaning and
Description are displayed, 10 rows at a time, with the last two fields on a stacked canvas. All of
this within a frame.

Image 2

Image 3

Set up the Form

Some setup is needed to enable folders and their proper functionality, it will be outlined in the
following sections.

Including Appropiate Libraries

In order to have the code needed for this functionality, we must include the following library
from $AU_TOP/resource (remember to remove directory when attaching):

• APPFLDR.pll

Image 4

If You are curious enough, and have time to do it, it's a good idea to browse trough the packages
included, as it can be also useful to learn on layout modification on run time.

Reference folder object group

To have access to objects required by folders, subclass the STANDARD_FOLDER object group
from the APPSTAND.fmb form, located in $AU_TOP/forms/US. Open the form, locate the
object group, drag and drop it to your form, choosing subclass in the dialog that shows up.
 Image 5

Create parameters

A parameter of type number with initial value 2 must be created. The name should be
<BLOCKNAME>_RECORD_COUNT, with BLOCKNAME being the name of the base block. For
the sample form, the HR_LOOKUPS_RECORD_COUNT parameter was created.

Write code in appropiate triggers

Akin to Flexfields functionality some code needs to be added to certain triggers, both at form and
block level.

WHEN-NEW-FORM-INSTANCE

To define the blocks and canvas to be used for the folder, this functionality must be enabled on
form launch, so we must include the following code in the WHEN-NEW-FORM-INSTANCE form
level trigger:
app_folder.def_folder_block(
object_name => 'Folder Test'
, folder_block_name => 'FOLDER_BLOCK'
, prompt_block_name => 'PROMPT_BLOCK'
, folder_canvas_name => 'STACKED_CANVAS'
, folder_window_name => 'WINDOW'
, dis_functions => 'UPPER, ENABLED, lower, disabled'
, tab_canvas => null
, fixed_canvas => 'STACKED_CANVAS_FIXED ) ;
app_folder.event( 'INSTANTIATE' ) ;
app_folder.event( 'VERIFY' ) ;

For the first procedure, the name of the parameters are self-explanatory. We should modify the
values passed with the names of the objects that we define in the following steps. Special
attention for the last two parameters as they are not included in the standard call on the trigger
that comes with the TEMPLATE.fmb form. tab_canvas could be used when the folder is to
be shown in such type of canvas, and as I haven't done such a thing it's not used in this article,
perhaps in a new one. The fixed_canvas parameter is what has to be used when a section on
the folder won't allow modification of it's layout, as is the case on the sample presented in this
post.

The second procedure call can be left out as no difference was found on using or commenting it
for the sample form. According to comments in the library, it's "Usually done when the block
must be painted correctly, but is not the first block on the window".

The third procedure should be left until the form works fine, as it provides validation and
informs what needs to be adjusted as we open the form for testing. Once the form is ready, we
should comment that line.

Note: For the verify functionality, on most recent versions of Oracle Applications, a message
will appear indicating that You must set the value for the GLOBAL.FOLDER_VERIFY_MODE
variable to TRUE via examine. You must do it to get the information on the adjustments needed
on the form for the folders to work. When using examine You will get a message indicating that
the value for GLOBAL.FOLDER_VERIFY_MODE can't be obtained, acknowledge the message,
put the value and select OK. This will generate a text file with the diagnostics on the Folders
implementation when opening the form.

Image 6
 Image 7

Image 8

KEY-CLRFRM

At form level:

app_folder.event( 'KEY-CLRFRM' ) ;

WHEN-WINDOW-RESIZED

At form level:

if :system.event_window = 'FOLDER_WINDOW' then

app_folder.event( 'WHEN-WINDOW-RESIZED' ) ;
end if ;

FOLDER_ACTION
At form level, uncomment the following line, and delete or comment the preceding message:

app_folder.event( :global.folder_action ) ;

KEY-PREV-ITEM

Defined at block level, referencing the previously defined parameter, only use the if when calling
app_folder.event( 'KEY-PREV-ITEM' ) ; may not work ok:

if (:parameter.<blockname>_record_count = 1) then
previous_item;
else
app_folder.event( 'KEY-PREV-ITEM' ) ;
end if;

KEY-NEXT-ITEM

Defined at block level, referencing the previously defined parameter, only use the if when calling
app_folder.event( 'KEY-NEXT-ITEM' ) ; may not work ok:

if ( :parameter.<blockname>_record_count = 1 ) then
next_item ;
else
app_folder.event( 'KEY-NEXT-ITEM' ) ;
end if;

Other triggers

At block level, add the following line

app_folder.event( 'EVENT' ) ;

To all of these triggers, changing 'EVENT' for the trigger name accordingly.

• WHEN-NEW-BLOCK-INSTANCE
• WHEN-NEW-RECORD-INSTANCE -- obsolete
• PRE-BLOCK
• POST-BLOCK
• PRE-QUERY
• KEY-ENTQRY
• KEY-EXEQRY
• POST-QUERY
• KEY-PRVREC
• KEY-NXTREC
 • KEY-CLRREC
• KEY-DELREC
• KEY-CLRBLK

Modifying the form

Provided that we have already created a multi-row block in our form and that is presented in a
canvas, this is what we must do to enable folders. We will use a stacked canvas to allow for
horizontal scrolling of every possible field to be show. We should left context fields on content
canvas, as standards suggest, later we'll see how to move those fields to a stacked canvas as
requiered for a fixed area on a folder.

Canvases

We'll need at least one stacked canvas for folder functionality to work. Optionally we can use
another stacked one to have a fixed section of the folder.

Content Canvas

This canvas won't need any modification.

Folder Canvas

A new stacked canvas with property class CANVAS_STACKED has to be created above the
content canvas. It's viewport position should be 0.2 X and 0.5 Y if all fields will be scrolled. If a
fixed section will be used, X position needs to be adjusted to allow for fixed fields to be
displayed. If the form has other blocks, Y position may need to be also adjusted.

Allow for enough vertical space to show the horizontal scrollbar and enable it on its properties.
Width only needs to be as big as the fields that we layout initially. At runtime, as fields are
dinamically shown and hidden, canvas size will be adequately adjusted, also considering space
for block vertical scrollbar if we use a fixed section.

Fixed Folder Canvas

If a fixed portion of a folder is required, a new stacked canvas will be created above content one
and the previous existing stacked canvas. Property class must be
CANVAS_STACK_FIXED_FIELDS. Define viewport size and position to the exact place that
the fixed fields will be placed. Canvas size must be that of the fields displayed plus 0.2 to allow
for the vertical scrollbar of the block to be included on it.

At runtime the canvas viewport will be resized to the maximum windows width, minus 0.2.
Items

Certain considerations are required for fields to control whether you will allow adding them to
the layout at rutime or not. Prompts have to be created as well as some control items.

Data Items

The items to show the information should be modified to the look and feel required by standards
as we normally do, that is, using the adequate item type, property class, format mask,
justification, etc. The prompt won't be taken from the Prompt property, so no modification is
needed yet, except for the Check Box item type items, as it has to be removed given that by
default it's displayed at item level and not above it.

We don't need to accommodate all the items in the stacked canvas, as it will be done by code at
runtime. We should only layout and arrange the order in the object navigator for the items that
will appear by default. All other fields can be at 0 X position.

Y position for all items that will be allowed to be added to the folder, must be at 0.25. Canvas
property for items will be the stacked one for those that will be scrolled, and the fixed stacked
one for the context fields. The displayed property has to be Yes for the items shown by default,
all other fields should use No.

On what fields can be added or not to the folder, that is controlled by the prompts, as we'll see
next.

Special case is the vertical scrollbar of the base block, as it has to be displayed at Y 0.25 on fixed
stacked canvas if used or in content canvas if not. For fixed canvas, it can be arranged in design
time at any X position as it will be rearranged on runtime to the right, after the movable fields. If
at runtime You get a message about an invalid position and the scrollbar seems to be out of
place, verity that the fixed canvas has enough space for the scrollbar and that will do it.

Prompt Items

As mentioned above, prompts are not taken from data items Prompt property, but from items that
will be defined explicitely.

A new block needs to be created to contain prompt items and some control items that we'll see
next. It has to be a control block, and for every item allowed to be displayed we'll need to create
a new Text Item item named equal to the data item. Property class must be
FOLDER_PROMPT_MULTIROW, the prompt removed and specified in the Initial Value property
instead. Y position must be 0 and the canvas the same of the base item, whether the stacked or
fixed stacked one. Also for the width it must be the one defined for the base item, as the prompt
will define the width of the field whenever it's shown. All prompts with displayed property Yes
at design time will be displayed by default and arranged according to the order they appear on
the object navigator.
Usually You just copy those on the base block, remove the database info, make them text items
and apply the property class.

Control items

Additionally we need to add control items for the folder, to allow for saving and loading
definitions of arranged layouts we create. These items must be created as follows:

Block Name Type Property Class Canvas Other

Base [FOLDER_]SWITCHER Checkbox SWITCHER Content *
Push
Prompt FOLDER_OPEN FOLDER_OPEN Content X: 0.2
Button
Prompt FOLDER_DUMMY Text Item FOLDER_DUMMY Toolbar
Display
Prompt FOLDER_TITLE DYNAMIC_TITLE Content X: 0.4
Item
Push
Prompt ORDER_BY1 FOLDER_ORDERBY Stacked
Button
Push
Prompt ORDER_BY2 FOLDER_ORDERBY Stacked
Button
Push
Prompt ORDER_BY3 FOLDER_ORDERBY Stacked
Button

Y Position for those displayed (FOLDER_OPEN and FOLDER_TITLE) depends on the layout. If
only a block is shown it will be 0.25.

* For [FOLDER_]SWITCHER, it may or not be required, review what the verify folder
functionality informs.

Compile and Execute form

Even if it may not be ready, we can now execute the form, so we get the feedback on what needs
to be adjusted. Folder functionality may be working, but not looking as good as we would have
expected. As mentioned on the coding of WNFI trigger, we have validation enabled, so we'll get
messages on specific modifications we need to apply for folders to work correctly and also the
arrangement of items can be seen. As the version I'm working on (11.5.10.2) requires the use of
the profile instead of the code, it generated a file, which is shown below.
 Image 9
Current form: XXAMX_HRLKFLDR

Checking prompt block HR_LOOKUPS_PROMPT...

APPLICATION_ID is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
HR_LOOKUPS_PROMPT.APPLICATION_ID must have a height of .25 inches.
HR_LOOKUPS_PROMPT.APPLICATION_ID must be on a canvas.
LAST_UPDATE_DATE is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
HR_LOOKUPS_PROMPT.LAST_UPDATE_DATE must have a height of .25 inches.
HR_LOOKUPS_PROMPT.LAST_UPDATE_DATE must be on a canvas.
LAST_UPDATED_BY is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
HR_LOOKUPS_PROMPT.LAST_UPDATED_BY must have a height of .25 inches.
HR_LOOKUPS_PROMPT.LAST_UPDATED_BY must be on a canvas.
ENABLED_FLAG is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
START_DATE_ACTIVE is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
END_DATE_ACTIVE is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
LAST_UPDATE_LOGIN is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
HR_LOOKUPS_PROMPT.LAST_UPDATE_LOGIN must have a height of .25 inches.
HR_LOOKUPS_PROMPT.LAST_UPDATE_LOGIN must be on a canvas.
CREATED_BY is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
HR_LOOKUPS_PROMPT.CREATED_BY must have a height of .25 inches.
HR_LOOKUPS_PROMPT.CREATED_BY must be on a canvas.
CREATION_DATE is in HR_LOOKUPS_PROMPT but on null canvas of HR_LOOKUPS.
HR_LOOKUPS_PROMPT.CREATION_DATE must have a height of .25 inches.
HR_LOOKUPS_PROMPT.CREATION_DATE must be on a canvas.
HR_LOOKUPS_PROMPT.LOOKUP_TYPE must be at Y=0.0 inches.
HR_LOOKUPS_PROMPT.LOOKUP_CODE must be at Y=0.0 inches.
HR_LOOKUPS_PROMPT.FOLDER_TITLE should be 4 inches wide.
HR_LOOKUPS_PROMPT.FOLDER_TITLE should be at X=0.4 inches.

Checking folder block HR_LOOKUPS...

HR_LOOKUPS.LOOKUP_TYPE must be at Y=.25 inches.
HR_LOOKUPS.LOOKUP_CODE must be at Y=.25 inches.

Checking for other specific items...

VERIFY: Completed for block HR_LOOKUPS.