[DRAFT] PLIP #5629: Enhance timezone support in UI for plone.app.event based types

[stevepiercy]

[DRAFT] PLIP #TBD: Enhance timezone support in UI for plone.app.event based types

Responsible Persons

• Steve Piercy @stevepiercy
• Add your name and GitHub username

Proposer: Steve Piercy @stevepiercy

Seconder: Johannes Raggam @thet

Abstract

Event content types, or events, have incomplete implementations and sometimes slightly different implementations between the two Plone frontends, Classic UI and Volto. This PLIP proposes to improve the implementations to be more complete and consistent.

In Volto, the event content type does not display a timezone. When visitors are located or travel across multiple time zones, they cannot determine whether the event's time zone is their own local one, the site's default, the author's setting, or the event's location's. This is particularly confusing when an event has online participation, or when participants travel across time zones. In sites that serve its visitors in only one time zone, this is not an issue.

In Classic UI, the event contact type displays only those timezones that have been made available by the Site Administrator.

The history of event content types is in the plone.app.event package. However it was implemented using pytz whereas the standard library zoneinfo and datetime with an optional third-party package tzdata are now recommended for Python 3.9 and later. From the pytz readme:

Projects using Python 3.9 or later should be using the support now included as part of the standard library, and third party packages work with it such as tzdata. pytz offers no advantages beyond backwards compatibility with code written for earlier versions of Python.

Plone 6.0 supports Python 3.8-3.11. Python support for Plone 6.1 and later is unknown at this time. When Python 3.8 support is dropped, we can use the standard library and tzdata instead. Plone 6.2 is expected to be released between October and December 2024, and Python 3.8's end of life is October 2024. It is unknown at this time whether Plone 6.2 will retain Python 3.8 support. Plone 7.0 is tentatively scheduled for release between April and June 2025, at which time Python 3.8 support would definitely be dropped. See Plone Release Schedule.

See also PEP 615 – Support for the IANA Time Zone Database in the Standard Library and Talk - Benjamin "Zags" Zagorsky: Handling Timezones in Python.

Several other related minor issues may be addressed as part of this PLIP.

Motivation

Everyone wants to have a good time with a date. 😉

zoneinfo is preferred over pytz since Python 3.9.

International audiences expect events to be held at a given date and time with a timezone designation. Consistency between the two frontends makes it easier to transition when upgrading Plone or migrating to Volto.

The following issues relate to the event content type, date, time, and timezone implementations.

• Cannot set events with a user preferred time zone:
  • Cannot set events with a user preferred time zone plone.org#141
  • Cannot set events with a user preferred time zone #5324
• Events do not display a timezone Events do not display a timezone plone.org#151
• Event Content Type Overhaul Event Content Type Overhaul #5551
  • When selecting a start datetime, the end datetime should be after the start datetime. #6143
  • The end date should be optional to allow infinite event recurrence. #6144
• Fixed utc problems in RecurrenceWidget
  • fix: fixed utc problems in RecurrenceWidget #5002
  • fix: fixed utc problems in RecurrenceWidget #5555
• Scroll down option for selecting months and years #5662
• Listing block shows wrong ending date for events when whole_day is clicked #5717
• Wrong Time displayed in DateTimeWidget #2597)
  • Possibly solved by Handle timezone in publication fields (effective and expires) plone.restapi#1192

Assumptions

• Timezone support. Every event has a timezone. Do not support naive datetimes, that is, a datetime without a timezone.

Proposal and Implementation

This PLIP is targeted for Plone 6.2 or 7.0, whichever version drops support for Python 3.8 first.

In Classic UI, inputs for events should continue to use the Patterns Lib datetime picker with an HTML5 datetime-local input as fallback, which in turn falls back to an input type of text.

In Classic UI, evaluate dependencies of plone.app.event to determine whether they should be kept or replaced.

In Volto, decide whether to continue to use its datetime widget—which consists of two text inputs, one each for the date and the time—or use a different implementation. The current implementation requires either keyboard input or an excessive number of clicks to select a specific month or year that is distant from the default. From #2392 (comment), there is a plan to move to React Aria, and we could use its calendar component with a styled calendar input with month and year selectors.

In addition to the resolution of the above issues, the following items would be addressed.

