You are here: Creating a Calendar Using a Constructor: voltmx.ui.Calendar

Calendar Widget

Calendar widget is used to select and display dates in your application. Some scenarios in which you can leverage the features of a Calendar widget are as follows:

• To select a range of dates for scheduling a trip or for insurance claims
• To show the tasks performed by a field service agent in the form of a grid, for any given date.

Here are some of features of the Calendar widget:

From Volt MX Iris V9 SP2, the Calendar widget is enhanced with a new look in Iris. Users can now select the year and month using the drop-down list. Prior to V9 SP2, users had to click on the Calendar icon and then click on the month/year to display the list. Further, users had to continue to choose the month and year from a grid view and then confirm the month/year after selecting the options.

Note: This feature is applicable only on the latest CSS lib.

Customizing Cells: Personalize the various cells inside a Calendar widget. This feature allows you to customize how you want to display the selected dates, un-selected dates, and other facets of a calendar.

Setting the Location: Customize where the calendar popup should appear in an app. For instance, in a banking app, you can set the location of the Calendar popup while selecting the date of transaction.

Enabling a Range of Dates: Enable a range of dates by just setting the start date and end date. For example, in a travel application, you can use this feature to display the duration of your stay while booking a hotel.

Widgets are normally added to your application using Volt MX Iris, but can also be added from code. For general information on using widgets in Iris, see Designing an Application in the Iris User Guide.

For general information on this widget see the Calendar topic in the Volt MX Iris User Guide.

The Calender widget capabilities can be broadly categorized into the following:

• Layout
• UI Appearance
• Animations
• Customizing Calendar
• Data Management
• 3D Touch
• User Input Handling
• Enabling RTL
• Miscellaneous
• Configurations common to all widgets

Layout

Events	Description
doLayout	Invoked for every widget when the widget position and dimensions are computed.

Properties	Description
anchorPoint	Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space.
bottom	Determines the bottom edge of the widget and is measured from the bottom bounds of the parent container.
centerX	Determines the center of a widget measured from the left bounds of the parent container.
centerY	Determines the center of a widget measured from the top bounds of the parent container.
containerHeight	Available only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or CALENDAR_VIEW_TYPE_GRID_ONSCREEN.
containerHeightReference	Available only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or CALENDAR_VIEW_TYPE_GRID_ONSCREEN and when you set the containerHeight.
contentAlignment	Specifies the alignment of the text for a widget with respect to its boundaries.
height	Determines the height of the widget and measured along the y-axis.
maxHeight	Specifies the maximum height of the widget and is applicable only when the height property is not specified.
maxWidth	Specifies the maximum width of the widget and is applicable only when the width property is not specified.
minHeight	Specifies the minimum height of the widget and is applicable only when the height property is not specified.
minWidth	Specifies the minimum width of the widget and is applicable only when the width property is not specified.
padding	Defines the space between the content of the widget and the widget boundaries.
paddingInPixel	Indicates if the padding is to be applied in pixels or in percentage.
right	Determines the lower right corner of the widget and is measured from the right bounds of the parent container.
top	Determines the top edge of the widget and measured from the top bounds of the parent container.
width	Determines the width of the widget and is measured along the x-axis.
zIndex	Specifies the stack order of a widget.

UI Appearance

