## WebCalendar Function Documentation

Home Page: | http://webcalendar.sourceforge.net/
WebCalendar Version: | v1.0RC3+CVS (?? ??? 2005)
Last updated: | 04-Mar-2005

## List of Functions

- activate_urls
- activity_log
- background_css
- boss_must_approve_event
- boss_must_be_notified
- build_entry_popup
- calc_time_slot
- check_for_conflicts
- clean_html
- clean_int
- clean_whitespace
- clean_word
- daily_matrix
- date_selection
- date_to_str
- dbi_affected_rows
- dbi_close
- dbi_connect
- dbi_error
- dbi_fatal_error
- dbi_fetch_row
- dbi_free_result
- dbi_query
- decode_string
- die_miserable_death
- display_small_month
- display_time
- display_unapproved_events
- do_debug
- do_redirect
- encode_string
- etooltip
- etranslate
- event_get_external_users
- getGetValue
- getIntValue
- getPostValue
- getValue
- get_all_dates
- get_entries
- get_last_view
- get_monday_before
- get_my_users
- get_nonuser_cals
- get_pref_setting
- get_preferred_view
- get_repeating_entries
- get_site_extra_fields
- get_sunday_before
- html_for_add_icon
- html_for_event_day_at_a_glance
- html_for_event_week_at_a_glance
- html_to_8bits
- languageToAbbrev
- load_global_settings
- load_nonuser_preferences
- load_translation_text
- load_user_categories
- load_user_layers
- load_user_preferences
- month_name
- month_short_name
- nonuser_load_variables
- print_category_menu
- print_date_entries
- print_date_entries_timebar
- date_selection
- print_day_at_a_glance
- print_entry
- print_entry_timebar
- print_header
- print_header_timebar
- print_trailer
- query_events
- read_events
- read_repeated_events
- remember_this_view
- repeated_event_matches_date
- reset_language
- send_http_login
- send_no_cache_header
- send_to_preferred_view
- set_today
- site_extras_for_popup
- time_to_minutes
- times_overlap
- tooltip
- translate
- user_get_boss_list
- user_has_boss
- user_is_assistant
- user_is_nonuser_admin
- week_number
- weekday_name
- weekday_short_name

### activate_urls

`activate_urls ( $text )`
Description:

> Look for URLs in the given text, and make them into links.

Parameters:

- `$text` - input text

Returns:

> The text altered to have HTML links for any web links (http or https)

Location:

> functions.php, line 3275

### activity_log

`activity_log ( $event_id, $user, $user_cal, $type, $text )`
Description:

> Add something to the activity log for an event. The information will be saved to the `webcal_entry_log` table.

Parameters:

- `$event_id` - event id
- `$user` - user doing this
- `$user_cal` - user whose calendar is affected
- `$type` - type of activity we are logging:
  - $LOG_CREATE
  - $LOG_APPROVE
  - $LOG_REJECT
  - $LOG_UPDATE
  - $LOG_DELETE
  - $LOG_NOTIFICATION
  - $LOG_REMINDER
- `$text` - text comment to add with activity log entry

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 771

### background_css

`background_css ( $color, $height, $percent )`
Description:

> Creates the CSS for using gradient.php, if the appropriate GD functions are available. A one-pixel wide image will be used for the background image.
> Note The gd library module needs to be available to use gradient images. If it is not available, a single background color will be used instead.

Parameters:

- `$color` - base color
- `$height` - height of gradient image
- `$percent` - how many percent lighter the top color should be than the base color at the bottom of the image

Returns:

> The style sheet text to use

Location:

> functions.php, line 4433

### boss_must_approve_event

`boss_must_approve_event ( $assistant, $boss )`
Description:

> Check the boss user preferences to see if the boss must approve events added to their calendar.

Parameters:

- `$assistant` - assistant login
- `$boss` - boss login

Returns:

> true if the boss must approve new events

Location:

> functions.php, line 3810

### boss_must_be_notified

`boss_must_be_notified ( $assistant, $boss )`
Description:

> Check the boss user preferences to see if the boss wants to be notified via email on changes to their calendar.

Parameters:

- `$assistant` - assistant login
- `$boss` - boss login

Returns:

> true if the boss wants email notifications

Location:

> functions.php, line 3794

### build_entry_popup

`build_entry_popup ( $popupid, $user, $description, $time, $site_extras )`
Description:

> Build the HTML for the event popup (but don't print it yet since we don't want this HTML to go inside the table for the month).

Parameters:

- `$popupid` - CSS id to use for event popup
- `$user` - user the event pertains to
- `$description` - event description
- `$time` - time of the event (already formatted in a display format)
- `$site_extras` - the HTML for any site_extras for this event

Returns:

> The HTML for the event popup

Location:

> functions.php, line 1084

### calc_time_slot

`calc_time_slot ( $time, $round_down, $10AM )`
Description:

> Calculate which row/slot this time represents. This is used in day and week views where hours of the time are separated into different cells in a table.

Parameters:

