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

UI Appearance

Animations

Customizing Calendar

Data Management

3D Touch

User Input Handling

Enabling RTL

Miscellaneous

Configurations common to all widgets

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.