Documentation

Calendar
in package

SMF

implements ActionInterface Uses BackwardCompatibility

This class has only one real task, showing the calendar.

Original module by Aaron O'Neil - aaron@mud-master.com

Interfaces

ActionInterface: Interface for all action classes.

Properties

$subaction : string
$subactions : array<string|int, mixed>
$obj : object
$backcompat : array<string|int, mixed>

Methods

cache_getOffsetIndependentEvents() : array<string|int, mixed>: Retrieve all events for the given days, independently of the users offset.
cache_getRecentEvents() : array<string|int, mixed>: cache callback function used to retrieve the upcoming birthdays, holidays, and events within the given period, taking into account the users time offset.
CalendarPost() : void: Backward compatibility wrapper for post sub-action.
call() : void: Convenience method to load() and execute() an instance of this class.
canLinkEvent() : void: Does permission checks to see if an event can be linked to a board/topic.
clock() : void: Nothing to see here. Move along.
convertDateToEnglish() : string: Helper function to convert date string to english so that date_parse can parse the date
execute() : void: Dispatcher to whichever sub-action method is necessary.
export() : void: This function offers up a download of an event in iCal 2.0 format.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
getBirthdayRange() : array<string|int, mixed>: Get all birthdays within the given time range.
getCalendarGrid() : array<string|int, mixed>: Provides information (link, month, year) about the previous and next month.
getCalendarList() : array<string|int, mixed>: Returns the information needed to show a list of upcoming events, birthdays, and holidays on the calendar.
getCalendarWeek() : array<string|int, mixed>: Returns the information needed to show a calendar for the given week.
getEventPoster() : int|bool: Get the event's poster.
getEventRange() : array<string|int, mixed>: Get all calendar events within the given time range.
getHolidayRange() : array<string|int, mixed>: Get all holidays within the given time range.
getTodayInfo() : array<string|int, mixed>: Returns date information about 'today' relative to the users time offset.
iCalDownload() : void: Backward compatibility wrapper for ical sub-action.
list_getHolidays() : array<string|int, mixed>: Gets all of the holidays for the listing
list_getNumHolidays() : int: Helper function to get the total number of holidays
load() : object: Static wrapper for constructor.
loadDatePair() : void: Loads the necessary JavaScript for Datepair.js.
loadDatePicker() : void: Loads the necessary JavaScript and CSS to create a datepicker.
loadTimePicker() : void: Loads the necessary JavaScript and CSS to create a timepicker.
post() : void: This method processes posting/editing/deleting a calendar event.
removeHolidays() : void: Remove a holiday from the calendar
show() : void: Shows the calendar.
validateEventPost() : void: Makes sure the calendar post is valid.
__construct() : mixed: Constructor. Protected to force instantiation via self::load().

$subaction


    public
        string
    $subaction
     = 'show'

The requested sub-action. This should be set by the constructor.

$subactions


    public
    static    array<string|int, mixed>
    $subactions
     = ['show' => 'show', 'ical' => 'export', 'post' => 'post', 'clock' => 'clock']

Available sub-actions of this action.

$obj


    protected
    static    object
    $obj

An instance of the class. This is used by the load() method to prevent mulitple instantiations.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['call' => 'CalendarMain', 'iCalDownload' => 'iCalDownload', 'CalendarPost' => 'CalendarPost', 'getBirthdayRange' => 'getBirthdayRange', 'getEventRange' => 'getEventRange', 'getHolidayRange' => 'getHolidayRange', 'canLinkEvent' => 'canLinkEvent', 'getTodayInfo' => 'getTodayInfo', 'getCalendarGrid' => 'getCalendarGrid', 'getCalendarWeek' => 'getCalendarWeek', 'getCalendarList' => 'getCalendarList', 'loadDatePicker' => 'loadDatePicker', 'loadTimePicker' => 'loadTimePicker', 'loadDatePair' => 'loadDatePair', 'cache_getOffsetIndependentEvents' => 'cache_getOffsetIndependentEvents', 'cache_getRecentEvents' => 'cache_getRecentEvents', 'validateEventPost' => 'validateEventPost', 'getEventPoster' => 'getEventPoster', 'list_getHolidays' => 'list_getHolidays', 'list_getNumHolidays' => 'list_getNumHolidays', 'removeHolidays' => 'removeHolidays', 'convertDateToEnglish' => 'convertDateToEnglish']]

BackwardCompatibility settings for this class.

cache_getOffsetIndependentEvents()

Retrieve all events for the given days, independently of the users offset.


    public
            static        cache_getOffsetIndependentEvents(array<string|int, mixed> $eventOptions) : array<string|int, mixed>

cache callback function used to retrieve the birthdays, holidays, and events between now and now + days_to_index. widens the search range by an extra 24 hours to support time offset shifts. used by the self::cache_getRecentEvents function to get the information needed to calculate the events taking the users time offset into account.

Parameters

