Creating, Modifying, and Troubleshooting Actions

An action is a programmable button that can be used to automate tasks. Actions normally appear in the Action bar, which can be displayed in forms, subforms, pages, folders, and views. Additionally, actions may be displayed in the Actions menu in the Notes client. Actions can be shared, enabling you to use an action in multiple forms, pages, views, and so on. Actions are most often used in the following situations:

• When you want to automate a function, but don't want the code stored with each individual design element.

• When Web clients need substitutes for Notes client menu choices (through the Action bar).

• When users need to see all the possible choices in a nonscrolling row at the top of a form or page or view. When buttons are placed in a form or page, they scroll with the form.

• When the function the action performs isn't limited to a particular section of a form or page.

• When you want to share an automated function between several design elements, making the maintenance of the application easier.

There are two basic types of actions: single use and shared. A single use action can be used only in the form, view, folder, or page where it is created. A shared action is stored as a database resource and can be used across multiple forms, subforms, views, folders and pages. Shared actions are covered in Chapter 9, “Design Elements.”

Action Coding Choices

When you create an Action, you have several coding choices, depending upon which environment (Web or Notes client) the Action will be used. Additionally, you may elect to use one of the predefined System actions Lotus has included.

You can use any of the following choices to program actions that will be used in Notes client applications:

• Simple actions

• Formulas

• JavaScript

• Common JavaScript (shared library).

  Common JavaScript is new to Domino 6 and can be used to write JavaScript code that can be used in certain limited events for both Notes client and Web applications.

  
  

• LotusScript

You can use JavaScript or Common Javascript (shared library) to program actions that will be used in Web client applications.

System Actions

Domino provides a set of predefined actions, known as system actions, that automate some of the most basic and common Notes features. The system actions are included in the following list:

• Categorize— Add values to the Categories field in the current document.

• Edit Document— Edit the current document.

• Forward— Copy the current document to a new email memo.

• Move to Folder— Move the current document to a specified folder.

• Remove from Folder— Remove the current document from a specified folder.

• Send Document— Send the current document via email.

Single-Use Actions

Follow these steps to create a single-use action that can only be used in the design element that hosts it:

1.	In the Notes Designer client, open the form or view.
2.	Choose Create, Action, Action, which launches the Action properties box and displays the Info tab, shown in Figure 4.2. Figure 4.2. The Action properties box enables you to define how your action will display.
3.	Enter a name for the action.
4.	Optionally, enter a label. This is a new feature in Domino 6; it enables you to enter a formula that will compute a value to display for the Action's label. If a label is not supplied, the name will be used for the label.
5.	If you plan to display the action within a specific frame, select the target frame.
6.	Select the display parameters of the action, which are defined in the following list: Select the position in which the action should appear in the Action bar or the Actions menu. If you want the action to appear in the Action bar, click Include Action in the Action Bar check box. You then have two additional options. Only Show Icon in Action Bar determines whether the text caption (label) appears with the icon;Right Align Action control determines whether the action appears right-aligned or not. Determine whether the action should appear in the Actions menu.
7.	If you are displaying the action as a button on the Action bar, you can select a graphic icon to display in the button. If you want to use an image resource, determine whether it is to be Notes, which uses the palette of available icons that come with Notes, or Custom, which enables you to select any image that you supply.
8.	Optionally, Click the Action Hide When tab (it looks like a window shade) if you want to hide the action under certain conditions.
9.	Select the appropriate choices, which are fairly self-explanatory. If the action should be hidden under certain conditions, check the Hide Action if Formula Is True check box and enter a formula that evaluates to true when the hide-when conditions are met.
10.	Optionally, define Publishing settings for the action in the Advanced tab.
11.	Close the Action properties box.
12.	In the Objects tab of the Programmer's pane, select the action you just created.
13.	Expand the Run pull-down list and select the environment in which the action will run: Client or Web.
14.	Choose a coding choice appropriate for the selected environment and enter code.
15.	Save the design element that contains the action.
16.	Test the action to ensure that it works properly.

Modifying Single-Use Actions

To modify a single-use action, follow these steps:

1.	In the Notes Designer client, open the design element that contains the action.
2.	Choose View, Action pane (which opens the Action pane), or select the border between the window in which the view or form is displayed and the Action pane and drag it to the desired position.
3.	Double-click the action to open the Action properties box, shown previously in Figure 4.2.
4.	Edit the action, following the steps listed in the section “Single-Use Actions.”

Troubleshooting Single-Use Action Hide-Whens and Programming

Problems with single-use Actions usually fall into one of two categories: actions that are either hidden or visible at inappropriate times, and programming problems.

Follow these steps when troubleshooting action hide-whens:

1.	In the Notes Designer client, open the design element that contains the action.
2.	Choose View, Action pane (which opens the Action pane), or select the border between the window in which the view or form is displayed and the Action pane and drag it to the desired position.
3.	Double-click the action to open the Action properties box, shown previously in Figure 4.2.
4.	Click the Hide When tab.
5.	Check the hide-when settings. If a hide-when formula has been used, ensure that the formula returns the value TRUE. One easy way to test the formula is to create a Computed for Display field in a form and paste the formula into it. Then open the form and examine the value in the field. It should contain 1, the formula language value for TRUE.
6.	Save the design element.
7.	Test the action to ensure that it is hidden or visible at the appropriate times.

Follow these steps when troubleshooting action programming:

1.	In the Notes Designer client, open the design element that contains the action.
2.	Choose View, Action pane (which opens the Action pane), or select the border between the window in which the view or form is displayed and the Action pane and drag it to the desired position.
3.	Click the action to display the action's contents in the Programmer's pane.
4.	Begin to debug the action. The type of action determines the most appropriate method of debugging. Table 4.2 lists the best way to debug a particular action based on its code. Table 4.2 contains some common action debugging methods. Table 4.2. Action Debugging Methods Type Method Formula Use the @Prompt function in the code to display key variables and field values and to show the progress and flow of the code. LotusScript Use the LotusScript debugger (File, Tools, Debug LotusScript) instead of or in conjunction with the MsgBox function to display key variables and field values and to show the progress and flow of the code. Additionally, users can use the NotesLog class to record a script's actions. This can be especially useful for debugging agents run by a Web client. JavaScript/CommonJavaScript Use the alert() function in the code to display key variables and field values and to show the progress and flow of the code.
5.	Save the form or view.
6.	Test the action to make sure the expected results are displayed.
7.	Repeat steps 4–6 until the action works as expected.