Package BBjCalendarWidget

The BBjJavaScriptExecutor is a BBj Custom Class that manages JavaScript code execution in a BBjHtmlView control, providing the ability to queue and debounce JavaScript execution.

Definition of terms:

- Debouncing: instead of immediately firing off several events in quick succession, if you choose to debounce the scripts then they will be batched together to improve performance. The batch size depends on how many scripts are enqueued, the amount of time that passes between their enqueing, and the defined Rate. Do NOT debounce scripts from which you are expecting a return value, as the return value will be associated with the entire batch, not an individual line of JavaScript. If you do need a valid return value, use the executeImmediately() methods.

- Rate: the number of milliseconds that must expire without enqueing any more scripts before the executor flushes the enqueued scripts on the client. The default Rate is 200ms, although you can override this by using the constructor that specifies a Rate time.

- Execute Key: The script's unique id. If you attempt to queue two scripts with the same key then the second script will overwrite the first and the first script will not be executed. You do not have to specify a key value with several of the execute() methods. The main point of the key is that if you think that you may be executing the exact same script several times, then reusing the same key is a way to have only the last instance of the script be executed. For example, if you execute a redraw() JavaScript function whenever the user resizes a window, then using the script as the key ensures that it won't get called dozens of times sequentially as the user is resizing the window.

- Execute Priority: The script's priority in the queue, starting from 0 and incrementing by ones. If you specify a priority, it will be used as the script's index in the queue (a ListOrderedMap). This MUST start at 0 and increment, or you will get an indexing error on the queue. If you use an execute() method that does not specify a priority, then the scripts will be added sequentually to the queue and executed in the order in which they were added.

Although this class offers several execute() methods for the most flexibility, the most common usage will be the execute(BBjString script!, BBjNumber debounced!) signature, as it reuses the provided script for the key, you can control debouncing, and sequential execution is desired (without having to keep track of priority levels).

If scripts are queued for execution, they will eventually be executed in the BBjHtmlView control either when the widget code explicitly calls the executor's flush() method, or after the Rate timer has expired, which is 200 milliseconds by default. The executor will continue to flush the queue whenever it is needed.

Note that every time you queue a new script it will reset the Rate timer. That means that if you are queueing up scripts for execution in quick succession, then they will all be executed in a batch after the last script is queued. If you are queueing up scripts occasionally, meaning longer than the Rate timer, then each script will end up being executed before the next one has been queued.

Note: The executor handles JSNI automatically so you don't have to check for BUI and adjust the window and document JavaScript objects.

Example use cases:

rem Create a new executor object specifying the rate time of 200ms where #this! is an
rem instance of the custom class (assuming the application is object-oriented)
executor! = new BBjJavaScriptExecutor(#this!, 200)

rem Have the executor enqueue then execute the JavaScript stored in the script! variable.
rem The "1" indicates that it should be debounced, or batched.
executor!.execute(script!, 1)

rem Have the executor immediately execute the provided JavaScript and return the result
rem in a BBjString or Object
viewType! = executor!.executeImmediately("window.calendar.view.type;")
 

Since this class is meant to be used with a BBjWidget, then it will automatically queue up scripts if the BBjWidget's getIsReady() returns false.

CalendarDateClickEvent is a BBj Interface that contains event information after the user clicks on a date or time. This data class will be made available to your custom callback routine after the user clicks on a date or time and you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_DATE_CLICK event.

CalendarEntriesSetEvent is a BBj Interface that contains event information after the calendar's entry data has been initially set or changed in some way. This data class will be made available to your custom callback routine after the user clicks the prev/next buttons, changes the view, adds events, clicks a navlink, etc. you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_ENTRIES_SET event.

CalendarEntryAddEvent is a BBj Interface that contains event information for when a single entry (not an event source) has been added to the calendar via the BBjCalendarWidget::addEntry() method. This data class will be made available to your custom callback routine after mouses over a calendar entry if you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_ENTRY_ADD event.

CalendarEntryClickEvent is a BBj Interface that contains event information for a calendar's entry click. This data class will be made available to your custom callback routine after the user executes a click on a calendar entry if you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_ENTRY_CLICK event.

CalendarEntryEvent is a BBj Interface that contains event information for a calendar's entry (appointment, event, etc.) object. It's the base class for several calendar events that deal with the calendar's entries (appointments, events, etc.) including the CalendarEntryClickEvent, CalendarEntryMouseEnterEvent, and CalendarEntryMouseLeaveEvent.

CalendarEntryMouseEnterEvent is a BBj Interface that contains event information for a calendar's entry mouse enter event. This data class will be made available to your custom callback routine after mouses over a calendar entry if you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_ENTRY_MOUSE_ENTER event.

CalendarEntryRemoveEvent is a BBj Interface that contains event information when an entry has been removed from the calendar. This data class will be made available to your custom callback routine after mouses over a calendar entry if you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_ENTRY_REMOVE event.

CalendarEntrySource is a BBj Custom Class that defines entry feeds for the BBjCalendarWidget and serves as a base class for more specific entry sources such as the CalendarEntrySourceGoogle and CalendarEntrySourceiCalendar classes.

Entry source feeds are a way to add multiple calendar entries to the calendar at once from a source like a public Google calendar, a web service that provides entries in JSON format, an iCalendar (ICS) file or document, etc.

CalendarEntrySource is a BBj Interface that defines entry feeds for the BBjCalendarWidget in the Google Calendar format.

Entry source feeds are a way to add multiple calendar entries to the calendar at once from a source like a public Google calendar, a web service that provides entries in JSON format, an iCalendar (ICS) file or document, etc.

CalendarEntrySourceiCalendar is a BBj Interface that defines entry feeds for the BBjCalendarWidget in the iCalendar format.

Entry source feeds are a way to add multiple calendar entries to the calendar at once from a source like a public Google calendar, a web service that provides entries in JSON format, an iCalendar (ICS) file or document, etc.

Note that iCalendar feeds will be queried upon calendar load and will not be queried after. Unlike a JSON or Google feed, the URL will not be queried when the user navigates forward or backward in time. However, calling the calendar's refetchEntrySource() or refetchAllEntrySources() or methods will cause the source feed to be requeried.

CalendarEventWithJavaScriptEvent is a BBj Interface that contains event information for a BBjCalendarWidget. This is the base class for all BBjCalendarWidget events that also contain the underlying native JavaScript event object.

This interface that provides methods that simplify retreiving useful information from the underly native JavaScript event object. For example, it gives developers easy access to mouse coordinates for events that have a native JavaScript event (see the hyperlinked list of qualifying events below). The data in this class is technically available in the JavaScript JSON event object if you call the getJsEvent() method and parse the resultant JSON for the desired coordinates. The purpose of this class is to simplify getting the mouse coordinates from the CalendarEvent instead of having to parse them out of the native JavaScript event. This makes it much easier to display a popup menu as a result of a user clicking on the calendar or a calendar entry, as you would usually call the BBjPopupMenu::show() method which takes a control (the calendar's control) and X and Y coordinates that are relative to the control. For example:

rem Display the popup menu based on the calendar control and the mouse's X and Y positions
myPopupMenu!.show(myCal!.getHtmlView(), myEvent!.getCalendarX(), myEvent!.getCalendarY())
 

This class provides the X/Y coordinates of the user's mouse for calendar events that contain such information, namely:

• CalendarSelectEvent
• CalendarUnselectEvent
• CalendarDateClickEvent
• CalendarEntryEvent and the classes that extend it:
• CalendarEntryResizeEvent
• CalendarEntryResizeStartEvent
• CalendarEntryResizeStopEvent
• CalendarEntryDropEvent
• CalendarEntryClickEvent
• CalendarEntryMouseEnterEvent
• CalendarEntryMouseLeaveEvent

The class parses out X/Y coordinates from the native JavaScript event for the screenX, screenY, clientX, and clientY values. It also provides computed coordinates called calendarX and calendarY. This values are relative to the calendar control, and they are determined by taking the mouse's clientX value and subtracting the calendar's X coordinate. This makes the X/Y values relative to the calendar control instead of the screen or client area of the browser.

CalendarReadyEvent is a BBj Interface that contains event information when the calendar has been initialized and may be interacted with. This data class will be made available to your custom callback routine after the calendar has initialized and you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_READY event.

The CalendarToolbar is a BBj Custom Class that defines the toolbar for the calendar that can be positioned on the top or bottom and contains three sections: start, center, and end. Each section is defined by a CalendarToolbarSection object that by default displays:

Location	Constant	Displays	Example
start	CalendarAPI.CALENDAR_TOOLBAR_ALIGNMENT_START()	date navigation buttons	[today] [previous year][previous][next][next year]
center	CalendarAPI.CALENDAR_TOOLBAR_ALIGNMENT_CENTER()	title	"December 2020"
end	CalendarAPI.CALENDAR_TOOLBAR_ALIGNMENT_END()	view type buttons	[month][week][day][list]

Note that it's possible to add both a header and footer toolbar to the calendar.

CalendarUnselectEvent is a BBj Interface that contains event information after the user deselects a previously-selected date and/or time. This data class will be made available to your custom callback routine after the user clears their date/time selection if you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_UNSELECT event.

CalendarViewChangeEvent is a BBj Interface that contains event information for a calendar's view change event. This data class will be made available to your custom callback routine after the user changes the calendar's view type and you have previously executed the BBjCalendarWidget::setCallback() method to register for the CalendarAPI.ON_CALENDAR_VIEW_CHANGE event.