Oracle Forms FormsGraph Bean

(c)  Oracle Corporation November 2002
      BI Bean Graph version 2.7

Table of content

Description
How does the Bean work

Building a simple graph
HowTo master-detail
Forms implementation


Properties registered in the FormsGraph wrapper

Named colors
Known issues

Feedback

Description

Many Oracle Forms applications require a graphical representation of data stored in a Forms table or the database. So far Oracle Graphics has been used and still can be used to render interactive graphs in Oracle Forms applications. For each Forms user process, Oracle Graphics runs in its own separate process on the middle tier server. Many customers regard a separate process for embedded charts too much an overhead and look for an alternative solution to Oracle Graphics. 

Oracle Forms Services provide a runtime environment for Java beans that allows Forms developers to add missing or extra functionality built in Java to their Web applications. With the BI Bean Graph Oracle also provides a powerful set of Java classes that can be used to render many types of charts when run in a Java environment. Because the BI Bean became a strategic product at Oracle, Oracle products like OracleAS Reports, OracleAS Discoverer  Oracle JDeveloper and OracleAS Portal use the BI Bean Graph for their users to create graphical displays. 

To make the BI Bean Graph work in OracleAS Forms Services applications, all that is required is a Bean wrapper to work within the Forms Bean Container. The wrapper can be built dynamically using the Forms Bean Manager or manually coded using Java. The FormsGraph component is a generic wrapper built in Java that exposes a set of functionality and properties provided within the BI Bean Graph to Forms. Using this wrapper allows customers to use the BI Bean Graph within their own applications, not requiring any additional line of Java code. The demo application to this help file contains an example implementation of the generic BI Bean Graph wrapper.    

This sample works with Oracle Forms and was not tested with Forms6i.

How does the Bean work

The FormsGraph class instantiates the BI Bean Graph when added to the implementation class property of a  Bean Container in Forms. Data is added to the graph by Forms calls to SET_CUSTOM_PROPERTY('BeanContainer',1,ADD_ROWDATA.'<column_label,row_label,value>'). The data is passed in a character delimited string, where the default value defined as a delimiter is the comma. The delimiter can, and sometimes must, be changed  by a call to SET_CUSTOM_PROPERTY('BeanContainer',1, 'SET_DELIMITER','<new_char>'). 

 column label The name of the data group, like salary, sales or home runs hit. The column label by default shows in the graph's legend
 row label The row label, in combination with the column label, defines the the cell for the data value. For the salary column this can be employee names and for the sales column the name of departments 
 value The value is defined as double 00.00. Though the value is passed as a string it gets converted to double within the FormsGraph wrapper. 

 ADD_ROWDATA is a registered property in the FormsGraph wrapper class that creates one relational row with each calls. This property can be called many times and the data is stored within the FormsGraph instance until it is explicitly deleted by a call to SET_CUSTOM_PROPERTY('BeanContainer',1, 'CLEAR_GRAPH',''). Note that even if no argument is required when setting a property it still needs to be passed in Forms. 

The following code uses a cursor to create rows in the graph for two columns, 'Sales Total' and 'Sales Tax' 


...
OPEN PopulateGraphWithData; 
    FETCH PopulateGraphWithData INTO vName, nOrder, vDate, nTotalValue, nTaxValue;
    while (PopulateGraphWithData%FOUND) LOOP
        vData :='Sales Total '||vDelimiter||vDate||vDelimiter||nTotalValue;
        SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA',vData);
   &nbs p;    vData :='Sales Tax '||vDelimiter||vDate||vDelimiter||nTaxValue;
        SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA',vData);
        FETCH PopulateGraphWithData INTO vName, nOrder, vDate, nTotalValue, nTaxValue;
    END LOOP;
    SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_DATA_TO_GRAPH','');
CLOSE PopulateGraphWithData;
...

The graph is shown in Forms after a call to SET_CUSTOM_PROPERTY('BeanContainer',1,'ADD_DATA_TO_GRAPH',''). 

The FormsGraph bean can be used for static charts and for drill down charts alike. The call to ADD_DATAROW can optionally have a forth argument, representing the primary key used for the drill down or drill across operation. Drill actions are handled by the same bean but in another Forms Bean Container. This ensures that the control over the operation is left to the Forms application developer.

Building a simple graph

A simple graph is a graph that does not have any drill down or drill across actions. To create a graph in Forms, you first need to place a Bean Container to the Forms canvas hosting the graph. Open the bean container's property palette and edit the value of the 'Implementation class' property to oracle.forms.demos.bigraph. FormsGraph. This instantiates the FormsGraph bean. 

