Scheduler User Control

Official Content
This documentation is valid for:

Control Description

The GXScheduler user control allows to manage 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 showed:

GxSchedulerDownloadAndInstall

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

SchedulerControl4

 

The Scheduler control works with a 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 dataprovider 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 where 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 access 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 doule clicks on an empty cell of the Scheduler. When the Scheduler control raise one of these events it load 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 raise the EventAdded. For this purpose do the following:

  1. Define the transaction that stores the events as 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 usefull 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 a 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
  • 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

Behaviour

  • Readonly: indicates if the events of the scheduler can only be viewed (true value) or also handled , that is allows 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  
  • 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 values is 1.000.
  • Heigh: Heigh (in pixels) of the scheduler control. The default values 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 events
  • 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 allows to navigate though 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 be 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 this 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@genexusconsulting.com

Implementation and Licensing

The scheduler control uses dhtmlxScheduler as the base control.

The license information about this control can be read here.

The project's source code is at https://github.com/gerardocanedo/gxscheduler

Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.