Build-On Tutorial:

iPad Time Entry

iPad Time Entry: Lesson 4

Filter Tasks When Entering Time

Lesson Overview

The objective for this lesson is to add two filters to the Task List layout you created in Lesson 3, so that users can easily narrow down the list and find the task for which they want to add time. You will add filters for Job Name and Job Status.

Here’s a sneak peek of what you will build:

Step 1 - Add filter fields to the layout

Enter Layout mode and navigate to the iPad | Time Entry - Task List layout.

  1. Add the following fields to the header of the layout:
    1. _GLOBAL::g_Filter_Job (the ::g_Filter_Job field from the _Global table)   
    2. _GLOBAL::g_Filter_Status (the ::g_Filter_Status field from the _Global table) 
  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 a list of values from another field (in this case, the Job_Name). Select File > Manage > Value Lists… and select New.
    1. Name the new value list “Task | Job ID by Task”
    2. Select Use values from field:
    3. In the following dialog, under Use values from first field, select the TASK table from the drop-down menu and then select the ID_Job field.
    4. Check Also display values from second field, and select the task_JOB table from the drop-down menu and then select the ::Job_Name field.
    5. Select Include all values.
    6. Check Show values only from second field.

      Note: You use the TASK table occurrence here as the source for the value list because you only want to show jobs that have tasks assigned to them.
  1. Apply the new value list to the g_Filter_Job field. Select the field and navigate to the Data tab of the Inspector.
    1. For the Control Style select Pop-up Menu.
    2. For Values from select the new list, Task | Job ID by Task.
    3. Check Include arrow to show and hide list and Override data formatting with value list.
    4. Add “By Job” as the Placeholder text (when field is empty
  1. You will also use a value list for the Status filter. However, you will use a value list that already exists in your file. Select the g_Filter_Status field and apply the following settings in the Data tab:
    1. For the Control style select Pop-up Menu.
    2. Set Value from: to Task Status.
    3. Check Include arrow to show and hide list and Override data formatting with value list.
    4. Add “By Status” as the Placeholder text (when field is empty).
    5. Rearrange the fields so that your layout should look similar to this:

Step 2 - Create filter scripts

You will create new scripts to filter the task list based on the user’s selection (by Job, Status, both, or none). This script will not be activated by a button, but rather by a script trigger. A script trigger is an event that occurs in conjunction with some other action (for instance, entering a layout, modifying a field, opening the file, etc.) For the task filter, the script will be triggered when the user modifies either of the filter fields; the task list will automatically update when the user selects an option from the list.

  1. Open the Script Workspace, duplicate the Template Script and rename it “TRIGGER_iPad | Time Entry - Filter Task List”.
  2. Add the following script steps:
    1. Set the Set Error Capture step to On so that any automatic error messages are suppressed and you have control over the error message the user sees. For this script, you will add a custom dialog in the event an error occurs (i.e. there are no tasks found).
    2. Set the Sort Script to sort, in the following order:

      task_JOB::Job_Name — Ascending order
      Task::Status – Ascending order
      Task::Date_Due — Ascending order

    3. For the Show Custom Dialog step, set the Title to “No Tasks Found”, set the Message to “There are no tasks that match your request.”, and remove the text for Button 2 — you only want the OK button for this dialog.

Set Error Capture [On]  

If [ IsEmpty ( _GLOBAL::g_Filter_Job) and IsEmpty (_GLOBAL::g_Filter_Status)]
   Show All Records
Else
   Enter Find Mode [Pause:Off]
   Set Field [TASK::ID_Job ; _GLOBAL::g_Filter_Job]
   Set Field [TASK::Status ; _GLOBAL::g_Filter_Status]
   Perform Find []
End If   

# If there are no tasks that match the filter criteria...
If [Get (LastError) ≠ 0]
   # Let user know there are no tasks to show.
   Show Custom Dialog ["No Tasks Found" ; "There are no tasks that match your request.”]
   Exit Script [Text Result: $null]  
End If  

Sort Records [ Restore: With dialog: Off ]
Go to Record/Request/Page [First]
Scroll Window [Home]  

Exit Script [ Text Result: $null]

Step 3 - Set script triggers

Now set up the script triggers that will run the script you just wrote.

  1. Navigate to the iPad | Time Entry - Task List layout and enter Layout mode.
  2. Right-click the g_Filter_Job field and select Set Script Triggers…
    1. Choose OnObjectModify as the Event.
    2. Select the TRIGGER_iPad | Time Entry - Filter Task List script.
  3. Repeat step 2 for the g_Filter_Status field.

Step 4 - Clear filters

You want users to be able to easily clear out the filters and see all of the tasks. You will create a new script to accomplish this, and then add two new buttons to the layout that will call the script.

  1. Open the Script Workspace, duplicate the Template Script, and rename it “iPad | Time Entry - Clear Task List Filter”
  2. Add the following script steps:

Set Variable [ $parameter ; Value: Get (ScriptParameter)]  

If [$parameter = "Job" ]
   # Clear out job filter
   Set Field [_GLOBAL::g_Filter_Job; “”]
Else If [$parameter = “Status"]
   #Clear out status filter
   Set Field [_GLOBAL::g_Filter_Status; “”]
End If

   Commit Records/Request [With dialog: On]
   # Perform trigger script to update found set
   Perform Script [Specified From List: "TRIGGER_iPad | Time Entry - Filter Task List" ; Parameter: ]

  1. Back on the iPad | Time Entry - Task List layout, enter Layout mode.
  2. Add a new button to call this new script. In the Button Setup:
    1. Select Display only a label.
    2. Add “Clear” as the label.
    3. Set Action: to Perform Script.
    4. Select iPad | Time Entry - Clear Task List Filter from the list.
    5. Set Optional script parameter to “Job”.
    6. Style the button as btn Minimal.Blue.Next
    7. Move the button so it sits under the g_Filter_Job field.
  3. Repeat step 4, creating a clear button for the g_Filter_Status field, setting the script parameter to “Status” and place it under the g_Filter_Status field.
  4. Update the visibility for the Clear buttons, since you do not need to see the buttons when the respective filter fields are empty:
    1. Select the clear button that pertains to the g_Filter_Job field. Set the hide conditions to: IsEmpty ( _GLOBAL::g_Filter_Job )
    2. Select the clear button that pertains to the g_Filter_Status field. Set the hide conditions to: IsEmpty ( _GLOBAL::g_Filter_Status )
  5. Your layout should look similar to this:

Step 5 - Review your work

  1. Using the Time Entry layout on an iPad, tap Add Time Entry. The task list should pop up with the new filters in the header.
  2. You should be able to filter the task list by Job, Status, or both.
  3. You should be able to clear both filters by tapping Clear.
  4. When you clear both fields, the task list should show all of the tasks.