Properties	Description
backgroundColor	Specifies the background color of the widget in hex format.
backgroundColorMultiStepGradient	Specifies the multi-step gradient color for the background of the widget.
backgroundColorTwoStepGradient	Specifies the two-step gradient color for the background of the widget.
backgroundImage	Sets the image for the background of the widget.
borderColor	Specifies the border color of the widget.
borderColorGradient	Specifies the multi-step gradient color for the border of the widget.
borderStyle	Specifies the border style for the widget.
borderWidth	Specifies the width of the border for the widget in pixels.
cornerRadius	Specifies the radius of the border for the widget.
disabledStateSkinProperties	Specifies the skin properties that define the look and feel of the widget, when the widget is disabled or blocked.
focusStateSkinProperties	Specifies the skin properties that define the look and feel of the widget, when the widget is in focus.
fontColor	Specifies the font color of the widget.
fontFamily	Specifies the font family for the font of the widget.
fontSize	Specifies the font size for the widget in percentage (%) units.
fontStyle	Specifies the font style for the widget.
fontWeight	Specifies the weight for the font of the widget.
hoverStateSkinProperties	Specifies the skin properties that define the look and feel of the widget, when the cursor hovers on the widget.
pressedStateSkinProperties	Specifies the skin properties that define the look and feel of the widget, when the widget is pressed or clicked.
shadowColor	Specifies the color for the shadow of the widget.
shadowOffset	This property specifies the current coordinates of the shadow region in the widget.
shadowRadius	Specifies the radius for the blur value of the shadow.
textShadowColor	Specifies the color for the text shadow of the widget.
textShadowOffset	This property specifies the current coordinates of the text shadow region in the widget.
textShadowRadius	Specifies the radius for the blur value of the text shadow.
focusSkin	Skin property that determines the look and feel when there is focus on a widget.
headerSkin	Used to provide a header for the DatePicker skin, if headerText is set.
hoverSkin	Specifies the look and feel of a widget when the cursor hovers on the widget.
skin	Specifies a background skin for Calendar.
timeSheetSkin	Specifies each cell color of the timesheet view when the calendar view type it set as CALENDAR_VIEW_TYPE_MONTH_VIEW.
viewConfig	Specifies the view configuration for different view types.
viewType	Specifies the view type of the Calendar.

Methods	Description
setDatesSkin	Allows you to set the skin and control the look and feel of each cell in the calendar.

Animations

Methods	Description
animate	Applies an animation to the widget.

Properties	Description
transform	Contains an animation transformation that can be used to animate the widget.
widgetSwipeMove	Used to enable and configure the left or right swipe actions for a widget.

Customizing Calendar

Methods	Description
open	Allows you to open the Calendar widget's popup view dynamically.
setContext	Specifies the calendar that must be displayed for the context and also helps you to position the calendar on the screen.
dismiss	Allows you to dismiss the calendar widget's popup view on which the method is called.
enableRangeOfDates	Allows you to enable/disable the range of dates that fall between the startdate and enddate and disables/enables the rest of the dates.
getAppointments	Used to get the appointments from the calendar view types.
navigateToNextMonth	Allows you to navigate to next month of the calendar widget.
navigateToPreviousMonth	Allows you to navigate to previous month of the calendar widget
switchToDate	Used to switch date from the calendar view types.

Properties	Description
calendarIcon	Replaces the system default calendar icon.
calendarIconAlignment	Determines the position of the calendar icon inside the calendar input box.
calendarLanguage	Used to provide a languagefor the DatePicker.
dateComponents	Specifies the default date that must appear in the Date field.
dateEditable	Determines whether the calendar date must be entered in the calendar textbox.
dateFormat	The date format in which the selected date must appear on the display and when accessed programmatically the "date" property.
day	Reads the day portion of the currently selected date.
dayTextAlignmentInCell	Available only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or CALENDAR_VIEW_TYPE_GRID_ONSCREEN.
displayedMonth	Applicable only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or CALENDAR_VIEW_TYPE_GRID_ONSCREEN.
gridTheme	Used to change the pre-defined CSS of a calendar widget.
formattedDate	Currently selected data as String the format that is set through "dateFormat" property.
hideDaysHeader	It indicates if the weekdays are hidden on the header for grid calendar.
hideMonthsHeader	It indicates if the months header is hidden for grid calendar including the navigation buttons.
hidePreviousNextMonthDates	Specifies the visibility of the previous and next months in a calendar.
hour	Reads the hour portion of the currently selected date.
isDayVisible	Specifies whether the Day combo box of the DatePicker is visible.
isMonthVisible	Specifies whether the Month combo box of the DatePicker is visible.
isYearVisible	Specifies whether the Year combo box of the DatePicker is visible.
minutes	Reads the minutes portion of the currently selected date.
month	Reads the month portion of the currently selected date.
noOfMonths	Specifies the number between 1 and 12 which indicates the number of months to be displayed when the calendar is selected.
seconds	Reads the seconds portion of the currently selected date.
validEndDate	Array representing the day, month and year portions of the date in the same order.
validStartDate	Array representing the day, month, and year portions of the date in the same order.
wheelBackgroundColor	Specifies the background color for the wheel that is displayed when you click the Calendar.
year	Reads the year portion of the currently selected date.

Data Management

