Sometimes, particularly in a programming language, simple is beautiful. An easy-to-use programming function or element is less likely to cause you bugs, which saves you time, effort, and the pain of banging your head on the monitor in frustration. Simple means good, clear, maintainable code. The message box function is just that-good and simple!

You have seen examples of the message box in earlier chapters. For example, you can insert a statement in your code that displays a small window with the message Break time! with just 20 characters of typing:

MsgBox "Break time!"

When this code statement is carried out, a window containing this message pops up in the middle of the screen. Not only does the user see this message in a nice little window, but that window even comes with a handy acknowledgment button. The window hangs around until the user clicks on the button to make it go away.

VBScript offers another way to send a message to your user: You can use the Alert function. This function was first used in the JavaScript language. It actually isn't a part of the VBScript language, but is a function supported by the Internet Explorer host environment. Because you have access to host objects from VBScript (covered in more detail on Day 18), you can use Alert. Like MsgBox, Alert displays the text in a message window and provides a button that must be selected to acknowledge the message. The windows generated by Alert and MsgBox are shown in Figure 14.1.

Figure 14.1 : The Alert and MsgBox message windows.

One obvious difference between these two functions is shown in Figure 14.1. Alert places a title at the top of the window that says Microsoft Internet Explorer and uses the ! icon; MsgBox provides the default title Visual Basic and does not show an icon.

Line Separation

The MsgBox function allows extensive customization of the information it presents. The first parameter to this function, as you have seen, provides the message that is displayed to the user. If you want this message to be provided as more than one line when the message is presented, you simply separate each desired line with the carriage return line feed constant vbCrLf which you must define. For example, the following sample displays "Line1", "Line2", and "Line3", each on a separate line within the message box:

Dim vbCrLf : vbCrLf = Chr(13) & Chr(10)
MsgBox "Line1" & vbCrLf & "Line2" & vbCrLf & "Line3"

In addition to using vbCrLf to force a line separation, you could also use just Chr(13) or Chr(13) & Chr(10). These are all different ways of telling VBScript to separate a line. VBScript knows to separate a line if it sees a carriage return character or a line feed character, represented by these constants and ASCII character codes. These invisible characters don't show up on the screen, but they do convey formatting information.

You may be wondering why you have so many choices about how to request a line separation. It used to be that for a particular operating system you had to supply exactly the right characters from a language to control line separation. For example, you had to use the command Chr(13) on some systems, and Chr(13) & Chr(10) on other types of systems. VBScript is smart enough to relieve you of this burden. If it gets any of these characters, it knows you want to separate a line. It won't be picky.

Buttons and Titles

Figure 14.1 shows a plain-looking message box that provides a minimum amount of interaction. First, let's consider the issue of interaction. The user could choose to click on OK, or he could choose to click on OK. There are no other choices! The purpose of forcing the user to select OK is to ensure that he has read the message presented. The OK button, in this case, is simply an acknowledgment button.

There are ways to use MsgBox to get much more information from the user than simply an acknowledgment. The second parameter of the function is used to specify message box attributes. One attribute that can be specified is the type of button choices that the message box can provide to the user. Consequently, this affects the type of return code information that is provided back to your code.

Several types of button choice attributes may be designated. Each attribute can be specified by a specific integer number. To make working with these attributes easier and make code that uses them more maintainable, a file is provided on the CD-ROM to define them. The file is constant.txt in the shared\tools directory. The needed declaration lines can be copied and pasted to your own script. The constant names, values, and purposes are summarized in Table 14.1. Normally if you use the supplied constant definitions you will refer to these attributes by constant name only, and will not have to use the value.

The message box shown in Figure 14.1 has the OK button. This button is provided by default if you do not supply a second parameter to designate the button attribute. A message that presents just an OK button is typically used to present information to the user and have him acknowledge that the information has been read.

You can use button attribute constants to request different combinations of buttons as well. All the available combinations are documented in Table 14.1. Most of these combinations give the user the opportunity to provide more feedback to the script than just a simple acknowledgment. The vbYesNoCancel constant, for example, provides three choices for the user. The script can then interpret which button the user selected and perform further processing based on that response.

The approach to interpreting the user's response from a script is considered next. But first, consider the cosmetic aspects of the message box. An example of a vbYesNoCancel message box appears in Figure 14.2.

Figure 14.2 : A message box with Yes, No, and Cancel buttons.

The line of code that produced this message box is

