brick-calendar

Provides a simple calendar UI widget.

Note that when the API works with datestrings, while it's best to pass in "YYYY-MM-DD" ISO strings to the calendar, the <brick-calendar> will also accept any string parseable by Date.parse(). However, be aware that browser implementations of Date.parse() may differ slightly.

Basic usage

Markup

<brick-calendar></brick-calendar>

Basic calendar with navigation controls

To add a simple set of navigation controls to the calendar, simply add the controls attribute to the <brick-calendar>

Markup

<brick-calendar controls></brick-calendar>

Initializing the viewport with view

While calendars default to focusing on the current day, by setting a date in the view attribute of the <brick-calendar>, users can specify the initial viewport of the calendar.

Markup

<brick-calendar view="2013-06-09" controls></brick-calendar>

Initializing selected dates with chosen/.chosen

While the user can directly select a date on the calendar, the calendar can also be initialized with a starting chosen date.

The chosen attribute is also accessible with the the .chosen property.

Markup

<brick-calendar chosen="2012-05-17" controls></brick-calendar>

Equivalent initial JavaScript

// assume calendar is already defined to be the
// <brick-calendar> DOM node
calendar.chosen = "2013-05-17";
// ...or...
calendar.chosen = "May 17, 2013";
// ...or...
// remember that Date() months start at 0, not 1
calendar.chosen = new Date(2013, 4, 17);

Allowing multi-selection with multiple

While the calendar defaults to only allowing one chosen date at a time, when the multiple attribute is applied, multiple dates can be chosen at once. (Try dragging the cursor around to paint over dates.)

In addition, this allows the chosen attribute to take more than one date. To do so, pass in a JSON string for an array whose elements are either: strings signifying single dates, or two-element arrays of strings signifying the start and end of a date range.

Important note: Because these must be JSON strings, make sure that all quoted strings in the attribute string are using double quotes, not single quotes!

If assigning to the calendar's .chosen property instead, the user can provide the actual array instead of a JSON string, and Date objects may be used instead of strings.

The multiple attribute is also accessible with the the .multiple property.

Markup

<brick-calendar multiple controls
       chosen='[["2013-06-04", "2013-06-10"], "2013-06-19", ["2013-06-29","2013-07-02"]]'>
</brick-calendar>

Equivalent initial JavaScript

// assume calendar is already defined to be the
// <brick-calendar> DOM node
calendar.chosen = '[["2013-06-04", "2013-06-10"], "2013-06-19", ["2013-06-29","2013-07-02"]]';
// ...or...
calendar.chosen = [["2013-06-04", "2013-06-10"], "2013-06-19", ["2013-06-29","2013-07-02"]];
// ...or...
// remember that Date() months start at 0, not 1
calendar.chosen = [[new Date(2013, 5, 4), new Date(2013, 5, 10)], 
                   new Date(2013, 5, 19), 
                   [new Date(2013, 5, 29), new Date(2013, 6, 2)]
                  ];

Preventing date selection with notoggle

By default, the <calendar> allows the user to select dates by clicking individual days.

However, if the notoggle attribute is provided, the calendar disables choosing dates through the interface. (This does not prevent developers from programmatically changing the chosen dates.)

This prevents datetoggleon and datetoggleoff events from being triggered normally through the interface, but datetap events are unaffected. (See events demo for details on these events)

Markup

<brick-calendar notoggle controls></brick-calendar>

Displaying multiple months with span

By default, the calendar only shows one month at a time, but by providing a number to the span attribute, the calendar can display as many months as the user needs.

The span attribute is also accessible with the the .span property.

Markup

<brick-calendar controls span=2></brick-calendar>

Changing the starting weekday with first-weekday-num/.firstWeekdayNum

By default, the calendar uses Sunday as the first day of the week. However, in many regions, this may not be the case, so the <brick-calendar> API provides the first-weekday-num attribute to change which day starts the week.

The number passed to first-weekday-num should be a number between 0 to 6, where 0=Sunday, 1=Monday, etc.

The first-weekday-num attribute is also accessible with the the .firstWeekdayNum property.

Markup

<brick-calendar controls first-weekday-num=1></brick-calendar>

Changing the calendar's labels with .labels

While the calendar defaults to using English labels, these labels can be edited by the user by editing the .labels property of the calendar.

When changing labels, the given data should be a JS object that can contain any of the following key:value pairs: 

