Asking and Telling the User

Sometimes a script needs to tell your users something"There are no records to include in this report"or ask the user a question"How many copies of the report do you want?" To this end, the Show Custom Dialog script step can display a dialog box that you control. Calling it a "Custom" dialog box might be a bit too generous (you don't have much say in how it looks), but you do get to give information to people using your database, and ask them simple questions.

Figure 15-1. This is the Send Email script you worked with in Chapter 14. Now, though, it has three comments explaining what it's supposed to do. The comment lines show up with a # symbol at the start, and in bold text.

When you add the Show Custom Dialog step to your script and click its Specify button, you see the window shown in Figure 15-2.

Figure 15-2. The Show Custom Dialog Options window has two tabs. Here you see what's under the General tab: Title, Message, and the buttons. In its most basic form, a custom dialog box shows a message with just one, two, or three buttons. Figure 15-3 shows how each of these settings affects the dialog box the user sees.

---

Note: There's another way to help people understand what your scripts are doing: Put comments in any embedded calculations. When a script has an If statement that uses a complex calculation for its condition, you're free to put comments in the calculation itself.

---

The Show Custom Dialog script step has three basic purposes. First, it can display a simple message. In a script that finds all overdue invoices, for example, you can have a message that says, "No invoices are overdue" if FileMaker finds nothing. Second, you can create a dialog box that asks a simple question. Say you have a script that posts a customer payment. Before launching into the process, your custom dialog box can ask, "Are you sure you want to post a payment?" and include Post Payment and Cancel buttons for your users' feedback. Finally, you can use this script step when you need to ask your users to enter some data, not just click a button. For example, a script that runs a sales report might start by asking what date range to report on. Here's how to create all three types:

15.2.1. Showing a Simple Message

In its simplest form, the Show Custom Dialog script step just delivers a message to the user. Figure 15-3 shows how to configure a box like this, and how the final result looks.

Figure 15-3. If you simply need to tell users something, give your custom dialog box only a title, message, and one button. In this picture, you can see the resulting dialog box below the options set in the script step. The title appears along the top of the dialog box, the message inside, and the button at the bottom. The first button (called Default Button in the Show Custom Dialog Options window) is the one that users can "click" by simply pressing Enter or Returnor, if they insist, by clicking with the mouse.

You can generate the title and message from a calculation to make it more dynamic. For instance, if someone wants to see all open invoices for a particular client, but there aren't any, you can show a calculated custom message that says, "Lucy Pevensie's account is paid in full," instead of something equally true, but less helpful, like "No records were found."

Using a custom dialog box like this in a script is simple. Just use the Show Custom Dialog step wherever you want in your script. When the dialog box pops up, your script waits for the user to click the button, and then continues with the next step.

15.2.2. Asking a Simple Question

To ask the user a simple question (one with either two or three possible responses), just add more buttons to the dialog box by filling in the Button 2 and Button 3 boxes in the Show Custom Dialog Options window. You can see this process in action in Figure 15-4.

Figure 15-4. This custom dialog box asks a question and offers two user choices (Cancel and Post). Notice that Cancel is the default button, acting as a safety device, since people often reflexively hit the Return or Enter key when they see a dialog box. By making Cancel the default button, you can prevent potentially destructive processes when someone fails to read instructions.

When a dialog box like this appears, your script waits for a click of one of its buttons, then continues. Although FileMaker knows whether button 1, 2, or 3 got clicked, you have to add logic to your script to tell the program what to do in each case. For that, you use the Get ( LastMessageChoice ) function and If statements based on its results. (The function returns 1 for the default button, 2 for Button 2, and 3 for Button 3.) The script in Figure 15-5 uses Get ( LastMessageChoice ) to take some steps only when someone clicks a custom dialog box's default button.

Figure 15-5. This script uses the Show Custom Dialog script step to ask a question (the same question shown in Figure 15-4). If your user clicks Post, the script creates a new record and sets the Payments::Amount field appropriately. To make this decision, it uses an If step with the condition Get ( LastMessageChoice ) = 2.

 

15.2.3. Asking a Not-so-simple Question

If you need user input that goes beyond two or three simple choices, you can venture into the second tabInput Fieldsin the Show Custom Dialog script step (Figure 15-6). The Show Custom Dialog Options window's Input Fields tab lets you add fields to your custom dialog box. To add a field to a custom dialog box, turn on one of the "Show input field" checkboxes in the Input Fields tab of the Show Custom Dialog Options window. When you do, FileMaker shows a Specify Field dialog box, in which you can pick the field to use. (If you want to change the field later, click the Specify button).

You can also give the field a label (like Start Date and End Date in Figure 15-6). The label can be the result of a calculation. Finally, if you turn on "Use password character" for an input field, the field works like a typical Password box: It shows * or • instead of the letters you type, so someone watching over your shoulder can't see what you're entering.

The fields you add to a custom dialog box have some limitations, including the ones listed below. (For other alternatives, see the box on Section 15.3.)

• As far as data entry goes, Show Custom Dialog can have only free-entry fields like those shown in Figure 15-6. You can't use radio buttons, checkboxes, or pop-up menus. You also have no control over the size of the field, so short fields for dates, or tall fields for lots of text, aren't an option.

  

  Figure 15-6. You can have, at most, three fields, each of which corresponds to a real field in your database. The window in the front shows how the dialog box looks when the script runs. When the user types something in one of the fields and then clicks the default button, FileMaker puts the entered value into the real field on the current record. If the user clicks Button 2 or Button 3, on the other hand, FileMaker leaves your record's fields alone.

• "Data-entry only" validation doesn't apply to fields in custom dialog boxes. If you use a dialog box to gather data for a record, either use the Always option in the field validation, or check the validity of the data in your script (Section 15.5.1).
• You must use the OK button as the default when you're using input fields in a custom dialog box. Consequently, you have to trust people to read the dialog box when they need to enter data in it.