Build-On Tutorial:

Task Notes

Task Notes: Lesson 1

Add and edit task notes

Lesson Overview

The objective of this Build-On is to allow users to enter multiple, individual notes against a single task, so they can track the progress of a task over time. You will create a new table with fields for this purpose, and adjust the Task Detail layout to display the new data. You will complete the entire Build-on in this lesson.

Step 1 - Add Task Notes table, fields, and relationship

Create a new table and fields for tracking task notes.

  1. Open the Manage Database dialog (File > Manage > Database...) and activate the Tables tab.
  2. Duplicate the Template table by selecting it, then click Copy, then Paste, at the bottom of the dialog.
  3. Rename the new table to “TaskNote”.
  4. Double-click the TaskNote table to see the list of fields it contains.
  5. To record the time a note was created, create a new field named Time, of Type: Time.
    1. Click Options to view more settings for the field.
    2. In the Auto-enter tab, select the Calculated value box.
    3. Set the auto-enter calculation to Get ( CurrentTime ). A user could override this if they need to, but in most cases it will save them data entry time.
  6. Similarly, to help users by automatically entering the note date, create a new field named Date, of Type: Date.
    1. Click Options to view more settings for the field.
    2. In the Auto-enter tab, select the Calculated value box.
    3. Set the auto-enter calculation to Get ( CurrentDate ).
  7. Create the following additional fields in the TaskNote table:
    • ID_Task, of Type: Number
    • Note, of Type: Text
    • Note_Summary, of Type: Text

Step 2 - Relate task notes to tasks

The ID_Task field in the TaskNote table is a foreign key that will be used to relate task notes back to a task. There is a one-to-many relationship from Task to TaskNote. You will now set up the relationships graph to reflect this.

  1. Switch to the Relationships tab of the Manage Database dialog. Note that a new table occurrence named TaskNote was automatically added to the graph when you created the new table in step 1.
  2. Double-click the TaskNote table occurrence and rename it to "TASKNOTE". This is done for consistency with the graph organization techniques used in the file.
  3. Drag the TASKNOTE table occurrence to the left column of table occurrences, and place it above the TASK table occurrence. Select both tables, then use the Arrange tools to Align Left Edges and Resize to Largest Width so the TASKNOTE table occurrence matches TASK.
  1. Select and duplicate the TASKNOTE table occurrence using Command-D (macOS) / Control-D (Windows).
  2. Double-click the new table occurrence and rename it to “task_TASKNOTE".
  1. Drag the task_TASKNOTE table occurrence down the graph to the other task-related table occurrences, and position it below task_TIMEENTRY.
  1. Create a relationship between TASK and task_TASKNOTE by clicking on the ID field in TASK and dragging over to the ID_Task field in task_TASKNOTE.
  1. Double-click the line that connects the two table occurrences to open the Edit Relationship dialog. Click the option on the right that reads Delete related records in this table when a record is deleted in the other table.

    This is called a "cascading delete" and means that if an Task record is deleted, any related TaskNote records will also be deleted.
  1. Clean up the graph by doing the following:
    1. Click the window icon at the top right of the task_TASKNOTE table occurrence to minimize it so it matches the height of the table occurrences around it, then highlight all four table occurrences that are “children” of TASK.
    2. Use the Arrange buttons to Align Left Edges, Distribute Vertically, and Resize to Largest Width.
    3. Exit out of the Manage Database dialog.

      NOTE: After clean-up, the Task area of your graph should look like this: 

Step 3 - View task notes