- `$time` - input time in YYYYMMDD format
- `$round_down` - should we change 1100 to 1059?
- `$10AM` - 100AM appointment just shows up in the 10AM slow and not in the 11AM slot also.)
  Note the global variable $TIME_SLOTS is used to determine how many time slots there are and how many minutes each is. This variable is defined user preferences (or defaulted to admin system settings).

Returns:

> The time slot index

Location:

> functions.php, line 2655

### check_for_conflicts

`check_for_conflicts ( $date, $duration, $hour, $minute, $participants, $login, $id )`
Description:

> Check for conflicts. Find overlaps between an array of dates and the other dates in the database.
> Limits on number of appointments: if enabled in System Settings ($LIMIT_APPTS global variable), too many appointments can also generate a scheduling conflict.
> TODO Update this to handle exceptions to repeating events

Parameters:

- `$date` - is an array of dates in YYYYMMDD format that is checked for overlaps.
- `$duration` - event duration in minutes
- `$hour` - hour of event (0-23)
- `$minute` - minute of the event (0-59)
- `$participants` - an array of users whose calendars are to be checked
- `$login` - the current user name
- `$id` - current event id (this keeps overlaps from wrongly checking an event against itself)

Returns:

> Return empty string for no conflicts or return the HTML of the conflicts when one or more are found.

Location:

> functions.php, line 2461

### clean_html

`clean_html ( $value )`
Description:

> Replace unsafe characters with HTML encoded equivalents

Parameters:

- `$value` - input text

Returns:

> the cleaned text

Location:

> functions.php, line 4363

### clean_int

`clean_int ( $data )`
Description:

> Remove non-digits from the specified text

Parameters:

- `$data` - input text

Returns:

> the converted text

Location:

> functions.php, line 4392

### clean_whitespace

`clean_whitespace ( $data )`
Description:

> Remove whitespace from the specified text

Parameters:

- `$data` - input text

Returns:

> the converted text

Location:

> functions.php, line 4404

### clean_word

`clean_word ( $data )`
Description:

> Remove non-word characters from the specified text

Parameters:

- `$data` - input text

Returns:

> the converted text

Location:

> functions.php, line 4380

### daily_matrix

`daily_matrix ( $date, $participants )`
Description:

> Draws a daily outlook style availability grid showing events that are approved and awaiting approval.

Parameters:

- `$date` - the date to show the grid for
- `$participants` - which users should be included in the grid

Returns:

> Nothing

Location:

> functions.php, line 4474

### date_selection

`date_selection ( $prefix, $date )`
Description:

> Print out a date selection for use in a form.

Parameters:

- `$prefix` - prefix to use in front of form element names
- `$date` - currently selected date (in YYYYMMDD) format

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 1152

### date_to_str

`date_to_str ( $indate, $format, $show_weekday, $short_months, $server_time )`
Description:

> Convert a date in YYYYMMDD format into "Friday, December 31, 1999", "Friday, 12-31-1999" or whatever format the user prefers.

Parameters:

- `$indate` - date in YYYYMMDD format
- `$format` - format to use for date (default is "__month__ __dd__, __yyyy__")
- `$show_weekday` - should the day of week also be included (true/false)
- `$short_months` - should the abbreviated month names be used instead of the full month names
- `$server_time` - ???

Returns:

> The query result resource on queries (which can then be passed to the `dbi_fetch_row` function to obtain the results), or true/false on insert or delete queries.

Location:

> functions.php, line 3430

### dbi_affected_rows

`dbi_affected_rows ( $conn, $res )`
Description:

> Returns the number of rows affected by the last INSERT, UPDATE or DELETE.
> Note Use the `dbi_error` function to get error information if the connection fails.

Parameters:

- `$conn` - The database connection
- `$res` - The database query resource returned from the `dbi_query` function.

Returns:

> The number or database rows affected.

Location:

> php-dbi.php, line 358

### dbi_close

`dbi_close ( $conn )`
Description:

> Close a database connection. (Not necessary for any database that uses pooled connections such as MySQL, but a good programming practice.)

Parameters:

- `$conn` - The database connection

Returns:

> true on success, false on error

Location:

> php-dbi.php, line 187

### dbi_connect

`dbi_connect ( $host, $login, $password, $database )`
Description:

> Open up a database connection. Use a pooled connection if the db supports it and the `db_persistent` setting is enabled.
> Notes
> - The database type is determined by the global variable `db_type`
> - For ODBC, $host is ignored, $database = DSN
> - For Oracle, $database = tnsnames name
> - Use the `dbi_error` function to get error information if the connection fails

Parameters:

- `$host` - Hostname of database server
- `$login` - Database login
- `$password` - Database login password
- `$database` - Name of database

Returns:

> The connection

Location:

> php-dbi.php, line 66

### dbi_error

`dbi_error ( $ )`
Description:

> Get the latest database error message.

Parameters:

- None

Returns:

> The text of the last database error. (The type of information varies depending on the which type of database is being used.)

Location:

> php-dbi.php, line 428

### dbi_fatal_error

`dbi_fatal_error ( $msg, $doExit, $showError )`
Description:

> Display a fatal database error and abort execution.

Parameters:

- `$msg` - The database error message
- `$doExit` - Abort execution (true/false)
- `$showError` - Show the details of the error (possibly including the SQL that caused the error)

