Sybernet / Supplied Procedures Reference
Release 3.00
Oct 07, 2006

HTTP.SP_HTML_FRAME

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.

SP_HTML_FRAME procedure

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.

Syntax

procedure sp_html_frame
(
    @BUTTON           IN  VARCHAR(92)    = NULL
,   @PROCNAME         IN  VARCHAR(92)    = NULL
,   @VERSION          IN  VARCHAR(60)    = NULL
,   @TITLE            IN  VARCHAR(92)    = NULL
,   @NORTH            IN  VARCHAR(10)    = '70'
,   @CENTER           IN  VARCHAR(10)    = NULL
,   @WEST             IN  VARCHAR(10)    = NULL
,   @EAST             IN  VARCHAR(10)    = NULL
,   @SOUTH            IN  VARCHAR(10)    = NULL

,   @CENTER_NORTH     IN  VARCHAR(10)    = NULL
,   @CENTER_CENTER    IN  VARCHAR(10)    = NULL
,   @CENTER_WEST      IN  VARCHAR(10)    = NULL
,   @CENTER_EAST      IN  VARCHAR(10)    = NULL
,   @CENTER_SOUTH     IN  VARCHAR(10)    = NULL

,   @WEST_NORTH       IN  VARCHAR(10)    = NULL
,   @WEST_CENTER      IN  VARCHAR(10)    = NULL
,   @WEST_WEST        IN  VARCHAR(10)    = NULL
,   @WEST_EAST        IN  VARCHAR(10)    = NULL
,   @WEST_SOUTH       IN  VARCHAR(10)    = NULL

,   @EAST_NORTH       IN  VARCHAR(10)    = NULL
,   @EAST_CENTER      IN  VARCHAR(10)    = NULL
,   @EAST_WEST        IN  VARCHAR(10)    = NULL
,   @EAST_EAST        IN  VARCHAR(10)    = NULL
,   @EAST_SOUTH       IN  VARCHAR(10)    = NULL

,   @SOUTH_NORTH      IN  VARCHAR(10)    = NULL
,   @SOUTH_CENTER     IN  VARCHAR(10)    = NULL
,   @SOUTH_WEST       IN  VARCHAR(10)    = NULL
,   @SOUTH_EAST       IN  VARCHAR(10)    = NULL
,   @SOUTH_SOUTH      IN  VARCHAR(10)    = NULL

,   @onLoad           IN  VARCHAR(255)   = NULL
,   @PASSTHROUGH      IN  VARCHAR(255)   = NULL
,   @BORDER           IN  VARCHAR(10)    = '1'
,   @BGCOLOR          IN  VARCHAR(20)    = '#660000'
,   @COLOR5           IN  VARCHAR(20)    = '#FFFFCC'
,   @COLOR1           IN  VARCHAR(20)    = '#FFE7C6'
,   @APPEARANCE       IN  VARCHAR(30)    = NULL
,   @WESTSCROLLING    IN  VARCHAR(6)     = 'AUTO'
,   @EASTSCROLLING    IN  VARCHAR(6)     = 'AUTO'
,   @CENTERSCROLLING  IN  VARCHAR(6)     = 'AUTO'
,   @SOUTHSCROLLING   IN  VARCHAR(6)     = 'AUTO'

,   @SP_HTML_FRAME    IN  VARCHAR(92)    = 'HTTP.SP_HTML_FRAME'
)

Parameters

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.
passthrough	An arbitray string that is passed to each frame.
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).

Explanation

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:

North
West	Center	East
South

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.

North

west_north

west_south

Center

East

South

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.

Example 1

The following example illustrates how to call SP_HTML_FRAME to create the default NORTH frame and one frame for your application:

create procedure example1 (@button in varchar(30))
as
begin
    if (@button is NULL) 
    begin
        exec http.dbo.sp_html_frame

            @PROCNAME     = 'EXAMPLE1'
        ,   @VERSION      = 'Version 1.0'
        ,   @TITLE        = 'Example 1'
        ,   @CENTER       = '*'
        return
    end

    if (@button = 'CENTER')
    begin
        select '<html>'
        exec http.dbo.sp_html_preferences
        /*
        ** This is where I do work.
        */
        select '</body>'
        select '</html>'
        return
    end
end

Example 2

To create the NORTH, WEST_NORTH, WEST_SOUTH, CENTER, EAST and SOUTH frames above, I would issue the following command:

    exec http.dbo.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.

Example 3

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 redrawn) and your form screen is untouched.

create procedure example3 (@button varchar(30) = null)
as
begin
    if (@button is NULL)
    begin
        exec http.dbo.sp_html_frame

            @PROCNAME     = 'EXAMPLE3'
        ,   @VERSION      = 'Version 1.0'
        ,   @TITLE        = 'Example 3'
        ,   @CENTER       = '*'
        return
    end

    if (@button = 'CENTER')
    begin
        select '<html>'
        exec http.dbo.sp_html_preferences
        exec http.dbo.sp_html_form

            @NAME = 'FORM'
        ,   @TARGET='NORTH'

        exec http.dbo.sp_html_input

            @TYPE = 'HIDDEN'
        ,   @NAME = 'PROCEDURE'
        ,   @VALUE = 'EXAMPLE3'

        exec http.dbo.sp_html_input

            @TYPE = 'SUBMIT'
        ,   @NAME = 'BUTTON'
        ,   @VALUE = 'CLICK'

        exec http.dbo.sp_html_form
        select '</body>'
        select '</html>'
        return
    end

    if (@button = 'CLICK')
    begin
        exec http.dbo.sp_html_frame

            @PROCNAME     = 'EXAMPLE3'
        ,   @VERSION      = 'Version 1.0'
        ,   @TITLE        = 'Example 3'
        ,   @BUTTON       = 'NORTH'
        ,   @onLoad       = 'alert(''Thank you!'');'
		
        return
    end
end