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

[stevepiercy]

PLIP #5629: 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.9-3.13. Plone 6.1 supports Python 3.10-3.13. Now that Python 3.8 support has been dropped, we can use the standard library and tzdata instead. Plone 6.2 is expected to be released in Q3 2025. Plone 7.0 is expected to be released in Q2 2026. 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.

Several issues, either added as sub-issues to this PLIP or as tracked issues, relate to the event content type, date, time, and timezone implementations.

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 completion in Plone 7.0. Some bugs may be fixed in Plone 6.2.

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.

See Deliverables and the Project Board for details of the implementation.

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 collective/volto-form-block#76

Deliverables

All the tracked pull requests and issues, the sub-issues at the end of this PLIP, and the following items.

Tracked pull requests and issues

• pat-datetime-picker is undocumented Patternslib/Patterns#1038
• [Seven] - Formatted Date component #6690
• [CMSUI Widgets] - Date/Time/Date ranges/Recurrence #6652

Planning and design

• Design document
• Migration of plone.app.event documentation from Plone 5 to Plone 6.
• Documentation of upgrade steps.
• 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
• 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.
• In the Date and Time control panel, add an option to toggle the display of timezones of events at the site level. The default would be "Don't display timezones of events", with the other option of "Display timezones of events".
• 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.

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. This was addressed in plone/plone.app.event#419.

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.

[stevepiercy]

I've thoroughly reviewed all the related open issues and pull requests, and revised the content of this PLIP to reflect recent developments with iCalendar, dropping Python 3.8, and the revised Plone release schedule. I also moved items into sub-issues, as that is a new feature in GitHub.

I need help from @plone/volto-team and @plone/classicui-team to comment on:

1. Shall we use React Aria DatePicker and its like in Volto?
2. In Classic UI, should inputs for events 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?
3. In Classic UI, evaluate dependencies of plone.app.event to determine whether they should be kept or replaced.

I also want to ensure that the items listed in "Proposal and Implementation" are acceptable and align with plans in both Classic UI and Volto.

I hope to resolve open questions during the Alpine Sprint this week. With those questions answered, this PLIP can be officially submitted and acted upon.

[davisagli]

@stevepiercy This PLIP is...sprawling. I'm not sure it's possible to provide a useful review of a PLIP that is basically "fix everything related to dates and times in Plone." I also don't think it's been a waste of time to try to collect all of those in one place. But as a next step I suggest that we should organize things into several areas of focus:

1. Add support for setting and displaying timezones per Event. As far as I can tell, this was the original focus for the PLIP. This includes some work on the backend and REST API to add a timezone field to events, as well as making sure that it can be edited and displayed well in both Classic UI and Volto, and sorting out the default timezone settings at the site- and user-level. Basically the stuff that's in the existing Design Document.

2. Switch from pytz to zoneinfo/tzdata. You're right to mention that this is a direction we should explore, but at first glance I don't think it's tightly coupled to adding the timezone field to Event. Both libraries are based on the IANA timezone database so the choices should be the same.

3. Widget improvements. This includes things like making the "whole day" and "open-end" options work well, adding a month/year selector, maybe even switching to different widgets. In my opinion we have a lot of good ideas in this area but they are a somewhat separate topic from adding a timezone field to Events and it might be helpful to consider them separately.

4. Miscellaneous date/time-related bugs. These don't need to be included in a PLIP unless fixing the bug has significant impact on existing users or the overall system design.

Personally I would be interested in contributing to work on the first focus area, as well as bugs that involve the REST API.

I hope this doesn't come across as stop energy. When I come back to look at this PLIP after some time away I have to spend an hour just remembering what all's in here, so I'm trying to figure out a useful way to break it down. Open to discussion on the specifics of how to do that.

[stevepiercy]

@davisagli thanks for your thoughtful feedback. Last night while gardening the issues, I realized it was too much and needed to be broken into smaller, achievable groups of tasks. I tried the available fields in GitHub Projects—Status, Priority, Label, and others—but they weren't doing it for me, and I ran out of steam.

I think your groupings are perfect. I created a new field in the Project Board called "Focus area", which is a select field with the following options:

• 1: Timezones in events
• 2: Use zoneinfo
• 3: Widget improvements
• 4: Miscellaneous bug fixes

I put the issues according to where I think they belong. I'd appreciate feedback on this part.

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

I'm reluctant to break apart this PLIP because having all these issues collected in one place is helpful in one aspect.

[stevepiercy]

Added an item to the PLIP Planning and Design:

• In the Date and Time control panel, add an option to toggle the display of timezones of events at the site level. The default would be "Don't display timezones of events", with the other option of "Display timezones of events".

[stevepiercy]

From the Design Document, there is one unanswered question open for discussion:

1. Currently if the site Admin does not set a Plone site's timezone, then it uses UTC. Should we change that behavior instead to use the server's local timezone?

[niccokunzmann]

Currently if the site Admin does not set a Plone site's timezone, then it uses UTC. Should we change that behavior instead to use the server's local timezone?

Users generally expect to see times in their timezone (device timezone).

UTC or server timezone does not make much of a difference if it is not the one on the device. In general, one can assume that most applications will be viewed from one timezone. If that is not configured it also does not mean that it is correct if it is the server's timezone. My server is in UTC when I rent it, until I change it. I think that having the timezone as a step in a setup guide is more useful.

[stevepiercy]

I think that having the timezone as a step in a setup guide is more useful.

@niccokunzmann Cookieplone lacks this prompt, so it can be overlooked, leaving the site to default to UTC. However when creating a new Plone site whether through a project generated by Cookieplone, pipx, or buildout, it is a required step. See plone/cookieplone#66 for details.