• Add <date> and <time> HTML markup for date and time values when displayed.
• Use an appropriate fallback of HTML5 <input type="TYPE">, where TYPE is either <input type="date">, <input type="time">, or <input type="datetime-local">.
• Ensure that Publish and Expiration Dates have times.
• Upgrade steps need to be considered for all objects that have a date or time.
• Volto detects the timezone of the user's browser and attempts to display dates for that local timezone. This may interfere with setting and displaying the correct time for an event content type. Ideally browser detection shenanigans would be dropped, and the display would rely upon the value stored in the backend and show the event's timezone. This implementation would remove all ambiguity over when the event occurs.
• The user and site preferences would be fallbacks, when no timezone is selected when creating an event. In other words, timezone order of preference would be: Event > User > Site.
• Add support for anywhere on earth (AoE) as a date. The event would be saved with a start datetime of yyyy-mm-dd 00:00:00 UTC+14 and an end datetime of the next day plus 2 hours less 1 second (yyyy-mm-dd +1d 01:59:59 UTC+14) because there is an overlap of two hours in the Pacific Ocean where the timezone UTC-12 is observed. That's right, there are 50 hours in a day. 🤯 See Time Zone Map and Time Zone Converter.
• Event: "whole day" and "open end" have no effect Volto #3243
  • Whole day events. When a user enters a date, they may check a box to make it an whole day event so that they do not have to enter a start and end time, although the system will save the event with the start time of 00:00:00 and end time of 23:59:59.
  • Open end events. When a user enters a date, they may check a box to make it an open end event, so that they do not have to enter an end date or time.
• pat-datetime-picker is undocumented Patternslib/Patterns#1038
• remove available_timezones from plone.app.event Products.CMFPlone#2031
• setuptools warning about missing packages plone.app.event#401

Exclusions

There are other issues that do not involve the event content type, but are related to date, time, and timezone issues. These issues are not part of this PLIP, but are mentioned to make it clear that they are out of scope.

• Handle timezone in publication fields (effective and expires) plone.restapi #1192
• Date widget does not account for timezone difference volto-form-block #76

Deliverables

All the above issues with a checkbox, as well as the following items.

• Design document
• Plone REST API needs to return a timezone in its event endpoint for the start and end attributes. See: https://6.docs.plone.org/plone.restapi/docs/source/endpoints/content-types.html#event
• Migration of plone.app.event documentation from Plone 5 to Plone 6.
• Documentation of upgrade steps.

Project board

https://github.com/orgs/plone/projects/43/views/1

Risks

Switching from pytz to the Python 3.9 or greater standard library and tzdata may cause compatibility issues.

It is unknown which version of Plone will drop support of Python 3.8 when it goes end of life in October 2024.

Dependencies of plone.app.event might need to be upgraded or replaced.

Returning a datetime with a timezone might cause issues in Volto, plone.restapi, and plone.app.event.

Removing detection of the browser's timezone in Volto may break entry and display of dates.

Participants

• Steve Piercy, @stevepiercy, Lead Cat Herder
• Johannes Raggam, @thet, contributor
• Giulia Ghisini, @giuliaghisini, contributor
• Timo Stollenwerk, @tisto, reporter
• Ishaan Dasgupta, @IshaanDasgupta, contributor
• Your name, GitHub username, Role

[IshaanDasgupta]

The REST API endpoint for the event content type also lacks a 'timezone' attribute(as simply returning the datetime with the timezone information may cause problems) so, I believe that should also be added in the IEventBasic schema.

[stevepiercy]

@IshaanDasgupta thanks for the feedback. However I think the IEventBasic schema does in fact include a timezone for both start and end attributes. Can you verify?

https://github.com/plone/plone.app.event/blob/69e6c1c3afdb0413dfe63a758f56c015ec070ded/plone/app/event/dx/behaviors.py#L63-L80

The Plone REST API does not return the timezone information for the event start and end attributes, according to this example.

[IshaanDasgupta]

Yes, the IEventBasic does have the timezone of the event stored internally but, when return HTTP response in plone.restapi, this timezone info is lost during the conversion of the date to UTC by datetimelike_to_iso function

And as this is a generalised function, modifying it would make all the dates to be returned with their original timezone which would cause problems as in volto, we are using moment and it does not directly take the timezone into account. So, all the datetimes would suddenly change by some amount. Hence, I thought that adding a separate 'timezone' attribute would be better as then, we could gradually implement the changes without breaking anything.

Also, we don't really need to store this information, as you said the timezone is already stored, we just need to calculate the timezone and return it in the REST API response. Do you know any other ways by which this can be achieved ?

[stevepiercy]

If we decide that this PLIP will be released in Plone 7.0, then it is OK to break stuff.

It is up for discussion whether Moment.js is harmful or beneficial. I would like to get more opinions.

Moment.js with timezone is an option. However, I am wary of duplicating what already comes with the Plone backend. What does Moment.js add? Was this a case of frontend developers not understanding what the backend does? That's not a rhetorical question, I really don't know. Why is it used? The Volto Release Notes don't explain why it is used.

[07tAnYa]

here, moment.js can be used a bridge between backend n frontend for fetching user timezone, converting meeting time and updating notification content.

And specifically speaking about the issue which I rose , it was for the better UX( a simple scroll for years and months)

[stevepiercy]

here, moment.js can be used a bridge between backend n frontend for fetching user timezone, converting meeting time and updating notification content.

