Outline of an owl uiloos

DateGallery<T>

CLASS

A DateGallery is a class that represents a frame of dates, a frame of dates is a sequence of chronologically sequential dates of a certain length.

The idea is that whenever you are creating components that use sequences of dates, so for example: date pickers, range selectors, or calendars, that you can use the DateGallery class to handle the dates for you.

The DateGallery comes in various modes:

  1. 'day': a single day per frame.
  2. 'week': seven days per frame, starting at the configured firstDayOfWeek.
  3. 'month': all days within a calendar month per frame. A frame will then always start on the first of the month, and end on the last day of the month.
  4. 'month-six-weeks': all days within a calendar month, but padded out to six weeks. Meaning that there are always 42 days in the frame. Useful for when you want you calendar / datepicker to be visually stable height wise. Starts the days on the configured firstDayOfWeek.
  5. 'month-pad-to-week': all days within a calendar month, but padded out so it always contains full weeks. Only the smallest amount of padding is added to get to the full weeks. Starts the days on the configured firstDayOfWeek. For example if the week is configured to start on sunday, and the month starts on a tuesday, it will add monday and sunday.
  6. 'year': a frame will contain all 365 days (or 366 when a leap year) within a year.

The frame part of a DateGallery is what is visually displayed to a user, when making a monthly based calendar you are making a whole year available but only show one month at a time. The month that you show is a "frames", the dates that are visually displayed.

The DateGallery provides methods for navigating through frames, for example you can go to the next / previous frame.

You can ask the DateGallery for multiple frames at the same time by stetting the numberOfFrames property, this allows you to for example display three months at the same time, or five years at the same time.

DateGallery also supports having events such as birthdays or holidays. For each "frame" that the DateGallery provides it will also tell you which events fall on that frame. Events also know if they are overlapping with other events.

Finally the DateGallery can help you select dates. It will also put this information in each frame so you know which dates are selected.

Since 1.6.0

Constructor

Creates an DateGallery based on the DateGalleryConfig config.

You can also optionally provide an subscriber so you can get informed of the changes happening to the DateGallery.

Since 1.6.0

Signature

constructor(
config : DateGalleryConfig<T> ,
subscriber : DateGallerySubscriber<T>
): DateGallery<T>

Parameters

config: DateGalleryConfig<T>

The initial configuration of the DateGallery.

subscriber: DateGallerySubscriber<T>

An optional subscriber which responds to changes in the DateGallery.

Throws

DateGalleryEventInvalidRangeError an events start date must lie before on on the end date.

DateGalleryFirstDayOfWeekError the configured day of the week must be between 0 and 6 inclusive.

DateGalleryInvalidDateError dates provided must be valid dates

DateGalleryModeError the mode must be one of the predefined modes

DateGallerySelectionLimitReachedError thrown when maxSelectionLimit is exceeded, and maxSelectionLimitBehavior is "error".

