Release 3.00
Oct 12, 2002
|
Sybernet / Supplied Procedures Reference
Release 3.00 Oct 12, 2002 |
|
SP_HTML_FRAME provides a standard interface for creating applications and frames in Sybernet. The standard interface occurs because the NORTH frame (when defined) creates a standard heading that includes the name of your procedure, its version, and its title. Calling SP_HTML_FRAME also calls HTTP.SP_AUDIT to record each invocation of your procedure.
Frames are easy to build, but SP_HTML_FRAME allows you to create frames by name (such as NORTH, WEST, EAST, CENTER, SOUTH) rather than by position. Doing so makes each application that uses it not only have the same look and feel to the user, but also to the author (or authors) that have to maintain it.
The position of each frame (when defined) occupies predefined locations on your window; for example, the SOUTH frame occupies the bottom area of your window. Under some conditions you may find this unacceptable because you really want the SOUTH frame split. Although you can't override the default layout of frames, you can define sub-frames (as many as 5) in a frame that should provide the desired effect.
Sub-frames are like regular frames except their name is prepended by the frame name that they are enclosed by; for example, the SOUTH frame can contain both a SOUTH_WEST and SOUTH_EAST frame when defined. While these frames can be created dynamcially by creating frames when the frame is invoked, SP_HTML_FRAME can create frames at the same level. It's just a question of whether you want to refer to a frame as SOUTH.WEST or SOUTH_WEST in your JavaScript code.
When you use SP_HTML_FRAME to create non-dynamic sub-frames, the original frame (SOUTH for example) cannot be referenced with JavaScript.
All Sybernet applications should call SP_HTML_FRAME. SP_HTML_FRAME provides a consistent look and feel for your users and knows how to call HTTP.SP_AUDIT when it is invoked. Both are important.
SP_HTML_FRAME (and your application) are event driven. The event is the denoted by the value of BUTTON. It is called button because it usually means your user has clicked a submit button on your form screen, but this does not mean your application can't pass other values of BUTTON that are recognized.
When you call SP_HTML_FRAME to build your frames, BUTTON should be NULL. A null value for BUTTON tells SP_HTML_FRAME to create your frames and to call HTTP.SP_AUDIT. A non-null value for BUTTON instructs SP_HTML_FRAME to build the body corresponding to the frame name that was passed.
PROCEDURE HTTP.SP_HTML_FRAME
(
BUTTON IN VARCHAR2 := NULL
, PROCNAME IN VARCHAR2 := NULL
, VERSION IN VARCHAR2 := NULL
, TITLE IN VARCHAR2 := NULL
, NORTH IN VARCHAR2 := '70'
, CENTER IN VARCHAR2 := NULL
, WEST IN VARCHAR2 := NULL
, EAST IN VARCHAR2 := NULL
, SOUTH IN VARCHAR2 := NULL
, CENTER_NORTH IN VARCHAR2 := NULL
, CENTER_CENTER IN VARCHAR2 := NULL
, CENTER_WEST IN VARCHAR2 := NULL
, CENTER_EAST IN VARCHAR2 := NULL
, CENTER_SOUTH IN VARCHAR2 := NULL
, WEST_NORTH IN VARCHAR2 := NULL
, WEST_CENTER IN VARCHAR2 := NULL
, WEST_WEST IN VARCHAR2 := NULL
, WEST_EAST IN VARCHAR2 := NULL
, WEST_SOUTH IN VARCHAR2 := NULL
, EAST_NORTH IN VARCHAR2 := NULL
, EAST_CENTER IN VARCHAR2 := NULL
, EAST_WEST IN VARCHAR2 := NULL
, EAST_EAST IN VARCHAR2 := NULL
, EAST_SOUTH IN VARCHAR2 := NULL
, SOUTH_NORTH IN VARCHAR2 := NULL
, SOUTH_CENTER IN VARCHAR2 := NULL
, SOUTH_WEST IN VARCHAR2 := NULL
, SOUTH_EAST IN VARCHAR2 := NULL
, SOUTH_SOUTH IN VARCHAR2 := NULL
, onLoad IN VARCHAR2 := NULL
, BORDER IN VARCHAR2 := '1'
, BGCOLOR IN VARCHAR2 := '#660000'
, COLOR5 IN VARCHAR2 := '#FFFFCC'
, COLOR1 IN VARCHAR2 := '#FFE7C6'
, APPEARANCE IN VARCHAR2 := NULL
, WESTSCROLLING IN VARCHAR2 := 'AUTO'
, EASTSCROLLING IN VARCHAR2 := 'AUTO'
, CENTERSCROLLING IN VARCHAR2 := 'AUTO'
, SOUTHSCROLLING IN VARCHAR2 := 'AUTO'
, SP_HTML_FRAME IN VARCHAR2 := 'HTTP.SP_HTML_FRAME'
)
| Parameter | Description |
|---|---|
button |
When null causes SP_HTML_FRAME to build your frames. When not null causes SP_HTML_FRAME to draw the body for the frame corresponding to BUTTON. |
procname |
The fully qualfied name of your procedure. |
version |
The version of your application. |
title |
The title of your application. |
north |
The size of the NORTH frame. |
center |
The size of the CENTER frame. |
west |
The size of the WEST frame. |
east |
The size of the EAST frame. |
south |
The size of the SOUTH frame. |
center_north |
The size of the CENTER_NORTH frame if CENTER is defined. |
center_center |
The size of the CENTER_CENTER frame if CENTER is defined. |
center_west |
The size of the CENTER_WEST frame if CENTER is defined. |
center_east |
The size of the CENTER_EAST frame if CENTER is defined. |
center_south |
The size of the CENTER_SOUTH frame if CENTER is defined. |
west_north |
The size of the WEST_NORTH frame if WEST is defined. |
west_center |
The size of the WEST_CENTER frame if WEST is defined. |
west_west |
The size of the WEST_WEST frame if WEST is defined. |
west_east |
The size of the WEST_EAST frame if WEST is defined. |
west_south |
The size of the WEST_SOUTH frame if WEST is defined. |
east_north |
The size of the EAST_NORTH frame if EAST is defined. |
east_center |
The size of the EAST_CENTER frame if EAST is defined. |
east_west |
The size of the EAST_WEST frame if EAST is defined. |
east_east |
The size of the EAST_EAST frame if EAST is defined. |
east_south |
The size of the EAST_SOUTH frame if EAST is defined. |
south_north |
The size of the SOUTH_NORTH frame if SOUTH is defined. |
south_center |
The size of the SOUTH_CENTER frame if SOUTH is defined. |
south_west |
The size of the SOUTH_WEST frame if SOUTH is defined. |
south_east |
The size of the SOUTH_EAST frame if SOUTH is defined. |
south_south |
The size of the SOUTH_SOUTH frame if SOUTH is defined. |
onLoad |
The onLoad event that is passed to the NORTH frame when its body has loaded. |
border |
The border size around all frames. |
bgcolor |
The background color for the north frame. |
color5 |
The text color for the NORTH frame. |
color1 |
The text color for the NORTH frame. |
appearance |
Allows you to override the appearance attribute in the user's preferences. |
westscrolling |
The type of scrolling in the WEST frame. |
eastscrolling |
The type of scrolling in the EAST frame. |
centerscolling |
The type of scrolling in the CENTER frame. |
southcrolling |
The type of scrolling in the SOUTH frame. |
sp_html_frame |
The name of the procedure that builds the NORTH frame (default HTTP.SP_HTML_FRAME). |
Frame sizes are specified just as though you were creating this frame with HTML. It can be an absolute value or a percentage (100 or 10%).
All applications should allow the default NORTH frame to create a common look and feel. Sometimes this is not acceptable. In this situation you have two options: the NORTH frame can be set to NULL (which suppresses the creation of the NORTH frame) or you can override the name of the procedure that is called to create the NORTH frame. In the latter case, specify a valid (fully qualified) procedure name for the parameter SP_HTML_FRAME.
If you attempt to create sub-frames (for example, SOUTH_SOUTH), then you must also specify the frame that contains this sub-frame (for example, SOUTH). If you specify SOUTH_SOUTH and SOUTH_NORTH and do not specify SOUTH, no sub-frames are created.
When all master frames are defined they resemble the following layout:
Except for the NORTH frame (which is reserved for providing a common look and feel), you can declare sub-frames in any frame; for example, if I wanted to break the WEST frame into NORTH and SOUTH frames I would specify WEST, WEST_NORTH, and WEST_SOUTH. Doing so means I can no longer refer to the frame called WEST, but I can refer to WEST_NORTH and WEST_SOUTH in my application.
|
||||
If I wanted to refer to all three (WEST, WEST_NORTH and WEST_SOUTH), then it would be my
responsibility to create these sub-frames when my procedure is called to create the WEST
frame.
The following example illustrates how to call SP_HTML_FRAME to create the default NORTH frame and one frame for your application:
create or replace procedure example1 (button in varchar2)
is
begin
if (button is NULL) then
http.sp_html_frame
(
PROCNAME => 'EXAMPLE1'
, VERSION => 'Version 1.0'
, TITLE => 'Example 1'
, CENTER => '*'
) ;
return;
end if;
if (button = 'CENTER') then
http.writeln('<html>');
http.sp_html_preferences;
/*
** This is where I do work.
*/
http.writeln('</body>');
http.writeln('</html>');
return;
end if;
end;
To create the NORTH, WEST_NORTH, WEST_SOUTH, CENTER, EAST and SOUTH frames above, I would issue the following command:
http.sp_html_frame
(
PROCNAME => 'NOTHING'
, VERSION => 'Version 1.0'
, TITLE => 'Example 2'
, WEST => '33%'
, CENTER => '33%'
, EAST => '33%'
, SOUTH => '33%'
, WEST_NORTH => '50%'
, WEST_SOUTH => '50%'
) ;
Note that to specify WEST_NORTH and WEST_SOUTH, it is required that you also specify WEST.
Besides providing a common look and feel, the NORTH frame allows your application to perform JavaScript commands (perhaps to update input fields). This example creates a very simple form screen with one submit button which when clicked, uses the NORTH frame to display an alert. What is important is that the NORTH frame is redrawn (because something has to be redrawm) and your form screen is untouched.
create or replace procedure example3 (button in varchar2 := null)
is
begin
if (button is NULL) then
http.sp_html_frame
(
PROCNAME => 'EXAMPLE3'
, VERSION => 'Version 1.0'
, TITLE => 'Example 3'
, CENTER => '*'
) ;
return;
end if;
if (button = 'CENTER') then
http.writeln('<html>');
http.sp_html_preferences;
http.sp_html_form
(
NAME => 'FORM'
, TARGET=>'NORTH'
) ;
http.sp_html_input
(
type => 'HIDDEN'
, name => 'PROCEDURE'
, value => 'EXAMPLE3'
) ;
http.sp_html_input
(
type => 'SUBMIT'
, name => 'BUTTON'
, value => 'CLICK'
) ;
http.sp_html_form;
http.writeln('</body>');
http.writeln('</html>');
return;
end if;
if (button = 'CLICK') then
http.sp_html_frame
(
PROCNAME => 'EXAMPLE3'
, VERSION => 'Version 1.0'
, TITLE => 'Example 3'
, BUTTON => 'NORTH'
, onLoad => 'alert(''Thank you!'');'
) ;
return;
end if;
end;