ResourceTimeRanges

Feature that draws resource time ranges, shaded areas displayed behind events. These zones are similar to events in that they have a start and end date but different in that they do not take part in the event layout, and they always occupy full row height.

Resource time ranges

//<code-header>
fiddle.title = 'Resource time ranges';
//</code-header>
targetElement.innerHTML = '<p>This demo shows the built-in colors available for resource time ranges:</p>';
const scheduler         = new Scheduler({
    appendTo : targetElement,

    // makes scheduler as high as it needs to be to fit rows
    autoHeight : true,

    features : {
        resourceTimeRanges : true
    },

    startDate : new Date(2018, 10, 25),
    endDate   : new Date(2018, 11, 8),

    rowHeight  : 100,
    barMargin  : 20,
    eventStyle : 'filled',

    columns : [
        { field : 'name', text : 'Name', width : 100 }
    ],

    resources : [
        { id : 1, name : 'Lady' },
        { id : 2, name : 'Dude' }
    ],

    events : [
        { id : 1, resourceId : 1, name : 'Event 1', startDate : '2018-11-29', duration : 2 },
        { id : 2, resourceId : 2, name : 'Event 2', startDate : '2018-11-30', duration : 2 }
    ],

    resourceTimeRanges : [
        { id : 1, resourceId : 1, name : 'Custom HTML', timeRangeColor : 'red', startDate : '2018-11-25', duration : 2 },
        { id : 2, resourceId : 2, name : 'Pink', timeRangeColor : 'pink', startDate : '2018-11-25', duration : 2 },
        { id : 3, resourceId : 1, name : 'Purple', timeRangeColor : 'purple', startDate : '2018-11-27', duration : 2 },
        { id : 4, resourceId : 2, name : 'Violet', timeRangeColor : 'violet', startDate : '2018-11-27', duration : 2 },
        { id : 5, resourceId : 1, name : 'Indigo', timeRangeColor : 'indigo', startDate : '2018-11-29', duration : 2 },
        { id : 6, resourceId : 2, name : 'Blue', timeRangeColor : 'blue', startDate : '2018-11-29', duration : 2 },
        { id : 7, resourceId : 1, name : 'Cyan', timeRangeColor : 'cyan', startDate : '2018-12-01', duration : 2 },
        { id : 8, resourceId : 2, name : 'Teal', timeRangeColor : 'teal', startDate : '2018-12-01', duration : 2 },
        { id : 9, resourceId : 1, name : 'Green', timeRangeColor : 'green', startDate : '2018-12-03', duration : 2 },
        { id : 11, resourceId : 2, name : 'Lime', timeRangeColor : 'lime', startDate : '2018-12-03', duration : 2 },
        { id : 12, resourceId : 1, name : 'Yellow (default)', startDate : '2018-12-05', duration : 2 },
        { id : 13, resourceId : 2, name : 'Orange', timeRangeColor : 'orange', startDate : '2018-12-05', duration : 2 }
    ],

    resourceTimeRangeRenderer({ resourceTimeRangeRecord, resourceRecord, renderData }) {
        if (resourceTimeRangeRecord.id === 1) {
            // Adds a CSS class to the range element
            renderData.cls.important = 1;

            return [
                {
                    tag   : 'i',
                    class : 'fa fa-warning',
                    style : 'margin-inline-end:.5em'
                },
                {
                    tag  : 'strong',
                    text : `${DateHelper.format(resourceTimeRangeRecord.startDate, 'MMM DD')} ${resourceTimeRangeRecord.name}`
                }
            ];
        }
        return resourceTimeRangeRecord.name;
    }
});

Each time range is represented by an instances of ResourceTimeRangeModel, held in a ResourceTimeRangeStore. Currently they are readonly UI-wise, but can be manipulated on the data level. To style the rendered elements, use the cls field or use the timeRangeColor field.

Data can be provided either using the resourceTimeRanges config on the Scheduler config object:

new Scheduler({
    ...
   features :  {
       resourceTimeRanges : true
   },

   // Data specified directly on the Scheduler instance
   resourceTimeRanges : [
       // Either specify startDate & endDate or startDate & duration when defining a range
       { startDate : new Date(2019,0,1), endDate : new Date(2019,0,3), name : 'Occupied', timeRangeColor : 'red' },
       { startDate : new Date(2019,0,3), duration : 2, durationUnit : 'd', name : 'Available' },
   ]
})

Or the resourceTimeRangeStore config on the Scheduler config object:

new Scheduler({
    ...
    features :  {
        resourceTimeRanges : true
    },
    resourceTimeRangeStore : new ResourceTimeRangeStore({
        readUrl : './resourceTimeRanges/'
    })
})

