Properties

The selectionMode property controls the selection, this property can take the following values:

• "none" - no selection is possible.
• "single" - only one item can be selected at most.
• "multiple" - zero or several items can be selected.

The selectedItems property contains the list of selected items from the data store.

The selectedItem property contains the last selected item.

These last two properties can read as well as programmatically set.

Using the mouse

To select a data item, simply click on an item renderer.

To deselect a data item, press the control key and click on an item renderer.

If the selection mode is "multiple", you can extend the selection or deselect a data item by pressing the control key and click on an item renderer.

Using the keyboard

If the calendar widget has the focus, press the left or right arrow keys to select a data item.

To move only the focus on a data item and not select it at the same time, press left or right arrow keys while maintaining the control key.

To deselect a data item or extend selection (if selection mode is "multiple"), move the focus to an item renderer and press the space bar while maintaining the control key.

Using a touch device

To select a data item, simply tap on it.

Using the mouse

To move a data item, press the mouse button over the body of an item renderer, drag the event at the desired position and release the mouse button.

To resize a data item, press the mouse button over the start or end of an item renderer, drag it to the desired position and release the mouse button.

If you press the escape key while editing a data item, the editing gesture will be canceled.

Using the keyboard

If a data item has the focus (see selection section), press the enter key to edit it.

In editing mode:

• press the arrow keys to move the data item,
• press the up or down arrow keys while maintaining the control key to resize it by moving the end of this data item.
• press the enter key to validate the changes and leaving the edit mode.
• press the escape key to cancel the changes and leaving the edit mode.

Using a touch device

To enter in edit mode press an item renderer for a small amount of time, until the it visually change its state.

In editing mode:

• press and move the body of the item renderer to move the event.
• press and move one (or both) of the resize areas to resize the data item.
• tap out of the item renderer to validate the changes and leave the edit mode.

Calendar views animations

On modern browsers, the calendar is performing an animation when:

• The displayed time interval is changing and/or
• The current view is changing to display the time interval.

To disable this animation set the calendar animateRange property to false (true by default).

To change the duration of the animation set the animationRangeDuration property (400 by default).

For the most skillful developers, subclass the _animateRange() method to implement your own animation.

View management

The default views are created in the _createDefaultViews() function. To specify the views to use instead of the default views, set the views property.

The view switching is determined according to the displayed time interval.

The calendar is going through the following steps:

• One or several properties that are defining the displayed time range are changed,
• The new displayed time interval is computed,
• The _computeCurrentView() function is called to determine which view should be used to properly display the time range.
• The view is configured (setting startDate, columnCount etc) in the _configureView() function.
• If the current view has changed, show the new view.

You can override these key function change the current and/or change the configuration of this view.

The following example shows the creation of custom views and a change the default view to display two weeks:

var secondarySheetClass = declare([ColumnViewSecondarySheet, CalendarKeyboard, CalendarMouse]);

var colView = declare([ColumnView, Keyboard, Mouse])({
  secondarySheetClass: secondarySheetClass,
  secondarySheetProps: {
    horizontalRendererHeight: 16
  },
  verticalRenderer: VerticalRenderer,
  horizontalRenderer: HorizontalRenderer,
  expandRenderer: ExpandRenderer
});

var matrixView = declare([MatrixView, Keyboard, Mouse])({
  horizontalRenderer: HorizontalRenderer,
  labelRenderer: LabelRenderer,
  expandRenderer: ExpandRenderer,
  verticalGap:4
});

var calendar = new CalendarBase({
  views: [colView, matrixView],
  columnView: colView,
  matrixView: matrixView,
  _computeCurrentView: function(startDate, endDate, duration){
    return duration <= 14 ? this.views[0] : this.views[1];
  },
  dateInterval: "week",
  dateIntervalSteps: 2
}, "calendarNode");

Renderer kind mapping

The itemToRendererKindFunc properties allow to specify a mapping between a data item and a kind of item renderer (vertical, horizontal or label).

Setting this function allows to:

• Filter out some data items, based on some of their properties,
• Choose which kind of item renderer is more suited to display the data item.

The default function behavior on the ColumnView is:

• If the data item is not an all day data item, use vertical item renderer,
• otherwise, do not display the data item.

