Namespace: api
SimpleCalendar.api
The SimpleCalendar.api
namespace contains functions and properties used to update the Simple Calendar module or get information from it.
Enumerations
- Calendars
- CompactViewDateTimeControlDisplay
- GameWorldTimeIntegrations
- Icons
- LeapYearRules
- MoonYearResetOptions
- NoteRepeat
- PresetTimeOfDay
- YearNamingRules
Functions
activateFullCalendarListeners
▸ activateFullCalendarListeners(calendarId
, onMonthChange?
, onDayClick?
): void
This function is used to activate event listeners for calendars displayed with the sc-full-calendar.
If being used in a FoundryVTT application or FormApplication it is best called in the activateListeners function.
Example
SimpleCalendar.api.activateFullCalendarListeners('example_1');
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | undefined | The ID of the HTML element of the calendar to activate listeners for. This is the same ID used in the sc-full-calendar. |
onMonthChange | null | Function | null | Optional function to be called when the month being viewed has changed. Returned parameters to the function are: - The direction moved, previous or next. - The options used to render the calendar, which includes the date being shown. |
onDayClick | null | Function | null | Optional function to be called when a day is clicked. Returned parameters to the function are: - The options used to render the calendar, which includes the selected date. |
Returns
void
addNote
▸ addNote(title
, content
, startDate
, endDate
, allDay
, repeats?
, categories?
, calendarId?
, macro?
, userVisibility?
, remindUsers?
): Promise
<StoredDocument
<JournalEntry
> | null
>
This function adds a new note to the calendar
Example
const newJournal = await SimpleCalendar.api.addNote('Christmas Day','Presents!', {year: 2022, month: 11, day: 24, hour: 0, minute: 0, seconds: 0}, {year: 2022, month: 11, day: 24, hour: 0, minute: 0, seconds: 0}, true, SimpleCalendar.api.NoteRepeat.Yearly, ['Holiday']);
// Will create a new note on Christmas day of 2022 that lasts all day and repeats yearly.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
title | string | undefined | The title of the new note |
content | string | undefined | The contents of the new note |
startDate | DateTimeParts | undefined | The date and time the note starts, if any date or time properties are missing the current date/time values will be used. |
endDate | DateTimeParts | undefined | The date and time the note ends (can be the same as the start date), if any date or time properties are missing the current date/time values will be used. |
allDay | boolean | undefined | If the note lasts all day or if it has a specific time duration. Whether to ignore the time portion of the start and end dates. |
repeats | NoteRepeat | NoteRepeat.Never | If the note repeats and how often it does |
categories | string [] | [] | A list of note categories to assign to this note |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to add the note too. If not provided the current active calendar will be used. |
macro | null | string | null | The ID of the macro that this note should execute when the in game time meets or exceeds the note time. Or null if no macro should be executed. |
userVisibility | string [] | [] | Optional parameter to specify an array of user ID's who will have permission to view the note. The creator of the note will always have permission. Use ['default'] if you want all users to be able to view it. |
remindUsers | string [] | [] | Optional parameter to provide an array of user ID's who will be reminded of the note. |
Returns
Promise
<StoredDocument
<JournalEntry
> | null
>
The newly created JournalEntry that contains the note data, or null if there was an error encountered.
addSidebarButton
▸ addSidebarButton(buttonTitle
, iconClass
, customClass
, showSidePanel
, onRender
): any
Add a custom button to the right side of the calendar (When in full view). The button will be added below the Note Search button.
Example
// Function to call to populate the side panel
function populateSidePanel(event, element){
if(element){
const header = document.createElement('h2');
header.innerText = "My Custom Button";
element.append(header);
}
}
// Function to call when the button is clicked
function sidePanelButtonClick(event, element){
if(event){
const dialog = new Dialog({
title: "My Module",
content: "You clicked the button!",
buttons:{
awesome: {
icon: '<i class="fa-solid fa-face-smile"></i>',
label: "Awesome!"
}
},
default: "awesome"
});
dialog.render(true);
}
}
// Adding a button that should show a side panel
// Clicking the button will show a side panel that will have the title "My Custom Button"
SimpleCalendar.api.addSidebarButton("My Module", "fa-computer-mouse", "my-custom-class", true, populateSidePanel);
// Adding a button that will show a dialog when clicked
SimpleCalendar.api.addSidebarButton("My Module", "fa-computer-mouse", "my-custom-class", false, sidePanelButtonClick);
Parameters
Name | Type | Description |
---|---|---|
buttonTitle | string | The text that appears when the button is hovered over. |
iconClass | string | The Font Awesome Free icon class to use for the buttons display. |
customClass | string | A custom CSS class to add to the button. |
showSidePanel | boolean | If the button should open a side panel or not. A side panel functions like the notes list but will be completely empty. |
onRender | (event : null | Event , renderTarget : undefined | null | HTMLElement ) => void | Function that is called to show information to users. If the showSidePanel parameter is true this function will be passed an HTMLElement representing the side panel. The element could potentially be null so code should account for that. This function is then responsible for populating the side panel with any information. This function is called everytime the calendar is rendered. If the showSidePanel parameter is false this function will be passed an Event for the click. The event could potentially be null so code should account for that. This function should then open up an application or dialog or perform an action for the user. This function is called everytime the button is clicked. |
Returns
any
advanceTimeToPreset
▸ advanceTimeToPreset(preset
, calendarId?
): boolean
Advance the date and time to match the next preset time.
Important: This function can only be run by users who have permission to change the date in Simple Calendar.
Example
//Assuming the current time is 11am, set the time to the next sunset
//Will result in the date staying the same but the time changing to 6pm
SimpleCalendar.api.advanceTimeToPreset(SimpleCalendar.api.PresetTimeOfDay.Sunset);
//Assuming the current time is 11am, set the time to the next sunrise
//Will result in the date advancing by 1 day and the time changing to 6am
SimpleCalendar.api.advanceTimeToPreset(SimpleCalendar.api.PresetTimeOfDay.Sunrise);
Parameters
Name | Type | Default value | Description |
---|---|---|---|
preset | PresetTimeOfDay | undefined | The preset time that is used to set the time of day. |
calendarId | string | "active" | Optional parameter specify the ID of the calendar to advance the time and date for. If not provided the current active calendar will be used. |
Returns
boolean
True if the date was set successfully, false if it was not.
changeDate
▸ changeDate(interval
, calendarId?
): boolean
Changes the current date of Simple Calendar. Important: This function can only be run by users who have permission to change the date in Simple Calendar.
Example
//Assuming a date of June 1, 2021 and user has permission to change the date
SimpleCalendar.api.changeDate({day: 1}); // Will set the new date to June 2, 2021
//Assuming a date of June 1, 2021 and user has permission to change the date
SimpleCalendar.api.changeDate({day: -1}); // Will set the new date to May 31, 2021
//Assuming a date of June 1, 2021 10:00:00 and user has permission to change the date
SimpleCalendar.api.changeDate({year: 1, month: 1, day: 1, hour: 1, minute: 1, seconds: 1}); // Will set the new date to July 2, 2022 11:01:01
//Assuming a date of June 1, 2021 10:00:00 and user has permission to change the date
SimpleCalendar.api.changeDate({seconds: 3600}); // Will set the new date to June 1, 2021 11:00:00
Parameters
Name | Type | Default value | Description |
---|---|---|---|
interval | DateTimeParts | undefined | The interval objects properties are all optional so only those that are needed have to be set. Where each property is how many of that interval to change the current date by. |
calendarId | string | "active" | Optional parameter specify the ID of the calendar to change the date on. If not provided the current active calendar will be used. |
Returns
boolean
True if the date change was successful and false if it was not.
chooseRandomDate
▸ chooseRandomDate(startingDate?
, endingDate?
, calendarId?
): DateTime
Will choose a random date between the 2 passed in dates, or if no dates are passed in will choose a random date.
Example
SimpleCalendar.api.chooseRandomDate({year: 2021, month: 3, day: 0}, {year: 2021, month: 5, day: 1})
// {
// day: 1
// hour: 12
// minute: 5
// month: 4
// seconds: 41
// year: 2021
// }
SimpleCalendar.api.chooseRandomDate({year: 1900, month: 3}, {year: 2021, month: 5})
// {
// day: 19
// hour: 8
// minute: 16
// month: 3
// seconds: 25
// year: 1982
// }
SimpleCalendar.api.chooseRandomDate();
// {
// day: 11
// hour: 0
// minute: 49
// month: 8
// seconds: 37
// year: 3276
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
startingDate | DateTimeParts | {} | The start date objects properties are all optional so only those needed have to be set. Where each property is the earliest date to be chosen when randomly selecting a date. The month and day properties are both index's so January would be 0 and the first day of the month is also 0. |
endingDate | DateTimeParts | {} | The end date objects properties are all optional so only those needed have to be set. Where each property is the latest date to be chosen when randomly selecting a date. The month and day properties are both index's so January would be 0 and the first day of the month is also 0. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to choose the random date from. If not provided the current active calendar will be used. |
Returns
A full date and time, where all properties will be randomly set. The month and day properties will be the index of the month/day chosen.
clockStatus
▸ clockStatus(calendarId?
): ClockStatus
Get the current status of the built-in clock for the specified calendar in Simple Calendar
Example
const status = SimpleCalendar.api.clockStatus();
console.log(status); // {started: false, stopped: true, paused: false}
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to check its clock status. If not provided the current active calendar will be used. |
Returns
The clock status for the specified calendar.
configureCalendar
▸ configureCalendar(calendarData
, calendarId?
): Promise
<boolean
>
Sets up the current calendar to match the passed in configuration. This function can only be run by GMs.
Example
//Set the calendar configuration to the Gregorian calendar
const result = await SimpleCalendar.api.configureCalendar(SimpleCalendar.api.Calendars.Gregorian);
//Set the calendar configuration to a custom calendar
const custom = {};
const result = await SimpleCalendar.api.configureCalendar(custom);
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarData | Calendars | CalendarData | undefined | The configuration to set the calendar to. It can be one of the predefined calendars or a CalendarData object representing a custom calendar. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to configure. If not provided the current active calendar will be used. |
Returns
Promise
<boolean
>
A promise that resolves to a boolean value, true if the change was successful and false if it was not.
currentDateTime
▸ currentDateTime(calendarId?
): DateTime
| null
Gets the current date and time for the current calendar or the passed in calendar.
Example
// Assuming a Gregorian calendar
SimpleCalendar.api.currentDateTime();
//Returns a DateTime object like this
// {
// year: 2021,
// month: 11,
// day: 24,
// hour: 12,
// minute: 13,
// seconds: 14
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current day from. If not provided the current active calendar will be used. |
Returns
DateTime
| null
The current date and time. The month and day are index's and as such start at 0 instead of 1. If the passed in calendar can't be found null will be returned.
currentDateTimeDisplay
▸ currentDateTimeDisplay(calendarId?
): DateDisplayData
| null
Gets the formatted display data for the current date and time of the active calendar, or the calendar with the passed in ID.
Example
// Assuming a Gregorian calendar
SimpleCalendar.api.currentDateTimeDisplay();
//Returns a DateTime object like this
// {
// date: "June 01, 2021",
// day: "1",
// daySuffix: "st",
// month: "6",
// monthName: "June",
// time: "00:00:00",
// weekday: "Tuesday",
// year: "2021",
// yearName: "",
// yearPostfix: "",
// yearPrefix: ""
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current day from. If not provided the current active calendar will be used. |
Returns
DateDisplayData
| null
All the formatted display strings for the current date and time. Or if the passed in calendar can't be found, null.
dateToTimestamp
▸ dateToTimestamp(date
, calendarId?
): number
Converts the passed in date to a timestamp.
Example
SimpleCalendar.api.dateToTimestamp({}); //Returns the timestamp for the current date
SimpleCalendar.api.dateToTimestamp({year: 2021, month: 0, day: 0, hour: 1, minute: 1, seconds: 0}); //Returns 1609462860
Parameters
Name | Type | Default value | Description |
---|---|---|---|
date | DateTimeParts | undefined | A date object (eg {year:2021, month: 4, day: 12, hour: 0, minute: 0, seconds: 0} ) with the parameters set to the date that should be converted to a timestamp. Any missing parameters will default to the current date value for that parameter.Important: The month and day are index based so January would be 0 and the first day of the month will also be 0. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to use when converting a date to a timestamp. If not provided the current active calendar will be used. |
Returns
number
The timestamp for that date.
formatDateTime
▸ formatDateTime(date
, format?
, calendarId?
): string
| { date
: string
; time
: string
}
Converts the passed in date/time into formatted date and time strings that match the configured date and time formats or the passed in format string.
- Any missing date/time parameters will default to a value of 0.
- If the date/time parameters are negative, their value will be set to 0. The exception to this is the year parameter, it can be negative.
- If the date/time parameters are set to a value greater than possible (eg. the 20th month in a calendar that only has 12 months, or the 34th hour when a day can only have 24 hours) the max value will be used.
Example
// Assuming that the default date and time formats are in place
// Date: Full Month Name Day, Year
// Time: 24Hour:Minute:Second
SimpleCalendar.api.formatDateTime({year: 2021, month: 11, day: 24, hour: 12, minute: 13, seconds: 14});
// Returns {date: 'December 25, 2021', time: '12:13:14'}
SimpleCalendar.api.formatDateTime({year: -2021, month: -11, day: 24, hour: 12, minute: 13, seconds: 14})
// Returns {date: 'January 25, -2021', time: '12:13:14'}
SimpleCalendar.api.formatDateTime({year: 2021, month: 111, day: 224, hour: 44, minute: 313, seconds: 314})
// Returns {date: 'December 31, 2021', time: '23:59:59'}
SimpleCalendar.api.formatDateTime({year: 2021, month: 111, day: 224, hour: 44, minute: 313, seconds: 314},"DD/MM/YYYY HH:mm:ss A")
// Returns "31/12/2021 23:59:00 PM"
Parameters
Name | Type | Default value | Description |
---|---|---|---|
date | DateTimeParts | undefined | A date object (eg {year:2021, month: 4, day: 12, hour: 0, minute: 0, seconds: 0} ) with the parameters set to the date and time that should be formatted.Important: The month and day are index based so January would be 0 and the first day of the month will also be 0. |
format | string | "" | Optional format string to return custom formats for the passed in date and time. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to use when converting a date to a formatted string. If not provided the current active calendar will be used. |
Returns
string
| { date
: string
; time
: string
}
If no format string is provided an object with the date and time formatted strings, as set in the configuration, will be returned. If a format is provided then a formatted string will be returned.
formatTimestamp
▸ formatTimestamp(timestamp
, format?
, calendarId?
): string
| { date
: string
; time
: string
}
Converts the passed in timestamp into formatted date and time strings that match the configured date and time formats or the passed in format string.
Example
// Assuming that the default date and time formats are in place
// Date: Full Month Name Day, Year
// Time: 24Hour:Minute:Second
SimpleCalendar.api.formatTimestamp(1640434394);
// Returns {date: 'December 25, 2021', time: '12:13:14'}
SimpleCalendar.api.formatTimestamp(1640434394,"DD/MM/YYYY HH:mm:ss A");
// Returns '25/12/2021 12:13:14 PM'
Parameters
Name | Type | Default value | Description |
---|---|---|---|
timestamp | number | undefined | The timestamp (in seconds) of the date to format. |
format | string | "" | Optional format string to return custom formats for the passed in date and time. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to use when converting a date to a formatted string. If not provided the current active calendar will be used. |
Returns
string
| { date
: string
; time
: string
}
If no format string is provided an object with the date and time formatted strings, as set in the configuration, will be returned. If a format is provided then a formatted string will be returned.
getAllCalendars
▸ getAllCalendars(): CalendarData
[]
Gets the details of all calendars that have been configured in Simple Calendar
Example
const c = SimpleCalendar.api.getAllCalendars();
console.log(c); // Will contain a list of all calendars and their data
Returns
Array of all calendars and their data.
getAllMonths
▸ getAllMonths(calendarId?
): MonthData
[]
Gets the details for all the months of the specified calendar.
Example
SimpleCalendar.api.getAllMonths();
// Returns an array like this, assuming the Gregorian Calendar
// [
// {
// "id": "13390ed",
// "name": "January",
// "description" : "",
// "abbreviation": "Jan",
// "numericRepresentation": 1,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "effafeee",
// "name": "February",
// "description" : "",
// "abbreviation": "Feb",
// "numericRepresentation": 2,
// "numericRepresentationOffset": 0,
// "numberOfDays": 28,
// "numberOfLeapYearDays": 29,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "25b48251",
// "name": "March",
// "description" : "",
// "abbreviation": "Mar",
// "numericRepresentation": 3,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "e5e9782f",
// "name": "April",
// "description" : "",
// "abbreviation": "Apr",
// "numericRepresentation": 4,
// "numericRepresentationOffset": 0,
// "numberOfDays": 30,
// "numberOfLeapYearDays": 30,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "93f626f6",
// "name": "May",
// "description" : "",
// "abbreviation": "May",
// "numericRepresentation": 5,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "22b4b204",
// "name": "June",
// "description" : "",
// "abbreviation": "Jun",
// "numericRepresentation": 6,
// "numericRepresentationOffset": 0,
// "numberOfDays": 30,
// "numberOfLeapYearDays": 30,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "adc0a7ca",
// "name": "July",
// "description" : "",
// "abbreviation": "Jul",
// "numericRepresentation": 7,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "58197d71",
// "name": "August",
// "description" : "",
// "abbreviation": "Aug",
// "numericRepresentation": 8,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "eca76bbd",
// "name": "September",
// "description" : "",
// "abbreviation": "Sep",
// "numericRepresentation": 9,
// "numericRepresentationOffset": 0,
// "numberOfDays": 30,
// "numberOfLeapYearDays": 30,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "6b0da33e",
// "name": "October",
// "description" : "",
// "abbreviation": "Oct",
// "numericRepresentation": 10,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "150f5519",
// "name": "November",
// "description" : "",
// "abbreviation": "Nov",
// "numericRepresentation": 11,
// "numericRepresentationOffset": 0,
// "numberOfDays": 30,
// "numberOfLeapYearDays": 30,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// },
// {
// "id": "b67bc3ee",
// "name": "December",
// "description" : "",
// "abbreviation": "Dec",
// "numericRepresentation": 12,
// "numericRepresentationOffset": 0,
// "numberOfDays": 31,
// "numberOfLeapYearDays": 31,
// "intercalary": false,
// "intercalaryInclude": false,
// "startingWeekday": null
// }
// ]
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the list of months from. If not provided the current active calendar will be used. |
Returns
Array of all months in the calendar.
getAllMoons
▸ getAllMoons(calendarId?
): MoonData
[]
Gets the details for all the moons of the specified calendar.
Example
SimpleCalendar.api.getAllMoons();
// Returns an array like this, assuming the Gregorian Calendar
// [
// {
// "id": "2c26abfa",
// "name": "Moon",
// "color": "#ffffff",
// "cycleLength": 29.53059,
// "cycleDayAdjust": 0.5,
// "firstNewMoon": {
// "year": 2000,
// "month": 1,
// "day": 6,
// "yearX": 0,
// "yearReset": "none"
// },
// "phases": [
// {
// "name": "New Moon",
// "length": 1,
// "icon": "new",
// "singleDay": true
// },
// {
// "name": "Waxing Crescent",
// "length": 6.3826,
// "icon": "waxing-crescent",
// "singleDay": false
// },
// {
// "name": "First Quarter",
// "length": 1,
// "icon": "first-quarter",
// "singleDay": true
// },
// {
// "name": "Waxing Gibbous",
// "length": 6.3826,
// "icon": "waxing-gibbous",
// "singleDay": false
// },
// {
// "name": "Full Moon",
// "length": 1,
// "icon": "full",
// "singleDay": true
// },
// {
// "name": "Waning Gibbous",
// "length": 6.3826,
// "icon": "waning-gibbous",
// "singleDay": false
// },
// {
// "name": "Last Quarter",
// "length": 1,
// "icon": "last-quarter",
// "singleDay": true
// },
// {
// "name": "Waning Crescent",
// "length": 6.3826,
// "icon": "waning-crescent",
// "singleDay": false
// }
// ],
// "currentPhase": {
// "name": "Waning Crescent",
// "length": 6.3826,
// "icon": "waning-crescent",
// "singleDay": false
// }
// }
// ]
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the list of moons from. If not provided the current active calendar will be used. |
Returns
MoonData
[]
Array of all moons in the calendar.
getAllSeasons
▸ getAllSeasons(calendarId?
): SeasonData
[]
Gets the details for all the seasons for the specified calendar.
Example
SimpleCalendar.api.getAllSeasons();
// Returns an array like this, assuming the Gregorian Calendar
// [
// {
// color: "#fffce8",
// description : "",
// icon: "spring,
// id: "4916a231",
// name: "Spring",
// startingDay: 20,
// startingMonth: 3,
// sunriseTime: 21600,
// sunsetTime: 64800
// },
// {
// color: "#f3fff3",
// description : "",
// icon: "summer,
// id: "e596489",
// name: "Summer",
// startingDay: 20,
// startingMonth: 6,
// sunriseTime: 21600,
// sunsetTime: 64800
// },
// {
// color: "#fff7f2",
// description : "",
// icon: "fall,
// id: "3f137ee5",
// name: "Fall",
// startingDay: 22,
// startingMonth: 9,
// sunriseTime: 21600,
// sunsetTime: 64800
// },
// {
// color: "#f2f8ff",
// description : "",
// icon: "winter,
// id: "92f919a2",
// name: "Winter",
// startingDay: 21,
// startingMonth: 12,
// sunriseTime: 21600,
// sunsetTime: 64800
// }
// ]
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the list of seasons from. If not provided the current active calendar will be used. |
Returns
Array of all seasons in the calendar.
getAllThemes
▸ getAllThemes(): Object
Gets a list of all available themes a user can choose from. System specific themes that do not match the current system will be excluded. Module specific themes whos modules are not installed and enabled will be excluded.
Example
SimpleCalendar.api.getAllThemes();
// {
// "dark": "Dark",
// "light": "Light",
// "classic": "Classic"
// }
Returns
Object
A object where the properties represent theme IDs and the values are the localized strings of the theme name.
getAllWeekdays
▸ getAllWeekdays(calendarId?
): WeekdayData
[]
Gets the details about all the weekdays for the specified calendar.
Example
SimpleCalendar.api.getAllWeekdays();
// Returns an array like this, assuming the Gregorian Calendar
// [
// {
// id: "dafbfd4",
// name: "Sunday",
// description : "",
// numericRepresentation: 1,
// restday : false,
// },
// {
// id: "8648c7e9",
// name: "Monday",
// description : "",
// numericRepresentation: 2,
// restday : false,
// }
// {
// id: "b40f3a20",
// name: "Tuesday",
// description : "",
// numericRepresentation: 3,
// restday : false,
// },
// {
// id: "6c20a99e",
// name: "Wednesday",
// description : "",
// numericRepresentation: 4,
// restday : false,
// },
// {
// id: "56c14ec7",
// name: "Thursday",
// description : "",
// numericRepresentation: 5,
// restday : false,
// },
// {
// id: "2c732d04",
// name: "Friday",
// description : "",
// numericRepresentation: 6,
// restday : false,
// },
// {
// id: "c8f72e3d",
// name: "Saturday",
// description : "",
// numericRepresentation: 7,
// restday : false,
// }
// ]
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the list of weekdays from. If not provided the current active calendar will be used. |
Returns
Array of all weekdays in the calendar.
getCurrentCalendar
▸ getCurrentCalendar(): CalendarData
Gets the details about the current active calendar.
Example
cosnt c = SimpleCalendar.api.getCurrentCalendar();
console.log(c); // Will contain all the configuration data for the current calendar.
Returns
The current active calendars configuration.
getCurrentDay
▸ getCurrentDay(calendarId?
): DayData
| null
Gets the details about the current day for the specified calendar.
Example
SimpleCalendar.api.getCurrentDay();
// Returns an object like this:
// {
// id: "cbdb31cb",
// name: "8",
// numericRepresentation: 8
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current day from. If not provided the current active calendar will be used. |
Returns
DayData
| null
The current day data or null if no current day can be found.
getCurrentMonth
▸ getCurrentMonth(calendarId?
): MonthData
| null
Gets the details about the current month for the specified calendar.
Example
SimpleCalendar.api.getCurrentMonth();
// Returns an object like this:
// {
// abbreviation: "Jun",
// id: "22b4b204",
// intercalary: false,
// intercalaryInclude: false,
// name: "June",
// description: "",
// numberOfDays: 30,
// numberOfLeapYearDays: 30,
// numericRepresentation: 6,
// numericRepresentationOffset: 0,
// startingWeekday: null
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current month from. If not provided the current active calendar will be used. |
Returns
MonthData
| null
The current month data or null if no current month can be found.
getCurrentSeason
▸ getCurrentSeason(calendarId?
): SeasonData
Gets the details about the season for the current date of the specified calendar.
Example
SimpleCalendar.api.getCurrentSeason();
// Returns an object like this
// {
// color: "#fffce8",
// id: "4916a231",
// name: "Spring",
// description: "",
// icon: "spring",
// startingDay: 19,
// startingMonth: 2,
// sunriseTime: 21600,
// sunsetTime: 64800
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current season from. If not provided the current active calendar will be used. |
Returns
The current seasons data or an empty season data object if no current season can be found.
getCurrentTheme
▸ getCurrentTheme(): string
Gets the ID of the theme being used by the player.
Example
SimpleCalendar.api.getCurrentTheme();
// Returns "dark"
Returns
string
A string ID of the theme being used.
getCurrentWeekday
▸ getCurrentWeekday(calendarId?
): WeekdayData
| null
Gets the details about the current weekday.
Example
SimpleCalendar.api.getCurrentWeekday();
// Returns an object like this
// {
// id: "b40f3a20",
// name: "Tuesday",
// abbreviation: "Tu",
// description: "",
// numericRepresentation: 3,
// restday: false
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current weekday from. If not provided the current active calendar will be used. |
Returns
WeekdayData
| null
The current weekday data or null if no current weekday can be found.
getCurrentYear
▸ getCurrentYear(calendarId?
): YearData
| null
Gets the details about the current year for the specified calendar.
Example
SimpleCalendar.api.getCurrentYear();
// Returns an object like this
// {
// firstWeekday: 4,
// id: "bbe5385c",
// numericRepresentation: 2021,
// postfix: "",
// prefix: "",
// showWeekdayHeadings: true,
// yearNames: [],
// yearNamesStart: 0,
// yearNamingRule: "default",
// yearZero: 1970
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the current year from. If not provided the current active calendar will be used. |
Returns
YearData
| null
The current year data or null if no current year can be found.
getLeapYearConfiguration
▸ getLeapYearConfiguration(calendarId?
): LeapYearData
| null
Gets the details about how leap years are configured for the specified calendar.
Example
SimpleCalendar.api.getLeapYearConfiguration();
// Returns an object like this
// {
// customMod: 0,
// id: "1468d034",
// rule: "gregorian"
}
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the leap year configuration from. If not provided the current active calendar will be used. |
Returns
LeapYearData
| null
The leap year configuration.
getNotes
▸ getNotes(calendarId?
): (StoredDocument
<JournalEntry
> | undefined
)[]
Gets all notes that the current user is able to see for the specified calendar.
Example
// Returns an array of JournalEntry objects
SimpleCalendar.api.getNotes();
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the notes from. If not provided the current active calendar will be used. |
Returns
(StoredDocument
<JournalEntry
> | undefined
)[]
A list of JournalEntries that contain the note data.
getNotesForDay
▸ getNotesForDay(year
, month
, day
, calendarId?
): (StoredDocument
<JournalEntry
> | undefined
)[]
Gets all notes that the current user is able to see for the specified date from the specified calendar.
Example
// Returns an array of JournalEntry objects
SimpleCalendar.api.getNotesForDay(2022, 11, 24);
Parameters
Name | Type | Default value | Description |
---|---|---|---|
year | number | undefined | The year of the date to get the notes for. |
month | number | undefined | The index of the month to get the notes for. |
day | number | undefined | The index of the day to get the notes for. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the notes from. If not provided the current active calendar will be used. |
Returns
(StoredDocument
<JournalEntry
> | undefined
)[]
A list of JournalEntries that contain the note data.
getTimeConfiguration
▸ getTimeConfiguration(calendarId?
): TimeData
| null
Get the details about how time is configured for the specified calendar.
Example
SimpleCalendar.api.getTimeConfiguration();
// Returns an object like this
// {
// gameTimeRatio: 1,
// hoursInDay: 24,
// id: "d4791796",
// minutesInHour: 60,
// secondsInCombatRound: 6,
// secondsInMinute: 60,
// unifyGameAndClockPause: true,
// updateFrequency: 1
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the time configuration from. If not provided the current active calendar will be used. |
Returns
TimeData
| null
The time configuration.
isOpen
▸ isOpen(): boolean
If the calendar is open or not.
Example
SimpleCalendar.api.isOpen(); // True or false depending on if the calendar is open or closed.
Returns
boolean
boolean True if the calendar is open, false if it is closed.
isPrimaryGM
▸ isPrimaryGM(): boolean
Get if the current user is considered the primary GM or not.
Example
SimpleCalendar.api.isPrimaryGM(); //True or Flase depending on if the current user is primary gm
Returns
boolean
If the current user is the primary GM.
pauseClock
▸ pauseClock(calendarId?
): boolean
Pauses the real time clock for the specified calendar. Only the primary GM can pause a clock.
Example
SimpleCalendar.api.pauseClock();
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to pause the real time clock for. If not provided the current active calendar will be used. |
Returns
boolean
True if the clock was paused, false otherwise
removeNote
▸ removeNote(journalEntryId
): Promise
<boolean
>
This function removes the specified note from Simple Calendar.
Example
SimpleCalendar.api.removeNote("asd123").then(...).catch(console.error);
Parameters
Name | Type | Description |
---|---|---|
journalEntryId | string | The ID of the journal entry associated with the note that is to be removed. |
Returns
Promise
<boolean
>
True if the note was removed or false if it was not.
runMigration
▸ runMigration(): void
Run the migration from Simple Calendar version 1 to version 2. This will only work if the current player is the primary GM.
A dialog will be shown to confirm if the GM wants to run the migration. This will prevent accidental running of the migration.
Example
SimpleCalendar.api.runMigration();
Returns
void
searchNotes
▸ searchNotes(term
, options?
, calendarId?
): (StoredDocument
<JournalEntry
> | undefined
)[]
Search the notes in Simple Calendar for a specific term. Only notes that the user can see are returned.
Example
SimpleCalendar.api.searchNotes("Note"); //Will return a list of notes that contained the word note somewhere in its content.
SimpleCalendar.api.searchNotes("Note", {title: true}); // Will return a list of notes that contain the world note in the title.
SimpleCalendar.api.searchNotes("Gamemaster", {author: true}); // Will return a list of notes that were written by the gamemaster.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
term | string | undefined | The text that is being searched for |
options | Object | undefined | Options parameter to specify which fields of the note to use when searching, If not provided all fields are searched against. |
options.author | boolean | true | - |
options.categories | boolean | true | - |
options.date | boolean | true | - |
options.details | boolean | true | - |
options.title | boolean | true | - |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar whose notes to search against. If not provided the current active calendar will be used. |
Returns
(StoredDocument
<JournalEntry
> | undefined
)[]
A list of JournalEntry that matched the term being searched.
secondsToInterval
▸ secondsToInterval(seconds
, calendarId?
): DateTimeParts
Will attempt to parse the passed in seconds into larger time intervals.
Example
//Assuming a Gregorian Calendar
SimpleCalendar.api.secondsToInterval(3600); //Returns {year: 0, month: 0, day: 0, hour: 1, minute: 0, seconds: 0}
SimpleCalendar.api.secondsToInterval(3660); //Returns {year: 0, month: 0, day: 0, hour: 1, minute: 1, seconds: 0}
SimpleCalendar.api.secondsToInterval(86400); //Returns {year: 0, month: 0, day: 1, hour: 0, minute: 0, seconds: 0}
SimpleCalendar.api.secondsToInterval(604800); //Returns {year: 0, month: 0, day: 7, hour: 0, minute: 0, seconds: 0}
SimpleCalendar.api.secondsToInterval(2629743); //Returns {year: 0, month: 1, day: 0, hour: 10, minute: 29, seconds: 3}
SimpleCalendar.api.secondsToInterval(31556926); //Returns {year: 1, month: 0, day: 0, hour: 5, minute: 48, seconds: 46}
Parameters
Name | Type | Default value | Description |
---|---|---|---|
seconds | number | undefined | The number of seconds to convert to different intervals. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to use when calculating the intervals. If not provided the current active calendar will be used. |
Returns
An object containing the larger time intervals that make up the number of seconds passed in.
setDate
▸ setDate(date
, calendarId?
): boolean
Will set the current date of the specified calendar to match the passed in date. Important: This function can only be run by users who have permission to change the date in Simple Calendar.
Example
//To set the date to December 25th 1999 with the time 00:00:00
SimpleCalendar.api.setDate({year: 1999, month: 11, day: 24, hour: 0, minute: 0, seconds: 0});
//To set the date to December 31st 1999 and the time to 11:59:59pm
SimpleCalendar.api.setDate({year: 1999, month: 11, day: 30, hour: 23, minute: 59, seconds: 59});
Parameters
Name | Type | Default value | Description |
---|---|---|---|
date | DateTimeParts | undefined | A date object (eg {year:2021, month: 4, day: 12, hour: 0, minute: 0, seconds: 0} ) with the parameters set to the date that the calendar should be set to. Any missing parameters will default to the current date value for that parameter.Important: The month and day are index based so January would be 0 and the first day of the month will also be 0. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to set the date of. If not provided the current active calendar will be used. |
Returns
boolean
True if the date was set successfully, false otherwise.
setTheme
▸ setTheme(themeId
): Promise
<boolean
>
Will set the players Simple Calendar theme that matches the passed in theme ID.
An information notification will be shown to the player if the theme was changed to let them know it has been changed programmatically.
Example
await SimpleCalendar.api.setTheme('light');
//Will return true and change Simple Calendar's theme to the light theme.
await SimpleCalendar.api.setTheme('light');
//Will return true and will not change the theme as it was already set to light.
await SimpleCalendar.api.setTheme('themeDoesNotExist');
//Will return false and log an error to the console.
Parameters
Name | Type | Description |
---|---|---|
themeId | string | The ID of the theme to set. The ID's of all available themes can be found using getAllThemes. |
Returns
Promise
<boolean
>
A promise that resolves to True if the theme is valid and was applied successfully, or it was the theme already being used. The promise will resolve to False if a theme with that ID could not be found.
showCalendar
▸ showCalendar(date?
, compact?
, calendarId?
): void
Will open up Simple Calendar to the current date, or the passed in date.
Example
//Assuming a Gregorian Calendar
SimpleCalendar.api.showCalendar(); // Will open the calendar to the current date.
SimpleCalendar.api.showCalendar({year: 1999, month: 11, day: 25}); // Will open the calendar to the date December 25th, 1999
SimpleCalendar.api.showCalendar(null, true); // Will open the calendar to the current date in compact mode.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
date | null | DateTimeParts | null | A date object (eg {year:2021, month: 4, day: 12} ) with the year, month and day set to the date to be visible when the calendar is opened.Important: The month is index based so January would be 0. |
compact | boolean | false | If to open the calendar in compact mode or not. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to focus when the calendar view is opened. If not provided the current active calendar will be used. |
Returns
void
startClock
▸ startClock(calendarId?
): boolean
Starts the real time clock for the specified calendar. Only the primary GM can start a clock.
Example
SimpleCalendar.api.startClock();
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to start the real time clock for. If not provided the current active calendar will be used. |
Returns
boolean
True if the clock was started, false otherwise
stopClock
▸ stopClock(calendarId?
): boolean
Stops the real time clock for the specified calendar. Only the primary GM can stop a clock.
Example
SimpleCalendar.api.stopClock();
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to stop the real time clock for. If not provided the current active calendar will be used. |
Returns
boolean
True if the clock was stopped, false otherwise
timestamp
▸ timestamp(calendarId?
): number
Get the timestamp (in seconds) of the specified calendars currently set date.
Example
const timestamp = SimpleCalendar.api.timestamp();
console.log(timestamp); // This will be a number representing the current number of seconds passed in the calendar.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to get the timestamp for. If not provided the current active calendar will be used. |
Returns
number
The time stamp of the calendar in seconds
timestampPlusInterval
▸ timestampPlusInterval(currentSeconds
, interval
, calendarId?
): number
Calculates a new timestamp from the passed in timestamp plus the passed in interval amount.
Example
let newTime = SimpleCalendar.api.timestampPlusInterval(0, {day: 1});
console.log(newTime); // this will be 0 + the number of seconds in 1 day. For most calendars this will be 86400
// Assuming Gregorian Calendar with the current date of June 1, 2021
newTime = SimpleCalendar.api.timestampPlusInterval(1622505600, {month: 1, day: 1});
console.log(newTime); // This will be the number of seconds that equal July 2nd 2021
Parameters
Name | Type | Default value | Description |
---|---|---|---|
currentSeconds | number | undefined | The timestamp (in seconds) to have the interval added too. |
interval | DateTimeParts | undefined | The interval objects properties are all optional so only those needed have to be set. Where each property is how many of that interval to increase the passed in timestamp by. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to use to calculate the new timestamp. If not provided the current active calendar will be used. |
Returns
number
The timestamp plus the passed in interval amount
timestampToDate
▸ timestampToDate(seconds
, calendarId?
): DateData
| null
Converts a timestamp (in seconds) into a DateData objet from the specified calendar
Example
// Assuming Gregorian Calendar with the current date of June 1, 2021
let scDate = SimpleCalendar.api.timestampToDate(1622505600);
console.log(scDate);
// This is what the returned object will look like
// {
// "currentSeason": { "showAdvanced": false, "id": "75a4ba97", "name": "Spring", "numericRepresentation": null, "description": "", "abbreviation": "", "color": "#46b946", "startingMonth": 2, "startingDay": 19, "sunriseTime": 21600, "sunsetTime": 64800, "icon": "spring"},
// day: 0,
// dayOfTheWeek: 2,
// dayOffset: 0,
// display: {
// date: "June 01, 2021",
// day: "1",
// daySuffix: "st",
// month: "6",
// monthName: "June",
// time: "00:00:00",
// weekday: "Tuesday",
// year: "2021",
// yearName: "",
// yearPostfix: "",
// yearPrefix: "",
// },
// hour: 0,
// isLeapYear: false,
// midday: 1622548800,
// minute: 0,
// month: 5,
// second: 0,
// showWeekdayHeadings: true,
// sunrise: 1622527200,
// sunset: 1622570400,
// weekdays: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
// year: 2021,
// yearZero: 1970
// }
Parameters
Name | Type | Default value | Description |
---|---|---|---|
seconds | number | undefined | The timestamp (in seconds) to convert into a date object. |
calendarId | string | "active" | Optional parameter to specify the ID of the calendar to use to calculate the DateData objet. If not provided the current active calendar will be used. |
Returns
DateData
| null
A date object with information about the date the timestamp represents or null if the specified calendar can not be found