Methods	Description
clone	When this method is used on a container widget, all the widgets inside the container are cloned.
clear	Enables you to clear the date in the calendar and the date format is shown.
clearAppointments	Used to clear existing appointments from the calendar view types.
clearData	Allows you to remove the data that is set through setData method.
deleteAppointments	Allows you to delete existing appointments or array of string consisting of unique ids that represent each appointment to any of the calendar scheduler views.
modifyAppointment	Allows you to modify the existing appointment with new appointment.
removeDataAt	Allows you to remove data set in a specific argument.
setData	Allows you to set new data to the widgets as specified in the widgetDataMap.
setDataAt

Properties	Description
data	JS Objects that represents the actual data to be rendered in each cell.
inputAccessoryViewType	The extra buttons (or controls) allow specific operations needed by your application, such as moving to the next or previous text field, making the keyboard disappear and so on. The area above the keyboard is known as Input Accessory View
widgetDataMapForCell	Specifies the mapping information between the widget id's and the keys in the data.

3D Touch

Methods	Description
registerForPeekandPop	Registers a widget to enable 3D Touch peek and pop gestures.
setOnPeek	Sets and overrides the existing onPeekCallback for the widget.
setOnPop	Overrides the existing onPopCallback for the widget.
unregisterForPeekandPop	Unregisters a widget from 3D Touch peek and pop gestures.

User Input Handling

Events	Description
onAppointmentTap	Triggered when you tap any of the existing appointments
onEmptyCellTap	Triggered when you tap on any of the empty cells of the calendar day view.
onScrollWidgetPosition	This event callback is invoked by the platform when the widget location position gets changed on scrolling.
onSelection	This event is triggered when an item is selected or deselected.
onTouchEnd	An event callback is invoked by the platform when the user touch is released from the touch surface.
onTouchMove	An event callback is invoked by the platform when the touch moves on the touch surface continuously until movement ends.
onTouchStart	An event callback is invoked by the platform when the user touches the touch surface.

Methods	Description
addGestureRecognizer	Allows you to set a gesture recognizer for a specified gesture for a specified widget.
removeGestureRecognizer	Allows you to remove the specified gesture recognizer for the specified widget.
setGestureRecognizer	Allows you to set a gesture recognizer for a specified gesture for a specified widget.

Properties	Description
selectedDates	Specifies the array of dates selected when multiple dates are selected.
selectionType	Specifies the method of date selection in a Calendar widget.

Enabling RTL

Properties	Description
retainContentAlignment	Helps to retain the content alignment of the widget while applying RTL.
retainFlexPositionProperties	Helps to retain the left, right and padding properties while applying RTL.
retainFlowHorizontalAlignment	Enables you to change the horizontal flow of the widget from left to right.

Miscellaneous

Methods	Description
getBadge	Enables you to read the badge value (if any) attached to the specified widget.
setBadge	Enables you to set the badge value to the given widget at the upper, right corner of the widget.

Properties	Description
cellTemplate	Available only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or CALENDAR_VIEW_TYPE_GRID_ONSCREEN.
cursorType	Specifies the type of the mouse pointer used.
titleOnPopup	Specifies the title text to be displayed on the calendar popup.
toolTip	Specifies the hint text when the cursor hovers over a widget, without clicking it.

Configurations common to all widgets

Methods	Description
blur	Enables you to make the widget look unfocused.
convertPointFromWidget	Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system).
convertPointToWidget	You can convert the receiver's co-ordinate system from a point to a Widget.
removeFromParent	Allows you to remove a child widget from a parent widget.
setEnabled	Allows you to enable/disable a list of dates if the startdate and enddate are not set in the calendar, then this API is used to enable/disable any date in the calendar.
setEnabledAll	Allows you to enable all the dates that fall between the startdate and enddate.
setFocus	Specifies the widget on which there must be focus.
setVisibility	Use this method to set the visibility of the widget.

Properties	Description
accessibilityConfig	Enables you to control accessibility behavior and alternative text for the widget.
enable	Allows you to make a widget visible but not actionable.
enableOrDisable	Allows you to enable or disable the list of given dates when the calendar is shown.
id	Defines a string of alpha numeric characters that uniquely identifies a calendar widget within an application.
info	A custom JSObject with the key value pairs that a developer can use to store the context with the widget.
isVisible	Controls the visibility of a widget on the form.

Calendar Widget Basics

The calendar widget allows you to select a date from a graphical calendar. The calendar widget appears as a label with a small calendar icon (icon does not appear on Mobile Web platforms) and displays the date or the date format specified by you. You can interact with the calendar widget by clicking on it.