The graph is not shown until the registered property ADD_DATA_TO_GRAPH is called using the Forms SET_CUSTOM_PROPERTY() built-in. Calling this property before adding data to the graph internal data store leaves the graph empty. Use the ADD_ROWDATA property to pass data to the graph bean, again using the SET_CUSTOM_ PROPERTY() built-in. The data rendered in the BI Bean graph is queried by and passed from Forms, which means that the Forms developer always in control. The ADD_ROWDATA property can be called as many times as needed, even after calling the ADD_DATA_TO_GRAPH property. To create a new graph, exposing new data, the CLEAR_GRAPH  needs to be called before adding new data with additional calls to ADD_ROWDATA.  

Without expecting too much, this is all that needs to be done to create a simply bar graph based on custom data in Forms. All other bean properties exposed through the FormsGraph wrapper class can be used for additional graph modification.

HowTo master-detail

A master-detail behavior in the graph is made of two bean containers, each running an instance of oracle.forms.demos.bigraph.FormsGraph . The master-detail behavior is controlled by Forms, where Forms acts like a controller accessed from the master-bean by the WHEN-CUSTOM-ITEM-EVENT trigger attached to the bean container of the master graph in Forms. 

Assume two Bean Conatiners created on one Forms canvas, "block1.masterBeanCon" and "block1.detailBeanCon". The block1.masterBeanCon component has an attached WHEN-CUSTOM-ITEM-EVENT trigger listening to events raised by the graph bean.

Further assuming the block1.masterBeanCon to be that simple graph explained above, the following calls to SET_CUSTOM_PROPERTY() must be performed to have the bean returning a value to the Bean container

SET_CUSTOM_PROPERTY(' block1.masterBeanCon',1,'MOUSEACTION',true);

SET_CUSTOM_PROPERTY('block1.masterBeanCon',1,'RETURN_VALUES_ON_CLICK','PRIMARY_KEY');

For the bean to return the primary key for a graph component that the user clicked on, a fourth argument must be passed when calling the ADD_ROWDATA property. 

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Sales,25000');

renders a row that does not have a primary key. Simply add the primary key as a fourth argument to be used in master-detail beh aviors.

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Sales,25000,12');

If a user clicks onto the bar that represents the sales value 25000 for Europe, then the bean returns the primary key 12, raising a WHEN-CUSTOM-ITEM-EVENT trigger attached to the bean container. The code in the WHEN-CUSTOM-ITEM-EVENT trigger looks like

DECLARE

    eventName varchar2(30) := :system.custom_item_event;
    tempString varchar2(100);
    eventValues ParamList;
    eventValueType number;


BEGIN

    IF (eventName='GRAPH_ACTION') THEN
        eventValues := get_parameter_list(:system.custom_item_event_parameters);
        get_parameter_attr(eventValues,'GRAPH_INFO',eventValueType, tempString);
        -- clear data stored and shown in block1.detailBeanCon 

        FORMSGRAPHSAMPLE.clearData('block1.detailBeanCon');
        -- call a procedure that populates the detail graph, by repeated calls to 
        -- ADD_ROWDATA and one to
ADD_DATA_TO_GRAPH
        FORMSGRAPHSAMPLE.populateDetailGraphData('
block1.detailBeanCon',tempString,',');
    ELSE
        null;
    END IF;
END;


You can debug the graph bean independently for both bean containers. You can provide a debugging prefix to distinguish the messages written to the Java panel. E.g. to have all messages of the master bean pre-fixed with "block1.master bean:"

set_custom_property('block1.masterBeanCon',1,'SET_DEBUG_PREFIX','block1.master bean:'); 

This creates a simple master-detail behavior controlled by Forms.

Forms Implementation

  1. Open a Forms canvas and add a Forms Bean container to it
  2. Open the Bean container property palette and add oracle.forms.demos.bigraph.FormsGraph to the implementation class property field
  3. Set the bean properties exposed by the FormsGraph wrapper using the SET_CUSTOM_PROPERTY() built-in

Deployment

  1. Add the FormsGraph.jar file to the application definition in the formsweb.cfg file. The FormsGraph.jar file contains all BI Bean Graph classes and the FormsGraph wrapper class used. The file size is 1.6 MB and is permanently stored on the client after a first time download. 
  2. Copy the FormsGraph.jar file into the forms/java directory of the Forms Services installation
  3. Set imagebase=codebase if you want to use graph icons, provided in the FormsGraph.jar file, within your application 

Example formsweb.cfg entry

[BIGraph]
...
imagebase=codebase
...
archive_jini=frmall_jinit.jar,/formsdemo/jars/FormsGraph.jar,/formsdemo/jars/demo.jar
...

Properties registered in the FormsGraph wrapper

Properties are named identifiers that map to a specific functionality in the BI Bean Graph component. Properties are called by the SET_CUSTOM_PROPERTY() built-in and may or may not require additional arguments to be passed.

ADD_DATA_TO_GRAPH

The ADD_DATA_TO_GRAPH property applies the data stored in the FormsGraph internal datastore to the actual BI Graph instance managed by a BeanContainer in Forms. 

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_DATA_TO_GRAPH','');

Call this property to update the graphical representation whenever changes have been made to the represented data stored in the bean data store.

ADD_ROWDATA

Data rows can be added to the FormsGraph internal data store before and after calling ADD_DATA_TO_GRAPH. However, if no data is available when the ADD_DATA_TO_GRAPH property is set, then no graph will show. The ADD_ROWDATA property appends a new row to the datastore. The syntax of the argument passed with ADD_ROWDATA is determined by the BI Bean Graph relational API and expects the column label to be passed as a first argument, the row label as a second and the cell value as a third. If the Graph is to be used as a master in a master/detail relation, then optional a forth argument can be passed representing the primary key.

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Sales,25000');

or

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Sales,25000,12');

In both cases the Series, or column name, is 'Europe', while the data, or row label, is 'Sales'. The first example shows a row with no primary key added, while the second example contains the primary key. The comma is the default delimiter for the number of arguments passed. The delimiter can be changed using the SET_DELIMITER property, which you may find helpful in situations where e.g. labels contain commas. To create three rows (Sales,Taxes,Savings) with 2 columns (Europe,USA) and to show them in the graph, in Forms you call

  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Sales,25000');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','USA,Sales,70000');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Taxes,2500');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','USA,Taxes,2500');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','Europe,Savings,22500');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_ROWDATA','USA,Savings,67500');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'ADD_DATA_TO_GRAPH','');

