HTTP.SP_HTML_BUTTON

This procedure creates a button suitable for submitting a form. Unlike regular submit buttons that you are already familiar with and which occur inside of the <FORM> tag, the buttons created by this procedure can be real images. They can also be regular submit buttons as well, and the reason for doing this will be explained shortly.

An image that acts like a submit button is accomplished by the JavaScript submit() and reset() functions. This means that a button or image built by sp_html_button must be able to refer to the form being submitted. This is the NAME that is given to sp_html_form when you define that form. NAME is passed as FORM when calling this procedure.

note If you attempt to call this procedure in the middle of a form (between the <FORM> and </FORM> tags), results will probably not be correct. This is especially true if you are creating "regular" submit buttons (as opposed to image buttons) or you are using the PROMPT option of this procedure. Either declare your buttons normally using sp_html_input or place these buttons outside of your form.

This procedure assumes that you are using FORMAT=SUPPRESSED. If you are not using this format, some of the buttons will not work or cause conversion errors in Sybase when your form is submitted.

All of the parameters are varchars. Only TYPE is required, but if that is the only parameter passed to this procedure, you are probably doing something wrong.

Syntax

Procedure SP_HTML_BUTTON
(
    FORM                          VARCHAR2
,   PROCNAME                      VARCHAR2
,   SEARCH                        VARCHAR2
,   TARGET                        VARCHAR2
,   TYPE                          VARCHAR2
,   NAME                          VARCHAR2
,   VALUE                         VARCHAR2
,   ALERT                         VARCHAR2
,   CONFIRM                       VARCHAR2
,   ONCLICK                       VARCHAR2
,   ONMOUSEOVER                   VARCHAR2
,   IMAGE                         VARCHAR2
,   GALLERY                       VARCHAR2
,   STATUS                        VARCHAR2
,   BORDER                        VARCHAR2
,   PROMPT                        VARCHAR2
)   ;

Parameters

Parameter	Description
form	FORM is the name of the form that is to be submitted when this image or button is submitted. FORM is the value of NAME that was passed to sp_html_form, but you will need to qualify this name if your form is in another window or frame.
procname	PROCNAME represents the name of the stored procedure that you want to execute when this button or image is clicked. Normally, PROCNAME is NULL because you want to submit a form and not execute a procedure, and the form that is submitted has already defined the procedure name. It's not only redundant to specify PROCNAME when you don't mean to, but also wrong and the effect will not be what you desire! Use PROCNAME only when you don't want to submit a form, but instead want to execute a procedure; for example, a button that points to the main menu page would be a good candidate for this option.
search	SEARCH represents the parameters to PROCNAME. sp_html_button will automatically URL Encode this string so you no longer have to worry about special characters when invoking a procedure. Be aware that if you are passing multiple parameters to a procedure that the entire length of this string does not exceed 255 characters. SEARCH corresponds to the Search argument in a URL request.
target	TARGET optionally specifies the windowName to be used for output when this image or button is clicked. Normally, this is not required since the form being submitted is already armed with this information (even if it were not explicitly specified). A button that points to the main menu page when frames are being used would be a good candidate. In this case, TARGET would be specified as "_parent" so that the page invoked is allowed to use the entire screen.
type	TYPE specifies the type of button you are creating. TYPE can be either SUBMIT, BUTTON and RESET, or it can be the name of an image. Except for the keyword UNDO all image names are interpreted as submit buttons. Images reside in the "images" directory of your default documents folder, and within this directory are grouped together under the GALLERY directory; for example, a button type of SAVE defaults to an image called "/images/buttons/netscape/save.gif" where "netscape" is the default gallery. Currently, the following images exist in the default gallery: SAVE, FIRST, FORWARD, BACK, LAST, NEW, DELETE, HOME, UNDO, CONTENT, INDEX, EXIT, and FIND. These special keywords are used only to associate their name with an image and type; for example, the keyword UNDO assigns IMAGE to "undo.gif" and TYPE to RESET. It is up to you to make the buttons actually do something. TYPE is required.
name	NAME is the name of your button and the name of an input field (hidden or otherwise) that exists in your form. This name is going to be set to the value of VALUE when the form is suibmitted. Failure to supply this name (either in this procedure or in your form declaration) will result in a JavaScript error.
value	VALUE is the value that is assigned to FORM.NAME.value when this button or image is clicked.
alert	ALERT causes a JavaScript alert and the form is not submitted.
confirm	CONFIRM calls the JavaScript function confirm. If the result is false, the form is not submitted.
onclick	onClick is inserted after ALERT and CONFIRM and just before the form is submitted. It is possible, for example, to call a validation function here and return false if you decide on your own that the form should not be submitted.
onmouseover	The text to display on a mouseOver.
image	IMAGE represents the name of an image in the images directory. If TYPE is one of the keywords listed above, the value of IMAGE is ignored. If IMAGE is NULL, regular type submit buttons are created.
gallery	GALLERY allows you to choose different images that all correspond to their image name. The default gallery name is "netscape." You can create your own images and copy them to their own gallery and use that name when calling this procedure.
status	The value of STATUS is written to the status line when a MouseOver event occurs on this link.
border	BORDER defines the size of the border that bounds your image. When 0, no border occurs.
prompt	PROMPT allows you to prompt the user for some input text. Normally, PROMPT is NULL because you want to submit the entire form and use that information to determine your next action; for example, when they click the next button, you probably need the current information to determine exactly what next actually means. PROMPT is primarily designed to implement a search function in your stored procedure so the values of your input fields are not as critical. As it is currently implemented, the PROMPT option returns the value of your button (indicated by NAME) and the text returned by your user in the field (probably hidden) identified by the value supplied in this name. The examples below explain this further. Although you can specify a value for onClick, doing so will override the code that performs this function. onClick should be NULL unless you absolutely know what you are doing.

