ScheduleWidget Tutorial 1

Tags: ScheduleWidget

Jun 20 2012 11:41 PM

A few days ago I announced the release of ScheduleWidget, a scheduling engine that handles recurring events for calendars. Now I'd like to do a simple introductory tutorial to show how to use it. Consider the Critical Mass bicycle event, which happens in many major cities on the last Friday of every month. Given that information we want ScheduleWidget to provide us with the upcoming dates of the event.

First, fire up a typical MVC 3 web application. Create a HomeController with a single Index action method. Add ScheduleWidget NuGet package to your Visual Studio project. (If you're brand spankin' new to NuGet see the Getting Started Guide for more information.) Every recurring schedule requires an Event object to initialize the schedule. So add this to your Index method:

// using ScheduleWidget.Enums;
// using ScheduleWidget.ScheduledEvents;
var aEvent = new Event()
{
    ID = 1,
    Title = "Critical Mass",
    FrequencyTypeOptions = FrequencyTypeEnum.Monthly,        
    MonthlyIntervalOptions =  MonthlyIntervalEnum.Last, 
    DaysOfWeekOptions = DayOfWeekEnum.Fri
};

ID and Title are optional but if you're fetching events from a database then you're probably going to want to track that information. So we have our event. Now we need to pass it into a Schedule:

var schedule = new Schedule(aEvent);

It doesn't get any easier than that. Now the Schedule has all the information it needs to answer questions like "when's the next ride?" or "what are the dates going out a year?" Let's answer that second question. The Schedule class has a method called Occurrences which returns a list of dates for any date range you give it. Here's how it looks:

var range = new DateRange()
{
    StartDateTime = DateTime.Now,
    EndDateTime = DateTime.Now.AddYears(1)
};

var occurrences = schedule.Occurrences(range);

That's all there is to it. Of course our Index method has to return the dates to our View. So here's the entire Index method with everything we've discussed to this point:

public ActionResult Index()
{
    var aEvent = new Event()
    {
        ID = 1,
        Title = "Critical Mass",
        FrequencyTypeOptions = FrequencyTypeEnum.Monthly,        
        MonthlyIntervalOptions =  MonthlyIntervalEnum.Last, 
        DaysOfWeekOptions = DayOfWeekEnum.Fri
    };

    var schedule = new Schedule(aEvent);
    var range = new DateRange()
    {
        StartDateTime = DateTime.Now,
        EndDateTime = DateTime.Now.AddYears(1)
    };

    var occurrences = schedule.Occurrences(range);
    return View(occurrences);
}

If you haven't done so already add a View and display the upcoming rides:

@model IEnumerable<DateTime>
@{
    ViewBag.Title = "Index";
}

<p><strong>Critical Mass Rides</strong></p>
<p><em>Occurs the last Friday of every month</em></p>

@foreach(var date in Model)
{
    @date.ToShortDateString()<br />
}

Run the MVC app and you should see something like this:

5 Comments

  • Chris said

    ScheduleWidget is a great tool. Thank you! I'm having an issue with the DaysOfWeekOptions. I want to pass a list or array of days to the event and enumerate them dynamically. It works when I hard code: DaysOfWeekOptions = DayOfWeekEnum.Mon | DayOfWeekEnum.Wed | DayOfWeekEnum.Fri But I want to pass the DaysOfWeek dynamically. I can't wrap my head around how to enumerate a list or array. Can you help point me in the right direction? Thanks again for a great tool.

  • Chris Scharf said

    Disregard my last comment! I hammered out the answer myself. I found that using DaysOfWeek instead of DaysOfWeekEnum allows me to use the binary representation of the DaysOfWeek that I already had set up. I'm liking it more and more as I dig deeper.

  • James said

    Hi Chris and thanks for pointing out a gap in my documentation. As you say it's not necessary to use the DayOfWeekEnum if you already know the bit flag attribute value. In my own projects I store the int value in the database and assign it to the DaysOfWeek property instead: /* Sun = 1 Mon = 2 Tue = 4 Wed = 8 Thu = 16 Fri = 32 Sat = 64 */ var aEvent = new Event() { FrequencyTypeOptions = FrequencyTypeEnum.Weekly, DaysOfWeek = 42 // Mon, Wed, Fri }; Enjoy!

  • Chris Scharf said

    James - I ran into something with ScheduleWidget that got me curious. I'll copy directly from the comments in my code: //ScheduleWidget defines Interval as first, second, third, fourth, last week of the month. However MSDN defines Interval as the number of weeks, months or years that an event recurrs and Instance as the first, second, third etc week of the month. Is this a case of MS defining their own standard apart from a more generalized standard described in Fowler's white paper? Was it an oversight on your part? I'm passing my Instance to ScheduleWidget and using it in the MonthlyIntervalOptions. It's not a big deal at all. I just wanted to point out the disparity in case you're interested. Chris

  • Dan said

    Love the widget. My only real need that seems to be missing is an every other week interval. Am working with custody schedules.

Add a Comment