The all day data item are displayed on the secondary sheet which also have a function with the inverse behavior.

For example, to show all-day data item and all the data items whose duration is equal or greater than a usual day (1440 minutes) on the secondary sheet only:

new ColumnView({
  itemToRendererKindFunc: function(item){
    return item.allDay ||
      this.dateFuncObj.difference(item.startTime, item.endTime, "minute") > 1440 ? "null" : "vertical";
    },
  secondarySheetProps: {
    itemToRendererKindFunc: function(item){
      return item.allDay ||
        this.dateFuncObj.difference(item.startTime, item.endTime, "minute") > 1440 ? "horizontal" : null;
    }
  }
});

The default function behavior on the MatrixView is:

• If the data item duration is equal or greater than a usual day (1440 minutes), use a horizontal item renderer,
• otherwise use a label item renderer.

You can customize this behavior to show only horizontal item renderers, for example:

new MatrixView({
  itemToRendererKindFunc: function(item){
    return "horizontal";
  }
}, null);

Grid cell styling

The grid cells can be customized either by using CSS or programmatically.

Each cell of the calendar has some CSS classes depending on the date/time it displays:

• "Sun", "Mon", "Tue", "Wed", "Thu", "Fri" or "Sat", depending on the day of week,
• "H0" to "H23" according to the time of day (Column view only).
• "Mxx" where xx is the minutes part of the time of day (Column view, depends on the the slot duration).

The following example specifies CSS classes to grey out Wednesdays and the time range between 12pm and 2pm for other days of week:

.dojoxCalendar .dojoxCalendarGrid .Wed,
.dojoxCalendar .dojoxCalendarGrid .H12,
.dojoxCalendar .dojoxCalendarGrid .H13        {
  background-color: #F8F8F8 !important;
}

For more advanced use cases, each view provides a styleGridCellFunc property that allows to customize a grid cell without subclassing a view.

The following example show how to install a CSS class to grey out Wednesdays and the time range between 12pm and 2pm for other days of week:

.greyCell{
  background-color: #F8F8F8 !important;
}

calendar.columnView.set("styleGridCellFunc", function(node, date, hours, minutes){
  // grey out Wednesday & time range between 12pm and 2pm
  if(hours >= 12 && hours < 14 || date.getDay() == 3){
    domClass.add(node, "greyCell");
  }
  this.defaultStyleGridCell(node, date, hours, minutes);
});

var func = function(node, date){
  // grey out Wednesdays
  if(date != null && date.getDay() == 3){
    domClass.add(node, "greyCell");
  }
  this.defaultStyleGridCell(node, date);
};
calendar.columnView.secondarySheet.set("styleGridCellFunc", func);
calendar.matrixView.set("styleGridCellFunc", func);
calendar.monthColumnView.set("styleGridCellFunc", func);

Item renderer overlap

When two item renderers are overlapping in time, the item renderers can either be displayed side by side (no overlap) or can overlap visually horizontally (vertical item renderers) or vertically (horizontal item renderers).

Note that the label item renderers cannot overlap visually.

To specify the overlap, set the percentOverlap property. A 0 value means no overlap, 50 means an overlapping of the half of item renderer size.

The following images show two overlapping events that are displayed by vertical item renderer. The first one shows a percentOverlap of 70%, the second on a percentOverlap of 0%.

Layout priority

During the layout process, the data items that are in the displayed time range are sorted according to the following comparison function:

• Data items that start first are placed first,
• If two data item have the same start time, the longest is placed first.

These simple rules allow to have nice looking layout when data items are overlapping in time.

If you want to change this data item layout priority management, set a sorting function to the layoutPriorityFunction. One use case is to build a sort function based on a priority value set on the data item itself.

Renderers

The renderer classes (item renderer and others) are not set by default on the views.

The calendar widget is setting the default renderers classes to the views. If a view is used alone, the renderers must be set explicitly.

Properties

The displayed time interval is defined by the startDate and columnCount properties. It is columnCount days from the startDate.

The time of day displayed is defined by the minHours (8 by default) and maxHours (18 by default) properties. For example to show the entire day set minHours to 0 and maxHours to 24.

The desired size of an hour is defined in the hourSize property (100 by default). According to the value of time slot duration, the size may be slightly bigger.