Returns:

> Nothing

Location:

> php-dbi.php, line 461

### dbi_fetch_row

`dbi_fetch_row ( $res )`
Description:

> Retrieve a single row from the database and return it as an array.
> Note we don't use the more useful xxx_fetch_array because not all databases support this function.
> Note Use the `dbi_error` function to get error information if the connection fails.

Parameters:

- `$res` - The database query resource returned from the `dbi_query` function.

Returns:

> An array of database columns representing a single row in the query result or false on an error.

Location:

> php-dbi.php, line 305

### dbi_free_result

`dbi_free_result ( $res )`
Description:

> Free a result set.

Parameters:

- `$res` - The database query resource returned from the `dbi_query` function.

Returns:

> true on success

Location:

> php-dbi.php, line 395

### dbi_query

`dbi_query ( $sql, $fatalOnError, $showError )`
Description:

> Execute a SQL query.
> Note Use the `dbi_error` function to get error information if the connection fails.

Parameters:

- `$sql` - SQL of query to execute
- `$fatalOnError` - Abort execution if there is a database error
- `$showError` - Display error to use (including possibly the SQL) if there is a database error

Returns:

> The query result resource on queries (which can then be passed to the `dbi_fetch_row` function to obtain the results), or true/false on insert or delete queries.

Location:

> php-dbi.php, line 230

### decode_string

`decode_string ( $instr )`
Description:

> Extract a user's name from a session id. This prevents users from begin able to edit their cookies.txt file and set the username in plain text.

Parameters:

- `$instr` - a hex-encoded string. "Hello" would be "678ea786a5".

Returns:

> The decoded string

Location:

> functions.php, line 3530

### die_miserable_death

`die_miserable_death ( $error )`
Description:

> Print a fatal error message to the user along with a link to the Troubleshooting section of the WebCalendar System Administrator's Guide. Execution is aborted.

Parameters:

- `$error` - The error message to display

Returns:

> Nothing

Location:

> config.php, line 39

### display_small_month

`display_small_month ( $thismonth, $thisyear, $showyear, $show_weeknums, $minical_id, $month_link )`
Description:

> Prints out a minicalendar for a month

Parameters:

- `$thismonth` - number of the month to print
- `$thisyear` - number of the year
- `$showyear` - boolean whether to show the year in the calendar's title
- `$show_weeknums` - boolean whether to show week numbers to the left of each row
- `$minical_id` - id attribute for the minical table
- `$month_link` - URL and query string for month link that should come before the date specification (i.e. month.php? or view_l.php?id=7&amp;) [defaults to 'month.php?']

Returns:

> Nothing

Location:

> functions.php, line 1195

### display_time

`display_time ( $time, $ignore_offset )`
Description:

> Display a time in either 12 or 24 hour format. The global variable $TZ_OFFSET to adjust the time. Note that this is somewhat of a kludge for timezone support. If an event is set for 11PM server time and the user is 2 hours ahead, it will show up as 1AM, but the date will not be adjusted to the next day.

Parameters:

- `$time` - input time in HHMMSS format
- `$ignore_offset` - if true, then do not use the timezone offset (optional)

Returns:

> The query result resource on queries (which can then be passed to the `dbi_fetch_row` function to obtain the results), or true/false on insert or delete queries.

Location:

> functions.php, line 3292

### display_unapproved_events

`display_unapproved_events ( $user )`
Description:

> Check for any unaproved events. If any are found, display a link to the unapproved events (where they can be approved). If the user is an admin user, also count up any public events. If the user is a nonuser admin, count up events on the nonuser calendar.

Parameters:

- `$user` - current user login

Returns:

> Nothing

Location:

> functions.php, line 3222

### do_debug

`do_debug ( $msg )`
Description:

> Log a debug message. Generally, we do not leave calls to this function in the code. It is used for debugging only.

Parameters:

- `$msg` - Text to be logged

Returns:

> Nothing

Location:

> functions.php, line 410

### do_redirect

`do_redirect ( $url )`
Description:

> Send a redirect to the specified page. The database connection is closed and execution terminates in this function.
> Note: MS IIS/PWS has a bug in which it does not allow us to send a cookie and a redirect in the same HTTP header. When we detect that the web server is IIS, we accomplish the redirect using meta-refresh. See the following for more info on the IIS bug:

> > http://www.faqts.com/knowledge_base/view.phtml/aid/9316/fid/4

Parameters:

- `$url` - The page to redirect to. In theory, this should be an absolute URL, but all browsers accept relative URLs (like "month.php").

Returns:

> Nothing

Location:

> functions.php, line 483

### encode_string

`encode_string ( $instr )`
Description:

> Take an input string and encode it into a slightly encoded hexval that we can use as a session cookie.

Parameters:

- `$instr` - text to encode

Returns:

> the encoded text

Location:

> functions.php, line 3564

### etooltip

`etooltip ( $str )`
Description:

> Translate text and remove and HTML from it. This is useful for tooltips, which barf on HTML.
> Note The `tooltip` function will return the result rather than print the value.

Parameters:

- `$str` - the input text to translate and print

Returns:

> Nothing

Location:

> translate.php, line 176

