search

JohnRDOrazio / jQuery-Clock-Plugin

Turns a given dom element into a jQuery Clock that can take an initial timestamp instead of client system time, supports internationalization and `Intl.DateTimeFormat` options or PHP Style Format Characters, and is relatively independent from system clock
https://www.johnromanodorazio.com
Apache License 2.0
73 stars 33 forks source link

should allow ECMA `Date#toLocaleDateString` #33

Closed JohnRDOrazio closed 6 months ago

JohnRDOrazio commented 7 months ago

Now that the DateTime APIs have been out for a while and have been supported in all major browsers for some time now, we could allow setting the Date format and the Time format using options that are supported by the DateTime API.

This would mean that the dateFormat option and the timeFormat option should allow for an object rather than just for a string with PHP style date / time formatters.

Supported Date Options:

day:

The representation of the day. Possible values are "numeric", "2-digit".

weekday:

The representation of the weekday. Possible values are "narrow", "short", "long".

year:

The representation of the year. Possible values are "numeric", "2-digit".

month:

The representation of the month. Possible values are "numeric", "2-digit", "narrow", "short", "long".

Supported Time Options:

hour:

The representation of the hour. Possible values are "numeric", "2-digit".

minute: The representation of the minute.

Possible values are "numeric", "2-digit".

second:

The representation of the second. Possible values are "numeric", 2-digit".

hour12:

The representation of time format. Accepts boolean true or false

And perhaps we should set the default Date / Time value to the default DateTime API formatting for the current locale, rather than to a default PHP style formatter?

JohnRDOrazio commented 7 months ago

It would seem better to use https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat rather than Date#toLocaleDateString, considering that the former will cache properties for successive calls with the same options, whereas the latter won't.

JohnRDOrazio commented 7 months ago

All possible options are:

Locale options

localeMatcher The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see Locale identification and negotiation.

calendar The calendar to use, such as "chinese", "gregory", "persian", and so on. For a list of supported calendar types, see Intl.Locale.prototype.getCalendars(). This option can also be set through the ca Unicode extension key; if both are provided, this options property takes precedence.

numberingSystem The numbering system to use for number formatting, such as "arab", "hans", "mathsans", and so on. For a list of supported numbering system types, see Intl.Locale.prototype.getNumberingSystems(). This option can also be set through the nu Unicode extension key; if both are provided, this options property takes precedence.

hour12 Whether to use 12-hour time (as opposed to 24-hour time). Possible values are true and false; the default is locale dependent. This option overrides the hc locale extension tag and/or the hourCycle option in case both are present. It sets hourCycle to "h11" or "h12" when true, and "h23" or "h24" when false, the exact choice depending on the locale — for example, if the locale most prefers "h23" but hour12 is true, then the final hour cycle is "h11".

hourCycle The hour cycle to use. Possible values are "h11", "h12", "h23", and "h24". This option can also be set through the hc Unicode extension key; if both are provided, this options property takes precedence.

timeZone The time zone to use. The only value implementations must recognize is "UTC"; the default is the runtime's default time zone. Implementations may also recognize the time zone names of the IANA time zone database, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".

Date-time component options

weekday The representation of the weekday. Possible values are:

"long" E.g., Thursday

"short" E.g., Thu

"narrow" E.g., T. Two weekdays may have the same narrow style for some locales (e.g. Tuesday's narrow style is also T).

era The representation of the era. Possible values are:

"long" E.g., Anno Domini

"short" E.g., AD

"narrow" E.g., A

year The representation of the year. Possible values are "numeric" and "2-digit".

month The representation of the month. Possible values are:

"numeric" E.g., 3

"2-digit" E.g., 03

"long" E.g., March

"short" E.g., Mar

"narrow" E.g., M). Two months may have the same narrow style for some locales (e.g. May's narrow style is also M).

day The representation of the day. Possible values are "numeric" and "2-digit".

dayPeriod The formatting style used for day periods like "in the morning", "am", "noon", "n" etc. Possible values are "narrow", "short", and "long".

Note: This option only has an effect if a 12-hour clock (hourCycle: "h12" or hourCycle: "h11") is used. Many locales use the same string irrespective of the width specified.

hour The representation of the hour. Possible values are "numeric" and "2-digit".

minute The representation of the minute. Possible values are "numeric" and "2-digit".

second The representation of the second. Possible values are "numeric" and "2-digit".

fractionalSecondDigits The number of digits used to represent fractions of a second (any additional digits are truncated). Possible values are from 1 to 3.

timeZoneName The localized representation of the time zone name. Possible values are:

"long" Long localized form (e.g., Pacific Standard Time, Nordamerikanische Westküsten-Normalzeit)

"short" Short localized form (e.g.: PST, GMT-8)

"shortOffset" Short localized GMT format (e.g., GMT-8)

"longOffset" Long localized GMT format (e.g., GMT-08:00)

"shortGeneric" Short generic non-location format (e.g.: PT, Los Angeles Zeit).

"longGeneric" Long generic non-location format (e.g.: Pacific Time, Nordamerikanische Westküstenzeit)

Note: Timezone display may fall back to another format if a required string is unavailable. For example, the non-location formats should display the timezone without a specific country/city location like "Pacific Time", but may fall back to a timezone like "Los Angeles Time".

The default value for each date-time component option is undefined, but if all component properties are undefined, then year, month, and day default to "numeric". If any of the date-time component options is specified, then dateStyle and timeStyle must be undefined.

formatMatcher The format matching algorithm to use. Possible values are "basic" and "best fit"; the default is "best fit". Implementations are required to support displaying at least the following subsets of date-time components:

Implementations may support other subsets, and requests will be negotiated against all available subset-representation combinations to find the best match. The algorithm for "best fit" is implementation-defined, and "basic" is defined by the spec. This option is only used when both dateStyle and timeStyle are undefined (so that each date-time component's format is individually customizable).

Style shortcuts

dateStyle The date formatting style to use when calling format(). Possible values are "full", "long", "medium", and "short".

timeStyle The time formatting style to use when calling format(). Possible values are "full", "long", "medium", and "short".

Note: dateStyle and timeStyle can be used with each other, but not with other date-time component options (e.g. weekday, hour, month, etc.).

JohnRDOrazio commented 6 months ago

implemented in commit https://github.com/JohnRDOrazio/jQuery-Clock-Plugin/commit/0ad6c61dac4981816c117b9e4b2746355303348b