Functions

Add a calendar event.

add_calendar_event(\AUTO_LINK $type, \SHORT_TEXT $recurrence, \?integer $recurrences, \BINARY $seg_recurrences, \SHORT_TEXT $title, \LONG_TEXT $content, integer $priority, \BINARY $is_public, integer $start_year, integer $start_month, integer $start_day, \ID_TEXT $start_monthly_spec_type, integer $start_hour, integer $start_minute, \?integer $end_year, \?integer $end_month, \?integer $end_day, \ID_TEXT $end_monthly_spec_type, \?integer $end_hour, \?integer $end_minute, \?ID_TEXT $timezone, \BINARY $do_timezone_conv, \BINARY $validated, \BINARY $allow_rating, \SHORT_INTEGER $allow_comments, \BINARY $allow_trackbacks, \LONG_TEXT $notes, \?MEMBER $submitter, integer $views, \?TIME $add_date, \?TIME $edit_date, \?AUTO_LINK $id) : \AUTO_LINK

range 1 5
set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards
set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$type

\AUTO_LINK

The event type

$recurrence

\SHORT_TEXT

The recurrence code (set to 'none' for no recurrences: blank means infinite and will basically time-out ocPortal)

$recurrences

\?integer

The number of recurrences (NULL: none/infinite)

$seg_recurrences

\BINARY

Whether to segregate the comment-topics/rating/trackbacks per-recurrence

$title

\SHORT_TEXT

The title of the event

$content

\LONG_TEXT

The full text describing the event

$priority

integer

The priority

$is_public

\BINARY

Whether it is a public event

$start_year

integer

The year the event starts at

$start_month

integer

The month the event starts at

$start_day

integer

The day the event starts at

$start_monthly_spec_type

\ID_TEXT

In-month specification type for start date

$start_hour

integer

The hour the event starts at

$start_minute

integer

The minute the event starts at

$end_year

\?integer

The year the event ends at (NULL: not a multi day event)

$end_month

\?integer

The month the event ends at (NULL: not a multi day event)

$end_day

\?integer

The day the event ends at (NULL: not a multi day event)

$end_monthly_spec_type

\ID_TEXT

In-month specification type for end date

$end_hour

\?integer

The hour the event ends at (NULL: not a multi day event)

$end_minute

\?integer

The minute the event ends at (NULL: not a multi day event)

$timezone

\?ID_TEXT

The timezone for the event (NULL: current user's timezone)

$do_timezone_conv

\BINARY

Whether the time should be presented in the viewer's own timezone

$validated

\BINARY

Whether the event has been validated

$allow_rating

\BINARY

Whether the event may be rated

$allow_comments

\SHORT_INTEGER

Whether comments are allowed (0=no, 1=yes, 2=review style)

$allow_trackbacks

\BINARY

Whether the event may be trackbacked

$notes

\LONG_TEXT

Hidden notes pertaining to the download

$submitter

\?MEMBER

The event submitter (NULL: current member)

$views

integer

The number of views so far

$add_date

\?TIME

The add time (NULL: now)

$edit_date

\?TIME

The edit time (NULL: never)

$id

\?AUTO_LINK

Force an ID (NULL: don't force an ID)

Returns

\AUTO_LINKThe ID of the event

Add a calendar event type.

add_event_type(\SHORT_TEXT $title, \ID_TEXT $logo, \URLPATH $external_feed) : \AUTO_LINK

Parameters

$title

\SHORT_TEXT

The title of the event type

$logo

\ID_TEXT

The theme image code

$external_feed

\URLPATH

URL to external feed to associate with this event type

Returns

\AUTO_LINKThe ID of the event type

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

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

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

Timezone

$year

integer

Year

$month

integer

Month

$day

integer

Day

$monthly_spec_type

\ID_TEXT

In-month specification type

$hour

\?integer

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)

$minute

\?integer

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)

$show_in_users_timezone

boolean

Whether the time should be converted to the viewer's own timezone instead.

Returns

\TIMETimestamp

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

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

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

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

$year

integer

Year

$month

integer

Month

$day

integer

Day

$monthly_spec_type

\ID_TEXT

In-month specification type

$hour

\?integer

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)

$minute

\?integer

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)

$show_in_users_timezone

boolean

Whether the time should be converted to the viewer's own timezone instead.

Returns

\TIMETimestamp

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

cal_utctime_to_usertime(\TIME $utc_timestamp, \ID_TEXT $default_timezone, boolean $show_in_users_timezone) : \TIME