### etranslate

`etranslate ( $str )`
Description:

> Translate text and print it. This is just an abbreviation for: echo translate ( $str )

Parameters:

- `$str` - input text to translate and print

Returns:

> Nothing

Location:

> translate.php, line 147

### event_get_external_users

`event_get_external_users ( $event_id, $use_mailto )`
Description:

> Get the list of external users for an event from the `webcal_entry_ext_user` table in an HTML format.

Parameters:

- `$event_id` - event id
- `$use_mailto` - when set to 1, email address will contain an href link with a mailto URL.

Returns:

> The list of external users for an event formatted in HTML.

Location:

> functions.php, line 729

### getGetValue

`getGetValue ( $name )`
Description:

> Get the value resulting from an HTTP GET method.
> Note: The return value will be affected by the value of `magic_quotes_gpc` in the `php.ini` file. If you need to enforce a specific input format (such as numeric input), then use the `getValue` function.

Parameters:

- `$name` - Name used in the HTML form or found in the URL

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 190

### getIntValue

`getIntValue ( $name, $fatal )`
Description:

> Get an integer value resulting from an HTTP GET or HTTP POST method.
> Note: The return value will be affected by the value of `magic_quotes_gpc` in the `php.ini` file.

Parameters:

- `$name` - Name used in the HTML form or found in the URL
- `$fatal` - Is it considered a fatal error requiring execution to stop if the value retrieved does not match the format regular expression?

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 257

### getPostValue

`getPostValue ( $name )`
Description:

> Get the value resulting from an HTTP POST method.
> Note: The return value will be affected by the value of `magic_quotes_gpc` in the `php.ini` file.

Parameters:

- `$name` - Name used in the HTML form

Returns:

> the value used in the HTML form

Location:

> functions.php, line 168

### getValue

`getValue ( $name, $format, $fatal )`
Description:

> Get the value resulting from either HTTP GET method or HTTP POST method.
> Note: The return value will be affected by the value of `magic_quotes_gpc` in the `php.ini` file.
> Note: If you need to get an integer value, you can use the `getIntValue` function.

Parameters:

- `$name` - Name used in the HTML form or found in the URL
- `$format` - A regular expression format that the input must match. If the input does not match, an empty string is returned and a warning is sent to the browser. If The $fatal parameter is true, then execution will also stop when the input does not match the format.
- `$fatal` - Is it considered a fatal error requiring execution to stop if the value retrieved does not match the format regular expression?

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 215

### get_all_dates

`get_all_dates ( $date, $rpt_type, $end, $days, $ex_dates, $freq )`
Description:

> Returns all the dates a specific event will fall on accounting for the repeating. Any event with no end will be assigned one.

Parameters:

- `$date` - initial date in raw format
- `$rpt_type` - repeating type as stored in the database
- `$end` - end date
- `$days` - days events occurs on (for weekly)
- `$ex_dates` - array of exception dates for this event in YYYYMMDD format
- `$freq` - frequency of repetition

Returns:

> An array of dates (in UNIX time format)

Location:

> functions.php, line 1856

### get_entries

`get_entries ( $user, $date, $get_unapproved )`
Description:

> Get all the events for a specific date from the array of pre-loaded events (which was loaded all at once to improve performance). The returned events will be sorted by time of day.

Parameters:

- `$user` - username
- `$date` - date to get events for in YYYYMMDD format
- `$get_unapproved` - load unapproved events (true/false)

Returns:

> An array of events

Location:

> functions.php, line 1594

### get_last_view

`get_last_view ( $ )`
Description:

> Get the last page stored using the `remember_this_view` function. Return empty string if we don't know.

Parameters:

- None

Returns:

> The URL of the last view or an empty string if it cannot be determined.

Location:

> functions.php, line 586

### get_monday_before

`get_monday_before ( $year, $month, $day )`
Description:

> Get the Monday of the week that the specified date is in. (If the date specified is a Monday, then that date is returned.)

Parameters:

- `$year` - year in YYYY format
- `$month` - month (1-12)
- `$day` - day of the month

Returns:

> The date (in unix time format)

Location:

> functions.php, line 2238

### get_my_users

`get_my_users ( $ )`
Description:

> Get a list of users. If groups are enabled, this will restrict the list of users to only those users who are in the same group(s) as the user (unless the user is an admin user). We allow admin users to see all users because they can also edit someone else's events (so they may need access to users who are not in the same groups that they are in).

Parameters:

- None

Returns:

> An array of users, where each element in the array is an array with the following keys:
> - cal_login
> - cal_lastname
> - cal_firstname
> - cal_is_admin
> - cal_is_admin
> - cal_email
> - cal_password
> - cal_fullname

Location:

> functions.php, line 826

### get_nonuser_cals

`get_nonuser_cals ( $user )`
Description:

> Get a list of nonuser calendars and return info in an array.

Parameters:

- `$user` - (optional) login of admin of the nonuser calendars

Returns:

> An array of nonuser cals, where each is an array with the following fields:
> - cal_login
> - cal_lastname
> - cal_firstname
> - cal_admin
> - cal_fullname

Location:

> functions.php, line 4107

### get_pref_setting

