Skip to content
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.

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

Update readme #264

Merged
merged 2 commits into from
Dec 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
55 changes: 30 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

With ODK Web Forms, you can define forms with powerful logic using the spreadsheet-based [XLSForm standard](https://docs.getodk.org/xlsform/). Use [our Vue-based frontend](/packages/web-forms/) or build your own user experience around [the engine](/packages/xforms-engine/)!

You can try a preview [on the ODK website](https://getodk.org/web-forms-preview/).

> [!IMPORTANT]
> ODK Web Forms is currently pre-release. We don't yet guarantee that its interfaces are stable and it is missing many features that are available in XLSForm form definitions.

Expand All @@ -18,6 +20,8 @@ https://github.com/getodk/web-forms/assets/447837/9b25e1bc-d209-462c-8e9e-3259bd
- [scenario](/packages/scenario): engine client used to express tests on forms
- [ui-solid](/packages/ui-solid): form-filling frontend built with Solid, likely not as up-to-date as the Vue client

Run the preview with `yarn workspace @getodk/web-forms dev`.

## Project status

ODK Web Forms is developed by the [ODK team](https://getodk.org/).
Expand All @@ -42,19 +46,20 @@ This section is auto generated. Please update `feature-matrix.json` and then run
<summary>

<!-- prettier-ignore -->
##### $\texttt{Question types (basic functionality)\hspace{5mm}\color{green}██\color{LightGray}█████████████ \color{initial} 18\\%}$
##### $\texttt{Question types (basic functionality)\hspace{5mm}\color{green}████\color{LightGray}███████████ \color{initial} 29\\%}$

</summary>
<br/>

| Feature <img width=250px/> | Progress |
| -------------------------- | :------: |
| text | ✅ |
| integer | |
| decimal | |
| integer | |
| decimal | |
| note | ✅ |
| select_one | ✅ |
| select_multiple | ✅ |
| select\_\*\_from_file | ✅ |
| repeat | ✅ |
| group | ✅ |
| geopoint | |
Expand All @@ -72,7 +77,7 @@ This section is auto generated. Please update `feature-matrix.json` and then run
| time | |
| datetime | |
| rank | |
| csv-external | |
| csv-external | |
| acknowledge | 🚧 |
| start | |
| end | |
Expand All @@ -89,18 +94,18 @@ This section is auto generated. Please update `feature-matrix.json` and then run
<summary>

<!-- prettier-ignore -->
##### $\texttt{Appearances\hspace{41mm}\color{green}███\color{LightGray}███████████ \color{initial} 24\\%}$
##### $\texttt{Appearances\hspace{41mm}\color{green}███\color{LightGray}███████████ \color{initial} 28\\%}$

</summary>
<br/>

| Feature <img width=250px/> | Progress |
| -------------------------- | :------: |
| numbers | |
| numbers | |
| multiline | |
| url | |
| ex: | |
| thousands-sep | |
| thousands-sep | |
| bearing | |
| vertical | |
| no-ticks | |
Expand Down Expand Up @@ -137,6 +142,7 @@ This section is auto generated. Please update `feature-matrix.json` and then run
| label | ✅ |
| list-nolabel | ✅ |
| list | ✅ |
| counter | |

</details>

Expand Down Expand Up @@ -193,28 +199,27 @@ This section is auto generated. Please update `feature-matrix.json` and then run
<summary>

<!-- prettier-ignore -->
##### $\texttt{Descriptions and Annotations\hspace{14mm}\color{green}███\color{LightGray}████████████ \color{initial} 20\\%}$
##### $\texttt{Descriptions and Annotations\hspace{14mm}\color{green}███\color{LightGray}████████████ \color{initial} 21\\%}$

</summary>
<br/>

| Feature <img width=250px/> | Progress |
| ---------------------------------------------- | :------: |
| label | ✅ |
| hint | ✅ |
| guidance hint | |
| Translations | ✅ |
| Translations with field/question value | |
| Markdown | |
| Inline HTML | |
| Form attachments | |
| image | |
| big-image | |
| audio | |
| video | |
| secondary instance (external choice file<br/>) | |
| secondary instance (last saved) | |
| autoplay | |
| Feature <img width=250px/> | Progress |
| -------------------------------------- | :------: |
| label | ✅ |
| hint | ✅ |
| guidance hint | |
| Translations | ✅ |
| Translations with field/question value | |
| Markdown | |
| Inline HTML | |
| Form attachments | |
| image | |
| big-image | |
| audio | |
| video | |
| secondary instance (last saved) | |
| autoplay | |

</details>

Expand Down
15 changes: 8 additions & 7 deletions feature-matrix.json
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
{
"Question types (basic functionality)": {
"text": "✅",
"integer": "",
"decimal": "",
"integer": "",
"decimal": "",
"note": "✅",
"select_one": "✅",
"select_multiple": "✅",
"select_*_from_file": "✅",
Copy link
Member

Choose a reason for hiding this comment

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

Since it appears we missed this before, I'm concerned that we've missed others. Not the biggest deal if we're updating it as we go, but definitely doesn't make me feel very confident in using this as a basis for programmatic form feature support detection.

Copy link
Member Author

Choose a reason for hiding this comment

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

I think it was put as part of secondary instance (external choice file) in another section. I went ahead and removed that in a new commit since I think this will be more useful for users.

The XLSForm template is intended to be authoritative but it doesn't include everything that's here because it's not all relevant to XLSForm authoring. I find this format and content pretty useful but let's definitely discuss other ideas you have!

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 using the XLSForm template might be a great starting point for programmatic concerns, and would probably help narrow down cross referencing with this as a companion source of truth.

"repeat": "✅",
"group": "✅",
"geopoint": "",
Expand All @@ -23,7 +24,7 @@
"time": "",
"datetime": "",
"rank": "",
"csv-external": "",
"csv-external": "",
"acknowledge": "🚧",
"start": "",
"end": "",
Expand All @@ -35,11 +36,11 @@
"audit": ""
},
"Appearances": {
"numbers": "",
"numbers": "",
"multiline": "",
"url": "",
"ex:": "",
"thousands-sep": "",
"thousands-sep": "",
"bearing": "",
"vertical": "",
"no-ticks": "",
Expand Down Expand Up @@ -75,7 +76,8 @@
"field-list": "✅",
"label": "✅",
"list-nolabel": "✅",
"list": "✅"
"list": "✅",
"counter": ""
Copy link
Member

Choose a reason for hiding this comment

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

I had never heard of this appearance before today—first in the meeting doc about design revisions for numeric inputs, now here. I don't see it in the XLSForm Docs, but from the meeting doc it sounds like the expectation is implemented (at least partly? increment/decrement buttons). Although I guess we'd want to explicitly account for (== implement it) it so we don't regress if we decide to limit that presentation for inputs without a counter appearance. I'm fine with leaving it unchecked here if that's the intent, but wanted to note my surprise at its addition.

I also think this emphasizes my caution about treating this as a starting point for building out some sort of programmatic form feature support detection. In this case, it isn't just a gap in what we're tracking. It also implicates cross-referencing at least one other project beyond the XLSForm Docs. I see it was added relatively recently, but now I also see other appearances there which aren't in the XLSForm Docs and weren't added as recently.

Copy link
Member Author

Choose a reason for hiding this comment

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

It was in the originalinteger issue and I probably should have at least mentioned it in review: #251 I think we need to figure out the design for the no-appearance question type and then go from there.

The authoritative sources of appearances are the XLSForm template and the ODK docs.

If you do see something missing from somewhere, please file an issue!

Copy link
Member

Choose a reason for hiding this comment

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

Ah, I totally glazed over it in #251! I saw the reference to Enketo's presentation and probably stopped there. (Likely because the increment/decrement presentation is a de facto default on the web, as it's the default presentation for <input type="number"> in many cases.)

},
"Parameters": {
"randomize": "✅",
Expand Down Expand Up @@ -115,7 +117,6 @@
"big-image": "",
"audio": "",
"video": "",
"secondary instance (external choice file)": "",
"secondary instance (last saved)": "",
"autoplay": ""
},
Expand Down
Loading