The row labels show on the X-axis for vertically presented graphs and on the Y-axis for horizontal graph types. The Column labels show in the graph legend.

ALIGN_TITLE_TEXT

The ALIGN_TITLE_TEXT property is used to align the text of either the title, the subtitle or the footer. Allowed alignment attributes are "LEFT", "RIGHT" and "CENTER". One property call can be used to set multiple title alignments. The following argument syntax sets the alignment of the title, the subtitle and finally the footer: 'title=CENTER,subtitle=LEFT,footnote=CENTER'. The default delimiter is a comma (',') if not set other using the SET_DELIMITER property. Values can be omitted from right to left, which means that the footnote attribute can be omitted when setting the title and subtitle alignment. The subtitle attribute can be omitted if the footnote as well is omitted.

 set_custom_property('block1.BeanArea1',1,'ALIGN_TITLE_TEXT','title=CENTER,subtitle=LEFT');

The example above aligns the title to the center of the graph and the subtitle to the left.

CLEAR_GRAPH

Clears the graph data store. This must be done before adding new data to the datastore.If using ADD_ROWDATA without before calling CLEAR_DATA, then the new row is appended to the list of existing rows. In a drilldown scenario CLEAR_GRAPH makes sure that the detail graph shows the right data. CLEAR_GRAPH does not require an additional argument to be passed.

set_custom_property('block1.BeanArea1',1,'CLEAR_GRAPH','');

DEBUG

The debug property turns a verbose debugging on or off. The debug information is written to the Java console of the Jinitiator panel. Debugging can be enabled and disabled to any time, thus allowing a close look to the problem area. 

 set_custom_property('block1.BeanArea1',1,'DEBUG','TRUE');

Arguments used with the DEBUG property are either 'TRUE', to turn debugging on, or 'FALSE', to turn it off. By default no debug message is written to the panel.

ENABLE_TOOLTIPS

Hovering the mouse over a graph component like a bar in a bar graph, shows a configurable set of information in form of tooltips. Tooltips are not shown by default. Allowed arguments when calling ENABLE_TOOLTIPS from a Forms SET_CUSTOM_PROPERTY() built-in are

"ALL" - show detail information (default)
"LABELS" - labels only
"VALUES" - show dat avalues only
"NONE" - show no tooltips

Examples

set_custom_property('block1.BeanArea1',1,'ENABLE_TOOLTIPS','ALL');     
set_custom_property('block1.BeanArea1',1,'ENABLE_TOOLTIPS','VALUES');  
set_custom_property('block1.BeanArea1',1,'ENABLE_TOOLTIPS','NONE');   
.

EXPLODE_PIESLICE

This property is registered to be used with pie graphs. By specifying a slice in a pie by its number and an integer value for the distance, the slice gets exploded from the rest of the pie. Note that the slice is not returned automatically but must be returned manually. By this it is possible to explode more than one slice in a graph.

set_custom_property('block1.BeanArea1',1,'EXPLODE_PIESLICE','2,60');

The current number of slices shown in a graph can be retrieved by a call to the COLUMN_COUNT registered property. This returns the number of slices in a pie within a WHEN-CUSTOM-EVENT trigger attached to the Bean area.

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'COLUMNCOUNT','');

