Skip to content

docs: add datepicker dateType property to input schema #1227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Nov 14, 2024
Merged

docs: add datepicker dateType property to input schema #1227

Changes from 3 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
202ef8e
docs: add datepicker isAbsolute/isRelative options
mfori Sep 25, 2024
2c0e0a1
mention supported relative units
mfori Sep 25, 2024
703212f
change isAbsolute/isRelative to allowAbsolute/allowRelative
mfori Sep 27, 2024
ab0126c
Merge branch 'refs/heads/master' into feat/datepicker-absolute-relative
mfori Oct 11, 2024
8467240
better description and example of input rendering
mfori Oct 11, 2024
d2f0598
address PR comments
mfori Oct 12, 2024
e45ca6a
replace allowAbsolute/allowRelative properties with dateType
mfori Oct 30, 2024
bdacb5d
add pattern to all example properties
mfori Oct 31, 2024
5d55dc0
Update sources/platform/actors/development/actor_definition/input_sch…
mfori Oct 31, 2024
bd909f5
Update sources/platform/actors/development/actor_definition/input_sch…
mfori Oct 31, 2024
551d105
Update sources/platform/actors/development/actor_definition/input_sch…
mfori Oct 31, 2024
d774d41
reformat
mfori Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions sources/platform/actors/development/actor_definition/input_schema/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,16 +183,18 @@ Rendered input:

Properties:

| Property | Value | Required | Description |
| --- | --- | --- | --- |
| `editor` | One of <ul><li>`textfield`</li><li>`textarea`</li><li>`javascript`</li><li>`python`</li><li>`select`</li><li>`datepicker`</li><li>`hidden`</li></ul> | Yes | Visual editor used for <br/>the input field. |
| `pattern` | String | No | Regular expression that will be <br/>used to validate the input. <br/> If validation fails, <br/>the Actor will not run. |
| `minLength` | Integer | No | Minimum length of the string. |
| `maxLength` | Integer | No | Maximum length of the string. |
| `enum` | [String] | Required if <br/>`editor` <br/>is `select` | Using this field, you can limit values <br/>to the given array of strings. <br/>Input will be displayed as select box. |
| `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. |
| Property | Value | Required | Description |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `editor` | One of <ul><li>`textfield`</li><li>`textarea`</li><li>`javascript`</li><li>`python`</li><li>`select`</li><li>`datepicker`</li><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li><li>`hidden`</li></ul> | Yes | Visual editor used for <br/>the input field. |
| `pattern` | String | No | Regular expression that will be <br/>used to validate the input. <br/> If validation fails, <br/>the Actor will not run. |
| `minLength` | Integer | No | Minimum length of the string. |
| `maxLength` | Integer | No | Maximum length of the string. |
| `enum` | [String] | Required if <br/>`editor` <br/>is `select` | Using this field, you can limit values <br/>to the given array of strings. <br/>Input will be displayed as select box. |
| `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`. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@gippy gippy Oct 9, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, that makes sense then.

| `allowRelative` | Boolean | No | Used only with `datepicker` editor for relative input in form `+/- {number} {unit}` e.g. `+ 3 weeks`. 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. |

:::note Regex escape

Expand Down