`get_pref_setting ( $user, $setting )`
Description:

> Get a preference setting for the specified user. If no value is found in the database, then the system default setting will be returned.

Parameters:

- `$user` - user login we are getting preference for
- `$setting` - the name of the setting

Returns:

> The value found in the `webcal_user_pref` table for the specified setting or the system default if no user settings was found.

Location:

> functions.php, line 901

### get_preferred_view

`get_preferred_view ( $date, $args )`
Description:

> Get user's preferred view. The user's preferred view is stored in the $STARTVIEW global variable. This is loaded from the user preferences (or system settings if there are no user preferences.)

Parameters:

- `$date` - (optional) date to pass to preferred view in YYYYMMDD format
- `$args` - (optional) arguments to include in the URL (such as "user=joe")

Returns:

> Nothing

Location:

> functions.php, line 425

### get_repeating_entries

`get_repeating_entries ( $user, $date, $get_unapproved )`
Description:

> Get all the repeating events for the specified data and return them in an array (which is sorted by time of day).
> Note The global variable `$repeated_events` needs to be set by calling the `read_repeated_events` function first.

Parameters:

- `$user` - username
- `$date` - date to get events for in YYYYMMDD format
- `$get_unapproved` - include unapproved events in results

Returns:

> The query result resource on queries (which can then be passed to the `dbi_fetch_row` function to obtain the results), or true/false on insert or delete queries.

Location:

> functions.php, line 2039

### get_site_extra_fields

`get_site_extra_fields ( $eventid )`
Description:

> Get any site-specific fields for an entry that are stored in the database in the `webcal_site_extras` table.

Parameters:

- `$eventid` - event id

Returns:

> Return an array of array with the keys as follows:
> - cal_name
> - cal_type
> - cal_date
> - cal_remind
> - cal_data

Location:

> functions.php, line 1475

### get_sunday_before

`get_sunday_before ( $year, $month, $day )`
Description:

> Get the Sunday of the week that the specified date is in. (If the date specified is a Sunday, then that date is returned.)

Parameters:

- `$year` - year in YYYY format
- `$month` - month (1-12)
- `$day` - day of the month

Returns:

> The date (in unix time format)

Location:

> functions.php, line 2221

### html_for_add_icon

`html_for_add_icon ( $ )`
Description:

> Generate the HTML for an icon to add a new event.

Parameters:

- None

Returns:

> The HTML for the add event icon

Location:

> functions.php, line 2690

### html_for_event_day_at_a_glance

`html_for_event_day_at_a_glance ( $id, $date, $time, $name, $description, $status, $pri, $access, $duration, $event_owner, $event_category )`
Description:

> Generate the HTML for an event to be viewed in the day-at-glance (day.php). The HTML will be stored in an array ($hour_arr) indexed on the event's starting hour.

Parameters:

- `$id` - event id
- `$date` - date of event in YYYYMMDD format
- `$time` - time of event in HHMM format
- `$name` - brief description of event
- `$description` - full description of event
- `$status` - status of event ('A', 'W')
- `$pri` - priority of event
- `$access` - access to event by others ('P', 'R')
- `$duration` - duration of event in minutes
- `$event_owner` - user who created event
- `$event_category` - category id for event

Returns:

> Nothing

Location:

> functions.php, line 2871

### html_for_event_week_at_a_glance

`html_for_event_week_at_a_glance ( $id, $date, $time, $name, $description, $status, $pri, $access, $duration, $event_owner, $event_category )`
Description:

> Generate the HTML for an event to be viewed in the week-at-glance (week.php). The HTML will be stored in an array (global variable $hour_arr) indexed on the event's starting hour.

Parameters:

- `$id` - event id
- `$date` - date of event in YYYYMMDD format
- `$time` - time of event in HHMM format
- `$name` - brief description of event
- `$description` - full description of event
- `$status` - status of event ('A', 'W')
- `$pri` - priority of event
- `$access` - access to event by others ('P', 'R')
- `$duration` - duration of event in minutes
- `$event_owner` - user who created event
- `$event_category` - category id for event

Returns:

> Nothing

Location:

> functions.php, line 2722

### html_to_8bits

`html_to_8bits ( $html )`
Description:

> Convert HTML entities in 8bit.
> Note Only supported for PHP4 (not PHP3).

Parameters:

- `$html` - HTML text

Returns:

> The converted text

Location:

> functions.php, line 3692

### languageToAbbrev

`languageToAbbrev ( $name )`
Description:

> Converts language names to their abbreviation

Parameters:

- `$name` - Name of the language (such as "French")

Returns:

> The abbreviation ("fr" for "French")

Location:

> functions.php, line 4416

### load_global_settings

`load_global_settings ( $ )`
Description:

> Load default system settings (which can be updated via admin.php) System settings are stored in the `webcal_config` table.
> Note: If the setting for "server_url" is not set, the value will be calculated and stored in the database.

Parameters:

- None

Returns:

> Nothing

Location:

> functions.php, line 276

### load_nonuser_preferences

`load_nonuser_preferences ( $nonuser )`
Description:

> Loads nonuser preferences from the `webcal_user_pref` table if on a nonuser admin page.

