mercurymedia / elm-datetime-picker / SingleDatePicker

A date picker component for a single datetime.

Architecture


type DatePicker msg

The opaque type representing a particular date picker instance.


type Msg

Internal Msg's to update the picker.

init : (Msg -> msg) -> DatePicker msg

Instantiates and returns a date picker.

view : Settings -> DatePicker msg -> Html msg

The date picker view. Simply pass it the configured settings and the date picker instance you wish to view.

update : Settings -> Msg -> DatePicker msg -> ( DatePicker msg, Maybe Time.Posix )

Update the SingleDatePicker according to the given internal msg.

Returns the updated picker and the currently selected datetime, if available.

subscriptions : Settings -> DatePicker msg -> Platform.Sub.Sub msg

Events external to the picker to which it is subscribed.

Settings


type alias Settings =
{ zone : Time.Zone
, id : String
, firstWeekDay : Time.Weekday
, formattedDay : Time.Weekday -> String
, formattedMonth : Time.Month -> String
, isDayDisabled : Time.Zone -> Time.Posix -> Basics.Bool
, focusedDate : Maybe Time.Posix
, dateStringFn : Time.Zone -> Time.Posix -> String
, timePickerVisibility : TimePickerVisibility
, showCalendarWeekNumbers : Basics.Bool 
}

The type facilitating the configuration of the datepicker settings.

id - provides a custom id to the picker element zone - the Zone in which the date picker is being used (client zone) formattedDay - a function that returns a string representation for the provided day of the week formattedMonth - a function that returns a string representation for the provided month isDayDisabled - a function that determines if the combined Posix and Zone represent a day that should be disabled in the picker focusedDate - a Posix that represents a day that should be highlighted on the picker (i.e. the current day) dateStringFn - a function that returns a string representation of the selected day timePickerVisibility - see below showCalendarWeekNumbers - wheather to display or not display caldendar week numbers

More information can be found in the examples.

defaultSettings : Time.Zone -> Settings

A record of default settings for the date picker. Extend this if you want to further customize the date picker.

Requires a Zone to inform the picker in which time zone it should display the picked time as well as a msg that expects a tuple containing a datepicker instance and a Maybe Posix representing a selected datetime.

( DatePicker, Maybe Posix ) -> msg


type TimePickerVisibility
    = NeverVisible
    | Toggleable TimePickerSettings
    | AlwaysVisible TimePickerSettings

Set the visibility of the timepicker in the DateTimePicker

NeverVisible - The time picker is never visible. Please note that while ostensibly picking a day, a selection still returns a Posix representing the beginning of that day (00:00). It is up to you to process the selection accordingly if you wish to treat it as a whole day.

Toggleable - The time picker visibility can be toggled but is by default closed when the datetime picker is opened. Additional configuration can be achieved via TimePickerSettings.

AlwaysVisible - The time picker is always visible. This is the default setting as it most explicitly shows that the datetime picker is indeed picking both a date and time, not simply a date. Additional configuration can be achieved via TimePickerSettings.


type alias TimePickerSettings =
{ timeStringFn : Time.Zone -> Time.Posix -> String
, allowedTimesOfDay : Time.Zone -> Time.Posix -> { startHour : Basics.Int
, startMinute : Basics.Int
, endHour : Basics.Int
, endMinute : Basics.Int } 
}

The type facilitating the configuration of the timepicker settings.

timeStringFn - a function that returns a string representation of the selected time of day

Because it could be the case that a picker is being used in a different timezone than the home timezone of the implementor, the allowedTimesofDay function ingests a Zone in addition to a Posix. The Zone represents the time zone in which the picker is being used. An implementor can leverage this to compare against a base time zone when enforcing allowable times of day, etc. You SHOULD assume that the Posix passed into these functions is floored to the start of its respective Day.

More information can be found in the examples.

defaultTimePickerSettings : TimePickerSettings

A record of default settings for the time picker. Extend this if you want to further customize the time picker.

Externally Triggered Actions

openPicker : Settings -> Time.Posix -> Maybe Time.Posix -> DatePicker msg -> DatePicker msg

Open the provided date picker and receive the updated picker instance. Also takes a default time the picker should center on (in the event a time has not yet been picked) as well as the picked time. A common example of a default time would be the datetime for the current day.

closePicker : DatePicker msg -> DatePicker msg

Close the provided date picker and receive the updated picker instance.

openPickerOutsideHierarchy : String -> Settings -> Time.Posix -> Maybe Time.Posix -> DatePicker msg -> ( DatePicker msg, Platform.Cmd.Cmd msg )

Open the provided date picker outside the DOM hierarchy. Uses the openPicker function and additionally takes an id of the trigger DOM element (e.g. a button) to manually attach the picker's position to it. Returns the updated picker instance plus the necessary command in order to find DOM elements and their positions.

updatePickerPosition : DatePicker msg -> Platform.Cmd.Cmd msg

Returns the command to update the trigger & picker DOM elements' instances. Is used internally but can also be used externally in case of a changing viewport (e.g. onScroll or onResize).

Query

isOpen : DatePicker msg -> Basics.Bool

Indicates whether the DatePicker is open