{
            "prev": a string to display on the previous-month navigation button,
            "next": a string to display on the next-month navigation button,
            "months": an array of 12 strings, where the first string corresponds to January, the second to February, etc, all the way up to December.,
            "weekdays": an array of 7 strings, where the first string corresponds to Sunday, the second to Monday, etc, all the way up to Saturday.
          }

If the new data given does not have any of these keys, that corresponding particular label will remain unchanged.

For example, we can use this to provide a French-language calendar.

Markup

<brick-calendar controls first-weekday-num=1></brick-calendar>

JavaScript

var frenchCal = document.querySelector("brick-calendar[lang=fr]");
frenchCal.labels = {
    prev: "<<",
    next: ">>",
    months: ["janvier", "f\u00E9vrier", "mars", "avril", "mai", 
             "juin", "juillet", "ao\u00FBt", "septembre", "octobre", 
             "novembre", "d\u00E9cembre"],
    weekdays: ["dim", "lun", "mar", "mer", "jeu", "ven", "sam"]
};

Events demo

To provide API hooks for developers, the <brick-calendar> fires several different events as it is interacted with:

  • datetoggleon events are fired when a date is first chosen/turned on. This event also provides the following information in e.detail: 
    {
                  'date': the Date object corresponding to the toggled date,
                  'iso': the ISO-formatted string representing the toggled date
                }
  • datetoggleoff events are similar to datetoggleoff, but are fired when a date is unchosen/turned off. This event also provides the following information in e.detail: 
    {
                  'date': the Date object corresponding to the toggled date,
                  'iso': the ISO-formatted string representing the toggled date
                }
  • datetap events are fired when the user taps a day without dragging/painting over other dates. The event also receives the following custom datamap in e.detail: 
    {
                  'date': the Date object corresponding to the tapped date,
                  'iso': the ISO-formatted string representing the tapped date
                }
  • prevmonth and nextmonth events are fired whenever the user uses the calendar's navigation controls to move back or forward a month, respectively.

Markup

<brick-calendar controls multiple></brick-calendar>

Events


        

      

      

        

          
Styling the calendar

          
Due to the number of elements in the calendar, utilize any of the following CSS selectors to customize the calendar's appearance:
            
    
              
  • To style the calendar's container, apply styles to brick-calendar.
    • 
              
  • To style the month label, apply styles to brick-calendar .month-label.
              
  • To style individual months, apply styles to brick-calendar .month.
                
      
                  
    • Note that to change how wide months are, apply the style here, as the width of days and weeks are percentages in relation to this width
      • 
                  
    • Also note that a month's max-width is constrained by the width of the brick-calendar.
      • 
                
    
              
    • 
              
  • To style individual weeks, apply styles to brick-calendar .week.
    • 
              
  • To style individual days, apply styles to brick-calendar .day.
    • 
              
  • To style the row of weekday labels, apply styles to brick-calendar .weekday-labels.
    • 
              
  • To style individual weekday labels, apply styles to brick-calendar .weekday-label.
    • 
              
  • To style the current day, apply styles to brick-calendar .day.today.
    • 
              
  • To style days that are not in the current month, apply styles to brick-calendar .day.badmonth
    • 
              
  • To style chosen days, apply styles to brick-calendar .day.chosen
    • 
              
  • To style the previous and next navigation control buttons, apply styles to brick-calendar .prev and brick-calendar .next.
    • 
              
  • To style how elements appear when the calendar is being dragged on, use the brick-calendar[active] selector.
                
      
                  
    • Similarly, to style the day that is being hovered over during a drag, use brick-calendar[active] .day[active]
      • 
                
    
            

          

        

        

          

            
          

        

        

          
Markup

          
<brick-calendar id="custom-style-cal" controls></brick-calendar>

          
CSS styling

          
#custom-style-cal{
    background-color: lightsteelblue;
}

#custom-style-cal .month-label{
    background-color: rgba(255,255,255,.3);
}

/* use height and line-height to 
* modify the height of weeks */
#custom-style-cal .week{
    height: 1.9em;
    line-height: 1.9em;
}

#custom-style-cal .day{
    font-size: .85em;
    border-radius: 50%;
    border: 1px solid #fff;
    box-shadow: inset 1px 1px 4px grey;
}

/* use :not selectors to let default colors 
 * fall through in those cases */
#custom-style-cal .day:not(:hover):not(.chosen){
    background-color: #fff;
}

#custom-style-cal .day.today{
    border-color: limegreen;
}