Examples

We first need to define a form screen. The form screen is required, but since the form is referenced by its name, you can actually create your buttons before creating the form. For our purposes, however, it will be clearer if we define the form first and then show how the procedure is used.

Since our buttons are no longer part of our form, we want to declare a hidden field that will be used to store the value of our button. In the following form declaration, the name of this button will be called BUTTON.

       http.sp_html_form
       (
           NAME     => 'myForm'
       ,   PROCNAME => 'sp_html_form'
       )   ;

       http.sp_html_input
       (
           TYPE     => 'HIDDEN'
       ,   NAME     => 'BUTTON'
       )   ;

       http.sp_html_input
       (
           TYPE     => 'HIDDEN'
       ,   NAME     => 'SEARCH'
       )   ;

       http.sp_html_form;

Example 1

The first example illustrates how to define a reset button.

Since IMAGE is not defined and TYPE is not one of our keywords, this is just a simple reset button. While this looks like a regular reset button, it can actually reside in a different window or frame. If your buttons do not, you should probably define your submit buttons with sp_html_input:

       http.sp_html_button
       (
           TYPE      => 'RESET'
       ,   NAME      => 'BUTTON'
       ,   VALUE     => 'Reset'
       ,   FORM      => 'myForm'
       )   ;

Example 2

Here is how to define the same button as an image.

Since UNDO is one of our keywords, IMAGE and TYPE are automatically assigned:

       http.sp_html_button
       (
           TYPE      => 'UNDO'
       ,   NAME      => 'BUTTON'
       ,   VALUE     => 'Reset'
       ,   FORM      => 'myForm'
       ,   STATUS    => 'Reset information on this page'
       )   ;

Example 3

The next example illustrates how to define a submit button.

When this image button is clicked, the form "myForm" is submitted and the value of BUTTON is set to "Save":

       
       http.sp_html_button
       (
           TYPE=> 'SAVE'
       ,   NAME=> 'BUTTON'
       ,   VALUE=> 'Save'
       ,   FORM=> 'myForm'
       ,   STATUS=> 'Click here to save your changes'
       )   ;

Example 4

Here's a similar example that first asks the user if they really want to save their change and then calls a JavaScript function (defined by you) before the form is submitted.

In order, the user is first asked to confirm that that they really want to save this form. If that succeeds, your JavaScript function validate is called. If that succeeds, only then is the form submitted:

       
       http.sp_html_button
       (
           TYPE      => 'SAVE'
       ,   NAME      => 'BUTTON'
       ,   VALUE     => 'Save'
       ,   FORM      => 'myForm'
       ,   CONFIRM   => 'You really want to save this?'
       ,   onClick   => 'if (!validate(myForm)) return false;'
       ,   STATUS    => 'Click here to save your changes'
       )   ;

Example 5

The next example illustrates how to override the form submission and call another procedure.

Since a procedure name is specified for PROCNAME, the values for FORM, NAME, and VALUE are not important. When this button or image is clicked, TARGET is set to "_parent" and the procedure "sp_html_login" is invoked.

       
       http.sp_html_button
       (
           TYPE      => 'HOME'
       ,   PROCNAME  => 'sp_html_login'
       ,   TARGET    => '_parent'
       ,   FORM      => 'Home'
       ,   NAME      => 'Home'
       ,   VALUE     => 'Home'
       ,   STATUS    => 'Return to the Sybernet main menu'
       )   ;

Example 6

The next example illustrates how you can prompt your user for some text. It uses the PROMPT option, and only the value of your button (indicated by NAME) and the text that was entered when the prompt was displayed is returned to your procedure:

Since the PROMPT option does not invoke our form, it is important to supply the name of the procedure you wish to execute. The name of the form is not needed; in fact, it is ignored. TARGET should be specified if you are using frames so that the results of the find can appear in their own window.

PROMPT also defines the name on your form (and is probably hidden) that is to receive the user's response. Note too that the value entered is "remembered" if your buttons appear in their own window or frame; otherwise, the value is reset whenever a form is submitted and the buttons are redrawn.

       
       http.sp_html_button
       (
           TYPE      => 'FIND'
       ,   PROCNAME  => 'sp_html_form'
       ,   TARGET    => 'Frame2'
       ,   NAME      => 'Button'
       ,   VALUE     => 'Find'
       ,   STATUS    => 'Search for some text in this file'
       ,   PROMPT    =>  'SEARCH'
       )   ;