Add and format a portal to the Task Detail layout that shows related task notes.

  1. 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).
  2. Use the Layout pulldown menu in the status toolbar to navigate to the Desktop > Task > Task Detail layout.
  3. Select the Tab Control object from the Objects tab. Currently there are two panels in the tab control: Details, and Time Entries. You will add a third for Notes.
  1. Double-click the tab control object on the layout to open the Tab Control Setup dialog, and create a new tab panel named "Notes".
  1. Each tab panel has a blue line under the tab name to indicate the active tab. To add this to the new Notes tab:
    1. Click the Notes tab to make sure it is the active tab.
    2. Scroll to the right and notice an object off the visible right edge of the layout
    3. Copy the blue horizontal line and drag it under the Notes tab name.
  1. Next you will add a large portal to the Notes tab, similar to the portal on the Time Entries tab. Click the Portal tool on the status toolbar, and draw a large rectangle to cover most of the Notes tab.
  1. In the Portal Setup dialog:
    1. Set the Show records from: option to task_TASKNOTE.
    2. Choose to Sort portal records, then specify the Date field and sort Descending.
    3. Allow vertical scrolling, then set Show scroll bar: to When scrolling.
    4. Set Number of rows: to 6
    5. Make sure that Use alternate row state is turned on.
  1. In the Add Fields to Portal dialog, select the Note_Summary, Date, and Time fields and move them to Included fields. Click OK to complete the portal setup.
  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 Position tab of the Inspector.
  1. Set the Autosizing option for the portal to anchor top, bottom, right, and left so the portal will stretch both vertically and horizontally to fill the space available as the window is resized. Also use the Position area to set the top left corner of the portal to the same coordinates as the top left corner of the portal on the Time Entries tab panel.
  1. Activate the Styles tab of the Inspector.
  1. Apply the following styles:
    • Leave the portal itself as the Default style
    • Note_Summary - style: txt Minimal.Black.Left
    • Date - style: txt Minimal.Black.Right
    • Time - style: txt Minimal.Black.Right
  2. Activate the Data tab of the Inspector.
  1. Select the Date field, then in the Data Formatting section of the Inspector, choose the format 12/25/14, with Zero as the leading character for day numbers and for month numbers. Then, select the Time field and choose the format hhmm.
  2. Select all three fields in the portal, and turn off field entry in Browse mode.
  1. Adjust the widths and positions of the fields in the portal so yours looks similar to the image below.
  1. Adjust the Autosizing as follows for the three fields in the portal:
    1. Note_Summary: Top, left, right
    2. Date: Top, right
    3. Time: Top, right
  2. Use the Exit Layout button to return to Browse mode and review your progress. Keep in mind there is no data yet in the TaskNote table.

    Note: You can also enter Browse mode using the View > Browse Mode menu item, or the keyboard shortcut Command-B (macOS) / Control-B (Windows).

Step 4 - Add field to display count of task notes

Create a field that will count how many notes have been added for a task and display it on the Notes tab.

  1. In the Manage Database dialog, create a calculation field in the Task table named z_TaskNote_Count with the following formula:

    NOTE: Deselect Do not evaluate if all referenced fields are empty. The calculation will display the count of how many notes exist, if there are any. If there are none, it will display a zero.

Let (
  c = Count ( task_TASKNOTE::ID )
  ;
  If ( c > 0 ; c ; 0 )
  )

  1. Exit the Manage Database dialog. Enter Layout mode and activate the Notes tab.
  2. Select Insert > Merge Field... to add the z_TaskNote_Count field to the layout.
  3. Make several formatting changes to the merge field:
    1. Double-click into it and add the text "Total Notes: " before the field name.
    2. Set the style to label Left.
    3. Position it above the portal, as shown below. To be exact, use the Position tab of the Inspector and compare the positions of the merge field and portal on the Time Entries tab to the positions of the new merge field and portal on the Notes tab. They should have the same positions.

Step 5 - Create card window for creating and editing task notes

