Content
View differences
Updated by Parimal Satyal over 3 years ago
This sub-feature is part of the epic related to the duration feature (<mention class="mention" data-id="31992" data-type="work_package" data-text="#31992">#31992</mention>) and describes the functioning of the new date picker.
**Please note that the date picker is being implemented in multiple stages. The first version, for 12.2, is described here:** [**#42047**](https://community.openproject.org/work_packages/42047) **(date picker excluding duration and non-working days).**
**This ticket describes** _**only**_ **additions and changes for 12.3.**
**The scheduling and working days switches are described here:** **#44147**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38674/content">
### **Base Acceptance criteria**
The date picker extends the date picker from 12.2 with these new features:
* The "Manual scheduling" and "Working days only" switches (described in <mention class="mention" data-id="44147" data-type="work_package" data-text="#44147">#44147</mention>)
* A new "Duration" field
### Duration field (basic characteristics)
* There is new "Duration" field to the right of finish date
* The visual format for displaying duration is "4 days".
* When in focus, this retains only the numerical value "4".
* The field only accepts integers when in focus. On blur, it goes back to the normal display with the units ("n days", "n Tage", "n jours"...).
* ~~If the user types "4 days" (or "4 Tage", "4 jours"...), all information apart from the number is ignored. It should be considered the same as typing "4".~~
* On blur (remove focus), the localised word for "days" is added again.
### How changing duration should affect start and finish dates
Normally, when clicking on individual dates in the mini calendar, the active field switches between the start the finish dates, with each click. With the introduction of Duration, this behaviour is maintained, but with these specificities:
* When the Duration field is clicked on (for manual input of duration), it is considered "active" (much like the start and finish date fields).
* Clicking outside of the duration field (blur) does not change the active field; it remains duration. It looses the focus only:
* with a click on the start or finish date fields
* with a click on a date in the mini calendar
* when the modal is closed
* When a user modifies the duration integer by typing:
* If no dates are entered, there is no visual impact on the mini-calendar.
* If both dates are present, the finish date is changed automatically based on the new duration input
* If only the start date was present, the finish date is now derived based on duration.
* If only the finish date was present, the start date is now derived based on duration.
* When the duration field is active and the user clicks on a date in the mini calendar:
* If the duration field has a value, the clicked date becomes the the start date and the finish date is then derived from the duration that was present. The active field moves to the finish date:
* A click on a second date then modifies the finish date. This second click can affect duration. The active field then shifts back to the start date.
* If the duration field has no value:
* Only start date exists: click on a date sets finish date. (Unless date clicked is before start date, then it swtiches). Focus moves to start date.
* Only finish date exists: click on a date sets start date. (Unless date clicked is after finish date, then it switches), Focus moves to finish date.
* No dates exist: click on a date sets start date, focus moves to finish date.
* For a work package that has a start date, a finish date and thus also a duration, removing one of the dates (start or finish) will also remove the duration.
* Of course, clicking on a second date (or manually adding a second date) will add a new duration and the duration will be changed and all three fields will now be complete.
* This also means that it is not possible to conserve duration when deleting dates, since deleting one date will also delete duration. To remove start and finish dates from a work package that already has these fields but keep the duration, the duration will then have to be re-entered after removing the dates.
* This also means that is not possible to retain both dates _and_ remove the duration. As described in scenario #6 in <mention class="mention" data-id="43539" data-type="work_package" data-text="#43539">#43539</mention>, removing the duration will also remove the finish date.
* Entering a new duration after the after will, then, also add a new finish date (start date + duration).
* Opening the datepicker modal with the new fields will result in the following field being active
* From the work package table, opening the modal:
* by clicking on a start date column cell, the start date is active
* by clicking on a finish date column cell, the finish date is active
* by clicking on a duration column cell, the duration field is active
* by clicking on any cell for a work package with type milestone, the single date field is active
* From the combined edit field, opening the modal:
* will focus the due date IF the start date is set, and finish date and duration is unset.
* will focus the start date otherwise.
### Mini calendar updates
Each calendar day has a few new states:
* **When enabled:**
* In the selected range but a non-working day (blue _feedback/info/dark_ text on a _gray#6_ background)
* **When disabled:**
* In the selected range but a non-working day (_gray#5_ on a _gray#6_ background)
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/37493/content"> <img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/37494/content">
### The "Working days" toggle set
The action bar has a new toggle set:
* By default, "Work week" is selected and non-working days, as defined in the admin settings, are not included in calculation of duration (when date ranges include them). In other words, these days are skipped over.
* These non-working days are also non-clickable on the mini calendar.
* Switching the toggle to "Include weekends" overrides this and includes non-working days in the calculation. It also makes these the previously disabled days clickable.
* This removes the grey background on non-working days; all days now look the same as a "normal" day.
* Switching the toggle to "Work week" box reverses this and non-working days become grey again and are skipped in calculations.
* Please refer to the testing scenarios for details on expected behaviour in a variety of different cases: <mention class="mention" data-id="43539" data-type="work_package" data-text="#43539">#43539</mention>.
### "Working days" and its relation to the start date, finish date and duration
* If a work package already has start and end dates, and thus also duration, and the user enables "Include weekends", the duration is preserved and the dates are updated to include days that were previously skipped.
* If the user goes back to working days only (from previously including weekends) the duration is once again maintained but the finish date is pushed to now skip over the non-working days.
* When "Include weekends" is enabled and the start date is a normally non-working day (eg. Saturday), going back to "Work week" will also push this start date to the first available working day (eg. Monday), moving also the finish date if necessary to maintain duration.
* If a work package only has one set of date information (just start date, just end date, or just duration), changing this toggle will normally not affect any of the values until a second piece of information is also input.
* **Exception:** When "Include weekends" mode enabled and the single date (start _or_ finish) is on a normally non-working day (eg. Saturday), then switching back to "Work week" has to move that date to the first available working day (in the future, Monday in our example).
### Defaults and instance settings
* New work packages have an empty (not set) default duration.
* For new work packages, by default, the toggle will be set to "Work week" and non-working days will not be taken into account when calculating duration by default.
* When migrating to 12.3, when the feature is introduced, all previous work packages will be toggled to "Include weekends" (since non-working days will not have been taken into account in previously created work packages).
* If the admin setting "User current date as start date for new work packages" is enabled and a work package is created on a weekend (and "include weekends" is not manually enabled by the user, so by default "work week" is selected), the start date will be set to the first available _working_ day (and not the weekend day).
* This is because the spirit of that admin setting is to simplify the creation of new work packages by not forcing the user to have to select a date every single time; this base default cannot make an assumption about the user's intention in terms of wanting to include non-working days or not. Creating a work package on a weekend does not necessarily mean that it will be scheduled to start that very day; if we automatically enable 'Include weekends' mode on their behalf without their instruction, this would affect scheduling even if they then select a start date that is normally a working day).
* If the user _meant_ for the work package to start on a weekend _and_ have its duration include weekends, they can the toggle to explicitly enable this mode.
* Updates to journal entries/activity log are described in <mention class="mention" data-id="31992" data-type="work_package" data-text="#31992">#31992</mention> under 'Activity log'.
### Logical changes
* Changing either a date, the duration or the non-working days will have automatic effects on the other fields. The concrete logic is described in <mention class="mention" data-id="43539" data-type="work_package" data-text="#43539">#43539</mention>
* **Technical note:** Ideally this calculation is done by the backend, so that we don't have to repeat it in the frontend.
### Visuals
**Regular scheduling, working days only (default):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38676/content">
**Regular scheduling, include non-working days:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38677/content">
**Banner info - Automatic scheduling (dates derived from children, mini calendar disabled):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38678/content">
**Banner warning - Manual scheduling (with relations):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38679/content">
**Banner info - Dates limited by relations:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38680/content">
**Banner warning - Dates will affect related WPs:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38681/content">
### One-day date picker
The one-day date picker (used for Milestones, for example) does not have a duration field:
**One-day date picker (Milestone):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38682/content">
**One-day date picker with a banner:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38683/content">
### Date-only date picker
Extracted, will be specified in <mention class="mention" data-id="42358" data-type="work_package" data-text="#42358">#42358</mention>.
### Mobile date picker
In the mobile version:
* The date picker is displayed with a dark background and has a consistent margin all around (same as other modals like _Include projects_ and _Project select,_ but without a close button).
* The date picker makes use of the full width available to it, vertically and horizontally. It should be centered on the viewport.
* Horizontal scrolling is not possible.
* The two switches ("Manual scheduling" and "Working dayss "Workingn days only" are stacked vertically)
* Each switch set takes the full width of the datepicker
* The text is left-aligned
* The switches are aligned to the right-edge
* The start/finish date fields continue to each take 50% of the width.
* The duration field is moved to a new line
* Only one calendar month is displayed.
* The date picker makes use of the full width available to it, vertically and horizontally. It should be centered on the viewport.
* There is a consistent margin around the date picker (same as other modals like _Include projects_ and _Project select_, with a dark background, but no close button).
* Opening the date picker will dismiss other open modals, and opening another modal will dismiss the date picker. (Only one modal can be open at a time).
The mobile version should be arranged like this (from specs):
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38884/content">
When vertical space is not enough, it should behave like this, so that the action bar on top:
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38885/content">
**Mobile one-day date picker (Milestones):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38686/content">
### Figma prototypes
Please keep in mind that Figma page has a "(12.3) with Duration" in the title (the 12.2 page looks very similar, so do double-check). When in doubt, follow this link:
https://www.figma.com/file/SMzHAQWcY9k0PkTEKd5UQn/?node-id=1806%3A50629
**Please note that the date picker is being implemented in multiple stages. The first version, for 12.2, is described here:** [**#42047**](https://community.openproject.org/work_packages/42047) **(date picker excluding duration and non-working days).**
**This ticket describes** _**only**_ **additions and changes for 12.3.**
**The scheduling and working days switches are described here:** **#44147**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38674/content">
### **Base Acceptance criteria**
The date picker extends the date picker from 12.2 with these new features:
* The "Manual scheduling" and "Working days only" switches (described in <mention class="mention" data-id="44147" data-type="work_package" data-text="#44147">#44147</mention>)
* A new "Duration" field
### Duration field (basic characteristics)
* There is new "Duration" field to the right of finish date
* The visual format for displaying duration is "4 days".
* When in focus, this retains only the numerical value "4".
* The field only accepts integers when in focus. On blur, it goes back to the normal display with the units ("n days", "n Tage", "n jours"...).
* ~~If the user types "4 days" (or "4 Tage", "4 jours"...), all information apart from the number is ignored. It should be considered the same as typing "4".~~
* On blur (remove focus), the localised word for "days" is added again.
### How changing duration should affect start and finish dates
Normally, when clicking on individual dates in the mini calendar, the active field switches between the start the finish dates, with each click. With the introduction of Duration, this behaviour is maintained, but with these specificities:
* When the Duration field is clicked on (for manual input of duration), it is considered "active" (much like the start and finish date fields).
* Clicking outside of the duration field (blur) does not change the active field; it remains duration. It looses the focus only:
* with a click on the start or finish date fields
* with a click on a date in the mini calendar
* when the modal is closed
* When a user modifies the duration integer by typing:
* If no dates are entered, there is no visual impact on the mini-calendar.
* If both dates are present, the finish date is changed automatically based on the new duration input
* If only the start date was present, the finish date is now derived based on duration.
* If only the finish date was present, the start date is now derived based on duration.
* When the duration field is active and the user clicks on a date in the mini calendar:
* If the duration field has a value, the clicked date becomes the the start date and the finish date is then derived from the duration that was present. The active field moves to the finish date:
* A click on a second date then modifies the finish date. This second click can affect duration. The active field then shifts back to the start date.
* If the duration field has no value:
* Only start date exists: click on a date sets finish date. (Unless date clicked is before start date, then it swtiches). Focus moves to start date.
* Only finish date exists: click on a date sets start date. (Unless date clicked is after finish date, then it switches), Focus moves to finish date.
* No dates exist: click on a date sets start date, focus moves to finish date.
* For a work package that has a start date, a finish date and thus also a duration, removing one of the dates (start or finish) will also remove the duration.
* Of course, clicking on a second date (or manually adding a second date) will add a new duration and the duration will be changed and all three fields will now be complete.
* This also means that it is not possible to conserve duration when deleting dates, since deleting one date will also delete duration. To remove start and finish dates from a work package that already has these fields but keep the duration, the duration will then have to be re-entered after removing the dates.
* This also means that is not possible to retain both dates _and_ remove the duration. As described in scenario #6 in <mention class="mention" data-id="43539" data-type="work_package" data-text="#43539">#43539</mention>, removing the duration will also remove the finish date.
* Entering a new duration after the after will, then, also add a new finish date (start date + duration).
* Opening the datepicker modal with the new fields will result in the following field being active
* From the work package table, opening the modal:
* by clicking on a start date column cell, the start date is active
* by clicking on a finish date column cell, the finish date is active
* by clicking on a duration column cell, the duration field is active
* by clicking on any cell for a work package with type milestone, the single date field is active
* From the combined edit field, opening the modal:
* will focus the due date IF the start date is set, and finish date and duration is unset.
* will focus the start date otherwise.
### Mini calendar updates
Each calendar day has a few new states:
* **When enabled:**
* In the selected range but a non-working day (blue _feedback/info/dark_ text on a _gray#6_ background)
* **When disabled:**
* In the selected range but a non-working day (_gray#5_ on a _gray#6_ background)
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/37493/content"> <img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/37494/content">
### The "Working days" toggle set
The action bar has a new toggle set:
* By default, "Work week" is selected and non-working days, as defined in the admin settings, are not included in calculation of duration (when date ranges include them). In other words, these days are skipped over.
* These non-working days are also non-clickable on the mini calendar.
* Switching the toggle to "Include weekends" overrides this and includes non-working days in the calculation. It also makes these the previously disabled days clickable.
* This removes the grey background on non-working days; all days now look the same as a "normal" day.
* Switching the toggle to "Work week" box reverses this and non-working days become grey again and are skipped in calculations.
* Please refer to the testing scenarios for details on expected behaviour in a variety of different cases: <mention class="mention" data-id="43539" data-type="work_package" data-text="#43539">#43539</mention>.
### "Working days" and its relation to the start date, finish date and duration
* If a work package already has start and end dates, and thus also duration, and the user enables "Include weekends", the duration is preserved and the dates are updated to include days that were previously skipped.
* If the user goes back to working days only (from previously including weekends) the duration is once again maintained but the finish date is pushed to now skip over the non-working days.
* When "Include weekends" is enabled and the start date is a normally non-working day (eg. Saturday), going back to "Work week" will also push this start date to the first available working day (eg. Monday), moving also the finish date if necessary to maintain duration.
* If a work package only has one set of date information (just start date, just end date, or just duration), changing this toggle will normally not affect any of the values until a second piece of information is also input.
* **Exception:** When "Include weekends" mode enabled and the single date (start _or_ finish) is on a normally non-working day (eg. Saturday), then switching back to "Work week" has to move that date to the first available working day (in the future, Monday in our example).
### Defaults and instance settings
* New work packages have an empty (not set) default duration.
* For new work packages, by default, the toggle will be set to "Work week" and non-working days will not be taken into account when calculating duration by default.
* When migrating to 12.3, when the feature is introduced, all previous work packages will be toggled to "Include weekends" (since non-working days will not have been taken into account in previously created work packages).
* If the admin setting "User current date as start date for new work packages" is enabled and a work package is created on a weekend (and "include weekends" is not manually enabled by the user, so by default "work week" is selected), the start date will be set to the first available _working_ day (and not the weekend day).
* This is because the spirit of that admin setting is to simplify the creation of new work packages by not forcing the user to have to select a date every single time; this base default cannot make an assumption about the user's intention in terms of wanting to include non-working days or not. Creating a work package on a weekend does not necessarily mean that it will be scheduled to start that very day; if we automatically enable 'Include weekends' mode on their behalf without their instruction, this would affect scheduling even if they then select a start date that is normally a working day).
* If the user _meant_ for the work package to start on a weekend _and_ have its duration include weekends, they can the toggle to explicitly enable this mode.
* Updates to journal entries/activity log are described in <mention class="mention" data-id="31992" data-type="work_package" data-text="#31992">#31992</mention> under 'Activity log'.
### Logical changes
* Changing either a date, the duration or the non-working days will have automatic effects on the other fields. The concrete logic is described in <mention class="mention" data-id="43539" data-type="work_package" data-text="#43539">#43539</mention>
* **Technical note:** Ideally this calculation is done by the backend, so that we don't have to repeat it in the frontend.
### Visuals
**Regular scheduling, working days only (default):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38676/content">
**Regular scheduling, include non-working days:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38677/content">
**Banner info - Automatic scheduling (dates derived from children, mini calendar disabled):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38678/content">
**Banner warning - Manual scheduling (with relations):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38679/content">
**Banner info - Dates limited by relations:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38680/content">
**Banner warning - Dates will affect related WPs:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38681/content">
### One-day date picker
The one-day date picker (used for Milestones, for example) does not have a duration field:
**One-day date picker (Milestone):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38682/content">
**One-day date picker with a banner:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38683/content">
### Date-only date picker
Extracted, will be specified in <mention class="mention" data-id="42358" data-type="work_package" data-text="#42358">#42358</mention>.
### Mobile date picker
In the mobile version:
* The date picker is displayed with a dark background and has a consistent margin all around (same as other modals like _Include projects_ and _Project select,_ but without a close button).
* The date picker makes use of the full width available to it, vertically and horizontally. It should be centered on the viewport.
* Horizontal scrolling is not possible.
* The two switches ("Manual scheduling" and "Working dayss
* Each switch set takes the full width of the datepicker
* The text is left-aligned
* The switches are aligned to the right-edge
* The start/finish date fields continue to each take 50% of the width.
* The duration field is moved to a new line
* Only one calendar month is displayed.
* The date picker makes use of the full width available to it, vertically and horizontally. It should be centered on the viewport.
* There is a consistent margin around the date picker (same as other modals like _Include projects_ and _Project select_, with a dark background, but no close button).
* Opening the date picker will dismiss other open modals, and opening another modal will dismiss the date picker. (Only one modal can be open at a time).
The mobile version should be arranged like this (from specs):
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38884/content">
When vertical space is not enough, it should behave like this, so that the action bar on top:
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38885/content">
**Mobile one-day date picker (Milestones):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/38686/content">
### Figma prototypes
Please keep in mind that Figma page has a "(12.3) with Duration" in the title (the 12.2 page looks very similar, so do double-check). When in doubt, follow this link:
https://www.figma.com/file/SMzHAQWcY9k0PkTEKd5UQn/?node-id=1806%3A50629