Parameters

$utc_timestamp

\TIME

Timestamp (proper UTC timestamp, not in user time)

$default_timezone

\ID_TEXT

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

$show_in_users_timezone

boolean

Whether the time should be converted to the viewer's own timezone instead

Returns

\TIMEAltered timestamp

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

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

Parameters

$member_id

\MEMBER

The member to detect conflicts for

$restrict

boolean

Whether to restrict only to viewable events for the current member

$period_start

\?TIME

The timestamp that found times must exceed. In user-time (NULL: use find_periods_recurrence default)

$period_end

\?TIME

The timestamp that found times must not exceed. In user-time (NULL: use find_periods_recurrence default)

$filter

\?array

The type filter (NULL: none)

$do_rss

boolean

Whether to include RSS events in the results

Returns

arrayA list of events happening, with time details

Converts year+week to year+month+day.

date_from_week_of_year(integer $year, integer $week) : array

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

$year

integer

Year #

$week

integer

Week #

Returns

arrayMonth #,Day #,Year #

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

date_range(\TIME $from, \TIME $to, boolean $do_time) : string

Parameters

$from

\TIME

From time in user time

$to

\TIME

To time in user time

$do_time

boolean

Whether time is included in this date range

Returns

stringTextual specially-formatted range

Delete a calendar event.

delete_calendar_event(\AUTO_LINK $id) 

Parameters

$id

\AUTO_LINK

The ID of the event

Delete a calendar event type.

delete_event_type(\AUTO_LINK $id) 

Parameters

$id

\AUTO_LINK

The ID of the event type

Detect conflicts with an event at a certain time.

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

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards
set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$member_id

\MEMBER

The member to detect conflicts for

$skip_id

\AUTO_LINK

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

$start_year

\?integer

The year the event starts at. This and the below are in server time (NULL: default)

$start_month

\?integer

The month the event starts at (NULL: default)

$start_day

\?integer

The day the event starts at (NULL: default)

$start_monthly_spec_type

\ID_TEXT

In-month specification type for start date

$start_hour

\?integer

The hour the event starts at (NULL: default)

$start_minute

\?integer

The minute the event starts at (NULL: default)

$end_year

\?integer

The year the event ends at (NULL: not a multi day event)

$end_month

\?integer

The month the event ends at (NULL: not a multi day event)

$end_day

\?integer

The day the event ends at (NULL: not a multi day event)

$end_monthly_spec_type

\ID_TEXT

In-month specification type for end date

$end_hour

\?integer

The hour the event ends at (NULL: not a multi day event)

$end_minute

\?integer

The minute the event ends at (NULL: not a multi day event)

$recurrence

string

The event recurrence

$recurrences

\?integer

The number of recurrences (NULL: none/infinite)

Returns

\?tempcodeInformation about conflicts (NULL: none)

Detect conflicts with an event in certain time periods.

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

Parameters

$member_id

\MEMBER

The member to detect conflicts for

$skip_id

\AUTO_LINK

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

$our_times

array

List of pairs specifying our happening time (in time order)

$restrict

boolean

Whether to restrict only to viewable events for the current member

$period_start

\?TIME

The timestamp that found times must exceed. In user-time (NULL: use find_periods_recurrence default)

$period_end

\?TIME

The timestamp that found times must not exceed. In user-time (NULL: use find_periods_recurrence default)

Returns

arrayA list of events happening, with time details

Edit a calendar event.

edit_calendar_event(\AUTO_LINK $id, \?AUTO_LINK $type, \SHORT_TEXT $recurrence, \?integer $recurrences, \BINARY $seg_recurrences, \SHORT_TEXT $title, \LONG_TEXT $content, integer $priority, \BINARY $is_public, integer $start_year, integer $start_month, integer $start_day, \ID_TEXT $start_monthly_spec_type, integer $start_hour, integer $start_minute, \?integer $end_year, \?integer $end_month, \?integer $end_day, \ID_TEXT $end_monthly_spec_type, \?integer $end_hour, \?integer $end_minute, \?ID_TEXT $timezone, \BINARY $do_timezone_conv, \SHORT_TEXT $meta_keywords, \LONG_TEXT $meta_description, \BINARY $validated, \BINARY $allow_rating, \SHORT_INTEGER $allow_comments, \BINARY $allow_trackbacks, \LONG_TEXT $notes) 

range 1 5
set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards
set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$id

\AUTO_LINK

The ID of the event

$type

\?AUTO_LINK