The portal you created in step 3 is perfect for viewing notes. For creating and editing notes, however, you will make a new card window layout.

  1. Open the Manage Layouts dialog (File > Manage > Layouts...)
  2. Locate the Blank > Blank | Desktop - Card layout and Duplicate it.
  3. With the new layout selected, click the Edit button to open the Layout Setup dialog, and make the following changes:
    1. Set the Layout Name to “Task Note | Card"
    2. Set the Show records from: to TASKNOTE
    3. Set the Menu Set: to Minimal for Card Windows
  1. Use the dropdown arrow next to the New button at the bottom of the dialog to create a new folder named Task Note. Move it into the Desktop folder, and then place the two new TASKNOTE layouts into it, as shown below. Make sure the Include in layout menus check box is deselected.
  1. Click the Open button to open the Task Note | Card layout, and enter Layout mode.
  2. Edit the merge field at the top of the layout to say "<<$$CARD_ACTION>> Task Note".

    The global variable will contain either "New" or "Edit" and will be set by scripts you create later in this lesson. This way, you can use the same layout both for creating a new record and for editing an existing one.
  3. Duplicate the sample field and text label, retaining their styling, and rename, resize, and arrange them as necessary so they look similar to image below.
    1. Use the Data tab of the Inspector to set the Control style for the Date field to Drop-down Calendar. Choose to Include icon to show and hide calendar.
    2. Apply Data Formatting of 12/25/14 to the Date field and hhmm to the Time field.
    3. The asterisk on the Note Summary label tells the user it is a required field. You will create that validation script later in this lesson.
  1. Enter Browse mode to save and review your work. Note that the card window layout uses a custom menu with minimal functionality, so users are restricted to just the options on the card window. To get back to a full developer menu set, either switch to a different layout or select the Tools > Custom Menus > [Standard FileMaker Menus] menu item.

Step 6 - New script to create task note

Next, you will create a script for adding a new task note. In a later step, you will attach this script to a button on the Notes tab of the Task Detail layout.

The script begins by using the #Assign custom function to parse any script parameters and test to make sure they are are valid. It then proceeds to open the card window, set the $$CARD_ACTION variable, create a new record, and put the cursor into the Note_Summary field so the user can immediately begin typing.

  1. Open the Script Workspace (Scripts > Script Workspace...).
  2. Create a new folder named “Task Note". Create a new script by duplicating the Template Script.
    1. Name the script “Create Task Note”
    2. Move it into the Task Note folder.
    3. Right-click the Task Note folder, and select the option to Exclude from Scripts Menu
  1. Modify the script by adding the highlighted steps below. Be sure to deselect the Close Window option when establishing the settings of your Task Note Detail card window, so users can only close the window with the scripts you write.

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Freeze Window

