Build-On Tutorial:

iPad Schedule

iPad Schedule: Lesson 3

Filter Session List

Lesson Overview

The objective for this lesson is to create functionality to allow a user to filter an event’s session list by date, category, or both. You will create new fields, value lists, a script, and buttons to accomplish this.

Here is a sneak peek of what you will build:

Step 1 - Create new fields for capturing filter selections

The first step is to create fields to capture the user’s selected session filter options.

  1. Open the Manage Database dialog (File > Manage > Database…) and activate the Tables tab.
  2. Double-click on the Globals table to see the list of fields it contains.
  3. Add two new fields to the Globals table:
    1. g_Session_Date_Filter (date)
    2. g_Session_Category_Filter (text)
  1. For each field, double-click on the field name (or select it and click the Options button), to open the Field Options dialog.
    1. Activate the Storage tab.
    2. Check the Use global storage (one value for all records) box. Fields with this setting are referred to as global fields. Global fields are helpful for storing or capturing information not specifically belonging to a record. Note that the Event Management Template uses the field name prefix “g_” to indicate global fields.
  1. Close the Manage Database dialog to save the new fields.

Step 2 - Create new value lists for the filter fields

Next you will create value lists that will display the range of session dates and categories for sessions related to a selected event. The value lists will utilize a new relationship, which you will create, to determine the sessions related to the selected event. You will also create a new calculation field to include the day of the week in the value list for session dates.

  1. Open the Manage Database dialog and activate the Relationships tab.
  2. Use the Add a Table button at the bottom of the graph to create a new table occurrence of the Session table, and name it _global_SESSION_SelectedEvent.
  1. Drag the new table occurrence to the right of the _GLOBAL table occurrence at the top of the graph. Then click the top-right corner of the _GLOBAL table to expand it so its fields are displayed.
  1. Create a relationship between _GLOBAL and _global_SESSION_SelectedEvent by clicking in the g_ID_Event_Selected field in _GLOBAL and dragging over to the ID_Event field in _global_SESSION_SelectedEvent.
  1. Switch to the Tables tab, and double-click on the Session table to view its fields on the Fields tab.
  2. Create a new calculation field named “zz_Day_Name”.
    1. In the resulting Specify Calculation dialog, set the following formula: DayName ( Date ).
    2. At the bottom of the dialog, set Calculation result is to Text.
  1. Close the Manage Database dialog to save your work.
  2. Open the Manage Value Lists dialog and create a new value list.
    1. Name the value list “Sessions | Session Date by Selected Event”.
    2. Check the Use value from field button.
    3. In the resulting Specify Fields for Value List dialog, in the Use value from first field area, first choose the table _global_SESSION_SelectedEvent, and then choose the field Date.
    4. Check the Also display values from second field option, and in the same table, choose the new field zz_DayName.
    5. Check the Include only related values starting from: button, and choose the table _GLOBAL.
    6. Set the Sort values using: option to First field.
    7. Click OK twice to save the new value list.
  1. Duplicate the new value list and name it “Sessions | Session Category by Selected Event”.
    1. Modify it to display Category as the first field.
    2. Uncheck the Also display values from second field box.
    3. Save the new value list.
  1. Close the Manage Value Lists dialog to save your work.