The event type (NULL: default)

$recurrence

\SHORT_TEXT

The recurrence code

$recurrences

\?integer

The number of recurrences (NULL: none/infinite)

$seg_recurrences

\BINARY

Whether to segregate the comment-topics/rating/trackbacks per-recurrence

$title

\SHORT_TEXT

The title of the event

$content

\LONG_TEXT

The full text describing the event

$priority

integer

The priority

$is_public

\BINARY

Whether it is a public event

$start_year

integer

The year the event starts at

$start_month

integer

The month the event starts at

$start_day

integer

The day the event starts at

$start_monthly_spec_type

\ID_TEXT

In-month specification type for start date

$start_hour

integer

The hour the event starts at

$start_minute

integer

The minute the event starts at

$end_year

\?integer

The year the event ends at (NULL: not a multi day event)

$end_month

\?integer

The month the event ends at (NULL: not a multi day event)

$end_day

\?integer

The day the event ends at (NULL: not a multi day event)

$end_monthly_spec_type

\ID_TEXT

In-month specification type for end date

$end_hour

\?integer

The hour the event ends at (NULL: not a multi day event)

$end_minute

\?integer

The minute the event ends at (NULL: not a multi day event)

$timezone

\?ID_TEXT

The timezone for the event (NULL: current user's timezone)

$do_timezone_conv

\BINARY

Whether the time should be presented in the viewer's own timezone

$meta_keywords

\SHORT_TEXT

Meta keywords

$meta_description

\LONG_TEXT

Meta description

$validated

\BINARY

Whether the download has been validated

$allow_rating

\BINARY

Whether the download may be rated

$allow_comments

\SHORT_INTEGER

Whether comments are allowed (0=no, 1=yes, 2=review style)

$allow_trackbacks

\BINARY

Whether the download may be trackbacked

$notes

\LONG_TEXT

Hidden notes pertaining to the download

Edit a calendar event type.

edit_event_type(\AUTO_LINK $id, \SHORT_TEXT $title, \ID_TEXT $logo, \URLPATH $external_feed) 

Parameters

$id

\AUTO_LINK

The ID of the event type

$title

\SHORT_TEXT

The title of the event type

$logo

\ID_TEXT

The theme image code

$external_feed

\URLPATH

URL to external feed to associate with this event type

Given a calendar day of month, work out the day of the month within the specified encoding.

find_abstract_day(integer $year, integer $month, integer $day_of_month, \ID_TEXT $monthly_spec_type) : integer

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$year

integer

The concrete year

$month

integer

The concrete month

$day_of_month

integer

The encoded day of month

$monthly_spec_type

\ID_TEXT

In-month specification type

Returns

integerConcrete day

Given a specially encoded day of month, work out the real day of the month.

find_concrete_day_of_month(integer $year, integer $month, integer $day, \ID_TEXT $monthly_spec_type, integer $hour, integer $minute, \ID_TEXT $timezone, boolean $show_in_users_timezone) : integer

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$year

integer

The concrete year

$month

integer

The concrete month

$day

integer

The encoded day of month

$monthly_spec_type

\ID_TEXT

In-month specification type

$hour

integer

The concrete hour

$minute

integer

The concrete minute

$timezone

\ID_TEXT

The timezone

$show_in_users_timezone

boolean

Whether to do a timezone conversion (NB: unused, as this is before conversion to what dates users see - we are only using timezones here to push the nth weekday appropriately to the correct timezone, due to alignment problems)

Returns

integerConcrete day

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

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

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards
set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

The timezone for the event (NULL: current user's timezone)

$do_timezone_conv

\BINARY

Whether the time should be converted to the viewer's own timezone

$start_year

integer

The year the event starts at. This and the below are in server time

$start_month

integer

The month the event starts at

$start_day

integer

The day the event starts at

$start_monthly_spec_type

\ID_TEXT

In-month specification type for start date

$start_hour

integer

The hour the event starts at

$start_minute

integer

The minute the event starts at

$end_year

\?integer

The year the event ends at (NULL: not a multi day event)

$end_month

\?integer

The month the event ends at (NULL: not a multi day event)

$end_day

\?integer

The day the event ends at (NULL: not a multi day event)

$end_monthly_spec_type

\ID_TEXT

In-month specification type for end date

$end_hour

\?integer

The hour the event ends at (NULL: not a multi day event / all day event)

$end_minute

\?integer

The minute the event ends at (NULL: not a multi day event / all day event)

$recurrence

string

The event recurrence

$recurrences

\?integer

The number of recurrences (NULL: none/infinite)

$period_start

\?TIME

The timestamp that found times must exceed. In user-time (NULL: now)

$period_end

\?TIME

The timestamp that found times must not exceed. In user-time (NULL: 20 years time)

Returns

arrayA 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'

Find last hour in day for a timezone.

find_timezone_end_hour_in_utc(\ID_TEXT $timezone, integer $year, integer $month, integer $day, \ID_TEXT $monthly_spec_type) : integer

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

Timezone

$year

integer

Year

$month

integer

Month

$day

integer

Day

$monthly_spec_type

\ID_TEXT

In-month specification type

Returns

integerHour

Find last minute in day for a timezone.

find_timezone_end_minute_in_utc(\ID_TEXT $timezone, integer $year, integer $month, integer $day, \ID_TEXT $monthly_spec_type) : integer

Usually 59, but some timezones have 30 min offsets.

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

Timezone

$year

integer

Year

$month

integer

Month

$day

integer

Day

$monthly_spec_type

\ID_TEXT

In-month specification type

Returns

integerHour

Find first hour in day for a timezone.

find_timezone_start_hour_in_utc(\ID_TEXT $timezone, integer $year, integer $month, integer $day, \ID_TEXT $monthly_spec_type) : integer

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

Timezone

$year

integer

Year

$month

integer

Month

$day

integer

Day

$monthly_spec_type

\ID_TEXT

In-month specification type

Returns

integerHour

Find first minute in day for a timezone.

find_timezone_start_minute_in_utc(\ID_TEXT $timezone, integer $year, integer $month, integer $day, \ID_TEXT $monthly_spec_type) : integer

Usually 0, but some timezones have 30 min offsets.

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$timezone

\ID_TEXT

Timezone

$year

integer

Year

$month

integer

Month

$day

integer

Day

$monthly_spec_type

\ID_TEXT

In-month specification type

Returns

integerHour

Get the number of days between two dates (so first+dif=second).

get_days_between(integer $initial_start_month, integer $initial_start_day, integer $initial_start_year, integer $initial_end_month, integer $initial_end_day, integer $initial_end_year) : integer

Parameters

$initial_start_month

integer

Start month

$initial_start_day

integer

Start day

$initial_start_year

integer

Start year

$initial_end_month

integer

End month

$initial_end_day

integer

End day

$initial_end_year

integer

End year

Returns

integerThe number of days

Get array of an events from node of an imported ical file

get_event_data_ical(array $calendar_nodes) : array

Parameters

$calendar_nodes

array

Array of given event details

Returns

arrayReturns array of event details for mapping

Get the week number for a time.

get_week_number_for(\TIME $timestamp, boolean $no_year) : string

Parameters

$timestamp

\TIME

The week number

$no_year

boolean

Whether to do it contextually to the year, rather than including the year

Returns

stringThe week number

Escapes a string as per the ical format.

ical_escape(string $in) : string

Parameters

$in

string

Input

Returns

stringOutput

Import ical events to members's event calendar.

ical_import(\PATH $file_name) 

Parameters

$file_name

\PATH

File path

Standard code module init function.

init__calendar() 

Choose how a recurring monthly event should be encoded.

monthly_spec_type_chooser(integer $day_of_month, integer $month, integer $year, \ID_TEXT $default_monthly_spec_type) : \tempcode

set day_of_month day_of_month_backwards dow_of_month dow_of_month_backwards

Parameters

$day_of_month

integer

The concrete day

$month

integer

The concrete month

$year

integer

The concrete year

$default_monthly_spec_type

\ID_TEXT

Current in-month specification type

Returns

\tempcodeChooser

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

nice_get_event_types(\?AUTO_LINK $it) : \tempcode

Parameters

$it

\?AUTO_LINK

The event type to select by default (NULL: none)

Returns

\tempcodeThe list

Get a list of events to edit.

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

Parameters

$only_owned

\?MEMBER

Only show events owned by this member (NULL: no such limitation)

$it

\?AUTO_LINK

Event to select by default (NULL: no specific default)

$edit_viewable_events

boolean

Whether owned public events should be shown

Returns

\tempcodeThe list

Outputs the logged-in member's calendar view to ical.

output_ical() 

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

regenerate_event_reminder_jobs(\AUTO_LINK $id, boolean $force) 

Parameters

$id

\AUTO_LINK

The ID of the event

$force

boolean

Force evaluation even if it's in the past. Only valid for code events