The slices of a pie are numbered starting with 0. The following WHEN-CUSTOM-EVENT code retrives the number of columns shown and populates a list in Forms for the user to select a slice number from.
...
IF (eventName='RETURNED_COLUMN_NUMBER') THEN
    eventValues := get_parameter_list(:system.custom_item_event_parameters);
    get_parameter_attr(eventValues,'GRAPH_INFO',eventValueType, tempString);
    /** 
    * populate list CONTROL.SLICE_NUMBER
    */
    col:=to_number(tempString);

    rg := Create_Group('ColumnCount');
    /* Add two number columns to the record group */ 
    gc1 := Add_Group_Column(rg, 'slice', CHAR_COLUMN,30); 
    gc2 := Add_Group_Column(rg, 'slice_no', CHAR_COLUMN,30);
        FOR i IN 1..col LOOP 
            Add_Group_Row(rg,i); 
            Set_Group_Char_Cell(gc1, i,to_char(i)); 
            -- columns in the pie Graph start counting by 0, so the first slice is 0 (i-1)
            Set_Group_Char_Cell(gc2, i,to_char(i-1)); 
        END LOOP; 
    populate_list('bloxk1.list1',rg);
    delete_group(rg);
    -- set initial value
    :CONTROL.SLICE_NUMBER:=0;

ELSIF ...

FRAME_POS

Property registered to determine the xy position of the external graph window on the screen. The default position is 0:0.

set_custom_property('block1.BeanArea1',1,'FRAME_POS','100,200');

GET_DELIMITER

Property r egistered to retrieve the current delimiter string returned in a WHEN-CUSTOM-EVENT trigger attached to the Bean area.

set_custom_property('block1.BeanArea1',1,'GET_DELIMITER','');

The WHEN-CUSTOM-EVENT trigger code would look like

...
IF (eventName='CURRENT_DELIMITER') THEN
    eventValues := get_parameter_list(:system.custom_item_event_parameters);
    get_parameter_attr(eventValues,'DELIMITER_INFO',eventValueType, tempString);
   //handle delimiter stored in tempString
   ...

ELSIF ...

SHOW_GRAPH

This property shows the BI Bean Graph inside of the Bean container specified. The other option is to display the Graph in an external frame.

set_custom_property('block1.BeanArea1',1,'SHOW_GRAPH','');

This command actually renders the graph in the Forms application.

SHOW_GRAPH_IN_FRAME

Calling this property from Forms will show the graph in a separate frame. For the BI Bean Graph to initialize it is important that the Forms Bean Container used is visible on the Canvas and at least has a size of 1x1 pixel. You can hide this widget by setting its border  to 'None' and the background color to the color of the canvas, using the property palette of the Bean Area.

set_custom_property('BeanArea',1,'SHOW_GRAPH_IN_FRAME','');

GRAPHTYPE

The GRAPHTYPE property is registered to set the type of the graph from Forms. Note that some of th esupported graph types show the values in percent. However, the tooltips always show the value in absolute numbers. The following graph types are supported, where the name in uppercase is supplied as an argument with the call to GRAPHTYPE

  1. HORIZONTAL_BAR, bar graph with horizontal value axis
  2. VERTICAL_BAR,  bar graph with vertical value axis. This is defined as the default graph type.
  3. VERTICAL_BAR_2Y, bar graph with two vertical value axis 
  4. VERTICAL_STACKED_BAR, bar graph with vertical value axis. The columns are shown stacked
  5. HORIZONTAL_STACKED_BAR, bar graph with a horizontal value axis. The columns are shown stacked
  6. VERTICAL_PERCENT_BAR, bar graph with vertical value axis. The columns are shown as stacked values showing their value in percent 
  7. HORIZONTAL_PERCENT_BAR, bar graph with horizontal value axis. The columns are shown as stacked values showing their value in percent 
  8. VERTICAL_LINE_GRAPH, line graph with a vertical value axis
  9. HORIZONTAL_LINE_GRAPH, line graph with a horizontal value axis
  10. VERTICAL_LINE_SPLIT_GRAPH, line graph showing the second group )column) in its own diagram. If e.g. four groups are shown, then 1,3,4 display in the first diagram and 2 in its own diagram below
  11. RING_BAR_GRAPH, Also known as the 'donough' graph. Column values are shown in percent 
  12. MULTI_RING_GRAPH, showing one ring graph per row label. E.g. show salary and bonus for SMITH, salary and bonus for JONES ...
  13. MULTI_RING_PROPORTIONAL_GRAPH, same as MULTI_RING_GRAPH but showing the size of the graph proportional to its total value compared to the other
  14. VERTICAL_STACKED_LINE_GRAPH, line graph with a vertical value axis. A line is based on top of the values of its predecessor
  15. HORIZONTAL_STACKED_LINE_GRAPH, line graph with a horizontal value axis. A line is based on top of the values of its predecessor
  16. VERTICAL_AREA_GRAPH, are graph with vertical value axis
  17. VERTICAL_PERCENT_AREA_GRAPH, area graph with vertical value axis and column values shown in percent 
  18. VERTICAL_STACKED_AREA_GRAPH, area graph with verti cal value axis and column values shown absolute 
  19. PIE_GRAPH, pie graph with values shown in percent
  20. PIE_BAR_GRAPH, pie graph with a separate graph showing the detail values buildingthe graph total. Clicking on a graph slice changes the details shown
  21. MULTI_PIE_GRAPH, showing one pie graph per row label. E.g. show salary and bonus for SMITH, salary and bonus for JONES ...
  22. MULTI_PIE_PROPORTIONAL_GRAPH, same as MULTI_PIE_GRAPH but showing the size of the graph proportional to its total value compared to the other
  23. RADAR, shows graph as a radar line. This graph does not make sense with only one or two groups (columns) displayed per each row
  24. STOCK_HIGHLOW_GRAPH, shows the high and low values of each group (column) grouped by low values and high values
  25. 3D_BAR_GRAPH, bar graph with vertival value axis and strong 3D appearance
  26. 3D_AREA_GRAPH, area graph with vertical value axis and strong 3D appearance - series orientation
  27. 3D_AREA_GROUP_GRAPH, area graph with vertical value axis and strong 3D appearance - group orientation
  28. 3D_CUBE_GRAPH, vertical axis graph showing cubes representing group/series value data