rc = MsgBox( "rc = MsgBox ""Text"", vbYesNoCancel + vbExclamation, _
      ""Title"" ", vbYesNoCancel + vbExclamation, "vbYesNoCancel")

The preceding is a complicated-looking line of code at first glance, but that is largely because the message that is provided in the first parameter contains sample syntax for a message box. For the sake of clarity, assume you wanted to use the same type of message box to display the question Do you use VBScript?. The call to generate that question with Yes, No, and Cancel buttons would be

rc = MsgBox( "Do you use VBScript?", vbYesNoCancel + vbExclamation, "My Title")

Consider this call a piece at a time. First of all, rc is the variable that is used here to receive the return code from the function call. This variable will be filled with a number that indicates the user's button choice. Then consider the three parameters to the MsgBox function. The first parameter is simply the message or question that you want to display. Turn your attention next to the third parameter (an easier one!). That parameter indicates the title that is displayed on the caption area of the message box. If no third parameter is supplied, Visual Basic will show up as the default title.

Finally, consider the second parameter. The values you supply here are codes that determine the attributes of the message box. Table 14.1 lists the attribute constant values you can use for certain combinations of buttons. The intrinsic constant vbYesNoCancel is used in the preceding sample to cause the Yes, No, and Cancel buttons to appear. When buttons are requested, the message box automatically takes care of generating them and returning a predefined number for that specific button through the function's return code. So the vbYesNoCancel constant in the second parameter causes generation of a window with three specific buttons, and each button will cause a specific documented number to be generated when it is clicked.

But that's not the whole story of the second parameter. The second parameter has two pieces joined by a plus sign. The button indicator code is on the left side. What's that on the right side? It's a value that indicates the icon to display with the message box. These values are represented by VBScript user-defined constant declarations in shared\tools\constant.txt on the CD-ROM. Just like the button value, they can be one of the entries in Table 14.2.

The attribute parameter can be used to convey two pieces of information to the message box function. This simply requires adding the button attribute and icon attribute value together. For example, the vbOKCancel value is 1 and the vbCritical icon value is 16. Normally you would request this combination of attributes with a statement like this:

MsgBox "Testing", vbOKCancel + vbCritical, "My Title"

But you could achieve the same result with this statement:

MsgBox "Testing", 17, "My Title"

The first approach is recommended because it makes for more readable, more maintainable code. But both work just the same. Even the combined number uniquely identifies both attributes because command button values are 5 and less, and icon values are 16 and higher. All you really have to know to use these effectively, however, is that you can combine both values into this one parameter.

Look again at Figure 14.2 to see an example of the exclamation point icon. This was produced, along with the Yes, No, and Cancel buttons, by this line of code:

rc = MsgBox( "rc = MsgBox ""Text"", vbYesNoCancel + vbExclamation, ""Title""", _
      vbYesNoCancel + vbExclamation, "vbYesNoCancel")

Figure 14.3 shows an example of the information icon on a message box.

Figure 14.3 : A message box with the information icon.

This message box has only the OK button. It was generated by the following statement:

rc = MsgBox( "rc = MsgBox ""Text"", vbOKOnly + vbInformation, _
     ""Title"" ",vbOKonly + vbInformation, "vbOKOnly")

The value of the vbOKOnly constant is 0. Therefore, this code would work exactly the same if the following statement were used:

rc = MsgBox( "rc = MsgBox ""Text"", vbInformation, ""Title"" ", vbInformation, _
    "vbOKOnly")

Figure 14.4 shows a message box that uses the question mark icon, along with Yes and No buttons. That message box was generated by the following statement:

Figure 14.4 : A message box with a question mark icon and Yes and No buttons.

rc = MsgBox( "rc = MsgBox ""Text"", vbYesNo + vbQuestion, ""Title"" ", _
      vbYesNo + vbQuestion, "vbYesNo")

Figure 14.5 rounds out the list of icon types. This figure shows an example of the critical error icon, combined with the OK and Cancel buttons. It was produced by this line of code:

Figure 14.5 : A message box with a critical error icon and OK and Cancel buttons.

rc = MsgBox( "rc = MsgBox ""Text"", vbOKCancel + vbCritical, ""Title"" ", _
     vbOKCancel + vbCritical, "vbOKCancel")

The choice of which icon to use in which situation should be based on the criteria that the icon names imply. Informational feedback that is not an error condition should use the information icon. If you are asking the user a direct question, use a question mark icon. Less severe errors are typically presented with the exclamation point icon. Very severe errors that can bring a script to a halt or invalidate results would warrant the use of the critical error icon.

Each of the code statements in the icon type illustrates the use of a variable to capture the MsgBox return code. When this function is used, it sends a return value back to the statement it was called from. This return code can be assigned to a variable of any name, although the convention of rc for return code is often used. The return code will indicate which button the user selected. This value will be one of the ones shown in Table 14.3.

If you have used programs in a Windows environment, you probably know one very important aspect of the message box window: It is modal. This means that when a message box is presented to the user, he must respond to it before he can interact further with that Web page. This is great news from a script programming standpoint. When a script puts up a message box, you know that by the time the next code statement is carried out, the user will have already provided a response to that message. This gives you a high degree of control over the interaction. You know the user has to respond when you offer a message, and you know that in the statement after the message you have a record of the user's response.

Your script can take further action based on the return code. An example of code that evaluates the return code from MsgBox is shown in Listing 14.1. This code makes use of the global constant declarations in the file shared/tools/constant.txt on the CD-ROM.

Listing 14.1. Evaluating the return code from MsgBox.

Sub cmdYesNoCan_OnClick
    dim strFeedback ' Feedback string
    dim rc ' return code from message box call
    rc = MsgBox( "rc = MsgBox ""Text"", vbYesNoCancel + vbExclamation, _
       ""Title""", _
         vbYesNoCancel + vbExclamation, "vbYesNoCancel")

    strFeedback = "Response was " & rc & "." & vbCrLf
    if rc = vbYes then
         strFeedback = strFeedback & _
         "This is equal to vbYes and indicates Yes was clicked."
    elseif rc = vbNo then
         strFeedback = strFeedback & _
         "This is equal to vbNo and indicates No was clicked."
    elseif rc = vbCancel then
         strFeedback = strFeedback & _
         "This is equal to vbCancel, indicates Cancel clicked."
    else
         strFeedback = strFeedback & _
        "This is not equal to any expected constant."
    end if

    msgbox strFeedback, vbOKOnly, "vbYesNoCancel Return Code"
end sub

The message box is generated by the third line of this code. Since the vbYesNoCancel attribute value is specified, the message box will have only three buttons-the Yes button, the No button, and the Cancel button. Therefore, these are the only possible buttons the user can interact with. As a result, the only possible values that can result from this call to the MsgBox function are vbYes, vbNo, and vbCancel. The code in the last half of the listing compares the return code to each of these possible values to build the final result string.

The message box provides yet another interaction choice to the user. You can specify a help file name and help file context in a fourth and fifth parameter to the function. The help file indicates a file with help information that corresponds to the message. The help file context identifies a specific topic within that help file to be displayed. If help file information is provided, a help button will also appear on the message box. Display of the help file will only occur if the user clicks on the help button or selects the f1 key. Help information is typically used to provide more details on an error message for the user.

Now you have been exposed to all the parameters of the message box. The only parameter that must be specified is the message parameter. The rest are optional. They are summarized here for your reference:

ResultVariable = MsgBox(prompt_string, optional_button_and_icon_values,
optional_title, optional_helpfile, optional_context)

Why might you want to get a user response through a message box? Perhaps your script detects invalid input and needs to know whether the user wants to respecify it or ignore it. Or maybe you need to ask a series of yes-and-no questions to determine how to carry out a calculation for a user. Or, if a calculation ends up taking many loops, you might want to present the user with a choice to continue or cancel the operation. In situations like these, feedback from the user can be crucial to the operation of your script. If you had to get this feedback by interacting with form controls every time, your pages would look intimidating to the user. They might contain prompt fields that are rarely used, and the user's interaction task would be much more complex. Instead of a window popping up before the user's eyes in the middle of the screen, the user would have to locate the equivalent field. For all these reasons, message boxes can play a very important role in your script user interface design.

Input Boxes

Message boxes can greatly extend the power of your scripts. You can provide feedback to the user without having to run it through the Web page. You can get responses from the user that the script can act on, all in a separate window that the user must interact with before proceeding. The message box model works great for collecting responses unless you want more feedback than simply yes, no, cancel, abort, retry, or ignore. But in the case of certain data on a form, you might need more information from the user before submitting the data. The information you need might be additional string information such as alternative supplier information. Ideally, you want to collect this information in a supplemental window to your page for the same reasons that message boxes are handy. If you had to provide additional input fields for just a few special cases, your page could be quite messy. It might be hard to highlight the appropriate fields for the user, and it would be difficult to ensure that all the information has been provided as you proceed through a sequence of steps. Fortunately, the message box has a close cousin that can come to the rescue in cases like this. The input box function InputBox provides a separate modal window much like the message box. It can present a prompt message to the user and collect an input string that is returned back to the script.

An example of an input box appears in Figure 14.6. Unlike the message box, the input box has no icon that is displayed. It also does not provide any control over the buttons that appear. OK and Cancel buttons appear on every input box.

Figure 14.6 : The input box prompting for user input.

The input box gives you control over the most important aspects. Namely, you can retrieve text from it. The code that generated the input box in Figure 14.6 is shown in Listing 14.2.

Listing 14.2. The InputBox function call.

Sub cmdInputBox_OnClick
    dim strFeedback ' Feedback string
    dim rc ' return code from message box call
    rc = InputBox( _
        "Please provide the name of your favorite Visual Basic author." & _
         vbCrLf & vbCrLf &  _
        "You may enter more more than one name if desired." , _
        "Determining user preferences", "Brophy and Koets", 0, 0)

    strFeedback = "Response was " & rc & "." & vbCrLf
    if rc = "" then
         strFeedback = strFeedback & _
         "The user did not care to provide a response."
    elseif rc = "Brophy and Koets" then
         strFeedback = strFeedback & "The user used the default response."
    else
         strFeedback = strFeedback & _
         "The free thinking user supplied their own response."
    end if

    msgbox strFeedback, vbOKOnly, "InputBox User Response"
end sub

The InputBox function statement appears in the fourth statement of the listing. This is the function call format:

ResultVar = InputBox(prompt_message, optional_title,
optional_default_response, optional_x_position,
optional_y_position, optional_helpfile,
optional_helpfile_context )

The first parameter is the prompt message. This is the message displayed in the input box window that prompts the user for his response. As you can see in Figure 14.6, the prompt for the sample is spread over more than one line. The vbCrLf declaration discussed earlier today can serve as a line separator for input box prompts, just as it can for message box prompts. The prompt must be supplied, but the rest of the parameters are optional.

The next parameter is the title of the window, which is displayed in the top caption area. If a title is not supplied, Visual Basic will appear in its place.

The third parameter is the default response. This response will show up in the text input area that is supplied for user input when the input box is generated. In the input box shown in Figure 14.6, Brophy and Koets was supplied as the default response. The default response is a response that the user is likely to provide. If he wants to go with the default, he can simply select the OK key and doesn't have to type in any text. To provide a specific response, the user simply types the desired response, then selects OK. The new input will automatically replace the highlighted default, and no backspacing or deletion is necessary.

The fourth and fifth parameters control the placement of the input box in x and y coordinates from the top of the screen. In the sample, the X and Y were specified to be 0, so the input box appeared at the top-left corner of the screen. If no values are supplied, the input box appears centered horizontally on the screen and a third of the way down. It is interesting to note that you cannot control the message box placement, but you can control the placement of the input box. You might want to control placement of an input box if you ask the user for information relating to what he has on the Web page in front of him. In that case, you don't want to obscure the user's view of the page any more than you have to in case he wants to rely on information on the page while deciding on his input.

The sixth and seventh parameters of the InputBox function call are for help file and help file context information. The help file support for InputBox is the same as that for the message box.

The manner of retrieving the user response for an InputBox call is also similar to that of MsgBox. After the user enters a string into the input area and clicks OK, that user-supplied value is returned. In the case of the example in Listing 14.2, the return value is assigned to the return code variable rc. From that point on, you can do anything with the variable that you would do with any string. The options are many, including comparing it, reassigning it, or searching it for a substring. If the user just selects OK without providing his own input, the default string will be returned. If there is no default, if the user deletes the text and presses OK, or if the user selects the Cancel button at any point, a zero-length string of "" will be returned. The code in Listing 14.2 illustrates how to check the return code to determine if a new string was provided, if the default string was used, or if a cancel occurred.

The InputBox function can extend the capabilities of your scripts very easily. The function is easy to use and integrate. Many languages provide similar functions. With traditional non-Web page applications, it might be considered bad form to rely too heavily on this function. A series of more detailed windows, or of good data collection on one dynamic window, often provides easier and better interaction for the user. However, in the scripted Web page model you are dealing with, your options are limited. It's not as easy to make the entire page dynamic since you often must share it with static HTML-generated text, and you can't provide the user with a series of windows controlled from one main script unless you resort to using more complex HTML frames. Often, the closest you can come is with controlled use of InputBox. This technique allows your scripts to make a page one step closer to an application and one step further away from being just a static display of information. At the end of this chapter a detailed example built on a flow of input boxes is provided. But first, consider one more interesting way to provide information to the user.

Documents

So far you've seen examples of many different ways to extend and control a Web page through your scripts. Integrated components such as input controls and ActiveX controls that can be manipulated through scripts were addressed on Day 10, "An Introduction to Objects and ActiveX Controls," and Day 11, "More ActiveX Controls." There are also capabilities for feedback that are intrinsic to VBScript such as the message box and input box functions examined today. But one area has not yet been approached. That is the Web page document itself and the HTML code on which it is based.

The document Object and the form Object