|
|
|
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.
|
|