Examples:

RING_BAR         ==>         set_custom_property('block1.BeanArea1',1,'GRAPHTYPE','RING_BAR_GRAPH');

PIE_BAR          ==>         set_custom_property('block1.BeanArea1',1,'GRAPHTYPE','PIE_BAR_GRAPH');

MULTI_PIE_GRAPH  ==>         set_custom_property('block1.BeanArea1',1,'GRAPHTYPE','MULTI_PIE_GRAPH');

HIDE_FRAME

Property called to hide the external graph frame.

set_custom_property('BeanArea',1,'HIDE_FRAME','');

HIDE_GRAPH

Property called to hide the graph, not showing in the Bean area container. This functionality is e.g. useful to hide the graph when no data was provided or as a result of a user action. Alternatively to hiding the graph when no data is shown, a customizable text string can be shown. Showing a string is useful e.g. in a master/detail scenario where not all master records have details.

set_custom_property('block1.BeanArea1',1,'HIDE_GRAPH','');

MODIFY_ROW_DATA

Property registered to change one column in a bar graph or one slice in a pie graph for a partial graph update. The row that needs an update is identified by its current column label, row label and value. The new value is passed as a forth argument

set_custom_property('block1.BeanArea1',1,'MODIFY_ROW_DATA','ColumnName,RowName,OldValue,NewValue');

The default delimiter, as shown in this example, is a comma, but can be chosen different calling the SET_DELIMITER property.

MOUSEACTION

Property registered to enable or disable mouse interactivity requiring Forms Server interaction. This property should be called to switch off mouse interactivity whenever no values shall be returned from the Graph to Forms (static graphs). Allowed arguments passed with the call to MOUSEACTION property are 'true' or 'false', where true is used to enable mouse actions while false disables it.

set_custom_property('block1.BeanArea1',1,'MOUSEACTION','false');

POSITION_LEGEND

Property registered to manually set the position of the legend shown in the graph. The default setting is to auto layout the legend. Use TOP, LEFT, RIGHT, BOTTOM or AUTO as an argument when calling set_custom_property()

set_custom_property('block1.BeanAr ea1',1,'POSITION_LEGEND','LEFT');

REMOVE_DATA

Property registered to remove a data row from the graph without refreshing the whole graph data storage. If the data row has an associated primary key, then this gets deleted as well. The row to delete is identified by the column label, the row label and the current value. The limitation is that the combination of these three values must be unique within the graph for this feature to work.

set_custom_property('block1.BeanArea1',1,'REMOVE_DATA','SALARY,SMITH,1700');

HIDE_FOOTER

Property that hides the graph footer text if displayed

set_custom_property('block1.BeanArea1',1,'HIDE_FOOTER','');

HIDE_SUBTITLE

Property that hides the graph subtitle text if displayed

