BBjCalendarWidget Overview

Overview

The BBjCalendarWidget is a BBj plug-in that facilitates using the JavaScript-based FullCalendar in a BBj application similar to a traditional built-in BBj control. Because the FullCalendar library is written in JavaScript, the BBjCalendarWidget plug-in manages the entire process of creating the calendar, adding and removing entries, sending the native JavaScript events from the calendar to the BBj code, and converting the processed events into custom event classes that are made available to the BBj application via callbacks. The plug-in is available in BBj 21.00 and higher and works in both GUI and BUI.

  For complete BBjCalendarWidget documentation, view the BBjCalendarWidget Javadocs.

Features

  • Leverages the popular FullCalendar JavaScript library used by industry-leading companies such as Amazon, Uber, Netflix, Samsung, PayPal, NASA, and more.
  • Offers plenty of configuration options to adapt to diverse use cases.
  • Offers a variety of view types including month view, week view, day view, an agenda or list-based view, and more.
  • Offers a configurable header and/or footer toolbar for navigating forwards and backwards by month, year, etc.
  • Supports adding calendar entries from a variety of sources including programmatically via BBj, JSON sources (local or remote), a public Google calendar, and ICS or iCalendar (local or remote).
  • Supports editing entries by dragging/dropping or resizing existing entries.
  • Supports extended entry attributes and custom tagging that may be used to dynamically hide or show tagged entries.
  • Supports theming via Bootstrap.
  • Offers numerous callbacks so your BBj program can respond to user events such as clicking on a date or entry, modifying an entry, etc.

Dependencies

Because the BBjCalendarWidget is a BBj plug-in, it relies on the BBjWidget.bbj base class that is pre-installed with BBj and may also be managed via the BBj Plugin Manager. The BBjCalendarWidget is installed with BBj 21.00 and higher into the <BBjHome>/plugins/BBjCalendarWidget directory.

Calendar Classes, Terms, and Definitions

Name Definition
CalendarAPI Provides methods to create most of the calendar objects and provides access to all the constants from the other classes.
BBjCalendarWidget

The main calendar control that you create from the CalendarAPI using one of the three creation methods. At a minimum, you will need to provide to the creation method a BBjTopLevelWindow or BBjChildWindow that will contain the calendar control. The other creation methods take more parameters to provide flexibility when creating the calendar control.
CalendarEntry A single calendar entry, or appointment, that can be created from the CalendarAPI and then added to an existing calendar.
CalendarEntrySource A source that provides multiple calendar entries. The entry source can be a web service that provides an array of calendar entries in JSON format, a public Google calendar, or a web service or ICS file that provides entries in the iCalendar format.
CalendarEvent

A calendar event, often triggered by the user interacting with the calendar, for which your application may set a callback. Because the BBjHtmlView control must initialize the calendar contained within, your application can set a callback to be notified when the calendar is ready for use. For example, executing the following line of code (as seen in the demo programs):

myCal!.setCallback(CalendarAPI.ON_CALENDAR_READY(), "OnCalendarReady")

results in the calendar executing the code in your OnCalendarReady subroutine as soon as the calendar has been initialized.
CalendarView

A particular view into the calendar, such as one that displays the entire month, a single week, a single day, or a list of entries similar to an agenda view. The calendar defaults to the CalendarAPI.CALENDAR_VIEW_DAY_GRID_MONTH() view, but the view may be changed via the API, via the user selecting a different view from the toolbar, or modifying the view in the calendar’s options.
CalendarOptions

