Build-On Tutorial:

iPad Attachments

iPad Attachments: Lesson 1

View Job and Task List from iPad

Lesson Overview

The objective for this build-on is to allow iPad users to log in to your app and add attachments to a task, and to allow desktop users to see these attachments. The first step is for iPad users to select a Job and Task to add their attachment to.

In this lesson, you will create a new table for attachments, then create a multi-purpose iPad list layout. This layout will let users see existing attachments, and also select a Job and Task they want to add an attachment to. In the next lesson you will build functionality so users can add new attachments.

Here is a sneak peak of what you will build for this lesson. (Note: You will not add any data at this point, so the attachment list will be empty.)

Step 1 - Add Attachment table and fields

Add a new Attachment table and associated fields.

  1. Open the Manage Database dialog using the File > Manage > Database... menu item.

    Note: You can also open the Manage Database dialog while in Layout mode by selecting the Manage drop-down icon in the top right of the tool bar, and then selecting Database, or you can use the keyboard shortcut Command-Shift-D (macOS) / Control-Shift-D (Windows).
  2. Navigate to the Tables tab duplicate the Template table by selecting it in the list, clicking the Copy button, and then clicking the Paste button. (You can also use the standard copy and paste keyboard shortcuts.)
  3. Change the name of the table from “Template 2” to “Attachment” and then click Change.

    Note: This table will represent the many side of the one-to-many relationship between Task and Attachment (each task can have multiple attachments, but each attachment will only belong to one task). Therefore, you will add a foreign key here to relate tasks and attachments.
  4. Now, navigate to the Fields tab. Be sure Attachment is selected in the Table: drop-down.
  5. Create a new field for the foreign key that will link an attachment to a task. Add a new field named ID_Task. For Type, select Text.
  6. Also add the following fields:
    1. Document (Container)
    2. Description (Text)
  7. Now create a field that will record the date an attachment was added, by adding a new field called Date_Added. Set the Type: to Date. Update the field options:
    1. Click Options… to bring up the field settings.
    2. In the Auto-Enter tab, check Creation and select Date from the drop-down.
  8. Next, create a field that will automatically update the name of the attachment based on the name of the file uploaded. Add a new field called Name and set Type: to Text. Update the field options:
    1. Click Options…
    2. In the Auto-Enter tab, check Calculated Value.
    3. In the subsequent dialog, enter the follow calculation:

         GetContainerAttribute ( Document ; "filename" )

    4. Back in the Options for Field “Name” dialog, uncheck Do not replace existing value of field (if any).

      Note: When a new attachment is added, this calculation will update the Name field to be the name of the file that is added. Unchecking the Do not replace… option will prompt the Name field to update each time the user inserts a different document into the record.
  9. Finally, add one more field that will automatically set the type of document added based on the file extension. Add a new field called Type and set Type: to Text. Update the field options:
    1. Click Options…
    2. In the Auto-Enter tab, check Calculated Value.
    3. In the subsequent dialog, enter the follow calculation (this calculation uses a custom function that already exists in your file):

         _Get_File_Extension ( Document )

    4. Back in the Options for Field “Type” dialog, uncheck Do not replace existing value of field (if any).
  10. The Attachment table should look like this:
  1. Navigate to the Relationships tab, and locate the Attachment table occurrence. Double-click the table and change the Name to ATTACHMENT. Leave the rest of the relationships graph as-is for now — you will update that in a later step.

Step 2 - Add a new layout

In this step you will create the new iPad layout by duplicating the existing Blank | iPad - List layout.

  1. FileMaker automatically created an Attachment layout when you created the new table. Using the Manage Layouts window, move that layout into the Developer folder, and rename it with a “dev_” prefix so it matches the other developer layouts.
  2. Enter Layout mode using the Edit Layout button in the status toolbar.

    Note: You can also enter Layout mode using the View > Layout Mode menu item, or the keyboard shortcut Command-L (macOS) / Control-L (Windows).
  3. Use the Layout pulldown menu in the status toolbar to switch to the Blank > Blank | iPad - List layout.
  4. Duplicate the layout using the Layouts > Duplicate Layout menu item.

    Note: You can also use the Manage Layouts dialog (File > Manage > Layouts...) to duplicate a layout. This dialog is also useful for organizing and reordering your layouts.
  5. Using the Layout Setup dialog (Layouts > Layout Setup…):
    1. Rename the layout to "iPad | Attachment - List“.
    2. Change the Show records from: dropdown to the ATTACHMENT table occurrence. This setting determines the context of the layout.

      Note: The iPad layout has been sized smaller than a standard iPad size. You may later decide to resize this layout based on the size of your iPad.

Step 3 - Add fields to the layout