Step 3 - Add the filter fields to the session list layout

  1. Enter Layout mode and navigate to the iPad | Session List layout.
  2. Select the Header part handle and set its height to 162 pt tall. This is to make room for the new filter fields.
  1. Select the Line tool in the status toolbar.
  1. Using the Line tool, draw a horizontal line in the Header part.
    1. The line should span the width of the layout. Set its width to 768 pt, and if necessary, set its height to 0 pt to ensure it is perfectly horizontal.
    2. Set top, left, and right anchors.
    3. Move it slightly under the g_App_Logo field with a left position of 0 pt and a top position of 88 pt.
  1. Duplicate the Date field and change it to the new _GLOBAL::g_Session_Date_Filter field.
  2. Use the Data tab of the Inspector to configure the field as a pop-up menu displaying the selected event’s session dates:
    1. Set the Control style to Pop-up Menu.
    2. In the Values from box, choose the value list Sessions | Session Date by Selected Event.
    3. Uncheck both the Include arrow to show and hide list and Override data formatting with value list boxes.
  1. Further modify the field as follows:
    1. Set its Width to 144 pt and Height to 36 pt.
    2. Set top and left anchors.
    3. Set the style to txt Filter.Blue.
    4. In the Field section of the Data tab of the Inspector, set its Placeholder text to “All”, as shown below.
    5. In the Behavior section of the Data tab, enable Field entry in Browse Mode. Since this is a filter field, the user needs to be able to enter it.
    6. In the Data Formatting section of the Data tab, set the Format to 12/25/2014, and under Leading character, include leading zero’s for both day and month numbers.
  1. Duplicate the field and change it to the new g_Session_Category_Filter field.
    1. Assign it the value list Sessions | Session Category by Selected Event value list.
    2. Resize it to 200 pt wide.
  2. Use the text tool to add a text label named “Filter by Date:” next to the date filter field. Assign it the style label Left. Then duplicate it and change the second label to “Category:”.
  3. Arrange the new labels and fields as shown below.
  1. Enter Browse mode to save and review your work.

Step 4 - Create a filter script

Next you will create a script that filters the event session list based on the filters the user has selected.

  1. Open the Script Workspace and duplicate the Template Script. Name the new script “iPad: TRIGGER Filter Session ( clear_option )” and move it into the iOS UI > iPad script folder.

    Note: The “TRIGGER” portion of the script name indicates this script can be called by a script trigger. You will learn more about this later on in the lesson.
  2. The script name indicates this script takes a parameter named “clear_option”. This is an optional parameter that, when specified, indicates which filter(s) should be cleared. Amend the “Parameters” comment in the script to indicate this.

    Note: The # and #Assign custom functions are used to pass and parse parameters. The # custom function is generally used to define a script parameter and accepts a key-value pair; the #Assign custom function is called in the script and turns key-value pairs into script variables. You will practice passing parameters with these functions in a later step.

# Parameters:        Specify using # function:
     $clear_option (optional) = date, category, all (to clear the specified filter or all filters)

  1. Add the highlighted script steps to modify the script to parse the parameters and require the starting context to be the Session table. It should then perform a search based on the filters and clear options specified and sort the results.

    NOTE: See Step 4 for additional detail on the Show Custom Dialog script step.

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" ]
End If

# required context
If [ Get ( LayoutTableName ) ≠ "SESSION" ]
   Show Custom Dialog [ “Alert" ; "This script can only be run from a Session screen.” ]
   Exit Script [ Text Result: $null ]
End If

# handle optional behavior
If [ $clear_option = "date" or $clear_option = "all" ]
   Set Field [ _GLOBAL::g_Session_Date_Filter ; "" ]
End If
If [ $clear_option = "category" or $clear_option = "all" ]
   Set Field [ _GLOBAL::g_Session_Category_Filter ; "" ]
End If

# perform search...
Enter Find Mode [ Pause: Off ]

# ...start with selected event
Set Field [ SESSION::ID_Event ; "==" & _GLOBAL::g_ID_Event_Selected ]

# ...then add search criteria
If [ not IsEmpty ( _GLOBAL::g_Session_Date_Filter ) ]
   Set Field [ SESSION::Date ; _GLOBAL::g_Session_Date_Filter ]
End If
If [ not IsEmpty ( _GLOBAL::g_Session_Category_Filter ) ]
   Set Field [ SESSION::Category ; _GLOBAL::g_Session_Category_Filter ]
End If

# ...and perform find
Set Error Capture [ On ]
Perform Find [ ]
Set Error Capture [ Off ]

# sort results
Perform Script [ Specified: From list ; “iPad: Sort Session” ; Parameter: ]

Exit Script [ Text Result: $null ]

  1. For the Show Custom Dialog script step, only the Default Button should be specified, with the button text “OK”.
  1. Save and close the script.