The time slot duration can defined defined by setting the timeSlotDuration property (15 by default). For example, to show only half hours set the timeSlotDuration to 30.

The scroll position can be retrieved or set using the startTimeOfDay property. The value is an objet containing the following properties:

• hours - The hours part of the time of day,
• minutes - the minutes part of the time of day,
• duration (setter) - the scroll animation duration to scroll from the minHours to the maxHours. The actual duration is computed according to the distance to scroll in order to scroll always at the same speed.
• easer (setter) - if duration is greater than 0, the easing function to use to animate the scroll.

For example to programmatically scroll the view to 9 am using an animation, use the following code:

columnView.set("startTimeOfDay", {hours:9, duration:1000});

The columns view is using a scroll bar, in right-to-left display, you can define the position of the scroll bar with respect to the sheet by setting the scrollBarRTLPosition property. Values are “left” (default) and “right”.

Row Header

The following properties allow to have a fine grained configuration of the row header:

• rowHeaderGridSlotDuration (60) - The duration of a slot for the row header grid.
• rowHeaderLabelSlotDuration (60) - The duration of a slot of the row header labels.
• rowHeaderLabelOffset (2) - The offset in pixels of the labels from the top of the row header cell.
• rowHeaderFirstLabelOffset (2) - The offset in pixels of the first label from the top of the first row header cell.

Using these properties, you can show a line every 15 minutes, a label every 30 min and center the label on the line (depend on font and font size) excepting the first one to be able to see it.

new ColumnView({
  rowHeaderGridSlotDuration: 15,
  rowHeaderLabelSlotDuration: 30,
  rowHeaderLabelOffset: -7
}, colViewNode);

Sub columns

The column can display several sub columns in a column displaying a day.

This is useful to show several calendars for example.