Or on the project, using the resourceTimeRangesData config.

This feature is disabled by default. For info on enabling it, see GridFeatures.

Recurring ranges support

Resource time ranges can also be recurring, as seen in the example below:

const resourceTimeRangeStore = new ResourceTimeRangeStore({
    data : [{
        id             : 1,
        resourceId     : 'r1',
        startDate      : '2019-01-01T11:00',
        endDate        : '2019-01-01T13:00',
        name           : 'Lunch',
        // this time range will repeat every day
        recurrenceRule : 'FREQ=DAILY'
    }]
});

Rendering custom HTML markup

Sometimes it is handy to be able to output custom HTML into the range elements. This can be done using the resourceTimeRangeRenderer config method.

// You can use a custom renderer method to output the contents of the range elements. The return value should
// be a string or a DOMConfig object defining the markup to generate
new Scheduler({
    resourceTimeRangeRenderer{ resourceTimeRangeRecord, resourceRecord, renderData }) {
        if (resourceTimeRangeRecord.important) {
            // Add a CSS class to the range element
            renderData.cls.important = 1;

            return [
                {
                    tag   : 'i',
                    class : 'fa fa-warning'
                },
                {
                    tag  : 'strong',
                    text : resourceTimeRangeRecord.name
                }
            ];
        }
        return resourceTimeRangeRecord.name;
    }
})

Configs

Common

disabledInstancePlugin

listenersEvents

Other

enableMouseEvents: Boolean= falseAlso a property

Set to true to allow mouse interactions with the rendered range elements. By default, the range elements are not reachable with the mouse, and only serve as a static background.

resourceTimeRangeRenderer: function

An empty function by default, but provided so that you can override it. This function is called each time a resource time range is rendered into the schedule. It's called with resourceTimeRangeRecord, resourceRecord, and renderData params.

You should never modify any records inside this method.

By default, the DOM markup of a resource time range bar includes placeholders for 'cls' and 'style'. The cls property is a DomClassList which will be added to the main element. The style property is an inline style declaration for the main element.

IMPORTANT: When returning content, be sure to consider how that content should be encoded to avoid XSS (Cross-Site Scripting) attacks. This is especially important when including user-controlled data such as the event's name. The function encodeHtml as well as xss can be helpful in these cases.

resourceTimeRangeRenderer({ resourceTimeRangeRecord, resourceRecord, renderData }) {
    renderData.style = 'color:white'; // You can use inline styles too.

    // Property names with truthy values are added to the resulting elements CSS class.
    renderData.cls.isModified = resourceTimeRangeRecord.isModified;

    // Or, you can treat it as a string, but this is less efficient, especially
    // if your renderer wants to *remove* classes that may be there.
    renderData.cls += ' extra-class';

    return StringHelper.xss`${DateHelper.format(resourceTimeRangeRecord.startDate, 'YYYY-MM-DD')}:
    ${resourceTimeRangeRecord.name}`;
}

Parameter	Type	Description
`detail`	Object	An object containing the information needed to render a ResourceTimeRangeModel.
`detail.resourceTimeRangeRecord`	ResourceTimeRangeModel	The resource time range record.
`detail.resourceRecord`	ResourceModel	The resource record.
`detail.renderData`	Object	An object containing details about the event rendering.

Returns: String | DomConfig | DomConfig[] -

A simple string, or a DomConfig object describing the markup

tabIndex: Number= 0

Specify value to use for the tabIndex attribute of resource time range elements

catchEventHandlerExceptionsEvents

Misc

bubbleEventsEvents

callOnFunctionsEvents

clientInstancePlugin

localeClassLocalizable

localizableLocalizable

localizablePropertiesLocalizable

Properties

Common

disabledInstancePlugin

Class hierarchy

isResourceTimeRanges: Boolean= truereadonly

Identifies an object as an instance of ResourceTimeRanges class, or subclass thereof.

isResourceTimeRanges: Boolean= truereadonlystatic

Identifies an object as an instance of ResourceTimeRanges class, or subclass thereof.

isResourceTimeRangesBase: Boolean= truereadonlyResourceTimeRangesBase

Identifies an object as an instance of ResourceTimeRangesBase class, or subclass thereof.

isResourceTimeRangesBase: Boolean= truereadonlystaticResourceTimeRangesBase

Identifies an object as an instance of ResourceTimeRangesBase class, or subclass thereof.

isEventsEvents

isInstancePluginInstancePlugin

isLocalizableLocalizable

Other

enableMouseEvents: Boolean= falseAlso a config