set_custom_property('block1.BeanArea1',1,'HIDE_SUBTITLE',''

HIDE_TITLE

Property that hides the graph title text if displayed

set_custom_property('block1.BeanArea1',1,'HIDE_TITLE','');

HIDE_X_TITLE

Property that hides the graph title text defines for the x-axis if displayed

set_custom_property('block1.BeanArea1',1,'HIDE_X_TITLE','');

HIDE_Y_TITLE

Property that hides the graph title text defines for the x-axis if displayed

set_custom_property('block1.BeanArea1',1,'HIDE_Y_TITLE','');

RETURN_VALUES_ON_CLICK

Property registered to determine the type of data returned by the bean as a result of a user mouse click. Allowed arguments are 

 The primary is returned only if it was passed using the ADD_ROW_DATA property.

Forms Example:
--Forms example for a master/detail Graph. Code added to the WHEN-CUSTOM-EVENT Trigger on the PJC.MASTERGRAPH

set_custom_property('block1.BeanArea',1,'RETURN_VALUES_ON_CLICK','ALL');

 to retrieve the returned data value in Forms:

DECLARE
  eventName varchar2(30) := :system.custom_item_event;
  tempString varchar2(100);
  eventValues ParamList;
  eventValueType number;
BEGIN
IF (eventName='GRAPH_ACTION') THEN
   eventValues := get_parameter_list(:system.custom_item_event_parameters);
   get_parameter_attr(eventValues,'GRAPH_INFO',eventValueType, tempString);
   /* ... do something with value in tempString ... */
ELSE ...

SCROLLBAR

Property registered to display a scrollbar on the Graph if needed. Set value to true for enablig the scrollbar (default) or false to disable the scrollbar. The default is false as this feature is only required if too many data columns are shown that do not fit into the graph

set_custom_property('block1.BeanArea1',1,'SCROLLBAR','true');

COLUMNCOUNT

Property registered to retrieve the number of groups shown in the graph. A group in the relational world is a column in a row (e.g. Salary, Commission). The column count is returned in a when-custom-event trigger.

Forms Example:

set_custom_property('block1.BeanArea1',1,'COLUMNCOUNT','');

In a when-custom-item-event trigger

DECLARE
    eventName varchar2(30) := :system.custom_item_event;
    tempString varchar2(100);
BEGIN
  IF (eventName='RETURNED_COLUMN_NUMBER') THEN
      eventValues := get_parameter_list(:system.custom_item_event_parameters);
      get_parameter_attr(eventValues,'GRAPH_INFO',eventValueType, tempString);
  &nbs p;   /*... do something with the value stored in tempString ...*/
END;

SET_BACKGROUND

Property registered to set the graph's background color. The background color excludes the plot area which can be set by another property.The color must be passed as sRGB color in a comma separated string, with the specified red, green, and blue values in the range (0 - 255), e.g. '255,255,255' for white. Basic colors: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white can be passed in clear text. 

set_custom_property('block1.BeanArea1',1,'SET_BACKGROUND','120,234,123');

SET_DEBUG_PREFIX

The BI Bean Graph can have multiple instances in one Forms application, each in its own Forms Bean Container. If debugging is activated for all graphs then the debug information written to the Java console (the Jinitiator panel) does not tell which bean is writing it. To distinguish bean messages the SET_DEBUG_PREFIX property can be set to identify the output of a bean container.

set_custom_property('block1.BeanArea1',1,'SET_DEBUG_PREFIX','block1.BeanArea1'); 

The debug output generated by this bean now looks like

block1.BeanArea1 ==> ENABLE_TOOLTIPS: setting label tooltips
block1.BeanArea1 ==> RETURN VALUES: trying to set return value ....
block1.BeanArea1 ==> RETURN VALUES: ... to COLUMNLABEL

SET_DELIMITER

Property registered to change the default string delimiter, a comma, to another string. This is required, e.g. when setting a title string including a RGB encoded font color. The RGB encoded color requires a comma as the delimiter so tha this character cannot be used with the rest of the string. The following examples will make this more clear

SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'SET_DELIMITER','#');
SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'SET_TITLE','Hello World#120,255,120#bi#12');
SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'SET_DELIMITER',',');

In this example the delimiter is set to '#' before the graph title is set to "Hello World". The color for this string is encoded by 120,255,120 (a light green) using a comma as a delimiter. Finally the delimiter is set back to the default value.

 SET_DEPTH

SET_DEPTH is a property to create a 3D appearance of a graph by creating it's shadow. The depth is provided in pixel for the width and a degree between 0 and 180 for the orientation. Specify both values in one call, where the fist value determines the depth and the second the angle. The delimiter is the actual delimiter defined or ',' if choosing the default. To se a depth of 20 pixel and a radius of 10 degrees, set the attribute value of this Forms property to '20,10' (if the default delimiter id used). 

 set_custom_property('block1.BeanArea1',1,'SET_DEPTH','30,75');

SET_FOOTER_BACKGROUND

Property registered to set the background color of the graph footer text field. Normally the color is set to the same value then the background, but sometimes having this appear in a different color may make sense. The color must be passed as RGB color in a comma separated string, with the specified red, green, and blue values in the range (0 - 255), e.g. '255,255,255' for white. Basic colors: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white can be passed in clear text.

set_custom_property('block1.BeanArea1',1,'SET_FOOTER_BACKGROUND','120,255,120');

SET_FOOTER

property registered to set the graph Footer title, font, font style, font size and color. The following string format is expected 

"title string,color,font style,font size,font"

