Build-On Tutorial:

iPad Attachments

iPad Attachments: Lesson 2

Add Attachments from iPad

Lesson Overview

The objective for this lesson is to create a new layout and scripts so iPad users can add attachments to tasks. You will use some fields and scripts that already exist in your file.

Here is a sneak peek of what you will build:

Step 1 - Add a new layout

First you will create a new iPad layout.

  1. Create a new iPad layout by duplicating the existing Blank | iPad - Card layout.
  2. Rename the new layout to “iPad | Attachment - Card”.
  3. Set Show records from: to ATTACHMENT.
  4. Open the new layout and enter Layout mode.

Step 2 - Add fields

  1. Remove all objects on the layout except for the text object in the Header. Edit the text in the Header and change it to “Add New Attachment”.
  2. Add the Document container field to the Body of the layout. This field will show the file — whether it is a photo, video, PDF, or some other document — so you want to make the field large.
    1. In the Position tab of the Inspector, adjust the Size by setting the width to 416 pt and the height to 216 pt.
    2. In the Style tab, set the style to container.
    3. Move the field just below the Header part of the layout.
  3. Add the following Attachment fields to the layout with labels positioned above the fields (double-click the field on the layout and click Create label in the Specify Field dialog box if they were not automatically added) and style the fields as txt.Black.Left via the Styles tab of the Inspector:
    1. Name
    2. Date_Added
    3. Description
  4. Next, add the Type field to the layout.

    Note: In Lesson 1, you made this field an auto-enter calculation that would automatically set this field based the the file extension. However, users may want the ability to change this (for instance, if the file is an extension that is not recognized by the calculation, it defaults to “Other”). To achieve this you will create a custom value list for the field.
  5. Add a new value list (File > Manage > Value Lists…).
    1. In the Edit Value List dialog set the name to “Attachment | Document Type”.
    2. Select Use custom values.
    3. Add the following text as the value list:

         Photo
         Video
         Audio
         -
         PDF
         Document

         -
         Signature
  6. Back on the layout, select the Type field, then on the Data tab of the Inspector:
    1. Change the Control style to Pop-up Menu.
    2. For Values from: select Attachment | Document Type.
    3. Check Include arrow to show and hide list and Allow editing of value list.
  7. Finally, amend the labels above each field if needed so they are user-friendly, and style them as label Left:
    1. “Name”
    2. “Date”
    3. “Type”
    4. “Description”
  8. Arrange the text and fields to look similar to this:

Step 3 - Create scripts to add new attachments

Now you will add scripts to help users smoothly follow a data-entry workflow.

Users will: Open the iPad, select a job from a drop-down, select a task from the other drop-down, then see a list of attachments associated with that Task (if the data exists). They can click a button to add a new attachment, and then in the subsequent card window they can add a document to the selected task.

  1. Create a new script to allow users to create a new attachment for a given task. Open the Script Workspace, duplicate the template script and re-name it “Attachment | Add New Attachment”.

    Any time you copy the template script, be sure to amend the comments at the top to fit your current script, and move the script to an appropriate folder. If you haven’t already, you may want to create a new folder to hold all of the scripts you will create for this Build-On, and name it “Attachments”.
  2. Add the following script steps:

    NOTE: See steps 3 - 4 for details on the Show Custom Dialog and the New Window script steps.

Set Error Capture [On]

Set Variable [$$CONTEXT ; Value: “Attachment”]

Set Variable [$task_id ; Value: _GLOBAL::g_Filter_Task]

#Verify a task has been selected. If not, tell user to select task.
If [ IsEmpty ($task_id)]
   Show Custom dialog [“Select Task” ; “Please select a task to add an attachment.”]
   Exit Script [Text Result: $null]
End If

New Window [ Style: Card; Using layout “iPad | Attachment - Card (ATTACHMENT)]

New Record/Request
Set Field [ATTACHMENT::ID_Task ; $task_id]