$eventOptions : array<string|int, mixed>: With the keys 'num_days_shown', 'include_holidays', 'include_birthdays' and 'include_events'

Return values

array<string|int, mixed> —

An array containing the data that was cached as well as an expression to calculate whether the data should be refreshed and when it expires

cache_getRecentEvents()

cache callback function used to retrieve the upcoming birthdays, holidays, and events within the given period, taking into account the users time offset.


    public
            static        cache_getRecentEvents(array<string|int, mixed> $eventOptions) : array<string|int, mixed>

Called from the BoardIndex to display the current day's events on the board index used by the board index and SSI to show the upcoming events.

Parameters

$eventOptions : array<string|int, mixed>: An array of event options.

Return values

array<string|int, mixed> —

An array containing the info that was cached as well as a few other relevant things

CalendarPost()

Backward compatibility wrapper for post sub-action.


    public
            static        CalendarPost() : void

call()

Convenience method to load() and execute() an instance of this class.


    public
            static        call() : void

canLinkEvent()

Does permission checks to see if an event can be linked to a board/topic.


    public
            static        canLinkEvent() : void

Checks if the current user can link the current topic to the calendar, permissions et al. This requires the calendar_post permission, a forum moderator, or a topic starter. Expects the Topic::$topic_id and Board::$info->id variables to be set. If the user doesn't have proper permissions, an error will be shown.

clock()

Nothing to see here. Move along.


    public
                    clock() : void

convertDateToEnglish()

Helper function to convert date string to english so that date_parse can parse the date


    public
            static        convertDateToEnglish(string $date) : string

Parameters

$date : string: A localized date string

Return values

string —

English date string

execute()

Dispatcher to whichever sub-action method is necessary.


    public
                    execute() : void

export()

This function offers up a download of an event in iCal 2.0 format.


    public
                    export() : void

Follows the conventions in RFC5546

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

getBirthdayRange()

Get all birthdays within the given time range.


    public
            static        getBirthdayRange(string $low_date, string $high_date) : array<string|int, mixed>

finds all the birthdays in the specified range of days. works with birthdays set for no year, or any other year, and respects month and year boundaries.

Parameters

$low_date : string: The low end of the range, inclusive, in YYYY-MM-DD format
$high_date : string: The high end of the range, inclusive, in YYYY-MM-DD format

Return values

array<string|int, mixed> —

An array of days, each of which is an array of birthday information for the context

getCalendarGrid()

Provides information (link, month, year) about the previous and next month.


    public
            static        getCalendarGrid(string $selected_date, array<string|int, mixed> $calendarOptions[, bool $is_previous = false ][, bool $has_picker = true ]) : array<string|int, mixed>

Parameters

$selected_date : string: A date in YYYY-MM-DD format
$calendarOptions : array<string|int, mixed>: An array of calendar options
$is_previous : bool = false: Whether this is the previous month
$has_picker : bool = true: Whether to add javascript to handle a date picker

Return values

array<string|int, mixed> —

A large array containing all the information needed to show a calendar grid for the given month

getCalendarList()

Returns the information needed to show a list of upcoming events, birthdays, and holidays on the calendar.


    public
            static        getCalendarList(string $start_date, string $end_date, array<string|int, mixed> $calendarOptions) : array<string|int, mixed>

Parameters

$start_date : string: The start of a date range in YYYY-MM-DD format
$end_date : string: The end of a date range in YYYY-MM-DD format
$calendarOptions : array<string|int, mixed>: An array of calendar options

Return values

array<string|int, mixed> —

An array of information needed to display a list of upcoming events, etc., on the calendar

getCalendarWeek()

Returns the information needed to show a calendar for the given week.


    public
            static        getCalendarWeek(string $selected_date, array<string|int, mixed> $calendarOptions) : array<string|int, mixed>

Parameters

$selected_date : string: A date in YYYY-MM-DD format
$calendarOptions : array<string|int, mixed>: An array of calendar options

Return values

array<string|int, mixed> —

An array of information needed to display the grid for a single week on the calendar

getEventPoster()

Get the event's poster.


    public
            static        getEventPoster(int $event_id) : int|bool

Parameters

$event_id : int: The ID of the event

Return values

int|bool —

The ID of the poster or false if the event was not found

getEventRange()

Get all calendar events within the given time range.


    public
            static        getEventRange(string $low_date, string $high_date[, bool $use_permissions = true ]) : array<string|int, mixed>

Finds all the posted calendar events within a date range.
Both the earliest_date and latest_date should be in the standard YYYY-MM-DD format.
Censors the posted event titles.
Uses the current user's permissions if use_permissions is true, otherwise it does nothing "permission specific"

Parameters

$low_date : string: The low end of the range, inclusive, in YYYY-MM-DD format
$high_date : string: The high end of the range, inclusive, in YYYY-MM-DD format
$use_permissions : bool = true: Whether to use permissions

Return values

array<string|int, mixed> —

The loaded events.

getHolidayRange()

Get all holidays within the given time range.


    public
            static        getHolidayRange(string $low_date, string $high_date) : array<string|int, mixed>