Properties

  • events

    DateGalleryEvent<T> []

    All events, such as birthdays, meetings etc that are associated with this DateGallery.

    Is sorted from old to new, events that appear earlier in the array are earlier than events that appear later in the array.

    Since 1.6.0

  • firstDayOfWeek

    DateGalleryDayOfWeek

    What is to be considered the first day of the week, is used in modes such as 'week' to determine on which day of the week to start the frame.

    The firstDayOfWeek is a number between 0 and 6, were each number represents a day of the week:

    0 = Sunday 1 = Monday 2 = Tuesday 3 = Wednesday 4 = Thursday 5 = Friday 6 = Saturday

    Since 1.6.0

  • firstFrame

    DateGalleryFrame<T>

    The first frame of dates that is visible to the user.

    Is a shortcut to the first frame in the frames property.

    If numberOfFrames is 1 this will be the only visible frame.

    Since 1.6.0

  • frames

    DateGalleryFrame<T> []

    The frames of dates that are currently visible to the user.

    Since 1.6.0

  • history

    DateGallerySubscriberEvent<T> []

    Contains the history of the changes in the contents array.

    Tracks 11 types of changes:

    1. INITIALIZED: fired when DateGallery is initialized.
    2. FRAME_CHANGED: fired when the frames changes.
    3. CONFIG_CHANGED: fires when the config is changed.
    4. DATE_SELECTED: fires when a date is selected.
    5. DATE_SELECTED_MULTIPLE: fires when multiple dates are selected.
    6. DATE_DESELECTED: fires when a date is deselected.
    7. DATE_DESELECTED_MULTIPLE: fires when multiple dates are deselected.
    8. EVENT_ADDED: fires when an event such as a birthday / appointment is added.
    9. EVENT_REMOVED: fires when an event such as a birthday / appointment is removed.
    10. EVENT_MOVED': fires when an event such as a birthday / appointment is moved.
    11. EVENT_MOVED': fires when an event such as a birthday / appointment has its data changed.

    Goes only as far back as configured in the Config property keepHistoryFor, to prevent an infinitely growing history. Note that by default no history is kept, as keepHistoryFor is zero by default.

    The last item in the history is the current active item. The further to the left the further in the past you go.

    This means that a history at index 0 is further in the past than an item at index 1.

    Since 1.6.0

  • isUTC

    boolean

    Whether the DateGallery is in UTC mode or not.

    When the DateGallery is in UTC mode all dates that are given to you via the DateGallery through a DateGalleryDate are given in UTC.

    Also all operations on Date objects within the DateGallery or done via the UTC variants.

    UTC is useful for when you want all datepickers / calendars to look the same al around the world, which is not very often.

    Since 1.60

  • maxSelectionLimit

    number | false

    How many dates can be selected at the same time.

    When the value of limit is false there is no limit to the number of active items.

    Defaults to false.

    Since 1.6.0

  • maxSelectionLimitBehavior

    DateGalleryMaxSelectionLimitBehavior

    How the limit is enforced. In other words what the behavior should be when the limit is surpassed.

    The modes are strings which can be the following values:

    1. 'circular': the first date that was selected which will be removed so the last selected date can be added without violating the limit. This basically means that the first one in is the first one out.
    2. 'error': An error is thrown whenever the limit is surpassed, the error is called the DateGallerySelectionLimitReachedError.
    3. 'ignore': Nothing happens when an date is selected and the limit is reached. The date is simply not selected, but no error is thrown.

    Defaults to 'circular'.

    Since 1.6.0

  • mode

    "day" | "week" | "month" | "month-six-weeks" | "month-pad-to-week" | "year"

    The mode the DateGallery is on.

    1. 'day': a single day per frame.
    2. 'week': seven days per frame, starting at the configured firstDayOfWeek.
    3. 'month': all days within a calendar month per frame. A frame will then always start on the first of the month, and end on the last day of the month.
    4. 'month-six-weeks': all days within a calendar month, but padded out to six weeks. Meaning that there are always 42 days in the frame. Useful for when you want you calendar / datepicker to be visually stable height wise. Starts the days on the configured firstDayOfWeek.
    5. 'month-pad-to-week': all days within a calendar month, but padded out to the closest firstDayOfWeek.

    For example given that firstDayOfWeek is set to 0 / Sunday: if the first day of the month starts on Wednesday it will pad to the previous Sunday of the previous month.

    If the month ends on a friday, it will add the next saturday of the next month.

    Starts the days on the configured firstDayOfWeek.

    1. 'year': a frame will contain all 365 days (or 366 when a leap year) within a year.

    Since 1.6.0

  • numberOfFrames

    number

    The number of frames that are visible at a time for the end user.

    This is useful for when you want to show a multiple frames at the same time. For example if you an entire years worth of month-single-month calendars you'd set the numberOfFrames to 12.

    Since 1.6.0

  • selectedDates

    Date []

    All dates which are currently considered selected.

    All dates will have their time set at midnight.

    The array is not sorted, the items will appear in insertion order.

    Since 1.6.0