colView.set("store", new Memory({data:[
  {
    summary: "My Event",
    startTime: new Date(2013, 0, 1, 10, 0),
    endTime: new Date(2013, 0, 1, 14, 0),
    calendar: "cal1"
  }
]});

colView.set("subColumns", ["cal1", "cal2"]);

colView.set("subColumnLabelFunc", function(v){
  if(v == "cal1"){ return "Calendar 1"; }
  if(v == "cal2"){ return "Calendar 2"; }
  return null;
});

var createItem = function(view, d, e, subColumn){

  // create item by maintaining control key
  if(!e.ctrlKey || e.shiftKey || e.altKey){
    return;
  }

  var start, end;
  var colView = calendar.columnView;
  var cal = calendar.dateModule;

  if(view == colView){
    start = calendar.floorDate(d, "minute", colView.timeSlotDuration);
    end = cal.add(start, "minute", colView.timeSlotDuration);
  }else{
    start = calendar.floorToDay(d);
    end = cal.add(start, "day", 1);
  }

  var item = {
    id: id,
    summary: "New event " + id,
    startTime: start,
    endTime: end,
    allDay: view.viewKind == "matrix",
    calendar: subColumn
  };

  id++;

  return item;
}

calendar.set("createOnGridClick", true);
calendar.set("createItemFunc", createItem);

Layout

In addition to the properties defined in the common section, the column view also exposes the horizontalGap property (default is 4).

This value is used to specify the gap in pixels between each overlapping renderer if percentOverlap is 0.

Renderers

The column view is using several renderers:

• vertical item renderers to show the data items in the main sheet.
• horizontal item renderers and expand renderers for secondary sheet.

The vertical item renderer class can be set on the verticalRenderer property.

The secondary sheet is a custom matrix view, see matrix view renderers for more information on the horizontal and expand renderers.

Styling

The styling of a column view is defined in the themes/claro/ColumnView.css and themes/claro/ColumnView_rtl.css. The base CSS class name is dojoxCalendarColumnView.

The styling of a simple column view is defined in the themes/claro/SimpleColumnView.css and themes/claro/SimpleColumnView_rtl.css. The base CSS class name is dojoxCalendarSimpleColumnView.

Several functions are provided to style or set a style class on part of the view:

• styleColumnHeaderCell(node, date, renderData): allows to style a column header cell. By default, it installs dojoxCalendarToday and dojoxCalendarWeekend CSS classes.
• styleRowHeaderCell(node, hour, renderData): allows to style a row header cell. By default, does nothing.
• styleGridCell(node, date, hours, minutes, renderData): allows to style a grid cell. By default, it installs dojoxCalendarToday and dojoxCalendarWeekend CSS classes.

The styleGridCellFunc property allows to customize a grid cell without subclassing a view.

Date formatting

To change the default formatting of the a label, one can:

• set a custom date pattern in a dedicated property or
• override the function that formats the date.

The properties and function used by the column view are described in the following table:

Properties

The displayed time range is defined by the startDate, columnCount and rowCount properties. The time range is columnCount x rowCount days from the startDate.

The refStartTime and refEndTime can be used to define a time range of interest. This time range must be included in the displayed time range. It allows to show days out of the time range of interest by greying their cells.

Expanded row

The matrix view can have one row expanded to show mode data items on this particular row (usually a week).

The following functions are available on the matrix view to manage this feature:

Renderers

The matrix view is using several renderers:

• horizontal item renderers (horizontalRenderer property) to display data items that last at least a day,
• label item renderers (labelRenderer property) to display the other data items.
• expand renderer (expandRenderer property), which indicates visually that some data items are visibles on a cell.

Horizontal item renderers are placed and sized according to the start and end time of the data item.

Label items renderers a placed in a cell and takes the cell width. They cannot overlap and cannot be resized.

Layout

The matrix view has several layout properties.

The roundToDay property (default true), indicates that horizontal items renderers that represent events whose start or end time is not the start or end of a day should fill the cells that they are overlapping.

The two following images show the same data items that starts at 8 am and finishes at the end of the next day. This first one shows the result when the roundToDay property is true and the next one is this property is false.

This property can also be set to false, if all the data items are displayed using horizontal items renderers (see itemToRendererKindFunc property).

The size of the renderers are defined by the following properties:

In addition all the renderers shifted vertically of the value of the cellPaddingTop property (16 by default) to show the cell header.

Styling

The styling of a matrix view is defined in the themes/claro/MatrixView.css and themes/claro/MatrixView_rtl.css.

The base CSS class name is dojoxCalendarMatrixView.

Several functions are provided to style or set a style class on part of the view:

• styleColumnHeaderCell(node, date, renderData): allows to style a column header cell. By default, it installs dojoxCalendarWeekend CSS classes.
• styleRowHeaderCell(node, hour, renderData): allows to style a row header cell. By default, does nothing.
• styleGridCell(node, date, renderData): allows to style a grid column. By default, it installs dojoxCalendarToday, dojoxCalendarWeekend and dojoxCalendarDisabled CSS classes.

The styleGridCellFunc property allows to customize a grid cell without subclassing a view.

Date formatting

To change the default formatting of the a label, one can:

• set a custom date pattern or a custom format length in a dedicated property or
• override the view function that formats the date.

The properties and function used by the column view are described in the following table:

Properties

The displayed time interval is defined by the startDate and columnCount properties. It is columnCount months from the first day of month defined by the startDate.

The desired size of a day is defined by the daySize property (30 by default).

The scroll position can be retrieved or set using the scrollPosition property. The value is an objet containing the following properties:

• date - The scroll position in day,
• duration (setter) - the scroll animation duration to scroll from the minHours to the maxHours. The actual duration is computed according to the distance to scroll in order to scroll always at the same speed.
• easer (setter) - if duration is greater than 0, the easing function to use to animate the scroll.

For example to programmatically scroll the view to the 10th using an animation, use the following code:

monthColumnView.set("scrollPosition", {position:10, duration:1000});

The month columns view is using a scroll bar, in right-to-left display, you can define the position of the scroll bar with respect to the sheet by setting the scrollBarRTLPosition property. Values are “left” (default) and “right”.

Layout

In addition to the properties defined in the common section, the month column view also exposes the horizontalGap property (default is 4).

This value is used to specify the gap in pixels between each overlapping renderer if percentOverlap is 0.

The hidden data items grid cell decoration can be not displayed by setting the showHiddenEvents property.

Renderers

The month columns view is only using item vertical renderers.

The vertical item renderer class can be set on the verticalRenderer property.

Styling

The styling of a month columns view is defined in the themes/claro/MonthColumnView.css and themes/claro/MonthColumnView_rtl.css. The base CSS class name is dojoxCalendarMonthColumnView.

Several functions are provided to style or set a style class on part of the view:

• styleColumnHeaderCell(node, date, renderData): allows to style a column header cell.
• styleGridCell(node, date, renderData): allows to style a grid cell. By default, it installs dojoxCalendarToday and dojoxCalendarWeekend CSS classes.

In an additional layout pass, the dojoxCalendarHiddenEvents CSS class is installed on grid cells if they are hidden data items in the corresponding date.

The styleGridCellFunc property allows to customize a grid cell without subclassing a view.

Date formatting

To change the default formatting of the a label, one can:

• set a custom date pattern in a dedicated property or
• override the function that formats the date.

The properties and function used by the column view are described in the following table:

Introduction

The calendar allows to interactively move or resize a data item.

Steps

The data item editing process is going through the following steps:

• The editing is initialized by a user interaction, the widget is entering in edit mode.
• The user is doing some move gestures or/and some resize gestures.
• The user validate or cancel the changes, the widget is leaving edit mode.

There are some specifics depending on the device used:

• Using the mouse: only one gesture (move or resize) per editing.
• Using touch events: cancellation is not possible (possible future improvement).

Editing flags

The editable property allows to globally enable or disable the editing capability of the widget.

If the editable property is true, the moveEnabled and resizeEnabled properties allow to control respectively if a data item can be moved or resized.

To have a control of editing, move or resize at the data item level, override respectively the isItemEditable(), isItemMoveEnabled() or isItemResizeEnabled() functions of the Calendar class.

The following example shows how to subclass the Calendar to override these functions to:

• allow resize of a data item if "editable" and "resizeEnabled" properties of the data item are resolved as true,
• allow move of a data item if "editable" and "moveEnabled" properties of the data item are resolved as true.

#calendarNode {
  position:absolute;
  left: 10px;
  right: 10px;
  top: 10px;
  bottom: 10px;
}