Set to true to allow mouse interactions with the rendered range elements. By default, the range elements are not reachable with the mouse, and only serve as a static background.

catchEventHandlerExceptionsEvents

Lifecycle

configBase

isConstructingBase

isDestroyedBase

isDestroyingBase

Misc

callOnFunctionsEvents

clientInstancePlugin

localeHelperLocalizable

localeManagerLocalizable

Functions

DOM

getElementFromResourceTimeRangeRecord

Returns the element for the passed resource time range record, if rendered into DOM.

Parameter	Type	Description
`record`	ResourceTimeRangeModel

Returns: HTMLElement

resolveResourceTimeRangeRecord

Returns a resource time range record from the passed element

Parameter	Type	Description
`rangeElement`	HTMLElement

Returns: ResourceTimeRangeModel

destroystaticBase

doDestroyBase

setConfigBase

Misc

animatePropertyBase

callbackBase

doDisableInstancePlugin

downloadTestCaseBase

initClassstaticBase

isOfTypeNamestaticBase

mixinstaticBase

optionalLstaticLocalizable

resolveCallbackBase

updateLocalizationLocalizable

Other

addListenerEvents

hasListenerEvents

LstaticLocalizable

onEvents

relayAllEvents

removeAllListenersEvents

removeListenerEvents

resumeEventsEvents

suspendEventsEvents

triggerEvents

unEvents

Events

resourceTimeRangeClick

Triggered for click on a resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeClick', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

resourceTimeRangeContextMenu

Triggered for right-click on a resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeContextMenu', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

resourceTimeRangeDblClick

Triggered for double-click on a resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeDblClick', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

resourceTimeRangeMouseDown

Triggered for mouse down ona resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeMouseDown', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

resourceTimeRangeMouseOut

Triggered for mouse out of a resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeMouseOut', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

resourceTimeRangeMouseOver

Triggered for mouse over on a resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeMouseOver', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

resourceTimeRangeMouseUp

Triggered for mouse up ona resource time range. Only triggered if the ResourceTimeRange feature is configured with enableMouseEvents: true.

// Adding a listener using the "on" method
resourceTimeRanges.on('resourceTimeRangeMouseUp', ({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) => {

});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

beforeDestroyEvents

catchAllEvents

destroyEvents

disableInstancePlugin

enableInstancePlugin

Event handlers

onResourceTimeRangeClick

Called for click on a resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeClick({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onResourceTimeRangeContextMenu

Called for right-click on a resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeContextMenu({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onResourceTimeRangeDblClick

Called for double-click on a resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeDblClick({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onResourceTimeRangeMouseDown

Called for mouse down ona resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeMouseDown({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onResourceTimeRangeMouseOut

Called for mouse out of a resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeMouseOut({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onResourceTimeRangeMouseOver

Called for mouse over on a resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeMouseOver({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onResourceTimeRangeMouseUp

Called for mouse up ona resource time range. Only called if the ResourceTimeRange feature is configured with enableMouseEvents: true.

new ResourceTimeRanges({
    onResourceTimeRangeMouseUp({ source, feature, resourceTimeRangeRecord, resourceRecord, domEvent }) {

    }
});

Parameter	Type	Description
`source`	Scheduler	This Scheduler
`feature`	ResourceTimeRanges	The ResourceTimeRange feature
`resourceTimeRangeRecord`	ResourceTimeRangeModel	Resource time range record
`resourceRecord`	ResourceModel	Resource record
`domEvent`	MouseEvent	Browser event

onBeforeDestroyEvents

onCatchAllEvents

onDestroyEvents

onDisableInstancePlugin

onEnableInstancePlugin

Typedefs

BryntumListenerConfigEvents

CSS variables

Name	Description
`--b-resource-time-range-zindex`	Resource time range z-index
`--b-resource-time-range-font-size`	Resource time range font size
`--b-resource-time-range-align-items`	Resource time range align items (flexbox)
`--b-resource-time-range-padding-block`	Resource time range padding block
`--b-resource-time-range-padding-inline`	Resource time range padding inline
`--b-resource-time-range-background-transparency`	Resource time range background transparency (color-mixed with primary color)
`--b-resource-time-range-background`	Resource time range background color (declared on .b-sch-resource-time-range)
`--b-resource-time-range-color`	Resource time range text color (declared on .b-sch-resource-time-range)

ResourceTimeRanges

Recurring ranges support

Rendering custom HTML markup

Configs

Common

Other

Misc

Properties

Common

Class hierarchy

Other

Lifecycle

Misc

Functions

DOM

Configuration

Events

Lifecycle

Misc

Other

Events

Event handlers

Typedefs

CSS variables