A Deep Look at the New Xuni Calendar Control

The Xuni Calendar control provides multiple date selection with month and year views for iOS, Android and Xamarin app development. It includes built-in navigation, animation and globalization so you can get up and running very quickly. You can customize the appearance and the selection behavior to fit your requirements. The control also enables you to customize the day slots so you can visualize date information on the calendar like marking important dates with dots or images. This lightweight feature lets you do a lot more with the control beyond simple date selection. Xuni Calendar is part of a larger strategy that also includes a scheduler control which will come later. Rather than squeezing everything into one control, we decided to have two controls that serve different needs. Calendar is more light-weight and focused on month views with date selection and quick month to year navigation. The Scheduler control will have built-in appointment/event management and support day and week view scheduling. With Calendar you can visualize appointments/events on the control, but you have to manage the data and design the UI to handle this.

Working with a Basic Calendar

The key functionality provided by Xuni Calendar is date range selection and navigation. Here is a list of the key properties that enable you to configure the basic calendar functions.

• DisplayDate
• MaxDate
• MaxSelectionCount
• MinDate
• SelectedDate
• SelectedDates
• ViewMode

By default, the calendar will display the current month. You can programmatically set the initial display date by setting the DisplayDate property. You can control the range of selection by setting the MaxDate, MinDate and MaxSelectionCount properties. If you set MaxSelectionCount = -1 then the selection count is unlimited. Commonly used events that will listen to the user interacting with the control include:

• DisplayDateChanged
• DisplayDateChanging
• SelectionChanged
• SelectionChanging
• ViewModeChanged

A Calendar Control with Both Horizontal and Vertical Navigation

What makes Xuni Calendar unique is that you can match any popular calendar UI with either horizontal or vertical scrolling navigation. We took a look at popular calendar apps on Android, iOS and Windows and we found that there is no standard direction the calendars flow in. Some flow horizontally, some vertically. So rather than decide on one solution for everyone we decided to make horizontal and vertical scrolling the initial feature. The control doesn’t support both simultaneously. Typically you will decide one direction or the other for your app, but certainly you could switch it dynamically like we do in the Xuni Explorer demo. To change the navigation or scrolling direction you set the Orientation property.

Create a Styled Calendar that Matches Your App

Xuni Calendar has an extensive API with many properties that allow you to change the style and format of the calendar. Below is a list with some of those properties. Every text part of the control also has correlating font properties but I excluded them for brevity. Custom Appearance (Android)

• AdjacentDayTextColor
• BackgroundColor
• BorderColor
• BorderWidth
• DayBorderColor
• DayBorderWidth
• DayOfWeekBackgroundColor
• DayOfWeekTextColor
• DisabledTextColor
• HeaderBackgroundColor
• HeaderTextColor
• SelectionBackgroundColor
• SelectionTextColor
• ShowHeader
• ShowNavigationButtons
• TextColor
• TodayBackgroundColor
• TodayTextColor

We needed to provide a default header for the calendar, but we realize that there is no one header layout that will fit every app’s requirements, so we made it very easy to customize the header. For example, you can create your own custom header by hiding the built-in header (ShowHeader = False) and listening to the DisplayDateChanged event. Or if you just don’t like the built-in navigation buttons you can hide them by setting ShowNavigationButtons = False. Custom Header (Android) In addition to customizing the style, there are a couple key properties that allow you to quickly change the date formats used within the calendar.

• DayOfWeekFormat
• FirstDayOfWeek

The FirstDayOfWeek property is pretty self-explanatory. The DayOfWeekFormat property is a bit non-standard since common date/time format strings don’t cover day of week names. So we invented our own format system heavily inspired by standard .NET format strings. You can set the property to any of the three following strings to get the desired format.

• "d" - S, M, T, W, T, F, S
• "ddd" - Sun, Mon, Tue, Wed, Thu, Fri, Sat (default)
• "dddd" - Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

The globalization feature is built-in and it depends on the language of the device.

Customizing the Day Slot Content

If you need to display custom content within the day slots, you can do so by subscribing to the DaySlotLoading event and setting the DaySlot parameter to your custom day slot content. Xuni Calendar supports four different day slot templates:

• CalendarImageDaySlot – used to display an image on any days
• CalendarDetailDaySlot – used to display text and subtext on any days
• CalendarTextDaySlot – used to display just text on any days
• CalendarViewDaySlot – used to display a custom view on any days. This is only supported in Xamarin.Forms.

In code you will define one of these per day loading, and set its properties to define your custom content. Here is a C# example that shows how to work with one of these classes to customize the day slot content for today’s date. Note that we preserve the original date number text by setting the DayText property.

public void OnDaySlotLoading(object sender, CalendarDaySlotLoadingEventArgs e)  
{  
    if (e.Date == DateTime.Now)  
    {  
        daySlotWithImage = new CalendarImageDaySlot(e.Date);  
        daySlotWithImage.DayText = e.Date.Day.ToString();  
        daySlotWithImage.DayFontSize = 8;  
        daySlotWithImage.ImageSource = myImage;  
        e.DaySlot = daySlotWithImage;  
    }  
}  

You can find a complete iOS, Android or Xamarin.Forms sample named “Custom Content” in the Calendar101 project installed under Documents/Xuni or on GitHub. The Xamarin.Forms sample also shows how to define the UI in XAML so you can work with MVVM. The sample named “CalendarSample” shows this feature for Xamarin.Android and Xamarin.iOS. Custom Content (iOS)

Controlling the Selection to Prevent Users from Selecting Certain Dates

A common task you will need to do is restrict users from selecting special dates, like weekends or holidays. We made this possible by giving you complete control over the collection of selected dates in the SelectionChanging event.

private void OnSelectionChanging(object sender, CalendarSelectionChangingEventArgs e)  
{  
    foreach (var date in e.SelectedDates.ToArray())  
    {  
        if (date.DayOfWeek == DayOfWeek.Saturday || date.DayOfWeek == DayOfWeek.Sunday)  
            e.SelectedDates.Remove(date);  
    }  
}  

For example, you could force the user to select every Saturday when they select any one Saturday of the month. You can remove blacked-out dates from the collection before the UI updates so it appears as though it’s disabled. To make dates look like they’re disabled as well, you can do this in the DaySlotLoading event mentioned earlier. Example below.

{  
    if (e.Date == MyDisabledDate)  
    {  
        var daySlotWithText = new CalendarTextDaySlot(e.Date);  
        daySlotWithText.DayText = e.Date.Day.ToString();  
        daySlotWithImage.DayTextColor = Color.Gray;  
        e.DaySlot = daySlotWithImage;  
    }  
}  

You can find a more complete custom selection code sample named “Custom Selection” in the Calendar101 samples. Custom Selection (Android)

The Calendar101 Samples Show More Functionality

Browse the Calendar101 sample to find more code examples that show how to use Xuni Calendar as a date picker pop-up and how to customize the header. You can also browse live demos on the Xuni Explorer app available in the App Store and Google Play.