Set Variable [ $$CARD_ACTION ; Value: “New” ]
Set Variable [ $$CONTEXT ; Value: “Task Note" ]

Set Variable [ $task_id; Value: TASK::ID ]

# open card window
New Window [ Style: Card ; Name: “Task Note Detail” ; Using layout: “Task Note | Card” (TASKNOTE) ]

# create record
New Record/Request
Set Field [ TASKNOTE::ID_Task ; $task_id ]

# leave the cursor in the Note Summary field
Go to Field [ Select/perform ; TASKNOTE::Note_Summary ]

Exit Script [ Text Result ; $null ]

  1. Save and close the script

Step 7 - Edit script to validate and save task note

The Create Task Note script in step 6 will take users to the card window and let them enter new data. Now you need a script that will validate that they have entered a note summary, then save the record and close the card window. Your file already has a script to handle this type of work for other card windows. In this step, you will modify the script so it also works for task notes.

  1. Open the Script Workspace and find the Save Record in Card Window ( context ) script.
  2. Modify the script by adding the highlighted steps below, to follow the If sequence for Time Entry. For the custom dialog, show users only one button for OK:

Else If [ IsEmpty ( TIMEENTRY::Time_Start) or IsEmpty (TIMEENR… ]
   Show Custom Dialog [ “A start and end time are required. “ ]
   Exit Script [ Test Result: $null ]

End If

# BUILD-ON: TASK NOTES
Else If [ $$CONTEXT = “Task Note” ]
# For task note card: validates that summary has been entered.

If [ IsEmpty ( TASKNOTE::Note_Summary ) ]
   Show Custom Dialog [ “Error” ; “A summary for the note is required.” ]
   Exit Script [ Text Result: $null ]
End If

End If

Commit Records/Requests {With dialog: Off ]
Close Window [ Current Window ]

  1. Save and close the script.

Step 8 - Edit script to open existing task note

The final script you need is one for handling editing an existing note. The template core file has a script to handle this for other types of records, so you will add to that so it recognizes the Task Note routine. You will add steps telling the script to open the Task Note record in the new card window layout, showing the “edit” options.

  1. Open the Script Workspace and find the Go To Related Record ( context ) script.
  2. Modify the script by adding the highlighted steps below, near the end of the script, after the other Else If clauses:

    NOTE: See step 3 for details on the Go to Related Record script step.

   # BUILD-ON: TASK NOTES
Else If [ $context = “Task to Task Note” ]
   # Task to Task Note
   Go to Related Record [Show only related records ; From table: “task_TASKNOTE” ; Using layout : “Task Note | Card” (TASKNOTE) ; New window ]
   Set Variable [$$CONTEXT ; Value: “Task Note”]
   Set Variable [$$CARD_ACTION ; Value: “Edit”]

End If

Exit Script [ Text Result: $null ]

  1. In the Go to Related Record step, make sure to show a New Window with a Window Style of Card. In the Window Options, turn off Close. When you select Show only related records, choose to Match current record only.
  1. Save and close the script.

Step 9 - Adding buttons

With all of the scripts now in place, your final task is to make buttons to trigger them. On the Notes tab of the Task Detail layout, you will create buttons for adding and editing task notes. On the card window, you will modify the existing buttons to call the appropriate actions for validating and saving a task note record.

  1. In Layout mode, return to the Task Detail layout and navigate to the Time Entries tab.
  2. Copy the Add Time Entry button, then navigate to the Notes tab and paste it in the same location on that tab.
  3. In the Button Setup dialog, set the following properties for the button:
    1. Set the button name to "Add Task Note"
    2. Make sure the Action: is set to Perform Script
    3. Select the Create Task Note script
    4. Clear all script parameters, then close out of the Button Setup dialog
  1. Next, you will place an invisible button over the entire portal row, so users will go to that note when they click the row.
    1. Select the Button tool which is the 6th button from the left in tool bar, then draw a button on the first portal row. 6th Button from the left
    2. In the Button Setup dialog, set the Action: to Perform Script.
    3. Select the Go To Related Record (context) script.
    4. Set the script parameter to “Task to Task Note”.
  1. Set left, right, and top anchors for the object.
  1. Change the style of the button to btn Row.Hover.
  2. In the Objects tab, you can control layering (which object is on top of another) by changing the order of objects listed. To move the button behind the fields in the portal, click and drag the Button so it is listed after the three Edit Box objects, as shown here:
  1. In Layout mode, navigate to the Task Note | Card layout.

    Note: This layout is designed to work in two cases: for creating a new record, and for editing an existing record. At the bottom of the layout, there are two sets of stacked buttons. If you move the Cancel and Create buttons, you will see Delete and Close buttons underneath them (see below). The user will see the “Create” set when they are making a new record, and the “Close” set when they are editing an existing record.

    The Cancel, Close, and Create buttons perform their functions without additional context. These do not require any modification by you.
  1. Go into the Button Setup dialog for the Delete button. Keep the script as it is, but add the parameter of “task note”.
  1. Return the buttons to their stacked positions, then enter Browse mode so you can save and review your work.

Step 10 - Review your work

With all of the schema, interface, and scripting now in place, you can test the new task notes features.

  1. When you go to the Task Detail layout, you should see a tab that lists the notes for that task, and a button for adding a new note.
  2. When you click the Add Task Note button, you should see the Task Note | Card layout and be shown a blank new record. The header should display "New Task Note" and the buttons at the bottom should be Cancel and Create.
  3. If you click the Cancel button, you should get no confirmation dialog, and there should be no new record in the portal.
  4. If you click the Create button, you should get a data validation error message and not be allowed to close the window. Enter data into the Note Summary field, click Create and verify that you are able to save the new record.
  5. When you return back to the Task Detail record, you should see the new note record in the portal.
  6. If you click on the portal row, the card window should reappear and display the data for the note you created previously. The header should display "Edit Task Note" and the buttons at the bottom should be Delete and Close. If you click Delete, the note should disappear from the portal on the Task Detail layout. If you click Close, you should still see the note in the portal.