Step 5 - Update script to clear filter fields

Since the user will be selecting values in the date and category filter fields, you need to create a process to clear those fields each time the user lands on the iPad | Session List layout. To do this, you will modify the iPad: Go to Event Session List script.

  1. In the Script Workspace, open the iPad: Go to Event Session List script.
  2. After the # set selected event portion of the script, add the following Set Field steps to initialize the date and category filter fields.

# clear session filter fields
Set Field [ _GLOBAL::g_Session_Category_Filter ; "" ]
Set Field [ _GLOBAL::g_Session_Date_Filter ; "" ]

  1. Save and close the script.

Step 6 - Create triggers and buttons to perform filtering actions

With the filter script in place, now you will create script triggers and buttons so the user can activate the filter when she selects a date or category filter option, and also remove the filter(s) to show all sessions again.

  1. Return to the iPad | Session List layout in Layout mode.
  2. Right-click on the g_Session_Date_Filter field and choose Set Script Triggers… (You can also add a script trigger by selecting the field and then choosing the Format > Set Script Triggers… menu). In the resulting Set Script Triggers dialog:
    1. Select the OnObjectModify checkbox.
    2. In the resulting Specify Script dialog, choose the script iPad: TRIGGER Filter Session ( clear_option ).
    3. You do not need to specify a script parameter.
  1. Assign the same script trigger to the g_Session_Category_Filter field.
  2. Now add a button to the right of the date filter field:
    1. Select the Display only an icon button, and assign it the “X” icon identified below. Set the icon size to 20 pt.
    2. Configure it to run the new iPad: TRIGGER Filter Session ( clear_option ) script, with the parameter: # ( “clear_option” ; “date” ).
  1. Further modify the button from the layout:
    1. Assign it the style btn icon.Blue.
    2. Set its width to 32 pt and height to 34 pt.
  2. In the Inspector, assign it the hide condition: IsEmpty ( _GLOBAL::g_Session_Date_Filter ). This will make it so the button only appears when a date filter has been selected.
  1. Duplicate the button.
    1. The new button should run the same script, but modify the parameter to: # ( “clear_option” ; “category” ).
    2. Assign it the hide condition: IsEmpty ( _GLOBAL::g_Session_Category_Filter ). The button will only appear when a category filter has been selected.
  2. Arrange the buttons as shown below.
  1. Create another new button to the right of the filter fields.
    1. Configure it to display only a label, and set the label to “Clear All”.
    2. It should run the same script as the “X” buttons above, but set its parameter to: # ( “clear_option” ; “all” )
    3. Assign it the style: btn Minimal.Blue.Previous.
    4. Assign it the hide condition: IsEmpty ( _GLOBAL::g_Session_Date_Filter ) or IsEmpty ( _GLOBAL::g_Session_Category_Filter ). This makes it so the Clear All button only appears when both the date and category filters have been specified.
  1. Resize the Clear All button to 88 pt wide and 36 pt tall, and position it as shown below.
  1. Enter Browse mode to save and review your work.

Step 7 - Review your work

  1. With the file open using FileMaker Pro Advanced on your desktop, open the Script Workspace and manually run the iPad: Startup script to go to the iPad | Event List layout.
  2. Select an event on the iPad: Event List layout to go to the iPad: Session List layout displaying the sessions for the event.
  3. In the date filter field, select a date from the list. The session list should now be filtered for the selected date. The X button should also appear; click it to show all sessions again.
  4. In the category filter field, select a category from the list. The session list should now be filtered for the selected category. The X button should also appear; click it to show all sessions again.
  5. Now try filtering for both a date and a category. The Clear All button should appear; click it to clear both filters and show all sessions again.
  6. Try performing various filters to verify you get the results you expect.
  7. Once you have finished testing iPad functionality on your desktop device, choose the View > Status Toolbar menu to gain access to the FileMaker toolbars again.
  8. Transfer the file to your iPad and open it (or host the file with FileMaker Server and open it remotely). Repeat the above steps to test the filter functionality on the iPad.