I would strongly encourage anyone in support of moment.js to read its Project Status. The arguments against its use are compelling, making its inclusion something I think is neither needed nor wanted. An important factor is saving 30Kb, especially where Internet speeds are slow.

[stevepiercy]

From a discussion in the Community Forum:

It has not yet been decided or discussed how to display [a datetime] to the end user, other than include a timezone. I imagine that a localized datetime with timezone would be preferred, and Python has great support for formatting dates. A preferred format could be configured in the Date and Time Settings control panel with an arbitrary format code.

[07tAnYa]

Yes I agree too that localised timings would be beneficial. And python can be used for this purpose , by this space can also be optimised. I have personally worked with this, it is good. @stevepiercy is your email linked to the GitHub, as I messaged you in email and you deleted the comment from GitHub.

…

On Tue, Jan 23, 2024, 02:38 Steve Piercy ***@***.***> wrote: From a discussion in the Community Forum <https://community.plone.org/t/issue-in-running-a-command/18598/19?u=stevepiercy> : It has not yet been decided or discussed how to display [a datetime] to the end user, other than include a timezone. I imagine that a localized datetime with timezone would be preferred, and Python has great support for formatting dates <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes>. A preferred format could be configured in the Date and Time Settings control panel <https://classic.demo.plone.org/@@dateandtime-controlpanel> with an arbitrary format code. — Reply to this email directly, view it on GitHub <#5629 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BBN43VNUVUXU5ANAHAG5Y5DYP3IL7AVCNFSM6AAAAABB4NGH6SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMBUHAYTSMRQGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[erral]

@stevepiercy I think that this PLIP has to be thought globally on the context of whole Plone itself, analyzing how the data is saved in Plone and then how it is exposed through the REST API and then how it is shown in Volto and also a Classic UI.

In the past we talked about how to expose the dates in the REST API, but we should revisit and document everything clearly.

[erral]

Sorry for the noise, I clicked the wrong button

[stevepiercy]

@sneridagh would you please move this item on the Volto Roadmap from Done to uh... Not Done? I reverted the other project board automatic updates.

---

@erral I thought I captured your general concerns in this PLIP. If not, please let me know what I can do to revise the PLIP accordingly.

FYI, I've already had discussions with Classic UI and Volto Teams. There will be many more planning discussions, including at upcoming sprints even if remotely, over the next several months.

[erral]

@stevepiercy I know that there are also issues with effective and expiration dates, you link them in the explanation above, but I think that the timezone issue and handling changes should also be extended to those fields and I would even say that also to internal created and modified dates.

I think that having timezone aware and not aware datetimes in the same content type, would be even a bigger nightmare.

Anyway, no matter we finally include them in other datetime fields, a big +1 to the PLIP.

[mauritsvanrees]

As discussed in the Plone Steering Circle today, we will drop Python 3.8 and 3.9 support in Plone 6.1. Alpha 2 still officially supports them, but we will drop them in the next alpha. So from that point of view it will be fine to start using the tzdata and timezone modules instead of pytz.
(I don't know much about timezone support, so I don't have a good feeling for how much of a breaking change this would be.)

[niccokunzmann]

This is an issue that discusses transition from pytz to zoneinfo in icalendar: collective/icalendar#609. @stevepiercy referred here in collective/icalendar#360 (reply in thread)

[stevepiercy]

Per a discussion with @jensens on the design document, we came up with a more concise and precise name of this PLIP: "Enhance timezone support in UI for plone.app.event based types".

[niccokunzmann]

icalendar's zoneinfo support (collective/icalendar#609) has progressed. If you would like to review the PR: collective/icalendar#623

[niccokunzmann]

This is how I let the user choose the timezone in the UI if the OpenWebCalendar:

(I do not know if that is in any way useful for this PLIP.)

[stevepiercy]

This is how I let the user choose the timezone in the UI if the OpenWebCalendar:

Indeed it is useful. @thet and I discussed that one issue with plain old select menus is the huge number of options for timezones. A typeahead select would be an improvement upon this, both for Volto and Classic UI via mockup.

[niccokunzmann]

I will watch what you are doing and it might be worth creating a separate library for this so it can be shared. When I was using the timezone choice in Etar (Android) I could not find my timezone. They just all had names like "British Summer Time" and so on. It would be cool to have one place that maps cities, timezone names, countries, GPS, ... and everything we can think of to timezones in a localized fashion. That could just be a set of JSON files that then can be exported into JS and Python modules and can be very useful also for Etar and other FOSS applications, with localization.
I will be watching what you do but I also think, we can do an excellent job and set a new standard ahead of others.

[tisto]

For what is worth I support this PLIP. It is an incredibly complex topic. Maybe we need a dedicated sprint to bring people together to being able to move on.

[stevepiercy]

I intend to finalize the draft PLIP, its design document, and its own project board. We're about 80% done with the planning phase after Axolotl Sprint and Buschenschanksprint.