Commit Records/Requests [With dialog: Off]

  1. For the Show Custom dialog script step, adjust the settings in the “Show Custom dialog” Options dialog:
    1. Set Title to "Select Task”.
    2. Set Message to "Please select a task to add an attachment.”
    3. The only button should should be the Default Button with a label of “OK”.
  1. For the New Window script step, adjust the settings in the New Window Options dialog:
    1. Set Window Style to Card.
    2. Leave Window Name blank.
    3. Set Layout to “iPad | Attachment - Card”.
    4. Uncheck Close under Window Options.

      Note: A variable that is set using the prefix $$ (in this case, $$CONTEXT) is called a global variable and can be used across multiple scripts. You are setting the CONTEXT global variable here because later in this lesson you will reference an existing script that requires this variable.

      Setting the Set Error Capture step to On will suppress any automatic error messages, so you can present your users with a more helpful error message. For this script, you added a custom dialog in the event the user has not selected a task to add the attachment to (i.e., the g_Filter_Task field is empty).
  1. In your file, there is a reusable script designed to save and close a card window. You will use this script for the card window you created in Step 1. Amend this script to add a requirement that the user must first add a document before the record is saved:
    1. Open the Save Record in Card Window (context) script.
    2. Add the following Else If statement to the existing If statement:

      NOTE: For the Show Custom Dialog step: in the Show Custom Dialog Options dialog, delete the Button 2 option, leaving only the Default Button: “OK”.

#BUILD-ON | ATTACHMENT
Else If [$$CONTEXT = “Attachment”]

   #Verify a document has been added to attachment.   
   If [IsEmpty (ATTACHMENT::Document)]
      Show Custom Dialog [“Error” ; “A document is required.”]
      Exit Script [Text: $null]
   End If

End If

  1. Create a script to refresh your list on the iPad | Attachment - List layout so that when a user selects a task, the list will show attachments for that task. From the attachment list layout this script will be called via a script trigger, when the user selects a task.

    Duplicate the Template Script, and name your new script “TRIGGER_iPad | Attachment - Find Attachments”.
  2. Add the following script steps:

    NOTE: See steps 8 - 9 for details on the Set Error Capture and Sort Records script steps.

Set Variable [$task_id ; Value: _GLOBAL::g_Filter_Task]

If [IsEmpty ($task_id)]
   # When no task is selected, show no records
   Show All Records
   Show Omitted Only
   Exit Script [Text Result: $null]
End If

Enter Find Mode [Pause: Off]
Set Field [ATTACHMENT::ID_Task ; $task_id]
Perform Find []

Sort Records [Restore; With dialog: Off]
Go to Records/Request/Page [First]

  1. Change the Set Error Capture step to [On] to suppress error messages.
  2. For the Sort Records step, click blue gear icon to right and click Select to bring up the dialog. Add the zz_Log_Create_Record_TS to the Sort Order and set it to sort Descending.
  1. The script to find and sort your attachment list should also run whenever your team adds new attachments, so the list will update to show the new information. To do this, update the Save Record in Card Window (context) script so it runs your new find/sort script. Open the Save Record in Card Window (context) script and add the following script steps after the Close Window step:

If [$$CONTEXT = “Attachment” and _DEVICE_iPad = True]
   #If adding attachment from iPad, rerun the find script to update the list to show new record.
   Perform Script [Specified: From list; “TRIGGER_iPad | Attachment - Find Attachments” Parameter: ]
   Go to Record/Request/Page [First]
End If

Step 4 - Add buttons

Now that you have the appropriate scripts, you can add buttons to the layouts to call these scripts.

  1. Create a button to call the script to add new attachments. Enter Layout mode and navigate to the iPad | Attachment - List layout.
  2. Select the Button Tool from the status toolbar and add a new button to the footer. In the button setup dialog:
    1. Choose the Display only a label icon, and add the label “Add Attachment”.
    2. Set the Action to Perform Script.
    3. Select the script Attachment | Add New Attachment from the list.
  1. Close the Button Setup dialog.
  2. Leave the button as the Default style, and adjust the Autosizing to anchor top and right.
  3. Your layout should look like this:
  1. Add a script trigger to call the TRIGGER_iPad | Attachment - Find Attachments script. You want the script to run after a user selects a task:
    1. Right-click the g_Filter_Task field and select Set Script Triggers…
    2. Choose OnObjectModify as the Event and select the TRIGGER_iPad | Attachment - Find Attachments script from the list.
  2. Next, add a button to the card window to run the script to save a new attachment. Navigate to the iPad | Attachment - Card layout and add a new button to the bottom of the layout.
    1. Choose the Display only a label option, and add the label “Create”.
    2. Set the Action to Perform Script.
    3. Select the script Save Record in Card Window (context) from the list. (The context in this case is the global variable you set elsewhere, so you do not need to include it as a parameter here.)
    4. Close the Button Setup dialog.
    5. Leave the button as the Default style.
  3. Create a button to close the card window. This button will call a script that already exists in the Job Tracking core file. This script closes the card window, in the event the user wants to exit the card window without creating a new attachment.
    1. Choose the Display only a label option, and add the label “Cancel”.
    2. Set the Action to Perform Script.
    3. Select the script Cancel and Close Card Window from the list.
    4. Close the Button Setup dialog.
    5. Set the style to btn.White.
  4. You want users to know that from the iPad they can tap into the Document field to add a new document. (By design, when a user taps into a container field using FileMaker Go, an Import list pops up prompting the user to select what type of file to import — but your team might not know that without a visual aid.)

    To prompt users to tap into the container field, add and empty button with a “+” to indicate they can tap to add documents:
    1. Still on the iPad | Attachment - Card layout, create a new button.
    2. Choose the Display only an icon option, and select the “+” icon.
    3. Set the icon size to 52.
    4. Leave the Action as Do nothing.
    5. Set the style to btn.Minimal Gray.
    6. Place the button over the Container field.
    7. You want to hide this button when the Document field contains data. In the Data tab of the Inspector, set Hide Object when to the following formula:

not IsEmpty ( ATTACHMENT::Document )

  1. Arrange the buttons so your layout looks like this:

Step 5 - Update list layout

Using the iPad, test out some of the features you have created so far. The functionality works as it should, but the iPad | Attachment - List layout itself can be confusing when there are no attachments to show for the task selected. You will update this layout to address this and improve the user experience.

If there are no attachments associated with the selected task, you will display text explaining this to the user.

  1. Because you are using a list view, you will first need to create a new layout part to hold the text:
    1. From the menu, select Layout > Part Setup…
    2. In the Part Setup dialog, click Create…
    3. Select Trailing Grand Summary.
    4. Style the new part as background Minimal.White and set the height to 55 pt.
  2. Add text to show when there are no records:
    1. Using the Text tool, add "There are no attachments for this task” to the Trailing Grand Summary part.
    2. Style it as label Center.
    3. Set Autosizing to anchor left, right, and bottom.
    4. You do not want the text to be visible if there are attachments to show. Select the text, then the Data tab of the Inspector, enter the following formula for Hide object when (and check Apply in Find mode ):

Get ( FoundCount ) ≠ 0
or
IsEmpty( _GLOBAL::g_Filter_Task )

  1. Add similar text to display before the user has selected a job and task:
    1. Duplicate the text you just created stating there are no attachments for this task.
    2. Change the text to “Select a Job & Task”.
    3. You do not want button to be visible once the user has selected a job and a task.

      Note: Typically, a Trailing Grand Summary part displays a summary of information for all records in the found set and is displayed at the end of the list. In this instance, you are not summarizing any data, rather using this part to display a message when the found count is null. Because the part appears at the end of the list, it will appear whether or not there are records present.

      In the Data tab of the Inspector, enter the following formula for Hide object when (and check Apply in Find mode ):

not IsEmpty( _GLOBAL::g_Filter_Task )
  1. Because the user must select a job before they can select a task, you can hide the g_Filter_Task field and its label until a job has been selected. Select the g_Filter_Task field and label and in the Hide object when area, add the follow formula:
IsEmpty( _GLOBAL::g_Filter_Job )
  1. Update the Add Attachment button to behave similarly — the user should not be able to add a new attachment until a task is selected. Select the Add Attachment button and in the Hide object when area, add the following formula:
IsEmpty( _GLOBAL::g_Filter_Task )
  1. Finally, add some separation between the header and the Job and Task filter fields. Select the Line Tool from the status toolbar and add a line under the g_logo field, stretching it the full length of the layout. Arrange the Position as follows:
  1. Your iPad | Attachment - List layout should look similar to this:

Step 6 - Review your work

Note: Because this file uses the _DEVICE_iPad function, the iPad-specific features will not function properly if tested from the desktop. Be sure to test iPad functionally with an iPad. For more on sharing files with FileMaker Go clients, see FileMaker Help.

  1. Using FileMaker Go on an iPad, open the file. On the Attachments List layout, you should only see the “Select a Job” field, and the text below should read “Select a Job & Task”. The Add Attachment button should not be visible.
  2. Select a job. The “Select a Task” field should appear.
  3. Select a task. The text below should read “There are no attachments for this task”. The Add Attachment button should be visible.
  4. You should be able to add a new attachment.
  5. You should be able to tap in the Document container (which should show a “+” icon) and add a new document (or take a photo or video) from the iPad.
  6. Once a new document is added, the NameDate, and Type fields should populate accordingly.