ig.scheduler.ScheduleListDataSource

ScheduleDataSource-derived class for use with lists of objects that provide data from which appointments and resources can be created.

Remarks

The ScheduleListDataSource class provides the ability to bind a list of "plain old CLR objects" (commonly referred to as a "POCOs"), which provide Appointment and ScheduleResource data. An existing class can be used to represent an appointment or a resource, provided that the class exposes properties of the required type. If the names of these properties are the same as the corresponding appointment/resource property, these properties are automatically bound to their respective appointment/resource properties; if the names are different, property mapping support is provided through the ScheduleListDataSource.appointmentPropertyMappings and ScheduleListDataSource.resourcePropertyMappings collections.

The ScheduleListDataSource.appointmentItemsSource property accepts any value which implements the IEnumerable interface. However, with a simple IEnumerable implementation, certain functionality is not supported, most notably creation of new appointments, and deletion of existing ones. External modifications to the item source are not reflected by the ScheduleListDataSource class, since the IEnumerable interface does not provide any change notification mechanism.

With an item source which implements the IList interface, creation and deletion of appointments through the ScheduleListDataSource API is supported, but external changes to the item source are, as with an IEnumerable implementation, not reflected by the ScheduleListDataSource, again due to the lack of a change notification mechanism. Note that the List class falls into this category as well.

An item source which implements the IList and INotifyCollectionChanged interfaces provides the most functionality, as content change methods as well as notification methods exist. In this case, creation and deletion is supported both through the ScheduleListDataSource API and via external changes to the collection. When possible, it is best to use the ObservableCollection class, which supports both content change and notification mechanisms.

Another requirement for the ability to create new appointments is a public parameterless constructor exposed by the underlying data object class. If the class does not expose a public parameterless constructor, the ScheduleListDataSource.createAppointmentDataObjectCallback property can be used to provide a factory method which is called when a new Appointment object is created. Without a parameterless constructor or a factory method, addition of new appointments is not supported, regardless of whether the item source supports content changes.

The ScheduleListDataSource.resourceItemsSource property works the same as AppointmentItemsSource, although because adding/removing resources is not supported through the user interface, it is not as important to use a list type which supports creation and deletion.

Note that the "POCO" object which provides the backing store for an appointment or resource must implement the INotifyPropertyChanged interface in order to support external changes made to that object. Without such a property change notification mechanism, ScheduleListDataSource cannot react to changes made to property values, and as such will not be able to keep the corresponding properties of the appointment or resource object synchronized. Changes made to property values of the Appointment and ScheduleResource class through the API, however, are immediately reflected by ScheduleListDataSource, and are immediately propagated back to the underlying data object as well.

The following table summarizes the functionality which is available under each usage scenario:

Interface(s) Functionality
IEnumerable Provides only basic functionality. An appointment/resource is created for each item in the list, but adding new items and removing existing ones is not supported.
IList Provides the ability to add/remove appointments/resources, but only through the API.
INotifyCollectionChanged Provides the ability to add/remove appointments/resources through external changes made to the item source.
IList + INotifyCollectionChanged Addition and removal of appointments/resources is supported both through the API as well as external changes made to the item source. For best results, the ObservableCollection class is recommended as this class implements both interfaces.
INotifyPropertyChanged If implemented on the underlying data object class (i.e., "POCO"), external changes made to properties of the object are immediately synchronized with the corresponding appointment/resource object. Note that changes made through appointment/resource properties are always propagated back to the underlying data object, so an INotifyPropertyChanged implementation is unnecessary in that scenario.

Dependencies