When the calendar widget is clicked, a grid-like calendar is displayed The calendar allows you to select a single date and move back-and-forth between months and years.

The appearance is not the same on all platforms.

Note: When the native calendar view is used, the individual dates cannot be enabled or disabled using the setEnable API. Also, when you use native calendar view, you cannot restrict the user to select the dates within the validStartDate and validEndDate range.

Creating a Calendar Using a Constructor: voltmx.ui.Calendar

var mycal = new voltmx.ui.Calendar(basicConf, layoutConf, pspConf);

• basicConf is an object with basic properties.
• layoutConf is an object with layout properties.
• pspConf is an object with platform specific properties.

Note: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored.

Example

//The below function is the callback function for onSelection event
function onSelectionCallBck(calendar) {
    alert("onSelection event triggered");
}

//Defining the properties for Calendar with onSelection:onSelectionCallBck
var calBasicConf = {
    id: "calID",
    isVisible: true,
    skin: "voltmxtextar",
    focusSkin: "calFocus",
    dateFormat: "dd/MM/yyyy",
    viewType: constants.CALENDAR_VIEW_TYPE_GRID_POPUP,
    validStartDate: [01, 01, 2012],
    validEndDate: [31, 12, 2012],
    placeholder: "JSCalendar",
    calendarIcon: "cal.png",
    onSelection: onSelectionCallBck
};

var calLayoutConf = {
    padding: [2, 2, 2, 2],
    margin: [5, 5, 5, 5],
    containerWeight: 100,
    hExpand: true,
    vExpand: true
};

var calPSPConf = {
    titleOnPopup: "calendarPopUpTitle"
};

//Creating the Calendar.
var Calendar = new voltmx.ui.Calendar(calBasicConf, calLayoutConf, calPSPConf);

//Reading the titleOnPopup property of calendar widget
alert("Calendar titleOnPopup ::" + Calendar.titleOnPopup);

Customizing Appearance

You can customize the appearance of the calendar widget using the following properties:

• widgetAlignment: Specifies the alignment of the widget.
• margin: Defines the space around a widget.
• padding: Defines the space between the content of the widget and the widget boundaries.
• skin: Specifies the skin.
• focusSkin: Specifies the focus skin.

Important Considerations

The Calendar widget has the following important considerations:

• On Android platform, restricting the date selection between validStartDate and validEndDate is not possible with Native Calendar View.
• On Android, when targeting older versions (5.0 through 6.0) the top label of the Calendar Widget may show duplicate data. This is an issue with the native behavior for the Android platform. It has been resolved in later versions of the OS (7.1 and later).
• On Desktop Web and SPA platforms, a valid calendar year selection range is from 1900 to 2099. If you select an year beyond the range shows an alert message (you can customize this error message).

DatePicker control

A new calendar control, the DatePicker, is available in Windows platform. Create this control using the Calendar viewType property value CALENDAR_VIEW_TYPE_DATEPICKER.

Calendar DatePicker native control popup

Limitations and Considerations for DatePicker Control

• This control is supported in Windows 10 only.
• This control does not support HExpand and VExpand.
• This control does not support ContentAlignment.
• This control does not support WidgetAlignment.
• This control is a Pickerview. This view and its properties are not compatible with other calendar view types. Therefore, changing the viewType dynamically will not work.
• The constant CALENDAR_VIEW_TYPE_DATEPICKER may not be available in Volt MX Iris. Therefore, this view must be created dynamically using code.

gridcalendar Templates

The Calendar widget provides gridcalendar templates to give you further control of the contents of a calendar cell.

What is a Template for gridcalendar?

A gridcalendar template enables you to define a template for Calendar Day cell. Only one template can be used for each Calendar. This is primarily useful for developers to achieve a customized look and feel of a Calendar Day cell.

You can define a template using the following widgets:

• HBox (deprecated)
• VBox (deprecated)
• FlexContainer (new in Iris 7.3)
• Button
• Image
• Label

Where to use a gridcalendar Template

gridcalendar templates are used to achieve custom look and feel of Calendar Day cell.

The gridcalendar templates are used:

• To define a Calendar Day cell with custom look and feel.
• To achieve the behavior of widgets such as an Image and a label for a Calendar Day cell.
• To perform an onclick action on a Calendar Day cell.