HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Developer's Guide: Calendar

» Return to Contents



sources/calendar.php

Global_functions_calendar.php

Function summary

void init__calendar ()
string get_week_number_for (TIME timestamp, boolean no_year)
array date_from_week_of_year (integer year, integer week)
array find_periods_recurrence (ID_TEXT timezone, BINARY do_timezone_conv, integer start_year, integer start_month, integer start_day, integer start_hour, integer start_minute, ?integer end_year, ?integer end_month, ?integer end_day, ?integer end_hour, ?integer end_minute, string recurrence, ?integer recurrences, ?TIME period_start, ?TIME period_end)
tempcode nice_get_event_types (?AUTO_LINK it)
void regenerate_event_reminder_jobs (AUTO_LINK id, boolean force)
string date_range (TIME from, TIME to, boolean do_time)
array calendar_matches (MEMBER member_id, boolean restrict, ?TIME period_start, ?TIME period_end, ?array filter, boolean do_rss)
tempcode nice_get_events (?MEMBER only_owned, ?AUTO_LINK it, boolean edit_viewable_events)
?tempcode detect_conflicts (MEMBER member_id, AUTO_LINK skip_id, ?integer start_year, ?integer start_month, ?integer start_day, ?integer start_hour, ?integer start_minute, ?integer end_year, ?integer end_month, ?integer end_day, ?integer end_hour, ?integer end_minute, string recurrence, ?integer recurrences)
integer find_timezone_start_hour_in_utc (ID_TEXT timezone, integer year, integer month, integer day)
integer find_timezone_start_minute_in_utc (ID_TEXT timezone, integer year, integer month, integer day)
integer find_timezone_end_hour_in_utc (ID_TEXT timezone, integer year, integer month, integer day)
integer find_timezone_end_minute_in_utc (ID_TEXT timezone, integer year, integer month, integer day)
TIME cal_get_start_utctime_for_event (ID_TEXT timezone, integer year, integer month, integer day, ?integer hour, ?integer minute, boolean show_in_users_timezone)
TIME cal_get_end_utctime_for_event (ID_TEXT timezone, integer year, integer month, integer day, ?integer hour, ?integer minute, boolean show_in_users_timezone)
TIME cal_utctime_to_usertime (TIME utc_timestamp, ID_TEXT default_timezone, boolean show_in_users_timezone)
array detect_happening_at (MEMBER member_id, AUTO_LINK skip_id, array our_times, boolean restrict, ?TIME period_start, ?TIME period_end)

void init__calendar()

Standard code module init function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

string get_week_number_for(TIME timestamp, boolean no_year)

Get the week number for a time.

Parameters…

Name timestamp
Description The week number
Type TIME

Name no_year
Description Whether to do it contextually to the year, rather than including the year
Default value boolean-false
Type boolean

Returns…

Description The week number
Type string

Return to the function index for this class Expand: View the source code to this function

array date_from_week_of_year(integer year, integer week)

Converts year+week to year+month+day. This is really complex. The first week of a year may actually start in December. The first day of the first week is a Monday or a Sunday, depending on configuration.

Parameters…

Name year
Description Year #
Type integer

Name week
Description Week #
Type integer

Returns…

Description Month #,Day #,Year #
Type array

Return to the function index for this class Expand: View the source code to this function

array find_periods_recurrence(ID_TEXT timezone, BINARY do_timezone_conv, integer start_year, integer start_month, integer start_day, integer start_hour, integer start_minute, ?integer end_year, ?integer end_month, ?integer end_day, ?integer end_hour, ?integer end_minute, string recurrence, ?integer recurrences, ?TIME period_start, ?TIME period_end)

Find a list of pairs specifying the times the event occurs, for 20 years into the future, in user-time.

Parameters…

