Documentation

Calendar
in package

SMF

implements ActionInterface, Routable uses ActionTrait, 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.
Routable: Classes implementing this interface can build routes from URL query parameters and parse routes back into URL query parameters.

Properties

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

Methods

buildRoute() : array<string|int, mixed>: Builds a routing path based on URL query parameters.
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.
call() : void: Convenience method to load() and execute() an instance of this class.
canBeLogged() : bool: Determines whether this action can be logged in the online log.
canLinkEvent() : bool: Does permission checks to see if the current user can link the current topic to a calendar event.
canShowDebuggingInfo() : bool: Determines whether debugging info should be shown.
canShowInMaintenanceMode() : bool: Determines whether this action allows access in maintenance mode.
clock() : void: Nothing to see here. Move along.
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.
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.
getOutputType() : OutputTypeInterface: Gets the output type for this action.
getTodayInfo() : array<string|int, mixed>: Returns date information about 'today' relative to the users time offset.
isAgreementAction() : bool: Determines whether this action can be accessed without accepting the registration agreement and privacy policy.
isRestrictedGuestAccessAllowed() : bool: Determines whether this action allows access if guest access is restricted.
isSimpleAction() : bool: Determines whether this is a simple action.
load() : static: Static wrapper for constructor.
parseRoute() : array<string|int, mixed>: Parses a route to get URL query parameters.
post() : void: This method processes posting/editing/deleting a calendar event.
show() : void: Shows the calendar.
subActionProvider() : null|array<string|int, mixed>: Called by Subs-Compat.php BackwardCompatibility wrapper functions to provide subaction execution for existing mods
validateEventPost() : void: Makes sure the calendar post is valid.
__construct() : mixed: Constructor. Protected to force instantiation via self::load().
authenticateForExport() : User: Validates the guest-supplided user ID and token combination, and loads and returns the requested user if the token is valid. Otherwise, returns the current user.
createToken() : string: Generates an calendar subscription authentication token.
getBoardsForExport() : array<string|int, mixed>: Gets the board IDs for boards where the passed user wants to see events.

$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    static
    $obj

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

buildRoute()

Builds a routing path based on URL query parameters.


    public
            static        buildRoute(array<string|int, mixed> $params) : array<string|int, mixed>

Parameters

$params : array<string|int, mixed>: URL query parameters.

Return values

array<string|int, mixed> —

Contains two elements: ['route' => [], 'params' => []]. The 'route' element contains the routing path. The 'params' element contains any $params that weren't incorporated into the route.

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

call()

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


    public
            static        call() : void

canBeLogged()

Determines whether this action can be logged in the online log.


    public
                    canBeLogged() : bool

Return values

bool

canLinkEvent()

Does permission checks to see if the current user can link the current topic to a calendar event.


    public
            static        canLinkEvent([bool $trigger_error = true ][, Event|null $event = null ]) : bool

To succeed, the following conditions must be met:

The calendar must be enabled.
If an event is passed to the $event parameter, the current user must be able to edit that event. Otherwise, the current user must be able to create new events.
There must be a current topic (i.e. Topic::$topic_id must be set).
The current user must be able to edit the first post in the current topic.

Parameters

$trigger_error : bool = true: Whether to trigger an error if the user cannot link an event to this topic. Default: true.
$event : Event|null = null: The event that the user wants to link to the current topic, or null if the user wants to create a new event.

Return values

bool —

Whether the user can link an event to the current topic.

canShowDebuggingInfo()

Determines whether debugging info should be shown.


    public
                    canShowDebuggingInfo() : bool

Return values

bool

canShowInMaintenanceMode()

Determines whether this action allows access in maintenance mode.


    public
                    canShowInMaintenanceMode() : bool

Return values

bool —

True if access is allowed, false otherwise.

clock()

Nothing to see here. Move along.


    public
                    clock() : void

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

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 ]) : 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

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.

getOutputType()

Gets the output type for this action.


    public
                    getOutputType() : OutputTypeInterface

Return values

OutputTypeInterface

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)

isAgreementAction()

Determines whether this action can be accessed without accepting the registration agreement and privacy policy.


    public
                    isAgreementAction() : bool

Return values

bool

isRestrictedGuestAccessAllowed()

Determines whether this action allows access if guest access is restricted.


    public
                    isRestrictedGuestAccessAllowed() : bool

Return values

bool —

True if access is allowed, false otherwise.

isSimpleAction()

Determines whether this is a simple action.


    public
                    isSimpleAction() : bool

Return values

bool

load()

Static wrapper for constructor.


    public
            static        load() : static

Return values

static —

An instance of this class.

parseRoute()

Parses a route to get URL query parameters.


    public
            static        parseRoute(array<string|int, mixed> $route[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>

Parameters

$route : array<string|int, mixed>: Array of routing path components.
$params : array<string|int, mixed> = []: Any existing URL query parameters.

Return values

array<string|int, mixed> —

URL query parameters

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.

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.

subActionProvider()

Called by Subs-Compat.php BackwardCompatibility wrapper functions to provide subaction execution for existing mods


    public
            static        subActionProvider([null|string $sa = null ][, bool $return_config = false ][, string|null $activity = null ]) : null|array<string|int, mixed>

Parameters

$sa : null|string = null
$return_config : bool = false
$activity : string|null = null

Return values

null|array<string|int, mixed>

validateEventPost()

Makes sure the calendar post is valid.


    public
            static        validateEventPost() : void

__construct()

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


    protected
                    __construct() : mixed

authenticateForExport()

Validates the guest-supplided user ID and token combination, and loads and returns the requested user if the token is valid. Otherwise, returns the current user.


    protected
                    authenticateForExport() : User

Return values

User —

whose permissions should be used for exporting events.

createToken()

Generates an calendar subscription authentication token.


    protected
                    createToken(User $user) : string

Parameters

$user : User: The member that this token is for.

Return values

string —

The authentication token.

getBoardsForExport()

Gets the board IDs for boards where the passed user wants to see events.


    protected
                    getBoardsForExport(User $user) : array<string|int, mixed>

Parameters

$user : User: The user whose permissions should be used.

Return values

array<string|int, mixed> —

An array of board IDs.

Calendar in package SMF implements ActionInterface, Routable uses ActionTrait, BackwardCompatibility

Table of Contents

Interfaces

Properties

Methods

Properties

$subaction

$subactions

$obj

Methods

buildRoute()

Parameters

Return values

cache_getOffsetIndependentEvents()

Parameters

Return values

cache_getRecentEvents()

Parameters

Return values

call()

canBeLogged()

Return values

canLinkEvent()

Parameters

Return values

canShowDebuggingInfo()

Return values

canShowInMaintenanceMode()

Return values

clock()

execute()

export()

Tags

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

getOutputType()

Return values

getTodayInfo()

Return values

isAgreementAction()

Return values

isRestrictedGuestAccessAllowed()

Return values

isSimpleAction()

Return values

load()

Return values

parseRoute()

Parameters

Return values

post()

show()

subActionProvider()

Parameters

Return values

validateEventPost()

__construct()

authenticateForExport()

Return values

createToken()

Parameters

Calendar
in package

SMF

implements ActionInterface, Routable uses ActionTrait, BackwardCompatibility