< prev
main
next >

Calendar Solution Documentation



Section 7: Developer Access (cont'd)

Section 7.5: Developer Access, Calendar.fp5


Calendar.fp5 (a.k.a. Calendar, Calendar module, Calendar file) - As previously mentioned, the Calendar file is a single-record database file, whose only purpose is to display related data from the People and Task files. The Calendar file uses relationships to the Task file to display related data in its Month, Week and Day views.

Most of the Calendar file just works. There's not a lot of value in explaining how every script in the Calendar module accomplishes its given task, since it's unlikely that you'll need to modify these routines. The value in having access to the Calendar file's programming is in being able to change the interface, value lists, and filters, and to add functionality beyond the basic workings of the Calendar. After all, if you wanted to take the time to build the basic Calendar functionality, you wouldn't have purchased the Calendar Solution! We've done all of the "busy work" so you could save the time of doing it yourself.

This section of the manual does give a general overview of the main underpinnings of the Calendar. After reading this section, you should understand the purpose of most of the programming involved, and should be able to make the modifications necessary to integrate the Calendar Solution, or parts thereof, into your own solution.

Fields - All fields in the Calendar file are developer fields; there are no user fields in this file. A full description of the purpose of every component of this file is not provided in this manual. The developer should take the time to look at the scripts, layouts and fields in all of the files to which he has access, familiarizing himself with the programming and determining the intent behind the programming. Scripts are well commented, when needed, and all programming is well-organized for the benefit of developers who employ this solution.

Those fields which are integral to the solution, or whose components or usage may be complex for the moderately experienced developer, will be described in detail in this manual. For more information on developer fields and naming conventions, see the
Preface for Section 7.

The following table lists the major groups of fields in the Calendar, and explains the purpose of each of those fields/field groups. Not every field is covered here; only those whose purpose is very important, and whose calculations are rather complex. '#' signs will replace variable sections in groups of field names in this section. Instead of using
zi.day.mo.aa.c, zi.day.mo.ab.c, and zi.day.mo.ac.c in explanations, for instance, you would see zi.day.mo.#.c. The '#' sign replaces those characters which are different in groups with the same field name structure.

Field/Group

Description

zc.day.wk.#.c

Used in zi.day.wk.#.c, whose function is described below. These fields may be removed in a later release.

zc.filter.#.c

Hundreds of key fields in the Calendar file use filters as part of their calculations. Using standard fields in these calculations would require changing all of the key field calculations to accommodate the changes. These calculated filter fields are a better alternative.

To change a filter value, simply change the value in the appropriate
zc.filter.#.c field. The corresponding calculation field in the Task file must also be changed so that the relationships will remain valid.

zc.my.date.c
through
zc.my.mo.top.c

All of these zc.my.#.c fields are based on global entry fields. Their general purpose is to transform a single date entered by a user into dates needed for various functions and display items in the calendar.

For example,
zc.my.date.mo.top.c is a calculation that returns the first day that appears in Month view; zc.my.hr.top.c returns the hour that should appear at the top left of Week/Day view.

zc.now.#.c

Used to determine the current date in various forms.

zi.day.mo.#.c

Display the numbers for each day of the current month in Month view. These numbers are black in Month view.

zi.day.mo.#Prev.c

Display the numbers for each day of the previous month in Month view. These numbers are gray in Month view. These fields are only used in the first row of days in any month.

zi.day.mo.#This.c

Display the numbers for each day of the current month in Month view. These numbers are black in Month view.

zi.day.mo.#Next.c

Display the numbers for each day of the previous month in Month view. These numbers are gray in Month view. These fields are only used in the last two rows of days in any month.

zi.day.wk.#.c

Display the current day number in white, if it falls within the currently displayed week.

zi.filter.name.#

These fields are not used currently. They may be used in a future release.

zi.time.#.c

These nine hour indicators are displayed to the left of their corresponding rows in Week and Day views.

zi.time.#.merid.c
zi.time.#.meridFirst.c
zi.time.#.meridLast.c

Display AM or PM in Week/Day views.

zk.day.mo.#.c

Key fields used for displaying event information in Month view.

zk.task.date.#.c

Key fields used for displaying task information in Week/Day view.

zk.time.date.#.c

Key fields used for displaying event information in Week/Day view.

zu.categ.#

Display category values, generate category value lists.

zzi.hue.#.o
zzi.tint.#.o

Display various colors & backgrounds. These fields have been named outside standard naming conventions in order to group all of the colors together, in a separate section in field definitions from text/number/date/time interface fields. These fields may be renamed in a later release to match standard naming conventions.



Relationships - There are over 180 relationships in the Calendar file, the vast majority of which are used to display data from the Task module. For example, the Month view contains 42 portals, each of which references a separate relationship which displays only the events related to that day. The week and day views have separate relationships for each half-hour (24 relationships per day).

There are essentially three kinds of relationships which display event data in the Calendar: Day-based relationships, Time/Day-based relationships, and Task-based relationships. Each type is described below.

Day-based Relationships - Day-based relationships are used to display event data in the Month calendar view. Since all events for any given day must be displayed together, time information is irrelevant in Month view, and therefore is not stored in day-based key fields.

There are 42 day-based relationships, one for each day displayed in the calendar Day view. Following is a description of each of the components of the day-based relationships:

Component

Description

task~d.aa~~act.date

This is an example of a day-based relationship name. Its sections are described below.

task~d.

The names of all day-based relationships begin with the prefix 'task~d.'. The 'task' prefix indicates that the relationship references the Task file, and the 'd' indicates that it is a day-based relationship.

aa

Letters are used instead of numbers in the names of the relationships to indicate which day in Month view is being referenced. The first letter indicates the row (row A in this case), and the second letter indicates the day (day A in this case).

Examples:
'aa' is week one, day one; 'ab' is week one, day two; 'ba' is week two, day one; 'cb' is week three, day two; and so on.

~~act.date

Activity date -- this suffix is a shortened version of the name of the actual field that is referenced in Task. All day-based relationships in the Calendar reference the field zc.tk.dateBegin.c in Task.


Time-based Relationships - Time-based relationships are used to display event data in the Week and Day calendar views. The key fields in Calendar that are referenced in time-based relationships are identical to the key fields for the day-based relationships, except that time information is also stored in them. Appointment times are rounded to the nearest half-hour for Week and Day view purposes; an appointment scheduled for 10:45 AM would display in the second half-hour of the ten o'clock hour block.

There are 126 day-based relationships, eighteen for each day displayed in both the calendar Week and Day views. Eighteen half-hours are displayed at once in Week and Day views, and seven days are represented in Week view. Following is a description of each of the components of the time-based relationships:

Component

Description

task~t.aaa~~tk.due.time.date

This is an example of a time-based relationship name. Its sections are described below.

task~t.

The names of all time-based relationships begin with the prefix 'task~t.'. The 'task' prefix indicates that the relationship references the Task file, and the 't' indicates that it is a time-based relationship.

aaa

Letters are used instead of numbers in the names of the relationships to indicate which day and hour in Week/Day view is being referenced.

The first letter indicates the day column (column A in this case), and the second letter indicates the hour row (column A in this case). The third letter indicates the half-hour being referenced; an
'a' represents the first 30 minutes of the hour, and a b represents the last 30 minutes of the hour.

Examples:
'aaa' is day one, hour one, half-hour one; 'aab' is day one, hour one, half-hour two; 'baa' is day two, hour one, half-hour one; 'cdb' is day three, hour four, half-hour two; and so on.

~~tk.due.time.date

Activity time/date -- this suffix represents the actual field that is referenced in Task. All time-based relationships in the Calendar reference the field zk.tk.timeBegin.c in Task.


Task-based Relationships - Task-based relationships are used to display event data in the Week and Day calendar views. The key fields in Calendar that are referenced in task-based relationships are identical to the key fields for the day-based relationships, except that the leading string 'task ', is also stored in them.

There are seven task-based relationships, one for each day displayed in the calendar Week and Day views. Following is a description of each of the components of the task-based relationships:

Component

Description

task~tk.a~~tk.due.time.date

This is an example of a task-based relationship name. Its sections are described below.

task~tk.

The names of all task-based relationships begin with the prefix 'task~tk.'. The 'task' prefix indicates that the relationship references the Task file, and the 'tk' indicates that it is a task-based relationship.

a

Letters are used instead of numbers in the names of the relationships to indicate which day in Week/Day view is being referenced.

The letter indicates the day column (column A in this case).

Examples:
'a' is day one; 'b' is day two; and so on.

~~tk.due.time.date

Activity time/date -- this suffix represents the actual field that is referenced in Task. All task-based relationships in the Calendar reference the field zk.tk.timeBegin.c in Task.



Value Lists - There are a few value lists in the Calendar file. The only important thing to note about the Calendar value lists is that the value lists used in the Task and Appointment creation dialogs are drawn from the People file, whereas the value lists used for the filters in the Calendar are drawn from the Task file. The reason for using separate value lists is to ensure that only valid filter values are included in the filter value lists. This precaution guarantees that filter selections will always result in a found set in the calendar.

Navigation - The bulk of the navigation scripts within the Calendar file are divided into three major categories: Month view navigation, Week view navigation, and Event Edit navigation.

Month View Navigation - Clicking on the day header in Month view navigates to the corresponding day in Day view. This action is achieved via one of the 42 Month view navigation scripts, which follow the naming format
nav.date.zi.day.mo.aa.c. Each of these scripts calls the subscript nav.date.zi.day.mo.ALL.after, which in turn calls the script rec.dateGet. None of these scripts are particularly complex. Global fields are set in each script, and branching subscripts take action based on the values of the global fields. The result is navigation to Day view for the corresponding day.

Week View Navigation - Clicking on the day header in Week view navigates to the corresponding day in Day view. This action is achieved via one of the 7 Day view navigation scripts, which follow the naming format
nav.day.zi.day.wk.a.c. Each of these scripts calls the subscript nav.date.zi.day.wk.ALL.after, which in turn calls the script rec.dateGet. None of these scripts are particularly complex. Global fields are set in each script, and branching subscripts take action based on the values of the global fields. The result is navigation to Day view for the corresponding day.

Event Edit Navigation - Clicking on an existing event in Month, Week or Day view navigates to the corresponding Task/Appointment dialog, allowing for editing/deleting the event. This action is achieved via one of the 150+ Event Edit navigation scripts, which follow the naming formats
nav.edit.appt.zi.day.mo.df.c (appointments, Month view), nav.edit.appt.zk.time.date.aaa.c (appointments, Week/Dayh view), and nav.edit.task.zk.task.date.ALL.after (tasks, Week/Day view).

Each of these scripts calls the appropriate corresponding subscript (
nav.edit.appt.zi.day.mo.ALL.after, nav.edit.appt.zi.time.date.ALL.after, or nav.edit.task.zk.task.date.ALL.after), which in turn call the script rec.dateGet. None of these scripts are particularly complex. Global fields are set in each script, and branching subscripts take action based on the values of the global fields. The result is navigation to Day view for the corresponding day.

< prev
main
next >

AppleScript - Links
Copyright 1998-2003 davedowling.com, All Rights Reserved.