jquery-1.4.4.js
infragistics.util.js
infragistics.ext_core.js
infragistics.ext_collections.js
infragistics.ext_collectionsExtended.js
infragistics.ext_io.js
infragistics.ext_text.js
infragistics.ext_web.js
infragistics.dv_core.js
infragistics.dv_jquerydom.js
infragistics.dv_interactivity.js
infragistics.ext_ui.js
The current widget has no options.
The current widget has no events.

  • ig.scheduler.ScheduleListDataSource
    Constructor

    new $.ig.scheduler.ScheduleListDataSource( );

    Creates a new instance.

  • appointmentItemsSource

    .appointmentItemsSource( );

    Returns the list of data objects from which appointments are created.

  • appointmentItemsSource

    .appointmentItemsSource( value:object );

    Sets the list of data objects from which appointments are created.

    • value
    • Type:object

  • appointmentPropertyMappings

    .appointmentPropertyMappings( );
    Return Type:
    ig.scheduler.AppointmentPropertyMappingsCollection
    Return Type Description:
    Returns a AppointmentPropertyMappingsCollection.

    Returns a collection which enables the developer to map an Appointment property to a property of the underlying data object which has a different name.

    Remarks

    In cases where the names of the properties on the underlying data object are all the same as that of the schedule object properties to which they are bound, a mapping can be automatically assumed to exist. In this case, no explicit mappings are necessary.

    In the case where a property of the underlying data object has the same name as a schedule object property, but the developer does not want a mapping to exist, add an AppointmentPropertyMapping with a null value for the SchedulePropertyMapping.dataObjectPropertyName property.

    In cases where the data type of the bound property does not match that of the corresponding schedule object property, conversion is attempted, but is limited by the functionality provided by the Convert class. For example, an appointment's Start property can be mapped to a field of type string (assuming the data contained therein is a valid string representation of a date/time). Similarly, the Id property can be mapped to a field of type integer, since the numeric value can be converted to a string.

    In cases where the value of the bound property is not convertible to that of the schedule object property, the SchedulePropertyMapping.convertCallback and SchedulePropertyMapping.convertBackCallback methods can be used to convert data bi-directionally.

    The following Appointment properties require mappings:

    See Also

  • appointmentPropertyMappings

    .appointmentPropertyMappings( index:number );
    Return Type:
    ig.scheduler.SchedulePropertyMapping
    Return Type Description:
    Returns a SchedulePropertyMapping.

    • index
    • Type:number

    See Also

  • appointmentPropertyMappings

    .appointmentPropertyMappings( index:number, value:ig.scheduler.SchedulePropertyMapping );
    Return Type:
    ig.scheduler.SchedulePropertyMapping
    Return Type Description:
    Returns a SchedulePropertyMapping.

    • index
    • Type:number
    • value
    • Type:ig.scheduler.SchedulePropertyMapping

    See Also

  • beginEdit

    .beginEdit( appointment:ig.scheduler.Appointment, errorCallback:function );
    Return Type:
    boolean
    Return Type Description:
    True if the operation was successful.

    Begins an edit mode session on the the specified appointment.

    • appointment
    • Type:ig.scheduler.Appointment
    • The Appointment-derived object to be edited.
    • errorCallback
    • Type:function

    See Also

  • bumpResourcesVersion
    Inherited

    .bumpResourcesVersion( );

    Marks the resources cache dirty.

  • cancelEdit

    .cancelEdit( appointment:ig.scheduler.Appointment );
    Return Type:
    ig.scheduler.AppointmentOperationResult
    Return Type Description:
    An AppointmentOperationResult instance containing the result of the operation.

    Reverses changes made to an Appointment during an edit mode session begun with the ScheduleListDataSource.beginEdit method.

    • appointment
    • Type:ig.scheduler.Appointment
    • The Appointment being edited.

    See Also

  • createAppointment

    .createAppointment( errorCallback:function );
    Return Type:
    ig.scheduler.Appointment
    Return Type Description:
    A AppointmentOperationResult instance containing a reference to the newly created Appointment, or a DataError object if the operation failed.

    Creates a new Appointment.

    • errorCallback
    • Type:function

    See Also

  • createAppointmentDataObjectCallback

    .createAppointmentDataObjectCallback( );

    Returns a delegate which is called to create a data object for a newly created Appointment.

    Remarks

    In cases where it is not possible to determine the type of the items contained within the ScheduleListDataSource.appointmentItemsSource, a new instance of that type cannot be automatically created using reflection. This is also the case for a type which does not publicly expose a parameterless constructor.

    This property makes it possible for the developer to receive a callback at the time of Appointment instance creation, thereby providing a way for a corresponding data object to be created.

    See Also

  • createAppointmentDataObjectCallback

    .createAppointmentDataObjectCallback( value:function );

    Sets a delegate which is called to create a data object for a newly created Appointment.

    • value
    • Type:function

    Remarks

    In cases where it is not possible to determine the type of the items contained within the ScheduleListDataSource.appointmentItemsSource, a new instance of that type cannot be automatically created using reflection. This is also the case for a type which does not publicly expose a parameterless constructor.

    This property makes it possible for the developer to receive a callback at the time of Appointment instance creation, thereby providing a way for a corresponding data object to be created.

    See Also

  • createVariance

    .createVariance( appointment:ig.scheduler.Appointment );

    Creates a variance, i.e., a modified occurrence of a recurrence.

    • appointment
    • Type:ig.scheduler.Appointment

    See Also

  • dataErrorCallback
    Inherited

    .dataErrorCallback( );

    Returns a delegate which is called when an error is encountered during interaction with the dataSource.

  • dataErrorCallback
    Inherited

    .dataErrorCallback( value:function );

    Sets a delegate which is called when an error is encountered during interaction with the dataSource.

    • value
    • Type:function

  • deleteAppointment

    .deleteAppointment( appointment:ig.scheduler.Appointment );
    Return Type:
    ig.scheduler.AppointmentOperationResult
    Return Type Description:
    An AppointmentOperationResult instance which contains the result of the operation.

    Deletes the specified Appointment.

    • appointment
    • Type:ig.scheduler.Appointment
    • The appointment to be deleted.

    Remarks

    The DeleteAppointment method implementation for the ScheduleListDataSource class executes synchronously; as such, it is not necessary to handle the OperationResultBase.completed event.

    See Also

  • destroy

    .destroy( );

    Releases any memory previously used by this class.

  • endEdit

    .endEdit( appointment:ig.scheduler.Appointment, force:boolean );

    Commits or discards changes made to an activity during an edit mode session.

    • appointment
    • Type:ig.scheduler.Appointment
    • The activity being edited.
    • force
    • Type:boolean
    • True to force exiting of edit mode.

    See Also

  • getAppointmentBackgroundColor
    Inherited

    .getAppointmentBackgroundColor( resource:ig.scheduler.ScheduleResource );
    Return Type:
    string
    Return Type Description:
    The resolved color in hexadecimal format.

    Returns the resolved Appointment background color for the specified ScheduleResource.

    See Also

  • getAppointmentsInRange
    Inherited

    .getAppointmentsInRange( range:ig.scheduler.DateTimeRange );
    Return Type:
    ig.scheduler.AppointmentQueryResult
    Return Type Description:
    An AppointmentQueryResult object containing the result of the query.

    Returns all appointments which lie within the specified date/time range.

    • range
    • Type:ig.scheduler.DateTimeRange
    • The range of time for which the appointments are to be returned.

    Remarks

    Note that this method returns all appointments in the specified range, regardless of which ScheduleResource the appointment may be associated with.

    Use the ScheduleDataSource.getAppointmentsInRange overload to filter the returned appointment list by one or more ScheduleResource.

    See Also

  • getAppointmentsInRange

    .getAppointmentsInRange( range:ig.scheduler.DateTimeRange, resources:ig.IEnumerable`1 );
    Return Type:
    ig.scheduler.AppointmentQueryResult
    Return Type Description:
    An AppointmentQueryResult object containing the result of the query. Note that for the ScheduleListDataSource class, the result of the query is available immediately upon return from the method, i.e., it is not necessary to handle the OperationResultBase.completed event. event

    Returns an enumerable list of objects representing all appointments which lie within the specified range, optionally filtering by one or more resources.

    • range
    • Type:ig.scheduler.DateTimeRange
    • The date range to test.
    • resources
    • Type:ig.IEnumerable`1
    • Optional list of owners on which to filter. If a non-null value is specified, only appointments which belong to one of the specified owners is returned.

    Remarks

    The GetAppointmentsInRange method implementation for the ScheduleListDataSource class executes the query synchronously; as such, the list of AppointmentQueryResult.appointments is fully populated before execution returns from the method.

    Use this method to obtain a list of each Appointment which intersects with the specified range, optionally filtered by one or more resources.

    See Also

  • getAppointmentTextColor
    Inherited

    .getAppointmentTextColor( resource:ig.scheduler.ScheduleResource );
    Return Type:
    string
    Return Type Description:
    The resolved color in hexadecimal format.

    Returns the resolved Appointment text color for the specified ScheduleResource.

    See Also

  • getResources

    .getResources( );

    Returns an enumerable list of all resources associated with this data source.

  • handleAppointmentItemsPropertyChanged

    .handleAppointmentItemsPropertyChanged( );

    Determines whether the INotifyPropertyChanged.PropertyChanged event is handled for Appointment data objects.

    Remarks

    In order to receive a notification when a property of an Appointment's underlying data object changes value, the data source will register as a listener of the data object's INotifyPropertyChanged.PropertyChanged event. This enables the corresponding Appointment object to react to external changes and synchronize it's own property values accordingly.

    In cases where the ScheduleListDataSource.appointmentItemsSource contains a relatively large number of items, this can affect performance and/or memory consumption adversely.

    This property provides a way for the developer to switch this behavior off, thus signaling to the data source that the PropertyChanged event should not be handled.

    This property is only applicable when the underlying data object implements the INotifycPropertyChanged interface.

    Also note that the data source exposes a ScheduleListDataSource.raisePropertyChanged method, which routes through the same logic as the handler for the data object's PropertyChanged event. Call this method directly to simulate the PropertyChanged event for the specified appointment data object, thus achieving the same result as handling the PropertyChanged event.

    See Also

  • handleAppointmentItemsPropertyChanged

    .handleAppointmentItemsPropertyChanged( value:boolean );

    Determines whether the INotifyPropertyChanged.PropertyChanged event is handled for Appointment data objects.

    • value
    • Type:boolean

    Remarks

    In order to receive a notification when a property of an Appointment's underlying data object changes value, the data source will register as a listener of the data object's INotifyPropertyChanged.PropertyChanged event. This enables the corresponding Appointment object to react to external changes and synchronize it's own property values accordingly.

    In cases where the ScheduleListDataSource.appointmentItemsSource contains a relatively large number of items, this can affect performance and/or memory consumption adversely.

    This property provides a way for the developer to switch this behavior off, thus signaling to the data source that the PropertyChanged event should not be handled.

    This property is only applicable when the underlying data object implements the INotifycPropertyChanged interface.

    Also note that the data source exposes a ScheduleListDataSource.raisePropertyChanged method, which routes through the same logic as the handler for the data object's PropertyChanged event. Call this method directly to simulate the PropertyChanged event for the specified appointment data object, thus achieving the same result as handling the PropertyChanged event.

    See Also

  • hasAppointmentsInRange

    .hasAppointmentsInRange( range:ig.scheduler.DateTimeRange, resources:ig.IEnumerable`1, findFirst:boolean );

    Returns a value indicating whether there is appointment activity for the given range, filtering on the specified resourceIds. Also returns an array of dates containing the days with activity.

    • range
    • Type:ig.scheduler.DateTimeRange
    • The range to test.
    • resources
    • Type:ig.IEnumerable`1
    • Resources on which to filter, or null/empty to include all resources.
    • findFirst
    • Type:boolean
    • If true, returns as soon as any one activity is found in the specified range for one of the specified resources. In this case the DateQueryResultBase.dates list is not populated. Pass true to optimize for the case where the actual dates with activity are not needed.

    See Also

  • internalNotifyPropertyChanging

    .internalNotifyPropertyChanging( activity:ig.scheduler.ActivityBase, propertyName:string, oldValue:object, newValue:object );
    Return Type:
    boolean
    Return Type Description:
    True to allow the notification, false to suppress it.

    Called before an internal property change notification is handled, giving the data source an opportunity to suppress the notification.

    • activity
    • Type:ig.scheduler.ActivityBase
    • The ActivityBase instance
    • propertyName
    • Type:string
    • The name of the property whose value is changing.
    • oldValue
    • Type:object
    • The property value before the change is made.
    • newValue
    • Type:object
    • The property value after the change is made.

    See Also

  • isAppointmentDataReady

    .isAppointmentDataReady( );

    Returns false in the case where an appointment item source has been assigned and the initialization process is currently underway.

  • onAppointmentPropertyChanged

    .onAppointmentPropertyChanged( appointment:ig.scheduler.Appointment, property:ig.scheduler.AppointmentProperty, oldValue:object, newValue:object, [raiseEvent:boolean] );

    Raises the AppointmentPropertyChanged event. This is our pseudo-handler for PropertyChanged - we don't actually listen to our own appointment's PropertyChanged event, we manually push the notification to this method.

    • appointment
    • Type:ig.scheduler.Appointment
    • property
    • Type:ig.scheduler.AppointmentProperty
    • oldValue
    • Type:object
    • newValue
    • Type:object
    • raiseEvent
    • Type:boolean
    • Optional

    See Also

  • onPropertyChanged
    Inherited

    .onPropertyChanged( propertyName:string );

    Raises the PropertyChanged event.

    • propertyName
    • Type:string

  • onResourcePropertyChanged
    Inherited

    .onResourcePropertyChanged( resource:ig.scheduler.ScheduleResource, property:ig.scheduler.ScheduleResourceProperty, dayOfWeek:ig.DayOfWeek );

    Raises the ResourcePropertyChanged event.

    • resource
    • Type:ig.scheduler.ScheduleResource
    • property
    • Type:ig.scheduler.ScheduleResourceProperty
    • dayOfWeek
    • Type:ig.DayOfWeek

    See Also

  • raisePropertyChanged

    .raisePropertyChanged( dataObject:object, property:ig.scheduler.AppointmentProperty );

    Notifies the data source of a change to a property value of the specified dataObject.

    • dataObject
    • Type:object
    • The data object whose property value has changed.
    • property
    • Type:ig.scheduler.AppointmentProperty
    • A constant identifying the property whose value has changed.

    Remarks

    In cases where there are a relatively large number of data objects in the ScheduleListDataSource.appointmentItemsSource, performance may be adversely impacted by handling the PropertyChanged event via the data object's INotifyPropertyChanged interface. To avoid this, set the ScheduleListDataSource.handleAppointmentItemsPropertyChanged property to false.

    Note that if the data source is created in this manner, the state of the corresponding Appointment object cannot be automatically synchronized with that of the underlying data object.

    Use this method to manually send a property change notification for the affected data object and property value, thus ensuring that the state of the appointment object is synchronized with that of the underlying data object.

    See Also

  • resourceItemsSource

    .resourceItemsSource( );

    Returns the list of data objects from which appointments are created.

  • resourceItemsSource

    .resourceItemsSource( value:ig.IEnumerable );

    Sets the list of data objects from which appointments are created.

    • value
    • Type:ig.IEnumerable

  • resourcePropertyMappings

    .resourcePropertyMappings( );
    Return Type:
    ig.scheduler.ResourcePropertyMappingsCollection
    Return Type Description:
    Returns a ResourcePropertyMappingsCollection.

    Returns a collection which enables the developer to map a ScheduleResource property to a property of the underlying data object which has a different name.

    Remarks

    In cases where the names of the properties on the underlying data object are all the same as that of the schedule object properties to which they are bound, a mapping can be automatically assumed to exist. In this case, no explicit mappings are necessary.

    In the case where a property of the underlying data object has the same name as a schedule object property, but the developer does not want a mapping to exist, add an ResourcePropertyMapping with a null value for the SchedulePropertyMapping.dataObjectPropertyName property.

    Note that in cases where the data type of the bound property does not match that of the schedule object property, the SchedulePropertyMapping.convertCallback and SchedulePropertyMapping.convertBackCallback methods can be used to convert data bi-directionally.

    The following ScheduleResource properties require mappings:

    See Also

  • resourcePropertyMappings

    .resourcePropertyMappings( index:number );
    Return Type:
    ig.scheduler.SchedulePropertyMapping
    Return Type Description:
    Returns a SchedulePropertyMapping.

    • index
    • Type:number

    See Also

  • resourcePropertyMappings

    .resourcePropertyMappings( index:number, value:ig.scheduler.SchedulePropertyMapping );
    Return Type:
    ig.scheduler.SchedulePropertyMapping
    Return Type Description:
    Returns a SchedulePropertyMapping.

    • index
    • Type:number
    • value
    • Type:ig.scheduler.SchedulePropertyMapping

    See Also

Copyright © 1996 - 2024 Infragistics, Inc. All rights reserved.