Parameters:

- `$nonuser` - login name for nonuser calendar

Returns:

> Nothing

Location:

> functions.php, line 4218

### load_translation_text

`load_translation_text ( $ )`
Description:

> Load all the language translation into an array for quick lookup.
> Note There is no need to call this manually. It will be invoked by the `translate` function the first time it is called.

Parameters:

- None

Returns:

> Nothing

Location:

> translate.php, line 71

### load_user_categories

`load_user_categories ( $ex_global )`
Description:

> Load current user's category info and stuff it into category global variable.

Parameters:

- `$ex_global` - Don't include global categories ('' or '1')

Returns:

> Nothing

Location:

> functions.php, line 3624

### load_user_layers

`load_user_layers ( $user, $force )`
Description:

> Load current user's layer info and stuff it into layer global variable. If the system setting $ALLOW_VIEW_OTHER is not set to 'Y', then we ignore all layer functionality. If $force is 0, we only load layers if the current user preferences have layers turned on.

Parameters:

- `$user` - User to load layers for
- `$force` - If set to 1, then load layers for this user even if user preferences have layers turned off.

Returns:

> Nothing

Location:

> functions.php, line 963

### load_user_preferences

`load_user_preferences ( $ )`
Description:

> Load the current user's preferences as global variables from the `webcal_user_pref` table. Also load the list of views for this user (not really a preference, but this is a convenient place to put this...)
> Notes
> - If the $ALLOW_COLOR_CUSTOMIZATION is set to 'N', then we ignore any color preferences.
> - Other default values will also be set if the user has not saved a preference and no global value has been set by the administrator in the system settings.

Parameters:

- None

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 622

### month_name

`month_name ( $m )`
Description:

> Return the full name of the specified month. Use the `month_short_name` function to get the abbreviated name of the month.

Parameters:

- `$m` - month (0-11)

Returns:

> The full name of the specified month

Location:

> functions.php, line 3330

### month_short_name

`month_short_name ( $m )`
Description:

> Return the abbreviated name of the specified month (such as "Jan"). Use the `month_name` function to get the full name of the month.

Parameters:

- `$m` - month (0-11)

Returns:

> The abbreviated name of the specified month (example: "Jan")

Location:

> functions.php, line 3358

### nonuser_load_variables

`nonuser_load_variables ( $login, $prefix )`
Description:

> Loads nonuser variables (login, firstname, etc.) The following variables will be set:
> - login
> - firstname
> - lastname
> - fullname
> - admin
> - email

Parameters:

- `$login` - login name of nonuser calendar
- `$prefix` - prefix to use for variables that will be set. For example, if prefix is "temp", then the login will be stored in the $templogin global variable.

Returns:

> Nothing

Location:

> functions.php, line 4149

### print_category_menu

`print_category_menu ( $form, $date, $cat_id )`
Description:

> Print dropdown HTML for categories.

Parameters:

- `$form` - the page to submit data to (without .php)
- `$date` - date in YYYYMMDD format
- `$cat_id` - category id that should be pre-selected

Returns:

> Nothing

Location:

> functions.php, line 3657

### print_date_entries

`print_date_entries ( $date, $user, $is_ssi )`
Description:

> Print all the calendar entries for the specified user for the specified date. If we are displaying data from someone other than the logged in user, then check the access permission of the entry.

Parameters:

- `$date` - date in YYYYMMDD format
- `$user` - username
- `$is_ssi` - is this being called from week_ssi.php? If so, then

Returns:

> Nothing

Location:

> functions.php, line 2296

### print_date_entries_timebar

`print_date_entries_timebar ( $date, $user, $ssi )`
Description:

> Print all the entries in a time bar format for the specified user for the specified date. If we are displaying data from someone other than the logged in user, then check the access permission of the entry.

Parameters:

- `$date` - date in YYYYMMDD format
- `$user` - username
- `$ssi` - should we not include links to add new events?

Returns:

> Nothing

Location:

> functions.php, line 3834

### date_selection

`date_selection ( $prefix, $date )`
Description:

> Print out a date selection for use in a form.

Parameters:

- `$prefix` - prefix to use in front of form element names
- `$date` - currently selected date (in YYYYMMDD) format

Returns:

> The value used in the HTML form (or URL)

Location:

> functions.php, line 1139

### print_day_at_a_glance

`print_day_at_a_glance ( $date, $user )`
Description:

> Print all the calendar entries for the specified user for the specified date in day-at-a-glance format. If we are displaying data from someone other than the logged in user, then check the access permission of the entry.

Parameters:

- `$date` - date in YYYYMMDD format
- `$user` - username of calendar

Returns:

> Nothing

Location:

> functions.php, line 3026

### print_entry

`print_entry ( $id, $date, $time, $duration, $name, $description, $status, $pri, $access, $event_owner, $event_cat )`
Description:

> Print the HTML for one day's events in the month view.

Parameters:

- `$id` - event id
- `$date` - date of event (relevant in repeating events) in YYYYMMDD format
- `$time` - time (in HHMMSS format)
- `$duration` - event duration (in minutes)
- `$name` - event name
- `$description` - long description of event
- `$status` - event status
- `$pri` - event priority
- `$access` - event access
- `$event_owner` - user associated with this event
- `$event_cat` - category of event for event_owner

