Skip to content

Latest commit

 

History

History
75 lines (43 loc) · 3.81 KB

design-patterns-controls-DateTimePicker.md

File metadata and controls

75 lines (43 loc) · 3.81 KB

DateTimePicker

Basics

The DateTimePicker control provides an easy way select date and time, e.g. 6/5/2017 1:45:00 PM.

When to use

There are a set of date, time and duration pickers available in the SDK. Choose the one that is most suitable to your need.

  • DatePicker - gets a specific date including month, day and year
  • DateTimePicker - gets a specific date including month, day, year and time including hours, minutes, seconds
  • DateTimeRangePicker - gets a range of time between two date and times
  • DayPicker - gets a day of the month
  • DurationPicker - gets a duration in terms of days, hours, minutes and seconds
  • TimePicker - gets a time including hours, minutes, seconds

Best practices

Use the DateTimePicker when the user must enter a date and time.

Do

  • Use the control as a single entity.
  • Set the default date to the current date unless a specific date is required for context (e.g. the date of the conference).
  • The control is designed to resize relative to available screen width. Allow it to render in either wide or narrow as appropriate.
  • When the control is engaged, the DatePicker renders as a flyout and has defined widths (300px -narrow and 440px – wide). Plan your UI implementation accordingly.
  • The control renders date in a specific format. If allowing for manual entry of date, provide helper text in the appropriate format.

Don't

  • Don't attempt to break apart year from month/day selectors. If granularity is required, use the Dropdown control or something similar.
  • Don't attempt to force resize the control in any way.
  • Don't force the control to render one mode vs. the other (year or month/day)
  • The flyout selector is a light dismiss control. Don't modify this behavior in any way.

Developer tips and tricks

By default, this control displays date according to the user's local timezoneoffset. If the showTimezoneDropdown option is supplied as true, users can choose a timezoneoffset using the Timezone Dropdown. The viewmodel's value property will always normalize the date/time value to the user's local timezoneoffset. Typically, backends will return UTC dates, and these will be converted by the DateTimePicker control such that the view model value property will reflect the user's locale.

Be aware that timezoneoffset !== timezone. If you need to use timezones (e.g., to ensure constant scheduling time), you should set showTimezoneDropdown to false, and use separate dropdown control populated with timezones used on your backend (which may vary, but preferably IANA timezones).

Interactive control and sample source code

Go to the playground site to use the latest control and get source code for your project. Learn more about playground.

Related info