Scheduler User Control

Official Content
This documentation is valid for:

Control Description

The GXScheduler user control allows managing a schedule of chronological events. The events can be viewed by day, week or month, as well as they can be added, updated and deleted directly on the control using the mouse. The edition of the events can be done using the default edit control of the control implementation or using a GeneXus web panel or transaction of your kb (see DetailsFormObject property)

Scheduler Control

Using the control

The Scheduler control is part of GeneXus X Evolution 1, it can be found at the toolbox – Extended Controls section:

 Scheduler Control 3

 To use it, just drag it on to your web panel form. At this moment the following dialog is shown:

GxSchedulerDownloadAndInstall

Some sample objects are automatically imported in your KB, under the folder Scheduler: 

SchedulerControl4

The Scheduler control works with an SDT to manage the different scheduled events of the Scheduler. The events loaded in this SDT are the ones showed at the control. The structure of this SDT is the following one:

 SchedulerControl5

How to load the events?

In order to load the events of the Scheduler in a web panel, a procedure or a dataProvider must be programmed. And then the name of this object must be specified in the LoadEventsObject property of the Scheduler control.

How does the dataprovider looks like?

This DataProvider is in charge of loading the events of a given period. It must have the following parameters:

parm(&dateFrom, &dateTo);
 // &dateFrom and &dateTo datatype is Date

The Output property of the DP must be set with the Scheduler SDT: SchedulerEvents

For example, this is the DataProvider used to show the previous screenshots:

SchedulerEvents
{
  Items
  {
     event
     {
         Id = "1"       
         Notes = "<img src='http://i.conmebol.com/banderas/VEN_flag_ssm.gif' /> <img src='http://i.conmebol.com/banderas/URU_flag_ssm.gif' />Venezuela vs Uruguay"
         StartTime = ctot("06/11/2009 01:00 AM")
         EndTime = ctot("06/11/2009 03:00 AM")                
     }
     event
        {
         Id = "2"       
         Notes = "<img src='http://i.conmebol.com/banderas/COL_flag_ssm.gif' /> <img src='http://i.conmebol.com/banderas/PER_flag_ssm.gif' />Colombia vs Peru"
         StartTime = ctot("06/10/2009 11:00 PM")
         EndTime = ctot("06/10/2009 11:45 PM")                     
        }
     event
        {
         Id = "3"       
         Notes = "<img src='http://i.conmebol.com/banderas/ECU_flag_ssm.gif' /> <img src='http://i.conmebol.com/banderas/ARG_flag_ssm.gif' />Ecuador vs Argentina"
         StartTime = ctot("06/10/2009 09:00 PM")
         EndTime = ctot("06/10/2009 11:00 PM")                     
        }
     event
        {
         Id = "4"       
         Notes = "<img src='http://i.conmebol.com/banderas/BRA_flag_ssm.gif' /> <img src='http://i.conmebol.com/banderas/PAR_flag_ssm.gif' />Brasil vs Paraguay"
         StartTime = ctot("06/11/2009 00:50 AM")
         EndTime = ctot("06/11/2009 01:50 AM")
        }
     event
        {
         Id = "5"       
         Notes = "<img src='http://i.conmebol.com/banderas/CHI_flag_ssm.gif' /> <img src='http://i.conmebol.com/banderas/BOL_flag_ssm.gif'Dentists patients per hour / >Chile vs Bolivia"
         StartTime = ctot("06/11/2009 01:00 AM")
         EndTime = ctot("06/11/2009 03:00 AM")
        }
  }
}

Now, let’s see how to load the scheduler control with data stored in the database. Suppose the events are stored in a table like this:

EventId * 
EventStart
EventEnd
EventDescription
EventDetails

Then the data provider will load the SDT from this table instead of using constants, for example like this:


SchedulerEvents
{
   items
   {
      event
         where EventStart >= &dateFrom
         where EventEnd   <= &dateTo
      {
         Id                    = EventId
         StartTime             = EventStart
         EndTime               = EventEnd
         Notes                 = EventDescription
         AdditionalInformation = EventDetails
      }
   }
}  

How to handle Scheduler user events?

An event can be added, updated or deleted directly from the scheduler. There are two ways to do this. A transaction can be called to work as any genexus transaction, or with some events and business components to save them.

Using Transaction

The control has a property named DetailsFormObject to specify the name of the transaction to be used in order to update the events.
This transaction must be defined with a certain parm and structure: The id of this transaction must be of Char Type (same as the EventId of the SDT) and the parm like the following one:

parm(&Mode,EventId, &EventStart,&EventEnd); 
default(EventStart,&EventStart);
default(EventEnd,&EventEnd);

Using control Events and BCs

The Scheduler control expose four events: EventAdded, EventDeleted, EventUpdated and EventSelected. In all these events the user accesses the event in the context using the CurrentEvent.
These events are triggered with a double click on the scheduler cell. A new event is created by the EventAdded when the user double clicks on an empty cell of the Scheduler. When the Scheduler control raises one of these events it loads the property CurrentEvent that is bound to a variable (by default the variable is called &currentEvent and its type is SchedulerEvents.Event).

So, suppose you want to add an event to your data store when the control raises the EventAdded. For this purpose do the following:

  1. Define the transaction that stores the events as a business component.
  2. Define in the web panel with the scheduler control, the variable &eventTrnBC of type of the BC defined in the previews step.
  3. Then the following user event must be written in the web panel where the Scheduler user control -named gxScheduler1- is used:

Event gxScheduler1.EventAdded
        &eventTrnBC.EventId = &currentEvent.Id
        &eventTrnBC.EventStart = &currentEvent.StartTime
        &eventTrnBC.EventEnd = &currentEvent.EndTime
        &eventTrnBC.EventDescription = &currentEvent.Notes
        &eventTrnBC.EventDetails = &currentEvent.AdditionalInformation
        &eventTrnBC.Save()
        commit 
EndEvent

Using control methods

It Could be useful to work with the scheduler events without using the control directly. For this purpose the following methods are availlable

  • AddEvent(Events.Event ev) Receive the event(s) to be added
  • UpdateEvent(Events.Event ev) Receive the event(s) to be updated
  • DeleteEvent(Events.Event ev) Receive the event(s) to be deleted

For example, the following can be inserted in a web panel

SchedulerControl6

And these events where &auxEvent is the event to be added, updated or deleted:


Event 'AddEvent'
      do 'GetRecords'
      gxScheduler1.AddEvent(&auxEvent)
EndEvent

Event 'UpdateEvent'
      do 'GetRecords'
      gxScheduler1.UpdateEvent(&auxEvent)
EndEvent 

Event'DeleteEvent'
      do 'GetRecords'
      gxScheduler1.DeleteEvent(&auxEvent)
EndEvent 

Sub'GetRecords'
      &auxEvent.Id = &id
      &auxEvent.Name = &name
      &auxEvent.StartTime = &startTime
      &auxEvent.EndTime = &endtime
      &auxEvent.Notes = &notes
      &auxEvent.AdditionalInformation = &additionalInformation
EndSub

Sample

 Here there is a KB that demo the use of this control to book Patient's Appointments.

Tip: previously to execute this sample read "Considerations" below in this document.

Properties

General

  • Autoload: Indicates which events will be automatically loaded. The values are day, week, month(*), year and none. For example, if the value is 'day', then each time the day is changed in the scheduler, the events of this day will be loaded. This allows to avoid to load all month events, when just changing an event in one day, and in many cases will offer better performance as fewer events are fetched (because the period is shorter).
  • LoadEventsObject: Is the name of the GeneXus object (DataProvider or Procedure) that loads the events managed in the Scheduler. This object must receive 2 dates as IN parameters and 1 SDT events as out parameter. In case of using a procedure, the &events must be specified in the parm rule, and in case of the data provider, it must be specified in the property Ouput = schedulerEvents.
  • DetailsFormObject: it allows to specify a transaction or web panel to handle specific data about the events. The default value is None
  • View: day (*), week, month (it has to be all in lowercase)
  • Default step time: minimal interval of time allowed to create events. The default value is 5 minutes.
  • DefaultLengthTime: Default time that is taken from the time new event of the Scheduler is initialized. The default value is 60 minutes.
  • HourSize: Is the size of the hour in rows. The default value is 2 rows.
  • FirstHour: initial hour of DAY view
  • LastHour: end hour of DAY view
  • ScrollHour: Indicates the hour in which the scroll will be moved to. It applies only when the scheduler control has a scroll, that is when the its height is too small. The default value is 0.
  • ControlName: Is the name of the scheduler control. The default value is GXScheduler1

Behavior

  • Readonly: indicates if the events of the scheduler can only be viewed (true value) or also handled, that is allowed to add, update and delete events (false value). The default value is false.
  • DetailsOnCreate (true, false): open or not the details dialog when creating a new event
  • DetailsOnDblClick (true, false): open or not the details dialog when updating an event  (This property only applies to Day and Week Views, but not to Month View - this is detailed in here).
  • OpenLinkNewWindow: open or not the details of the events in a new window. The values are true and false (default one)

Appearance

  • Width: Width (in pixels) of the scheduler control. The default value is 1.000.
  • Heigh: Heigh (in pixels) of the scheduler control. The default value is 1.000. 
  • Autoresize: Indicates if the control gets a size automatically (true) or if it can be changed at execution time. The default value is true.
  • PastEventsColor: Sets the color of the past events
  • TodayEventsColor: Sets the color of the today event
  • FutureEventsColor: Sets the color of the future events
  • DisplayMonthTab: Displays the month tab of the control or not. The default value is true. 
  • DisplayWeekTab: Displays the week tab of the control or not. The default value is true.
  • DisplayDayTab: Displays the day tab of the control or not. The default value is true.
  • DisplayNavigationButtons: Displays the buttons that allow to navigate through the different days, months, etc or not. The default value is true.

DataBindings

  • Initial Date: Is the name of the variable that defines the date in which the Scheduler will start to show. A variable of DATE type must be set, and by default, the variable &initialDate is defined in the object and its value by default is today().
  • CurrentEvent: Is the name of the variable used to manage the current event of the control. A variable of  SchedulerEvents.Event type must be set, and by default, the variable &currentEvent is defined in the object

Considerations

  • Only one scheduler control per web panel can be used. The base implementation (dhtmlx.com) does not allow this feature.
  • The SDT base structure can be modified, for example, to change the id datatype from char(20) to numeric(4). But consider that it is distributed within GeneXus, so when you update your GeneXus version, you will lose these changes.
  • In order to use the sample provided you must previously install GXScheduler User Control because it uses dhtmlxScheduler as the base control. Otherwise, errors like: "Error copying C:\Genexus\UserControls\GXScheduler\dhtmlxscheduler.css to MyApp\web\GXScheduler" may appear

Contact information

Please send feedback to gcanedo at genexusconsulting.com

Implementation and Licensing

The scheduler control uses dhtmlxScheduler as the base control.

The license information about this control can be read here.