Next, you will add fields and text objects to the new layout and specify styles for them.

  1. You should still be in Layout mode after completing Step 2. If not, re-enter Layout mode.
  2. Double-click on the "Title" text in the header so you can edit it. Change the text to “View Attachments".
  3. Remove the sample label and field. Open the Fields tab. (If the Fields tab is not open, click the icon in the status toolbar to Show the objects pane, then click Fields.) At the bottom of the Fields tab, set the Drag Preferences to Place fields horizontally when being dragged to the layout and No labels for fields dragged to the layout. Select the Document, Name, Description and Date_Added fields and drag and drop them to the body of the layout. For now, your layout will look like this:
  1. Open the Inspector using the View > Inspector menu item (you can also access it using keyboard shortcut Command-I (macOS) / Control-I (Windows)).
  2. Activate the Styles tab of the Inspector, which is used for specifying object styles.
  1. Select the Document field on the layout and apply the container Minimal style for it in the Inspector.
  2. Similarly, select and assign styles to the other fields:
    1. Date_Added: style as txt Minimal.Black.Right
    2. Description: style as txt Minimal.Gray.Left
    3. Name: style as txt Minimal.Black.Left
  3. Select the Description field. Activate the Position tab of the Inspector and adjust the Autosizing options to anchor top, right, and left. This will allow the field to stretch horizontally as the layout is resized.
  1. Repeat Step 8 for the following fields, setting the anchors as noted:
    1. Document and Name — top and left (this is the default)
    2. Date_Added — top and right
  2. You do not want users to edit data on this layout. Select the Document, Name, Description, and Date_Added fields. On the Data tab of the Inspector, scroll down to Behavior and under Field entry uncheck Browse Mode.
  1. Finally, add labels in the header for the list. Select the Text tool from the status toolbar and add the following text objects to the header: “Attachment”, “Description”, “Date Added”, and style all of them as label List.Left. Adjust the Date Added label to anchor top and right.
  2. Arrange and resize the fields so they fit in the body as shown in the screenshot below:

Step 4 - Add filter fields for Job and Task

When a user opens the app, you want them to see a list of attachments for a specific Job and Task. They will select a Job from a drop-down list, then select an associated Task from another drop-down list. To achieve this functionality, you will add global fields to the header that will be assigned specific value lists. Global fields are fields that have been set to use global storage. They contain one value that is used for all records in the file.

  1. On the Fields tab, first click the drop-down to select the _GLOBAL table, then add the _GLOBAL::g_Filter_Job field to the Header of the layout.
  2. You want users to be able to select from a list of Jobs when they tap the g_Filter_Job field. In order to do this, you will create a Value List using the set of values in another field (in this case, the Job_Name). To add a new value list, select File > Manage > Value Lists… and select New.
    1. Name the new value list “Attachment | Job IDs by Task”.
    2. Select Use values from field:
    3. In the subsequent dialog, under Use values from first field, select the TASK::ID_Job field.
    4. Check Also display values from second field, and select the task_JOB::Job_Name field.
    5. Select Include all values.
    6. Check Show values only from second field. With this setting, the field will store the ID_Job value, but the user will see the Job_Name.
  1. To apply the new value list to the g_Filter_Job field, select the field on your layout then navigate to the Data tab of the Inspector.
    1. For Control Style select Pop-up Menu.
    2. For Values from: select the new list, Attachment | Job IDs by Task.
    3. Check Include arrow to show and hide list and Override data formatting with value list.
    4. Add “Select a Job” as the Placeholder text (when field is empty).
  1. For the Task filter, you will need to create a new global field. Open the Manage Database dialog and navigate to the Fields tab.
    1. For Table: select the Global table.
    2. Create a new field called “g_Filter_Task” (Type is Text).
    3. Select Options…
    4. Select the Storage tab and check Use global storage (one value for all records).
  1. Just as you did for the Job filter, you will need to assign a value list to the Task filter. Users should be able to see the tasks that are related to the job they selected in the Job filter. To accomplish this you will create a new relationship between the _GLOBAL table occurrence and the Task table occurrence. That relationship will relate the ID of the selected job to the ID_Job of the task.

    You should still be in the Manage Database dialog from the previous step. If not, open the Manage Database dialog. Navigate to the Relationships tab.
    1. Locate the _GLOBAL table occurrence and move it to the bottom of the graph.
    2. Add a new table occurrence based on the Task table: begin by selecting the Add a table icon from the toolbar below the graph. From the Specify Table dialog, select the Task table, and name the table occurrence “_global_TASK__byJob”. Move the new table occurrence to the right of the _GLOBAL table occurrence.
    3. Create a new relationship between the two table occurrences by selecting the Create a relationship icon from the toolbar.
    4. On the left side of the Edit Relationship dialog, select the _GLOBAL table from the Table: drop-down.
    5. Under the _GLOBAL table, select the g_Filter_Job field.
    6. On the right, select _global_TASK__byJob from the Table: drop-down.
    7. Under the _global_TASK__byJob table, select the ID_Job field.
    8. Make sure the = operator is selected from the drop-down in the middle.
    9. Select Add.  

      Note: You can also create this relationship within the graph itself: Under the _GLOBAL table occurrence, select the g_Filter_Job field and click and drag the line to the ID_Job field of the _global_TASK__byJob table occurrence.
  2. Back on the Attachment List layout, add the g_Filter_Task to the header.
  3. Users should be able to select from a list of tasks related to the selected job when they tap the g_Filter_Task field. To achieve this, you will create a value list based on fields using the relationship you created in Step 5. Open the Manage Value Lists dialog and create a new value list:
    1. Name the new value list “Attachment | Task ID by Job Filter (global)”.
    2. Select Use values from field:
    3. In the following dialog, under Use values from first field, select the _global_TASK__byJOB table, then the ID field.
    4. Check Also display values from second field, and select the _global_TASK__byJOB table, then the Task_Name field.
    5. Select Include only related values starting from: and select _GLOBAL from the drop-down.
    6. Check Show values only from second field.
  1. To apply the value list to the g_Filter_Task field, select the field and navigate to the Data tab of the Inspector.
    1. For Control Style select Pop-up Menu.
    2. For Values from select the new list, Attachment | Task ID by Job Filter (global).
    3. Check Include arrow to show and hide list and Override data formatting with value list.
    4. Add “Select a Task” as the Placeholder text (when field is empty).
  2. Finally, select the Text tool from the status toolbar and add the following text objects as labels for each of the filters:
    1. “Job:" style as label Left
    2. “Task:" style as label Left
  3. Arrange the objects on your layout to look similar to this:

Step 5 - Add script to clear Task filter

Enter Browse mode and select a job from your new filter. The Task filter should populate with the correct tasks for that job. However, if you select a different job, you will notice the task filter looks odd. To correct this, you will add a new script that will clear the task filter once a different job is selected. This new script will be called by a script trigger.

A script trigger is an event that occurs in conjunction with another action (for instance, entering a layout, modifying a field, opening the file, etc.). Your new script will be triggered when the user modifies the Job filter.

Note: If you have not worked with scripts before, you will find it helpful to review the Creating and Editing Scripts section of the FileMaker Pro Advanced Help system before starting this task.

  1. Open the Script Workspace (Scripts > Script Workspace...) and duplicate the Template Script, and rename it “TRIGGER_iPad | Attachment - Clear Task Filter”.

    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. 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: The Show All Records and Show Omitted Only steps will not be evident until you have attachment data in your file. These steps are designed to clear the list completely when a user changes the Job selection, so no records are shown until the user chooses a task.

Set Field [_GLOBAL::g_Filter_Task ; “”]
Show All Records
Show Omitted Only

  1. Back on the Attachment List layout, enter Layout mode.
  2. Right-click the the g_Filter_Job field and select Set Script Triggers…
    1. Select OnObjectModify as the Event and select TRIGGER_iPad | Attachment - Clear Task Filter script from the list.
    2. Exit out of the dialog, then enter Browse Mode to save your work.

Step 6 - Update scripts

In your file, a script manages some actions that occur when the file is first opened. You will modify that opening script so it will check which device the user is on (desktop or iPad) and then navigate to an appropriate layout. These changes make use of two custom functions already added to the core file (_DEVICE_Desktop and _DEVICE_iPad).

Note: the Build-On for iPad time entry also redirects users to an iPad layout in the opening script. If you plan to add both iPad build-ons, you will need to choose where to direct iPad users when they open the file. You may want to add an additional iPad home page with navigation, so mobile users can choose whether to enter time or add attachments.

  1. Open the Script Workspace and select the TRIGGER_On Open script from the list of scripts on the left of the dialog. (General > TRIGGER_On Open)
  2. Modify the script so the user is taken to the Dashboard layout if they are on a desktop. Add these script steps:

# If user is on desktop, go to dashboard.
If [_DEVICE_Desktop = True]   
   Go to Layout ["Dashboard" (_Global) ; Animation: None ]     
   Adjust Window [ Resize to Fit ]     
   Move/Resize Window [ Current Window ; Top: 0 ; Left: 0 ]
End If

  1. Add another If block around the final Go To Layout step, just before Exit Script. These steps will navigate iPad users to the new iPad layout, clear the filter fields, and will not show any records.

    Note: Setting the zoom level to Lock: On; 100% disables the zoom feature on the iPad so users don't accidentally zoom in, and Show/Hide Toolbars hides the FileMaker toolbars, resulting in a more "iOS" user experience.

If [_DEVICE_Desktop = True]
   #If user is on desktop, go back to dashboard.
   Go to Layout [“Dashboard” (_GLOBAL) ; Animation: None]

Else If [_DEVICE_iPad = True]

   #If user is on iPad, go the iPad attachment list.
   Go to Layout [“iPad | Attachment - List” (ATTACHMENT) ; Animation:None]

   #Start with no filters set
   Set Field [_GLOBAL::g_Filter_Job ; “”]
   Set Field [_GLOBAL::g_Filter_Task ; “”]

   Set Zoom Level [Lock: On: 100%]
   Show/Hide Toolbars [Hide]

   #Start with an empty found set
   Show All Records
   Show Omitted Only
End If

Step 7 - Review your work

Note: You will not have any data at this point so the attachment list will be empty.

Also, 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 an iPad, open the file using FileMaker Go. The Attachments List layout should open by default.
  2. Tapping the “Select a Job” filter should show a list of jobs.
  3. When a job is selected, tapping on “Select a Task” should bring up a list of tasks for that job.
  4. When a different job is select, the task filter should clear and you should see “Select a Task”.