docs: add datepicker dateType property to input schema #1227

mfori · 2024-09-25T13:32:56Z

Add new datepicker ~~allowAbsolute and allowRelative options~~ dateType property to input schema specification.
This is based on this issue: https://github.com/apify/apify-core/issues/15662 and part of

~~Input schema PR: feat(input_schema): datepicker allowAbsolute/allowRelative properties and validation apify-shared-js#477~~
Input schema PR: feat(input_schema): datepicker dateType property apify-shared-js#485
(app) AdvancedDatePicker PR: https://github.com/apify/apify-core/pull/17465

This one will be merged as the last one.

drobnikj

Thing I found in other PR.

sources/platform/actors/development/actor_definition/input_schema/specification.md

drobnikj · 2024-09-26T14:37:09Z

Just note to do not fofget, the params were changes from is* to allow*

TC-MO

LGTM

… and validation (#477) This PR introduce new input_schema properties `allowAbsolute` and `allowRelative` used when the `editor` property is set to `datepicker`: - the `schema.json` is updated in the way, that properties `allowAbsolute` and `allowRelative` are valid only when `editor` is `datepicker`, `allowAbsolute` is considered as default and any of `allowAbsolute` or `allowRelative` is true - value format validation - unit tests for schema validation and value validation - New datepicker with support for absolute and relative dates PR: apify/apify-core#17465 - Docs PR: apify/apify-docs#1227 --------- Co-authored-by: Martin Adámek <[email protected]>

mtrunkat · 2024-10-08T09:57:29Z

sources/platform/actors/development/actor_definition/input_schema/specification.md

+| `enumTitles`    | [String]                                                                                                                                                                                                              | No                                         | Titles for the `enum` keys described.                                                                                                                                                                                                                                                          |
+| `nullable`      | Boolean                                                                                                                                                                                                               | No                                         | Specifies whether `null` <br/>is an allowed value.                                                                                                                                                                                                                                             |
+| `isSecret`      | Boolean                                                                                                                                                                                                               | No                                         | Specifies whether the input field<br />will be stored encrypted.<br />Only available <br />with `textfield` and `textarea` editors.                                                                                                                                                            |
+| `allowAbsolute` | Boolean                                                                                                                                                                                                               | No                                         | Used only with `datepicker` editor for absolute date value picker in form `YYYY-MM-DD`. This defaults to `true`.                                                                                                                                                                               |


The properties are fine, but I don't understand what they mean well. Perhaps there should be better explanation. Is it:

If I enable allow absolute then I am able to pick certain date

If I enable allow relative then I can type "3 months"??
But what is the returned value is what? Always a date in ISO format?

Yep, the docs could be improved. The value is always string.

If you set allowAbsolute true (which is the default value, so you do not have to set it), then the datepicker allows user to select a date from a calendar and the final value is stored in YYYY-MM-DD format and also validated like this.

If you pick allowRelative true (which is not the default value), then the datepicker allows user to enter a value in a format +- <number> <unit> and the final string value in the field is validated against this format.

If you have both set to true, then in the UI you can choose which format you want to use.
It's then up to the actor to correctly parse the value, but it will be validated in UI and in API.

The reason for this logic is that store team needs to have a single field that can be switched between absolute date like 2024-10-08 and relative option - 3 days. For example when you want comments on a post from a specific day or for last 3 days relative to when the actor started. They do not want to use two fields because that can then cause confusion.

They currently work around this by having a single string field with no validation (or regex). This should allow them to validate the values correctly and help users enter the correct values in a standardized format.

By default if you do not set any of these two properties, the datepicker will behave exactly the same as before and only show a single field with calendar in popover.

I think the allowRelative explanation is good, but the allowAbsolute can be improved. Also could maybe show an example like we do it for other more complicated fields.

So, in this case, we should have 2 different editors or "resources types". You should not have varying outputs from a single component.

Like one function should always return either date object or relative string but not both.

But the main requirement from store team is to have a single field, so it's one editor, which can return two different resource types based on users choice, but not both at the same time. Author of the actor can choose which options to allow

Ok, that makes sense then.

# Conflicts: # sources/platform/actors/development/actor_definition/input_schema/specification.md

mfori · 2024-10-11T06:13:02Z

Added also example as we have with some other editors:

TC-MO

few rewrites for clarity & consistency with the rest of the docs

sources/platform/actors/development/actor_definition/input_schema/specification.md

TC-MO · 2024-10-11T08:40:32Z

sources/platform/actors/development/actor_definition/input_schema/specification.md

+| `nullable`      | Boolean                                                                                                                                              | No                                         | Specifies whether `null` <br/>is an allowed value.                                                                                                                                                                                                                                                                                                                                                  |
+| `isSecret`      | Boolean                                                                                                                                              | No                                         | Specifies whether the input field<br />will be stored encrypted.<br />Only available <br />with `textfield` and `textarea` editors.                                                                                                                                                                                                                                                                 |
+| `allowAbsolute` | Boolean                                                                                                                                              | No                                         | Used only with `datepicker` editor for absolute date value picker in form `YYYY-MM-DD`. This defaults to `true`.                                                                                                                                                                                                                                                                                    |
+| `allowRelative` | Boolean                                                                                                                                              | No                                         | Used only with `datepicker` editor for relative input in form `+/- {number} {unit}`.<br/>The value passed to Actor input is in plain text  e.g. `"+ 3 weeks"` and it's up to Actor author to parse it.<br/>Supported units are: days, weeks, months and years.<br/>If only relative input is required, `allowAbsolute` needs to be explicitly set to `false`, otherwise both formats are supported. |


Suggested change

| `allowRelative` | Boolean | No | Used only with `datepicker` editor for relative input in form `+/- {number} {unit}`. The value passed to Actor input is in plain text e.g. `"+ 3 weeks"` and it's up to Actor author to parse it. Supported units are: days, weeks, months and years. If only relative input is required, `allowAbsolute` needs to be explicitly set to `false`, otherwise both formats are supported. |

| `allowRelative` | Boolean | No | Enables relative date input in `+/- {number} {unit}` format. Supported units are: days, weeks, months, years. The input is passed to the Actor as plain text (e.g., "+3 weeks"). Set `allowAbsolute` to `false` to allow only relative input, otherwise both formats are supported. Only available with `datepicker` editor. |

Can we also recommend here a library we use to parse this? It's docs for devs so let's give them some hints.

I added regex that can be used to parse the relative value:

TC-MO · 2024-10-11T09:11:45Z

sources/platform/actors/development/actor_definition/input_schema/specification.md

+}
+```
+
+Rendered input for `absolute_date` property. See that by default, the date picker allows selecting only an absolute date in the form `YYYY-MM-DD`:


Suggested change

Rendered input for `absolute_date` property. See that by default, the date picker allows selecting only an absolute date in the form `YYYY-MM-DD`:

The `absolute_date` property renders a date picker that allows selection of a specific date in the format `YYYY-MM-DD`.

Also, I'd stress here that this is the value returned by the field. See comment bellow.

TC-MO · 2024-10-11T09:11:57Z

sources/platform/actors/development/actor_definition/input_schema/specification.md

+
+![Apify Actor input schema - country input](./images/input-schema-date-absolute.png)
+
+Rendered input for `relative_date` property in form of `+/- {number} {unit}`. (The `allowAbsolute` is explicitly set to `false`):


Suggested change

Rendered input for `relative_date` property in form of `+/- {number} {unit}`. (The `allowAbsolute` is explicitly set to `false`):

The `relative_date` property renders an input field that accepts dates in the `+/- {number} {unit}`. nthe `allowAbsolute` parameter is set to `false` to restrict input to relative dates only.

IMHO, to make this clear, we should write that

...renders an input field that enables the user to choose the relative date and returns the value in the format +/- {number} {unit}, for example, + 2 days.

This is a documentation for Actor developers so we need to focus on what is returned by the field which is what they work with.

sources/platform/actors/development/actor_definition/input_schema/specification.md

mfori · 2024-10-12T22:21:29Z

sources/platform/actors/development/actor_definition/input_schema/specification.md

jancurn

Looks good, thanks, just last small changes

sources/platform/actors/development/actor_definition/input_schema/specification.md

mfori · 2024-10-31T09:42:11Z

We have changed allowAbsolute/allowRelative properties to single property dateType with options absolute, relative and absoluteOrRelative as proposed here: https://apify.slack.com/archives/C010Q0FBYG3/p1730210649660309?thread_ts=1728907212.870409&cid=C010Q0FBYG3

So I will ask you for one more review round 🙏 😁

jancurn

Great stuff, thank you

sources/platform/actors/development/actor_definition/input_schema/specification.md

…ema/specification.md Co-authored-by: Michał Olender <[email protected]>

This PR replace `allowAbsolute`/`allowRelative` boolean properties for datepicker with single `dateType` property that accepts values `absolute`, `relative` and `absoluteOrRelative` based on: - apify/apify-docs#1227 - https://apify.slack.com/archives/C010Q0FBYG3/p1730210649660309?thread_ts=1728907212.870409&cid=C010Q0FBYG3 `dateType` property: - is optional - is valid only when `editor` is `datepicker` - is only for ui input representation, no validation is executed based on this property

docs: add datepicker isAbsolute/isRelative options

202ef8e

mfori added documentation Improvements or additions to documentation. t-console Issues with this label are in the ownership of the console team. labels Sep 25, 2024

mfori requested review from TC-MO and gippy September 25, 2024 13:32

mfori self-assigned this Sep 25, 2024

github-actions bot added this to the 99th sprint - Console team milestone Sep 25, 2024

mfori mentioned this pull request Sep 25, 2024

feat(input_schema): datepicker allowAbsolute/allowRelative properties and validation apify/apify-shared-js#477

Merged

drobnikj requested changes Sep 25, 2024

View reviewed changes

sources/platform/actors/development/actor_definition/input_schema/specification.md Outdated Show resolved Hide resolved

mention supported relative units

2c0e0a1

mfori requested a review from drobnikj September 25, 2024 15:02

change isAbsolute/isRelative to allowAbsolute/allowRelative

703212f

mfori changed the title ~~docs: add datepicker isAbsolute/isRelative options~~ docs: add datepicker allowAbsolute/allowRelative options Sep 27, 2024

TC-MO approved these changes Sep 27, 2024

View reviewed changes

gippy approved these changes Sep 27, 2024

View reviewed changes

drobnikj approved these changes Sep 30, 2024

View reviewed changes

mfori requested review from mtrunkat and netmilk October 7, 2024 14:17

mtrunkat requested changes Oct 8, 2024

View reviewed changes

mfori added 2 commits October 11, 2024 07:34

Merge branch 'refs/heads/master' into feat/datepicker-absolute-relative

ab0126c

# Conflicts: # sources/platform/actors/development/actor_definition/input_schema/specification.md

better description and example of input rendering

8467240

mfori requested review from TC-MO and mtrunkat October 11, 2024 06:13

TC-MO requested changes Oct 11, 2024

View reviewed changes

address PR comments

d2f0598

mfori requested a review from TC-MO October 12, 2024 22:21

TC-MO approved these changes Oct 18, 2024

View reviewed changes

mtrunkat approved these changes Oct 23, 2024

View reviewed changes

netmilk approved these changes Oct 24, 2024

View reviewed changes

jancurn requested changes Oct 29, 2024

View reviewed changes

replace allowAbsolute/allowRelative properties with dateType

e45ca6a

jancurn reviewed Oct 30, 2024

View reviewed changes

sources/platform/actors/development/actor_definition/input_schema/specification.md Outdated Show resolved Hide resolved

sources/platform/actors/development/actor_definition/input_schema/specification.md Outdated Show resolved Hide resolved

add pattern to all example properties

bdacb5d

mfori requested review from TC-MO, jancurn, mtrunkat and netmilk October 31, 2024 09:42

mtrunkat approved these changes Oct 31, 2024

View reviewed changes

jancurn approved these changes Oct 31, 2024

View reviewed changes

TC-MO requested changes Oct 31, 2024

View reviewed changes

mfori and others added 4 commits October 31, 2024 13:32

Update sources/platform/actors/development/actor_definition/input_sch…

5d55dc0

…ema/specification.md Co-authored-by: Michał Olender <[email protected]>

Update sources/platform/actors/development/actor_definition/input_sch…

bd909f5

…ema/specification.md Co-authored-by: Michał Olender <[email protected]>

Update sources/platform/actors/development/actor_definition/input_sch…

551d105

…ema/specification.md Co-authored-by: Michał Olender <[email protected]>

reformat

d774d41

mfori requested a review from TC-MO October 31, 2024 12:37

TC-MO approved these changes Oct 31, 2024

View reviewed changes

mfori changed the title ~~docs: add datepicker allowAbsolute/allowRelative options~~ docs: add datepicker dateType property to input schema Nov 1, 2024

mfori mentioned this pull request Nov 1, 2024

feat(input_schema): datepicker dateType property apify/apify-shared-js#485

Merged

mfori merged commit b923891 into master Nov 14, 2024
11 checks passed

mfori deleted the feat/datepicker-absolute-relative branch November 14, 2024 19:23

	Rendered input for `absolute_date` property. See that by default, the date picker allows selecting only an absolute date in the form `YYYY-MM-DD`:
	The `absolute_date` property renders a date picker that allows selection of a specific date in the format `YYYY-MM-DD`.


		![Apify Actor input schema - country input](./images/input-schema-date-absolute.png)

		Rendered input for `relative_date` property in form of `+/- {number} {unit}`. (The `allowAbsolute` is explicitly set to `false`):

	Rendered input for `relative_date` property in form of `+/- {number} {unit}`. (The `allowAbsolute` is explicitly set to `false`):
	The `relative_date` property renders an input field that accepts dates in the `+/- {number} {unit}`. nthe `allowAbsolute` parameter is set to `false` to restrict input to relative dates only.

docs: add datepicker dateType property to input schema #1227

docs: add datepicker dateType property to input schema #1227

Uh oh!

Conversation

mfori commented Sep 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drobnikj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

drobnikj commented Sep 26, 2024

Uh oh!

TC-MO left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gippy Oct 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfori commented Oct 11, 2024

Uh oh!

TC-MO left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfori commented Oct 12, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jancurn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mfori commented Oct 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jancurn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

mfori commented Sep 25, 2024 •

edited

Loading

gippy Oct 9, 2024 •

edited

Loading

mfori commented Oct 31, 2024 •

edited

Loading