Build-On Tutorial:

Attachments

Attachments: Lesson 2

Working with Attachment Files

Lesson Overview

The objective for this lesson is to enhance the user interface so that users can easily view and manipulate attachment files.

Here is a sneak peek of what you will build:

Step 1 - New script to handle file manipulation

Now that you have a place to store attachments, you need to create easy ways to work with the actual attachment files: inserting them, viewing them, and removing them. In this step, you will create a script to handle all three of these file actions. The script works by taking a parameter named “action” that indicates one of the three possible actions.

  1. Open the Script Workspace, duplicate the Template Script, name it “Attachment File Action ( action )”, and move it into the ATTACHMENT folder.
  2. Modify the Parameters comment to describe the expected values for the action parameter.

# Parameters:     Specify using # function:
    $action (required) =
        clear = clear existing file
         edit = insert new file
        open = export to temporary folder and automatically open

  1. Start modifying the script by adding steps to load the parameter and require the context to be the ATTACHMENT table.

    NOTE: For detail on the Show Custom Dialog script steps, see Step 4 below.

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Enter Browse Mode [ Pause: Off ]
Freeze Window

# load parameter(s)
Set Variable [ $parameter_parsing_ok ; Value: #Assign ( Get ( ScriptParameter ) ) ]
If [ $parameter_parsing_ok = False ]
    # parameters could not be parsed, exit this script and report back
    Exit Script [ Text Result: "error" ]
Else If [ $action ≠ "clear" and $action ≠ "edit" and $action ≠ "open" ]
    # invalid parameter(s) passed
    Show Custom Dialog [ “Error" ; "Invalid parameter(s) passed to script: " & Get ( ScriptName ) ]
    Exit Script [ Text Result: "error" ]
End If

# required context
If [ Get ( LayoutTableName ) ≠ "ATTACHMENT" ]
    Show Custom Dialog [ “Alert" ; "This script can only be run from an Attachment screen.” ]
    Exit Script [ Text Result: "error" ]
End If



  1. For the Show Custom Dialog script steps, double-click on the script step or click the gear icon at right to open the Show Custom Dialog Options dialog. In both instances of this step, only the Default Button should be specified, with the button text “OK”. The Button 2 information should be removed.
  2. Next, add the basic logic that checks for each of the three possible file actions.

# handle action
If [ $action = "clear" ]
    # clear file

Else If [ $action = "edit" ]
    # change file

Else
    # open file

End If


Exit Script [ Text Result: $null ]

  1. Finally, add the code (highlighted below) to handle each action:

    NOTE: For more detail on the Show Custom Dialog, Insert File, Set Variable, and Export Field Contents script steps, see Steps 7-10 below.

# handle action
If [ $action = "clear" ]
    # clear file

    # ask for confirmation
    Show Custom Dialog [ “Alert" ; "Are you sure you want to remove the attachment file?” ]
    # 1 = cancel, 2 = clear
    If [ Get ( LastMessageChoice ) = 2 ]
        Set Field [ ATTACHMENT::Attachment ; "" ]
        Commit Records/Requests [ With dialog: Off ]
    End If


Else If [ $action = "edit" ]
    # change file

    Insert File [ Insert ; Display content ; Never compress ; ATTACHMENT::Attachment ]
    Commit Records/Requests [ With dialog: Off ]


Else
    # open file

    # verify container file exists
    If [ IsEmpty ( ATTACHMENT::Attachment ) ]
        Show Custom Dialog [ “Alert"; "No attachment has been uploaded.” ]
        Exit Script [ Text Result: $null ]
    End If

    # export to temporary folder and open
    Set Variable [ $file_path ; Value: “file:” & Get ( TemporaryPath ) & GetContainerAttribute ( ATTACHMENT::Attachment ; “filename” ) ]
    Export Field Contents [ ATTACHMENT::Attachment ; “$file_path” ; Automatically open ; Create directories: Off ]


End If

Exit Script [ Text Result: $null ]

  1. In the # clear file portion of the script, the Show Custom Dialog step (line 39 in the image in Step 5 above) should be configured to show two buttons, as shown below.
  1. For the Insert File script step, click on the gear icon to open a popover with additional options.
    1. Check the Dialog Options box to open the Insert File Options dialog. Set the Custom Dialog Title to “Insert File”, Storage options: to Insert, Display: to Content of file (when possible), and select Never compress. The full dialog is shown below.
    2. Back in the options popover, check the Target box to open the Specify Target dialog. Then choose the Field option and select the ATTACHMENT::Attachment field.
  1. The Set Variable script step sets a variable named $file_path which defines the path of the file that will later be created by the Export Field Contents script step. Set $file_path to the following calculated value:

       "file:" & Get ( TemporaryPath ) & GetContainerAttribute ( ATTACHMENT::Attachment ; “filename” )


    Note the following about this calculation:
    1. The file: prefix is used to indicate a relative, cross-platform file path.
    2. Get ( TemporaryPath ) returns the path of the temporary folder on the user’s device.
    3. The GetContainerAttribute function returns the specified attribute of the file stored in the specified container field. The filename attribute is used here to obtain the name of the original file that was inserted into the container field.
  1. For the Export Field Contents script step, click on the gear icon to open a popover with additional options.
    1. Check the Specify target field box and select ATTACHMENT::Attachment.
    2. Back in the options popover, check the Specify output file box to open the Specify Output File dialog. Type $file_path in the file path list, and check the Automatically open file box, as shown below.
  1. Save and close the script.

Step 2 - Add button bar to the card window

Add a button bar to the Attachment | Card layout to allow the various actions to be performed. The button bar segments will be hidden dynamically when they are not relevant.

  1. Enter Layout mode and navigate to the Attachment | Card layout.
  2. Select the Button Bar tool in the status toolbar.
  1. Using the Button Bar tool, draw a rectangle beneath the Attachment field to start creating a button bar. In the resulting Button Bar Setup dialog, name the first segment "Open" and set it to perform the Attachment File Action ( action ) script with the parameter: # ( "action" ; "open" ).
  1. On the Data tab of the Inspector, set the Hide object when calculation for the first segment to: IsEmpty ( ATTACHMENT::Attachment )
  1. Back in the Button Bar Setup dialog, click the > (right arrow) button to switch to the second segment. The name of the this segment will be dynamic depending on the content of the Attachment field. Click on the pencil icon and enter the following calculation:

If ( IsEmpty ( ATTACHMENT::Attachment ) ;
"Insert" ;
"Replace"
)

  1. Set the second segment to perform the Attachment File Action ( action ) script with the parameter: # ( "action" ; "edit" )
  1. Now switch to the third button segment. Name it "Clear" and set it to perform the Attachment File Action ( action ) script with the parameter: # ( "action" ; "clear" ). Then use the Inspector to set the hide condition: IsEmpty ( ATTACHMENT::Attachment ).
  2. Resize the button bar to the exact width of the Attachment field and align it with the bottom edge of the field. Your work should look similar to the image below.
  1. Enter Browse mode to save and review your work.

Step 3 - Prevent user from accidentally deleting an attachment

A user should be allowed to interact with the Attachment container field by dragging and dropping a file or using the field’s contextual (right-click) menu. However, the user should not be allowed to accidentally delete an attachment by pressing the delete key. A script trigger can prevent this action.

  1. Return to Layout mode on the Attachment | Card layout.
  2. Right-click the Attachment field and choose the Set Script Triggers… menu item. (You can also select the field and choose Format > Set Script Triggers…).
  3. In the Set Script Triggers dialog, select the the OnObjectKeystroke event. A Specify Script dialog will then appear; select the TRIGGER Suppress Delete Keystroke script. This script has already been added to your file.
  1. Enter Browse mode to save and review your work.

Step 4 - Additional user interface

A few more enhancements will make the user interface clearer and more intuitive for users.

  1. Return to Layout mode on the Attachment | Card layout.
  2. Add a text object with the text "Drag and Drop" as shown below. Using the Inspector:
    1. Assign it the style label Center.
    2. Set the hide condition to: not IsEmpty ( ATTACHMENT::Attachment )
  1. Create a button near the Attachment field. In the Button Setup dialog:
    1. Click the Display only an icon button.
    2. Choose the document icon indicated below (eleventh row, second column) and set the size to 100 pt.
    3. Set the button action to Do Nothing.
  1. Further modify the button using the Inspector:
    1. Give it the style: btn Icon.Info 
    2. Set the hide condition: not IsEmpty ( ATTACHMENT::Attachment ) 
    3. If the button is too small to display the full icon, increase its dimensions as necessary. Then position the button in the center of the Attachment field.
  1. Enter Browse mode to save and review your work.

Step 5 - Attachment validation

For the purpose of this lesson, imagine that when a user is done adding or editing an attachment, their entry needs to pass certain validation rules before they can proceed. This will provide you with a good example of how to define and implement business rules in your apps.

The validation rule you will enforce is that the Attachment field must not be empty. If the user tries to create or save an attachment record without inserting a file, she will see an error message and not be allowed to close the window.

  1. Open the Script Workspace, duplicate the Template Script, name it “Validate and Save Attachment”, and move it into the ATTACHMENT folder.
  2. Modify the script by adding the highlighted steps below.

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Enter Browse Mode [ Pause: Off ]
Freeze Window

# context requirements
If [ Get ( LayoutTableName ) ≠ "ATTACHMENT" ]
    # required table context
    Show Custom Dialog [ “Alert" ; "This script can only be run from an Attachment screen.” ]
    Exit Script [ Text Result: "error" ]
Else If [ Get ( FoundCount ) = 0 ]
    # require record showing
    Show Custom Dialog [ “Alert" ; "This script can only be run with an Attachment record displayed.” ]
     Exit Script [ Text Result: "error" ]
End If

Commit Records/Requests [ With dialog: Off ]

# verify container file exists

If [ IsEmpty ( ATTACHMENT::Attachment ) ]
    # no container file; inform user and stay in card window
    Show Custom Dialog [ “Alert" ; "An attachment file is required.” ]

Else
    # close card window
    If [ Get ( WindowStyle ) = 3 ]
        Perform Script [ Specified: From list ; “Close Window” ; Parameter: ]
    End If

End If


Exit Script [ Text Result: $null }

  1. Return to Layout mode on the Attachment | Card layout.

    At the bottom of this layout, there are two sets of stacked buttons. If you temporarily move or hide the Cancel and Create buttons, you will see Delete and Close buttons underneath them (see below). Hide conditions have been specified for these objects so the first pair displays when $$CARD_ACTION is "New" and the second pair when it is not.

    The Cancel and Delete buttons are specified to call the Delete Record ( msg ) script. These do not require any modification by you.
  1. Go into the Button Setup dialog for both the Create and Close buttons and change them so that each triggers the Validate and Save Attachment script.

    To get to the hidden Close button, you can do one of two things:
    1. Temporarily move the Create button. If you do this, be sure to move it back when you are done.
    2. Select the Objects tab, find and select the Create button in the list of objects, and then click the eye icon (see below) to temporarily hide it from view in Layout mode.
  1. Enter Browse mode so you can save and review your work.

Step 6 - Review your work

  1. In Browse mode, navigate to the Attachments tab for a session and click the Add Attachment button. The card window should now display a document icon and the text "Drag and Drop" with an Insert button beneath the Attachment field.
  2. Click the Insert button to add an attachment file. After adding the file, you should now see Open, Replace, and Clear buttons beneath the Attachment field. Click the Open button and the attachment file should be opened automatically in another application, such as Preview. Click the Replace button and you will be prompted to select a different attachment file. Click the Clear button and you will be prompted to confirm that you want to remove the attachment.
  3. Back on the Session Detail > Attachments tab, click the Add Attachment button and then click the Create button without actually inserting an attachment file. You should see an error message indicating an attachment is required.