Returns:

> Nothing

Location:

> functions.php, line 1350

### print_entry_timebar

`print_entry_timebar ( $id, $date, $time, $duration, $name, $description, $status, $pri, $access, $event_owner, $event_category )`
Description:

> Print the HTML for an events with a timebar.

Parameters:

- `$id` - event id
- `$date` - date of event in YYYYMMDD format
- `$time` - time of event in HHMM format
- `$duration` - duration of event in minutes
- `$name` - brief description of event
- `$description` - full description of event
- `$status` - status of event ('A', 'W')
- `$pri` - priority of event
- `$access` - access to event by others ('P', 'R')
- `$event_owner` - user who created event
- `$event_category` - category id for event

Returns:

> Nothing

Location:

> functions.php, line 3914

### print_header

`print_header ( $includes, $HeadX, $BodyX, $disbleCustom, $disableStyle )`
Description:

> Prints the HTML header and opening HTML body tag.

Parameters:

- `$includes` - an array of additional files to include referenced from the includes directory
- `$HeadX` - a variable containing any other data to be printed inside the head tag (meta, script, etc)
- `$BodyX` - a variable containing any other data to be printed inside the Body tag (onload for example)
- `$disbleCustom` - do not include custom header (useful for small popup windows, such as color selection)
- `$disableStyle` - do not include the standard css

Returns:

> Nothing

Location:

> init.php, line 213

### print_header_timebar

`print_header_timebar ( $start_hour, $end_hour )`
Description:

> Print the header for the timebar.

Parameters:

- `$start_hour` - start hour
- `$end_hour` - end hour

Returns:

> Nothing

Location:

> functions.php, line 4069

### print_trailer

`print_trailer ( $include_nav_links, $closeDb, $disableCustom )`
Description:

> Print the common trailer.

Parameters:

- `$include_nav_links` - should the standard navigation links be included in the trailer (true/false).
- `$closeDb` - close the database connection (true/false)
- `$disableCustom` - disable the custom trailer the administrator has setup. (This is useful for small popup windows and pages being used in an iframe.)

Returns:

> Nothing

Location:

> init.php, line 334

### query_events

`query_events ( $user, $want_repeated, $non, $date_filter, $cat_id )`
Description:

> Read events visible to a user (including layers and possibly public access if enabled); Return results in an array sorted by time of day.

Parameters:

- `$user` - username
- `$want_repeated` - true to get repeating events; false to get
- `$non` - repeating.
- `$date_filter` - SQL phrase starting with AND, to be appended to the WHERE clause. May be empty string.
- `$cat_id` - category ID to filter on. May be empty.

Returns:

> An array of events

Location:

> functions.php, line 1676

### read_events

`read_events ( $user, $startdate, $enddate, $cat_id )`
Description:

> Read all the events for a user for the specified range of dates. This is only called once per page request to improve performance. All the events get loaded into the array $events sorted by time of day (not date).

Parameters:

- `$user` - username
- `$startdate` - start date range, inclusive (in YYYYMMDD format)
- `$enddate` - end date range, inclusive (in YYYYMMDD format)
- `$cat_id` - category ID to filter on

Returns:

> An array of events

Location:

> functions.php, line 1512

### read_repeated_events

`read_repeated_events ( $user, $date, $cat_id )`
Description:

> Read all the repeated events for a user. This is only called once per page request to improve performance. All the events get loaded into the array $repeated_events sorted by time of day (not date). This will load all the repeated events into memory.
> Notes
> - To get which events repeat on a specific date, use the `get_repeating_entries` function.
> - To get all the dates that one specific event repeats on, the `get_all_dates` function should be called.

Parameters:

- `$user` - username
- `$cat_id` - category ID to filter on (May be empty)
- `$date` - cutoff date for repeating event endtimes in YYYYMMDD format (may be empty)

Returns:

> An array of repeating events

Location:

> functions.php, line 1828

### remember_this_view

`remember_this_view ( $ )`
Description:

> Generate a cookie that saves the last calendar view (month, week, day) based on the current $REQUEST_URI so we can return to this same page after a user edits/deletes/etc an event.

Parameters:

- None

Returns:

> Nothing

Location:

> functions.php, line 567

### repeated_event_matches_date

`repeated_event_matches_date ( $event, $dateYmd )`
Description:

> Returns a boolean stating whether or not the event passed in will fall on the date passed.

Parameters:

- `$event` - the event as an array
- `$dateYmd` - the date to check in YYYYMMDD format

Returns:

> true or false

Location:

> functions.php, line 2073

### reset_language

`reset_language ( $new_language )`
Description:

> Unload translations so we can switch languages and translate into a different language).

Parameters:

- `$new_language` - new language file to load (just the base filename, no directory or file suffix. Example: "French")

Returns:

> Nothing

Location:

> translate.php, line 48

### send_http_login

`send_http_login ( $ )`
Description:

> Send an HTTP login request to the browser and stop execution.

Parameters:

- None

Returns:

> Nothing

Location:

> functions.php, line 534