// subclass Calendar class
var ECalendar = declare("extended.Calendar", Calendar, {

  isItemEditable: function(item, rendererKind){
    return item.editable;
  },

  isItemResizeEnabled: function(item, rendererKind){
    return this.isItemEditable(item, rendererKind) && item.resizeEnabled;
  },

  isItemMoveEnabled: function(item, rendererKind){
    return this.isItemEditable(item, rendererKind) && item.moveEnabled;
  }
});

var calendar = new ECalendar(null, "calendarNode");

<div id="calendarNode"></div>

Editing behavior properties

To customize the event editing behavior, a set of properties are exposed by the views.

For example to change the minimal duration of an event to 30 minutes.

calendar.columnView.set("minDurationSteps", 30);
calendar.columnView.set("minDurationUnit", "minute");

Editing event handlers

In some advanced use cases, the editing properties are not sufficient, the editing events are used to have a specific behavior.

These events are listed in the following table:

All the editing events have the following properties:

• item: an object that contains the start and end time during the event editing in the startTime and endTime properties. When the data item is moved or resized, new start and end time values are computed and put in these properties. The itemEditMoveGesture and itemEditResizeGesture default event handlers are then manipulating these properties to apply snapping, limits etc according to the editing properties values.
• storeItem: The data item that is being edited. This object must not be changed excepting in itemEditEnd event.

To prevent the editing default behavior applied by the calendar, call in your handler of the item editing event preventDefault().

The following example is cancelling the editing gesture when the data item has a specific property and its start time is after 1pm (included)

var ss, se;
calendar.on("itemEditBegin", function(e){
  // save initial values
  ss = calendar.newDate(e.item.startTime);
  se = calendar.newDate(e.item.endTime);
});

calendar.on("itemEditEnd", function(e){
  // a condition using properties of the store item and the render item
  if(e.storeItem.calendar == "cal2" && e.item.startTime.getHours() >= 13){
    // cancel default behavior (i.e. applying changes to store)
    e.preventDefault();

    // set the previously values to revert changes on the render item
    e.item.startTime = ss;
    e.item.endTime = se;
  } // default behavior for other use cases
});