Parameters

$low_date : string: The low end of the range, inclusive, in YYYY-MM-DD format
$high_date : string: The high end of the range, inclusive, in YYYY-MM-DD format

Return values

array<string|int, mixed> —

An array of days, which are all arrays of holiday names.

getTodayInfo()

Returns date information about 'today' relative to the users time offset.


    public
            static        getTodayInfo() : array<string|int, mixed>

returns an array with the current date, day, month, and year. takes the users time offset into account.

Return values

array<string|int, mixed> —

An array of info about today, based on forum time. Has 'day', 'month', 'year' and 'date' (in YYYY-MM-DD format)

iCalDownload()

Backward compatibility wrapper for ical sub-action.


    public
            static        iCalDownload() : void

list_getHolidays()

Gets all of the holidays for the listing


    public
            static        list_getHolidays(int $start, int $items_per_page, string $sort) : array<string|int, mixed>

Parameters

$start : int: The item to start with (for pagination purposes)
$items_per_page : int: How many items to show on each page
$sort : string: A string indicating how to sort the results

Return values

array<string|int, mixed> —

An array of holidays, each of which is an array containing the id, year, month, day and title of the holiday

list_getNumHolidays()

Helper function to get the total number of holidays


    public
            static        list_getNumHolidays() : int

Return values

int —

The total number of holidays

load()

Static wrapper for constructor.


    public
            static        load() : object

Return values

object —

An instance of this class.

loadDatePair()

Loads the necessary JavaScript for Datepair.js.


    public
            static        loadDatePair(string $container[, string $date_class = '' ][, string $time_class = '' ]) : void

Datepair.js helps to keep date ranges sane in the UI.

Parameters

$container : string: CSS selector for the containing element of the date/time inputs to be paired.
$date_class : string = '': The CSS class of the date inputs to be paired.
$time_class : string = '': The CSS class of the time inputs to be paired.

loadDatePicker()

Loads the necessary JavaScript and CSS to create a datepicker.


    public
            static        loadDatePicker([string $selector = 'input.date_input' ][, string $date_format = '' ]) : void

Parameters

$selector : string = 'input.date_input': A CSS selector for the input field(s) that the datepicker should be attached to.
$date_format : string = '': The date format to use, in strftime() format.

loadTimePicker()

Loads the necessary JavaScript and CSS to create a timepicker.


    public
            static        loadTimePicker([string $selector = 'input.time_input' ][, string $time_format = '' ]) : void

Parameters

$selector : string = 'input.time_input': A CSS selector for the input field(s) that the timepicker should be attached to.
$time_format : string = '': A time format in strftime format

post()

This method processes posting/editing/deleting a calendar event.


    public
                    post() : void

Calls Post() function if event is linked to a post.

It requires the calendar_post permission to use. It uses the event_post sub template in the Calendar template. It is accessed with ?action=calendar;sa=post.

removeHolidays()

Remove a holiday from the calendar


    public
            static        removeHolidays(array<string|int, mixed> $holiday_ids) : void

Parameters

$holiday_ids : array<string|int, mixed>: An array of IDs of holidays to delete

show()

Shows the calendar.


    public
                    show() : void

It loads the specified month's events, holidays, and birthdays. It requires the calendar_view permission. It depends on the cal_enabled setting, and many of the other cal_ settings. It uses the calendar_start_day theme option. (Monday/Sunday) It uses the main sub template in the Calendar template. It goes to the month and year passed in 'month' and 'year' by get or post. It is accessed through ?action=calendar.

validateEventPost()

Makes sure the calendar post is valid.


    public
            static        validateEventPost() : void

__construct()

Constructor. Protected to force instantiation via self::load().


    protected
                    __construct() : mixed

Calendar in package SMF implements ActionInterface Uses BackwardCompatibility

Table of Contents

Interfaces

Properties

Methods

Properties

$subaction

$subactions

$obj

$backcompat

Methods

cache_getOffsetIndependentEvents()

Parameters

Return values

cache_getRecentEvents()

Parameters

Return values

CalendarPost()

call()

canLinkEvent()

clock()

convertDateToEnglish()

Parameters

Return values

execute()

export()

Tags

exportStatic()

getBirthdayRange()

Parameters

Return values

getCalendarGrid()

Parameters

Return values

getCalendarList()

Parameters

Return values

getCalendarWeek()

Parameters

Return values

getEventPoster()

Parameters

Return values

getEventRange()

Parameters

Return values

getHolidayRange()

Parameters

Return values

getTodayInfo()

Return values

iCalDownload()

list_getHolidays()

Parameters

Return values

list_getNumHolidays()

Return values

load()

Return values

loadDatePair()

Parameters

loadDatePicker()

Parameters

loadTimePicker()

Parameters

post()

removeHolidays()

Parameters

show()

validateEventPost()

__construct()

Calendar
in package

SMF

implements ActionInterface Uses BackwardCompatibility