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

Show file tree
Hide file tree
Changes from 5 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
Binary file added ...development/actor_definition/input_schema/images/input-schema-date-absolute.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...ors/development/actor_definition/input_schema/images/input-schema-date-both.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...development/actor_definition/input_schema/images/input-schema-date-relative.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
62 changes: 52 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 @@ -181,18 +181,60 @@ Rendered input:

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

Example of date selection using absolute and relative `datepicker` editor:

```json
{
"absolute_date": {
"title": "Date",
"type": "string",
"description": "Select date",
"editor": "datepicker"
},
"relative_date": {
"title": "Relative date",
"type": "string",
"description": "Select date",
"editor": "datepicker",
"allowAbsolute": false,
"allowRelative": true
},
"any_date": {
"title": "Any date",
"type": "string",
"description": "Select date",
"editor": "datepicker",
"allowRelative": true
}
}
```

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`:
Copy link
Contributor

@TC-MO TC-MO Oct 11, 2024

Choose a reason for hiding this comment

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

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`.

Copy link
Member

@mtrunkat mtrunkat Oct 11, 2024

Choose a reason for hiding this comment

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

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


![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`):
Copy link
Contributor

@TC-MO TC-MO Oct 11, 2024

Choose a reason for hiding this comment

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

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.

Copy link
Member

@mtrunkat mtrunkat Oct 11, 2024

Choose a reason for hiding this comment

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

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.


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

Rendered input for `any_date` property. The date picker allows selecting both absolute and relative dates, and it's up to the Actor author to parse recognize the chosen form:

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

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>`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`. |
| `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. |
Copy link
Contributor

@TC-MO TC-MO Oct 11, 2024

Choose a reason for hiding this comment

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

Suggested change
| `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. |
| `allowRelative` | Boolean | No | Enables relative date input in <br/>`+/- {number} {unit}` format. <br/>Supported units are: days, weeks, months, years. <br/><br/>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. |

Copy link
Member

@mtrunkat mtrunkat Oct 11, 2024

Choose a reason for hiding this comment

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

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

Copy link
Member Author

@mfori mfori Oct 12, 2024

Choose a reason for hiding this comment

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

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

Screenshot 2024-10-13 at 0 17 59


:::note Regex escape

Expand Down