For example to set a Subtitle to "Hello World", the Font to TimesNewRoman, the font style to bold [b] and italic [i] and the color to red the string shows:

'Hello World,red,bi,10,TimesNewRoman'

The color can be specified as color name or as a sRGB value in a range from (0..255). Values can be omitted from right to left. Passing color values as RGB values may require switching the default delimiter as the comma must be used to set RGB values

Forms Example:

set_custom_property('block1.BeanArea1',1,'SET_FOOTER','Hello World,red,bi,10,TimesNewRoman');

or

set_custom_property('BeanArea',1,'SET_DELIMITER','#');

set_custom_property('BeanArea',1,'SET_FOOTER','Hello World#120,234,120#bi#10#TimesNewRoman');

set_custom_property('BeanArea',1,'SET_DELIMITER',',');

SET_FRAME_HEIGHT_WIDTH

Property registered to set the width and hight for the Graph external frame. The size is passed as a string representing two integer values. The syntax is height <delimiter>width. This property is defaulted to 200,300 and if set only has an effect on graphs running in a separate frame.

set_custom_property('block1.BeanArea1',1,'SET_FRAME_HEIGHT_WIDTH','200,300');

SET_LEGEND_BORDER

Property registered to set the border and background color of the legend shown in a graph. The color can be provided as a RGB encoded value e.g. 120,234,220 or as a named color e.g. red, orange or green. The first value passed is for the border, the second for the background. '120,200,220|223,223,100' If one or both setting should be transparent, then pass 'TRANSPARENT' as a color name. E.g. 'Transparent|123,334,120'. Note that in this case the default delimiter must be changed since the color coding requires ',' as a delimiter

Forms Example:

set_custom_property('block1.BeanArea1',1,'SET_LEGEND_BORDER','blue,yellow');

or

set_custom_property('block1.BeanArea1',1,'SET_DELIMITER','#');

set_custom_property('block1.BeanArea1',1,'SET_LEGEND_BORDER','120,120,120#220,23,120');

set_custom_property('block1.BeanArea1',1,'SET_DELIMITER',',');

or

set_custom_property('block1.BeanArea1',1,'SET_DELIMITER','#');

set_custom_property('block1.BeanArea1',1,'SET_LEGEND_BORDER','TRANSPARENT#220,23,120');

set_custom_property('block1.BeanArea1',1,'SET_DELIMITER',',');

SET_LINEGRAPH_MARKER

Property registered to enable / disable symbolic data value markers shown in line graphs. To enable this feature pass 'true' as an argument with the set_custom_property() call. Use 'false' to switch it off (default)

set_custom_property('block1.BeanArea1',1,'SET_LINEGRAPH_MARKER','true');

SET_NO_DATA_FOUND

Property registered to set the message shown when no data is available for the graph to render. This is the case whenever a master-detail relationship does not have detail data.

set_custom_property('block1.BeanArea1',1,'SET_NO_DATA_FOUND','Sorry - we are out of data today');

Note that the default delimiter needs to be changed if the message contains a comma.

SET_PLOT_AREA_COLOR

Property registered to set the color of the Plot Area. If not set then the area is chosen to be white. The color must be passed as RGB color in a comma separated string, with the specified red, green, and blue values in a range of (0 - 255), e.g. '255,255,255' for white. Basic colors: black, blue, cyan, darkGray, gray,green, lightGray, magenta, orange, pink, red, white can be passed in clear text.

set_custom_property('block1.BeanArea1',1,'SET_PLOT_AREA_COLOR','120,255,120');

SET_SCALED_LOGARITHMIC

Propert y registered to logarithmic scale the Y and X Axis. The following information must be passed as an argument when calling SET_SCALED_LOGARITHMIC.: 

The delimiter used must match the currently defined delimiter, which is by default ','.

Forms Example:

set_custom_property('BeanArea',1,'SET_SCALED_LOGARITHMIC','Y,true,2');

This creates a graphs with a logarithmic scaled Y axis with a base of 2. The base is provided as a double value.

set_custom_property('block1.BeanArea1',1,'SET_SCALED_LOGARITHMIC','X,true');

Note that there is always only one axis that shows the value of the graph. The ability to set the X axis to scale logarithmic in this bean is not used because the row label is of type String. This may change in a future version based on customer feedback.

SET_SUBTITLE

Property registered to set the graph Sub title, font, font style, font size and color. The following string format is expected: "title string,color,font style,font size,font". For example to set a Subtitle to "Hello World", the Font to TimesNewRoman, the font style to bold [b] and italic [i] and the color to red the string shows:

'Hello World,red,bi,10,TimesNewRoman'

The color can be specified as color name or as a sRGB value in a range from (0..255). Values can be omitted from right to left. Passing color values as RGB values may require switching the default delimiter as the comma must be used to set RGB values

set_custom_property('block1.BeanArea1',1,'SET_SUBTITLE','Hello World,red,bi,10,TimesNewRoman');