Name timezone
Description The timezone for the event (NULL: current user's timezone)
Type ID_TEXT

Name do_timezone_conv
Description Whether the time should be converted to the viewer's own timezone
Type BINARY

Name start_year
Description The year the event starts at. This and the below are in server time
Type integer

Name start_month
Description The month the event starts at
Type integer

Name start_day
Description The day the event starts at
Type integer

Name start_hour
Description The hour the event starts at
Type integer

Name start_minute
Description The minute the event starts at
Type integer

Name end_year
Description The year the event ends at (NULL: not a multi day event)
Type ?integer

Name end_month
Description The month the event ends at (NULL: not a multi day event)
Type ?integer

Name end_day
Description The day the event ends at (NULL: not a multi day event)
Type ?integer

Name end_hour
Description The hour the event ends at (NULL: not a multi day event / all day event)
Type ?integer

Name end_minute
Description The minute the event ends at (NULL: not a multi day event / all day event)
Type ?integer

Name recurrence
Description The event recurrence
Type string

Name recurrences
Description The number of recurrences (NULL: none/infinite)
Type ?integer

Name period_start
Description The timestamp that found times must exceed. In user-time (NULL: now)
Default value
Type ?TIME

Name period_end
Description The timestamp that found times must not exceed. In user-time (NULL: 20 years time)
Default value
Type ?TIME

Returns…

Description A list of pairs for period times (timestamps, in user-time). Actually a series of pairs, 'window-bound timestamps' is first pair, then 'true coverage timestamps', then 'true coverage timestamps without timezone conversions'
Type array

Return to the function index for this class Expand: View the source code to this function

tempcode nice_get_event_types(?AUTO_LINK it)

Get a list of event types, taking security into account against the current member.

Parameters…

Name it
Description The event type to select by default (NULL: none)
Default value
Type ?AUTO_LINK

Returns…

Description The list
Type tempcode

Return to the function index for this class Expand: View the source code to this function

void regenerate_event_reminder_jobs(AUTO_LINK id, boolean force)

Regenerate all the calendar jobs for reminders for next occurance of an event (because the event was added or edited).

Parameters…

Name id
Description The ID of the event
Type AUTO_LINK

Name force
Description Force evaluation even if it's in the past. Only valid for code events
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

string date_range(TIME from, TIME to, boolean do_time)

Create a neatly human-readable date range, using various user-friendly readability tricks.

Parameters…

Name from
Description From time in user time
Type TIME

Name to
Description To time in user time
Type TIME

Name do_time
Description Whether time is included in this date range
Default value boolean-true
Type boolean

Returns…

Description Textual specially-formatted range
Type string

Return to the function index for this class Expand: View the source code to this function

array calendar_matches(MEMBER member_id, boolean restrict, ?TIME period_start, ?TIME period_end, ?array filter, boolean do_rss)

Detect calendar matches in a time period, in user-time.

Parameters…

Name member_id
Description The member to detect conflicts for
Type MEMBER

Name restrict
Description Whether to restrict only to viewable events for the current member
Type boolean

Name period_start
Description The timestamp that found times must exceed. In user-time (NULL: use find_periods_recurrence default)
Type ?TIME

Name period_end
Description The timestamp that found times must not exceed. In user-time (NULL: use find_periods_recurrence default)
Type ?TIME

Name filter
Description The type filter (NULL: none)
Default value
Type ?array

Name do_rss
Description Whether to include RSS events in the results
Default value boolean-true
Type boolean

Returns…

Description A list of events happening, with time details
Type array

Return to the function index for this class Expand: View the source code to this function

tempcode nice_get_events(?MEMBER only_owned, ?AUTO_LINK it, boolean edit_viewable_events)

Get a list of events to edit.

Parameters…

Name only_owned
Description Only show events owned by this member (NULL: no such limitation)
Type ?MEMBER

Name it
Description Event to select by default (NULL: no specific default)
Type ?AUTO_LINK

Name edit_viewable_events
Description Whether owned public events should be shown
Default value boolean-true
Type boolean

Returns…

Description The list
Type tempcode

Return to the function index for this class Expand: View the source code to this function

?tempcode detect_conflicts(MEMBER member_id, AUTO_LINK skip_id, ?integer start_year, ?integer start_month, ?integer start_day, ?integer start_hour, ?integer start_minute, ?integer end_year, ?integer end_month, ?integer end_day, ?integer end_hour, ?integer end_minute, string recurrence, ?integer recurrences)

Detect conflicts with an event at a certain time.

Parameters…

Name member_id
Description The member to detect conflicts for
Type MEMBER

Name skip_id
Description The event ID that we are detecting conflicts with (we need this so we don't think we conflict with ourself)
Type AUTO_LINK

Name start_year
Description The year the event starts at. This and the below are in server time (NULL: default)
Type ?integer

Name start_month
Description The month the event starts at (NULL: default)
Type ?integer

Name start_day
Description The day the event starts at (NULL: default)
Type ?integer

Name start_hour
Description The hour the event starts at (NULL: default)
Type ?integer

Name start_minute
Description The minute the event starts at (NULL: default)
Type ?integer

Name end_year
Description The year the event ends at (NULL: not a multi day event)
Type ?integer

Name end_month
Description The month the event ends at (NULL: not a multi day event)
Type ?integer

Name end_day
Description The day the event ends at (NULL: not a multi day event)
Type ?integer

Name end_hour
Description The hour the event ends at (NULL: not a multi day event)
Type ?integer

Name end_minute
Description The minute the event ends at (NULL: not a multi day event)
Type ?integer

Name recurrence
Description The event recurrence
Type string

Name recurrences
Description The number of recurrences (NULL: none/infinite)
Type ?integer

Returns…

Description Information about conflicts (NULL: none)
Type ?tempcode

Return to the function index for this class Expand: View the source code to this function

integer find_timezone_start_hour_in_utc(ID_TEXT timezone, integer year, integer month, integer day)

Find first hour in day for a timezone.

Parameters…

Name timezone
Description Timezone
Type ID_TEXT

Name year
Description Year
Type integer

Name month
Description Month
Type integer

Name day
Description Day
Type integer

Returns…

Description Hour
Type integer

Return to the function index for this class Expand: View the source code to this function

integer find_timezone_start_minute_in_utc(ID_TEXT timezone, integer year, integer month, integer day)

Find first minute in day for a timezone. Usually 0, but some timezones have 30 min offsets.

Parameters…

Name timezone
Description Timezone
Type ID_TEXT

Name year
Description Year
Type integer

Name month
Description Month
Type integer

Name day
Description Day
Type integer

Returns…

Description Hour
Type integer

Return to the function index for this class Expand: View the source code to this function

integer find_timezone_end_hour_in_utc(ID_TEXT timezone, integer year, integer month, integer day)

Find last hour in day for a timezone.

Parameters…

Name timezone
Description Timezone
Type ID_TEXT

Name year
Description Year
Type integer

Name month
Description Month
Type integer

Name day
Description Day
Type integer

Returns…

Description Hour
Type integer

Return to the function index for this class Expand: View the source code to this function

integer find_timezone_end_minute_in_utc(ID_TEXT timezone, integer year, integer month, integer day)

Find last minute in day for a timezone. Usually 59, but some timezones have 30 min offsets.

Parameters…

Name timezone
Description Timezone
Type ID_TEXT

Name year
Description Year
Type integer

Name month
Description Month
Type integer

Name day
Description Day
Type integer

Returns…

Description Hour
Type integer

Return to the function index for this class Expand: View the source code to this function

TIME cal_get_start_utctime_for_event(ID_TEXT timezone, integer year, integer month, integer day, ?integer hour, ?integer minute, boolean show_in_users_timezone)

Get the UTC start time for a specified UTC time event.

Parameters…

Name timezone
Description The timezone it is in; used to derive $hour and $minute if those are NULL, such that they start the day correctly for this timezone
Type ID_TEXT

Name year
Description Year
Type integer

Name month
Description Month
Type integer

Name day
Description Day
Type integer

Name hour
Description Hour (NULL: start hour of day in the timezone expressed as UTC, for whatever day the given midnight day/month/year shifts to after timezone conversion)
Type ?integer

Name minute
Description Minute (NULL: start minute of day in the timezone expressed as UTC, for whatever day the given midnight day/month/year shifts to after timezone conversion)
Type ?integer

Name show_in_users_timezone
Description Whether the time should be converted to the viewer's own timezone instead.
Type boolean

Returns…

Description Timestamp
Type TIME

Return to the function index for this class Expand: View the source code to this function

TIME cal_get_end_utctime_for_event(ID_TEXT timezone, integer year, integer month, integer day, ?integer hour, ?integer minute, boolean show_in_users_timezone)

Get the UTC end time for a specified UTC time event.

Parameters…

Name timezone
Description Timezone
Type ID_TEXT

Name year
Description Year
Type integer

Name month
Description Month
Type integer

Name day
Description Day
Type integer

Name hour
Description Hour (NULL: end hour of day in the timezone expressed as UTC, for whatever day the given midnight day/month/year shifts to after timezone conversion)
Type ?integer

Name minute
Description Minute (NULL: end minute of day in the timezone expressed as UTC, for whatever day the given midnight day/month/year shifts to after timezone conversion)
Type ?integer

Name show_in_users_timezone
Description Whether the time should be converted to the viewer's own timezone instead.
Type boolean

Returns…

Description Timestamp
Type TIME

Return to the function index for this class Expand: View the source code to this function

TIME cal_utctime_to_usertime(TIME utc_timestamp, ID_TEXT default_timezone, boolean show_in_users_timezone)

Put a timestamp into the correct timezone for being reported onto the calendar.

Parameters…

Name utc_timestamp
Description Timestamp (proper UTC timestamp, not in user time)
Type TIME

Name default_timezone
Description The timezone associated with the event (the passed $utc_timestamp should NOT be relative to this timezone, that must be UTC)
Type ID_TEXT

Name show_in_users_timezone
Description Whether the time should be converted to the viewer's own timezone instead
Type boolean

Returns…

Description Altered timestamp
Type TIME

Return to the function index for this class Expand: View the source code to this function

array detect_happening_at(MEMBER member_id, AUTO_LINK skip_id, array our_times, boolean restrict, ?TIME period_start, ?TIME period_end)

Detect conflicts with an event in certain time periods.

Parameters…

Name member_id
Description The member to detect conflicts for
Type MEMBER

Name skip_id
Description The event ID that we are detecting conflicts with (we need this so we don't think we conflict with ourself)
Type AUTO_LINK

Name our_times
Description List of pairs specifying our happening time (in time order)
Type array

Name restrict
Description Whether to restrict only to viewable events for the current member
Default value boolean-true
Type boolean

Name period_start
Description The timestamp that found times must exceed. In user-time (NULL: use find_periods_recurrence default)
Default value
Type ?TIME

Name period_end
Description The timestamp that found times must not exceed. In user-time (NULL: use find_periods_recurrence default)
Default value
Type ?TIME

Returns…

Description A list of events happening, with time details
Type array

Return to the function index for this class Expand: View the source code to this function