A class that contains all the options for the calendar in one place. It’s possible to change the calendar’s options after creating the calendar (see demo #3), or you can create an instance of the options from the CalendarAPI and specify it when creating the calendar itself (see demo #4). When done this way, you can affect the calendar’s appearance, e.g. its theme, before the calendar is displayed to the user to avoid an abrupt change in appearance.
CalendarToolbar

A class that defines a header or footer configurable toolbar for the calendar. By default, the calendar is created with a default header toolbar that contains navigation buttons (today, yesterday, tomorrow, etc.), the current view’s title, and view option buttons (month, week, day, list). It’s possible to remove the toolbar completely, or even add both header and footer toolbars.
Programmatic Navigation By default, once you have added a calendar to your BBj program it defaults to the current date. But you can call methods like navigateNext(), navigateNextYear(), etc. to cause the calendar to display the desired date.

Class Overview

The BBjCalendarWidget plug-in includes several BBj custom classes that cover every aspect of the calendar including the calendar itself (BBjCalendarWidget.bbj), calendar configuration (CalendarOptions.bbj), calendar entries (CalendarEntry.bbj), calendar entry sources (CalendarEntrySource.bbj), calendar views (CalendarView.bbj), calendar toolbars (CalendarToolbar.bbj), and calendar events (CalendarEvents.bbj).

Demos

The BBjCalendarWidget is installed with a few different demos in the <BBjHome>/plugins/BBjCalendarWidget/demo directory. These demos may be run by traditional means, via the Eclipse IDE, or even from the BBjPluginManager. The demos are numbered, and range from a simple example that displays an empty calendar to more complex programs that demonstrate adding feeds from web services and Google public calendars.

Demo Description
calDemo1-BasicCalendar.bbj Creates an empty calendar object in a BBjWindow
calDemo2-AddingEntries.bbj Creates a calendar object in a BBjWindow, registers a callback, and adds multiple entries
calDemo3-AddGoogleCalendars.bbj Creates a calendar and adds multiple entry sources including public Google calendars and a web service
calDemo4-CustomOptions.bbj Creates a customized calendar object in a BBjWindow by providing a CalendarOptions object
calDemo5-EntryTags.bbj Creates a customized calendar object and reads in entries from a CSV file
calDemo6-Navigation.bbj Creates a calendar object and demonstrates programmatic navigation
calDemo7-EditingEntries.bbj Creates an editable calendar object that reads in entries from an MKEYED file

Example

rem ' BBjCalendarWidget Example

rem '/**
rem '* calDemo1-BasicCalendar.bbj
rem '* @author ndecker
rem '*
rem '* Overview: This demo creates an empty calendar object in a BBjWindow.
rem '*
rem '* This demo instantiates a BBjCalendarWidget in a BBjWindow.
rem '* After running the demo, you should see a calendar that displays the current month.
rem '* The demo doesn't do anything else with the calendar, as that's covered in other demos.
rem '* But it's possible to change the calendar's view types and scroll backward and forward
rem '* to other dates via the buttons in the calendar's toolbar.
rem '*/

rem 'Declares
declare auto BBjAPI                 myApi!
declare auto BBjSysGui              mySysGui!
declare auto BBjTopLevelWindow      myWindow!
declare auto BBjCalendarWidget      myCal!
declare auto BBjResizeEvent         myResizeEvent!

rem '===============================================================================================
rem 'Main program
rem '===============================================================================================
myApi! = BBjAPI()
sysgui=UNT
open (SYSGUI) "X0"
mySysGui!=myAPI!.getSysGui()
mySysGui!.setContext(0)

rem 'Create a window
myWindow! = mySysGui!.addWindow(25, 25, 800, 500, "BBjCalendarWidget - Demo 1 - Basic Calendar", $00080003$)

rem 'Add the calendar widget to our window
myCal! = CalendarAPI.createBBjCalendarWidget(myWindow!)

rem 'Register callback events
myWindow!.setCallback(mySysGui!.ON_CLOSE, "OnAppClose")
myWindow!.setCallback(mySysGui!.ON_RESIZE, "OnResize")

rem 'Process events
process_events

rem '===============================================================================================
rem 'Callbacks
rem '===============================================================================================
rem 'Handle the window's resize event by resizing the calendar widget
OnResize:
    myResizeEvent! = mySysGui!.getLastEvent()
    if !(myResizeEvent!.isAdjusting()) then myCal!.setSize(myResizeEvent!.getWidth(), myResizeEvent!.getHeight())
return

rem 'Handle the on close event by releasing the interpreter
OnAppClose:
release

rem 'BBjCalendarWidget USE Statements
use ::BBjCalendarWidget/CalendarAPI.bbj::CalendarAPI
use ::BBjCalendarWidget/BBjCalendarWidget.bbj::BBjCalendarWidget

See Also

Advantage Article: Introducing the BBjCalendarWidget Plug-In