or

set_custom_property('block1.BeanArea1',1,'SET_DELIMITER','#');
set_custom_property('block1.BeanArea1',1,'SET_SUBTITLE','Hello World#120,234,120#bi#10#TimesNewRoman');
set_custom_property('block1.BeanArea1',1,'SET_DELIMITER',',');

SET_SUBTITLE_BACKGROUND

Property registered to set the background color of the subtitle title text field. Normally you want that color be set to the same value as the background, but sometimes having this appear in a different color makes sense. The color must be passed as RGB color in a comma separated string, with the specified red, green, and blue values in the range (0 - 255), e.g. '255,255,255' for white. Basic colors: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white can be passed in clear text.

Forms Example:

set_custom_property('block1.BeanArea1',1,'SET_SUBTITLE_BACKGROUND','120,255,220');

SET_TITLE

Property registered to set the graph title, title font, title font style, title font size and title color,  expecting the following string format title string,color,fontstyle,font size,fontname. For example to set a Subtitle to "Hello World", the Font to TimesNewRoman, the font style to bold [b] and italic [i] and the color to red the string shows: 'Hello World,red,bi,10,TimesNewRoman' The color can be specified as color name or as a sRGB value in a range from (0..255). Values can be omitted from right to left.

BEGIN 
  -- the color is defined with comma separated rgb values. The default delimiter
  -- must be changed temporarily. Alos set the font type to bold and italic (bi)
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'SET_DELIMITER','#');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'SET_TITLE','Hello World#120,234,120#bi#12');
  SET_CUSTOM_PROPERTY('block1.BeanArea1',1,'SET_DELIMITER',',');
END;

SET_TITLE_BACKGROUND

Property registered to set the background color of the title text field. Normally you want that color be set to the same value as the background, but sometimes having this appear in a different color may make sense. The color must be passed as RGB color in a comma separated string, with the specified red, green, and blue values in the range (0 - 255), e.g. '255,255,255' for white. Basic colors: black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white can be passed in clear text.

set_custom_property('BeanArea',1,'SET_TITLE_BACKGROUND','255,255,255');

SET_X_LABEL

Property registered to set the x-Axis title

set_custom_property('block1.BeanArea1',1,'SET_X_LABEL','Hello World X');

SET_Y_LABEL

Property registered to set the y-Axis title

set_custom_property('block1.BeanArea1',1,'SET_Y_LABEL','Hello World Y');

SHOW_COLUMNS_AS_ROWS

Forms property registered to show columns as rows and rows a columns in the Graph. If specifying the argument passed as "true" then the columns will show as series data and the rows as group data. To switch this presentation back to normal mode, call the same property again and pass "false" as an argument.

set_custom_property('block1.BeanArea1',1,'SHOW_COLUMNS_AS_ROWS','true');

SHOW_FRAME

Forms property registered to show the external graph frame. This feature is used when running the Graph in an external frame to the Forms window. It is to unhide a frame that previously was hidden.

set_custom_property('block1.BeanArea1',1,'SHOW_FRAME','');

SHOW_GRID

Property registered to show/hide the grid in a graph. The default value is set to true, use false to hide the grid in the graph

set_custom_property('block1.BeanArea1',1,'SHOW_GRID','false');

SHOW_LABELS

Forms property registered to show/hide the labels shown on the x and y axis. Labels are shown by default, to hide labels pass a value of false as an argument for  the Forms property. Use the following syntax: 'x=false,y1=true' to show labels for the y1 axis but to hide labels for the x axis. You can omit the outer right value if no change is needed e.g. 'x=true'. 

set_custom_property('block1.BeanArea1',1,'SHOW_LABELS','x=false,y=true');

SHOW_LEGEND

Forms property registered to show/hide the graph legend. Argument value are 'true' to show the legend (default) and 'false' to hide the legend

set_custom_property('block1.BeanArea1',1,'SHOW_LEGEND','true');

Named colors

The following colors can be used by their name and do not require RGB encoding

black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, yellow

Known issues

This implementation is treated as a reusable component and Java code is shipped with the Forms demo. The source code can be edited within all projects in JDeveloper that have the BI Bean Graph added. The following is a list of known issues

  1. The Forms Graph overlaps Alerts and lists in Forms. This behavior is caused by heavy weight components (awt classes) in a lightweight interface (Oracle ewt). This may get addressed in the future, but no promises are made to this time
  2. For interactive graphs to work, the combination of column label, row label and value must be unique. This is required for retrieving the primary key stored within a different Java object

Feedback

There exist no current plans to integrate the BI Graph Bean directly into Forms Developer. So for the time being and the near future this sample provides the only out-of-the-box solution to integrated graphical charts in Oracle Forms, beside of using Oracle Graphics. If you have feedback to share regarding this sample, the please use the Forms discussion forum on otn.oracle.com.