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 Quantum Visualizer V9SP3, the Calendar widget is enhanced with a new look in Visualizer. The following are some of the enhancements:
- Roboto-medium is the default font used in the widget.
- The bold format is removed for the text elements.
- The default background color for the skin of the widget is modified to Blue (#417ADE).
- The default skin color for selected Calendar elements is changed to Blue (#417ADE).
- The Left and Right navigation images re changed to White arrows. This is done to accommodate the new background color Blue.
- The Calender widget grid now has borders between the date cells. The color used is Light Grey shade.
- The Calender widget now has rounded corners.
- In the drop-down list, the space between Months and Years is re-adjusted to avoid clustered view.
From Quantum Visualizer V9 SP2, the Calendar widget is enhanced with a new look in Visualizer. 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 pop-up 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 Quantum Visualizer, but can also be added from code. For general information on using widgets in Visualizer, see Designing an Application in the Visualizer User Guide.
For general information on this widget see the Calendar topic in the Quantum Visualizer 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 | Allows you to set new data to the segment. |
| 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: kony.ui.Calendar
var mycal = new kony.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: "konytextar",
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 kony.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 platform, 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 Quantum Visualizer. 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 Visualizer 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.