Methods

  • addEvent

    Takes a DateGalleryEventConfig and adds that config as a DateGalleryEvent to the DateGallery.

    Since 1.6.0

    Signature

    addEvent(
    event : DateGalleryEventConfig<T>
    ): DateGalleryEvent<T>

    Parameters

    event: DateGalleryEventConfig<T>

    The config of the event you want to add.

    Returns

    The created DateGalleryEvent.

    Throws

    DateGalleryEventInvalidRangeError an events start date must lie before on on the end date.

    DateGalleryInvalidDateError dates provided must be valid dates

  • changeConfig

    Changes the configuration of the DateGallery, allowing you to change the mode the initial date and numberOfFrames.

    All properties are optional and can be used in any combination. Meaning you can change the mode and numberOfFrames, or the mode and initialDate or just the numberOfFrames.

    Note: the events and selectedDates are kept as is.

    Since 1.6.0

    Signature

    changeConfig(
    config : DateGalleryChangeConfig
    ): void

    Parameters

    config: DateGalleryChangeConfig

    The new configuration.

    Throws

    DateGalleryModeError the mode must be one of the predefined modes

    DateGalleryInvalidDateError the initialDate when provided must be valid date

    DateGalleryNumberOfFramesError numberOfFrames must be a positive number when defined

  • changeEventData

    Changes the data of the given DateGalleryEvent, and informs the subscribers of the change.

    Note: if you provide the exact same data it will still set the data and inform the subscribers, even though nothing has actually changed.

    This way, when data is an object or an array, you can mutate the object / array directly, and pass in the same data object to the changeData, without having to create copies.

    Since 1.6.0

    Signature

    changeEventData(
    event : DateGalleryEvent<T> ,
    data : T
    ): void

    Parameters

    event: DateGalleryEvent<T>

    data: T

    The new data for the DateGalleryEvent

    Throws

    DateGalleryEventNotFoundError item must be in the views array based on === equality

  • deselectAll

    Deselects all dates, effectively clearing the selectedDates property.

    Since 1.6.0

    Signature

    deselectAll(): void

  • deselectDate

    Deselects the given date, the date can either be a Date instance, or a string which can be passed to the Date constructor to make a date.

    The given date will be converted to midnight so it better matches the selectedDates which are always at midnight.

    Since 1.6.0

    Signature

    deselectDate(
    date : string | Date
    ): void

    Parameters

    date: string | Date

    An optional date to act as the new initial date

    Throws

    DateGalleryModeError the mode must be one of the predefined modes

    DateGalleryInvalidDateError date provided must be valid date

  • initialize

    Initializes the DateGallery based on the config provided. This can effectively reset the DateGallery when called, including the frames and history.

    Since 1.6.0

    Signature

    initialize(
    config : DateGalleryConfig<T>
    ): void

    Parameters

    config: DateGalleryConfig<T>

    The new configuration which will override the old one

    Throws

    DateGalleryEventInvalidRangeError an events start date must lie before on on the end date.

    DateGalleryFirstDayOfWeekError the configured day of the week must be between 0 and 6 inclusive.

    DateGalleryInvalidDateError dates provided must be valid dates

    DateGalleryModeError the mode must be one of the predefined modes

    DateGalleryNumberOfFramesError numberOfFrames must be a positive number when defined

    DateGallerySelectionLimitReachedError thrown when maxSelectionLimit is exceeded, and maxSelectionLimitBehavior is "error".

  • isSameDay

    Compares two dates and returns whether or not they are on the same date.

    The given dates can either be a Date instance, or a string which can be passed to the Date constructor to make a date.

    Takes into account the isUTC of the DateGallery when UTC is true it will compare the UTC dates.

    Since 1.6.0

    Signature

    isSameDay(
    a : string | Date ,
    b : string | Date
    ): boolean

    Parameters

    a: string | Date

    The first date you want to check

    b: string | Date

    The second date you want to check

    Returns

    whether or not the dates are on the same date.

    Throws

    DateGalleryInvalidDateError dates provided must be valid dates

  • moveEvent

    Takes a DateGalleryEvent and moves that event chronologically, in other words it changes the events start and end time to the given range.

    Since 1.6.0

    Signature

    moveEvent(
    event : DateGalleryEvent<T> ,
    range : DateGalleryRange
    ): void

    Parameters

    event: DateGalleryEvent<T>

    The event you want to move / change the start / end time for.

    range: DateGalleryRange

    The new start and end times of the event.

    Throws

    DateGalleryEventInvalidRangeError an events start date must lie before on on the end date.

    DateGalleryEventNotFoundError the provided event must be part of the DateGallery.

  • next

    Moves the frame of the DateGallery to the next frame.

    For example if the mode is set to month and the current anchor date is in March it will move to April.

    Since 1.6.0

    Signature

    next(): void

  • previous

    Moves the frame of the DateGallery to the previous frame.

    For example if the mode is set to month and the current anchor date is in April it will move to March.

    Since 1.6.0

    Signature

    previous(): void

  • removeEvent

    Takes a DateGalleryEvent and removes that event from this DateGallery, and all associated frames.

    Note: if the event cannot be found within the DateGallery nothing happens.

    Since 1.6.0

    Signature

    removeEvent(
    event : DateGalleryEvent<T>
    ): DateGalleryEvent<T>

    Parameters

    event: DateGalleryEvent<T>

    The event you want to remove.

    Returns

    The removed DateGalleryEvent.

  • selectDate

    Selects the given date, the date can either be a Date instance, or a string which can be passed to the Dateconstructor to make a date.

    The given date will be converted to midnight, so all times in the selectedDates array are always at midnight.

    When a canSelect predicate is configured, the date is first checked to see if it can be added. When a date does not pass the check nothing happens, and no error is thrown.

    Since 1.6.0

    Signature

    selectDate(
    date : string | Date
    ): void

    Parameters

    date: string | Date

    An optional date to act as the new initial date

    Throws

    DateGalleryModeError the mode must be one of the predefined modes

    DateGalleryInvalidDateError date provided must be valid date

    DateGallerySelectionLimitReachedError thrown when maxSelectionLimit is exceeded, and maxSelectionLimitBehavior is "error".

  • selectRange

    Selects all dates from within the given date range.

    If the range is end inclusive meaning if the starts on Monday and end ends on Friday: Monday, Tuesday, Wednesday, Thursday and Friday are selected.

    The given dates can either be a Date instance, or a string which can be passed to the Date constructor to make a date.

    The order of the two parameters does not matter as selectRange will check whether a or b is the earlier date.

    If a date is already selected and falls within the range the date will stay selected.

    When a canSelect predicate is configured, the date is first checked to see if it can be added. When a date does not pass the check nothing happens, and no error is thrown.

    Dates can also become deselected if the maxSelection is set to a number and the maxSelectionLimitBehavior is set to "circular", if space needs to be made for the new dates.

    When maxSelectionLimitBehavior is set to "error", all dates that can be accommodated become selected, but when the limit is exceeded the selection stops. The subscribers are then informed of which dates were selected, and then the error is thrown.

    Even through each date is selected sequentially, only one event is emitted, and one call is made to the subscribers, even if multiple dates are selected and deselected.

    Within the DateGalleryDateSelectedMultipleEvent only the end activate / deactivate results are reported.

    Since 1.6.0

    Signature

    selectRange(
    a : string | Date ,
    b : string | Date
    ): void

    Parameters

    a: string | Date

    the start or end date of the range

    b: string | Date

    The start or end date of the range

    Throws

    DateGalleryInvalidDateError dates provided must be valid dates

    DateGallerySelectionLimitReachedError thrown when maxSelectionLimit is exceeded, and maxSelectionLimitBehavior is "error".

  • subscribe

    Subscribe to changes of the DateGallery. The function you provide will get called whenever changes occur in the DateGallery.

    Returns an unsubscribe function which when called will unsubscribe from the DateGallery.

    Since 1.6.0

    Signature

    subscribe(
    subscriber : DateGallerySubscriber<T>
    ): UnsubscribeFunction

    Parameters

    subscriber: DateGallerySubscriber<T>

    The subscriber which responds to changes in the DateGallery.

    Returns

    A function which when called will unsubscribe from the DateGallery.

  • today

    Changes the anchor date of the DateGallery to today.

    Since 1.6.0

    Signature

    today(): void

  • toggleDateSelection

    Toggles the date selection of the given date, if the date is selected it becomes deselected, if the date is deselected it becomes selected.

    The given date can either be a Date instance, or a string which can be passed to the Date constructor to make a date.

    The given date will be converted to midnight, so all times in the selectedDates array are always at midnight.

    When a canSelect predicate is configured, the date is first checked to see if it can be added. When a date does not pass the check nothing happens, and no error is thrown.

    Since 1.6.0

    Signature

    toggleDateSelection(
    date : string | Date
    ): void

    Parameters

    date: string | Date

    An optional date to act as the new initial date

    Throws

    DateGalleryModeError the mode must be one of the predefined modes

    DateGalleryInvalidDateError date provided must be valid date

    DateGallerySelectionLimitReachedError thrown when maxSelectionLimit is exceeded, and maxSelectionLimitBehavior is "error".

  • unsubscribe

    Unsubscribe the subscriber so it no longer receives changes / updates of the state changes of the DateGallery.

    Since 1.6.0

    Signature

    unsubscribe(
    subscriber : DateGallerySubscriber<T>
    ): void

    Parameters

    subscriber: DateGallerySubscriber<T>

    The subscriber which you want to unsubscribe.

  • unsubscribeAll

    Unsubscribes all subscribers at once, all subscribers will no longer receives changes / updates of the state changes of the DateGallery.

    Since 1.6.0

    Signature

    unsubscribeAll(): void