### send_no_cache_header

`send_no_cache_header ( $ )`
Description:

> Send header stuff that tells the browser not to cache this page. Different browser use different mechanisms for this, so a series of HTTP header directives are sent.
> Note This function needs to be called before any HTML output is sent to the browser.

Parameters:

- None

Returns:

> Nothing

Location:

> functions.php, line 606

### send_to_preferred_view

`send_to_preferred_view ( $date, $args )`
Description:

> Send a redirect to the user's preferred view. The user's preferred view is stored in the $STARTVIEW global variable. This is loaded from the user preferences (or system settings if there are no user preferences.)

Parameters:

- `$date` - (optional) date to pass to preferred view in YYYYMMDD format
- `$args` - (optional) arguments to include in the URL (such as "user=joe")

Returns:

> Nothing

Location:

> functions.php, line 467

### set_today

`set_today ( $date )`
Description:

> Determines what the day is after the $TZ_OFFSET and sets it globally. The following global variables will be set:
> - $thisyear
> - $thismonth
> - $thisday
> - $thisdate
> - $today

Parameters:

- `$date` - the date in YYYYMMDD format

Returns:

> Nothing

Location:

> functions.php, line 4246

### site_extras_for_popup

`site_extras_for_popup ( $id )`
Description:

> Generate the HTML used in an event popup for the site_extras fields of an event.

Parameters:

- `$id` - event id

Returns:

> The HTML to be used within the event popup for any site_extra fields found for the specified event

Location:

> functions.php, line 1011

### time_to_minutes

`time_to_minutes ( $time )`
Description:

> Convert a time format HHMMSS (like 131000 for 1PM) into number of minutes past midnight.

Parameters:

- `$time` - input time in HHMMSS format

Returns:

> The number of minutes since midnight

Location:

> functions.php, line 2639

### times_overlap

`times_overlap ( $time1, $duration1, $time2, $duration1 )`
Description:

> Check to see if two events overlap.

Parameters:

- `$time1` - time 1 in HHMMSS format
- `$duration1` - duration 1 in minutes
- `$time2` - time 2 in HHMMSS format
- `$duration1` - duration 1 in minutes

Returns:

> true if the two times overlap, false if they do not

Location:

> functions.php, line 2428

### tooltip

`tooltip ( $str )`
Description:

> Translate text and remove and HTML from it. This is useful for tooltips, which barf on HTML.
> Note The `etooltip` function will print the result rather than return the value.

Parameters:

- `$str` - the input text to translate

Returns:

> The translated text with all HTML removed

Location:

> translate.php, line 158

### translate

`translate ( $str )`
Description:

> Translate a string from the default English usage to some other language. The first time that this is called, the translation file will be loaded (with the `load_translation_text` function).

Parameters:

- `$str` - text to translate

Returns:

> The translated text, if available. If no translation is available, then the original untranslated text is returned.

Location:

> translate.php, line 115

### user_get_boss_list

`user_get_boss_list ( $assistant )`
Description:

> Get a list of an assistant's boss from the `webcal_asst` table.

Parameters:

- `$assistant` - login of assistant

Returns:

> An array of bosses, where each boss is an array with the following fields:
> - cal_login
> - cal_fullname

Location:

> functions.php, line 3714

### user_has_boss

`user_has_boss ( $assistant )`
Description:

> Check the `webcal_asst` table to see if the specified user login has any bosses associated with it.

Parameters:

- `$assistant` - login for user

Returns:

> true if the user is an assistant to one or more bosses

Location:

> functions.php, line 3773

### user_is_assistant

`user_is_assistant ( $assistant, $boss )`
Description:

> Return true if $user is $boss assistant by checking in the `webcal_asst` table.

Parameters:

- `$assistant` - login of potential assistant
- `$boss` - login of potential boss

Returns:

> true or false

Location:

> functions.php, line 3748

### user_is_nonuser_admin

`user_is_nonuser_admin ( $login, $nonuser )`
Description:

> Check the `webcal_nonuser_cals` table to determine if the user is the administrator for the nonuser calendar.

Parameters:

- `$login` - login of user that is the potential administrator
- `$nonuser` - login name for nonuser calendar

Returns:

> true if the user is the administrator for the nonuser calendar

Location:

> functions.php, line 4195

### week_number

`week_number ( $date )`
Description:

> Returns week number for specified date. depending from week numbering settings.

Parameters:

- `$date` - date in UNIX time format

Returns:

> The week number of the specified date

Location:

> functions.php, line 2258

### weekday_name

`weekday_name ( $w )`
Description:

> Return the full weekday name. Use the `weekday_short_name` function to get the abbreviated weekday name.

Parameters:

- `$w` - weekday (0=Sunday,...,6=Saturday)

Returns:

> the full weekday name ("Sunday")

Location:

> functions.php, line 3386

### weekday_short_name

`weekday_short_name ( $w )`
Description:

> Return the abbreviated weekday name. Use the `weekday_name` function to get the full weekday name.

Parameters:

- `$w` - weekday (0=Sunday,...,6=Saturday)

Returns:

> the abbreviated weekday name ("Sun")

Location:

> functions.php, line 3408