Skip to content

Document the FormData constructor submitter parameter#23950

Merged
Elchi3 merged 5 commits intomdn:mainfrom
jenseng:form-data-submitter
Mar 14, 2023
Merged

Document the FormData constructor submitter parameter#23950
Elchi3 merged 5 commits intomdn:mainfrom
jenseng:form-data-submitter

Conversation

@jenseng
Copy link
Copy Markdown
Contributor

@jenseng jenseng commented Jan 28, 2023

Description

Document the FormData constructor submitter parameter.

Also add a "Submit button" glossary page and link to it from various places to help facilitate a consistent and complete understanding of what a submit button is :)

Motivation

This is a new feature which is landing in major browsers soon, so it would be useful to have it documented.

Additional details

Spec: https://xhr.spec.whatwg.org/#interface-formdata
Spec PR (merged): whatwg/xhr#366
Chromium implementation (landing in Chrome 112): https://chromium-review.googlesource.com/c/chromium/src/+/4189297
WebKit implementation (landing in Safari 16.4): WebKit/WebKit#9188
Gecko implementation (landing in Firefox 111): https://phabricator.services.mozilla.com/D167576

Related issues and pull requests

Fixes #23917

@jenseng jenseng requested review from a team as code owners January 28, 2023 06:59
@jenseng jenseng requested review from Elchi3, jpmedley and schalkneethling and removed request for a team January 28, 2023 06:59
@github-actions github-actions bot added Content:Glossary Glossary entries Content:HTML Hypertext Markup Language docs Content:Learn Learning area docs Content:WebAPI Web API docs labels Jan 28, 2023
@jenseng jenseng force-pushed the form-data-submitter branch from 2d730c6 to de47be4 Compare January 28, 2023 07:01
@jenseng
Copy link
Copy Markdown
Contributor Author

jenseng commented Jan 28, 2023

Here's what the example looks like in bleeding edge WebKit w/ submitter support:

safari-submitter

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 30, 2023

Preview URLs (7 pages)
Flaws (1)

Note! 6 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/FormData/FormData
Title: FormData()
Flaw count: 1

  • broken_links:
    • Anchor not lowercase
External URLs (1)

URL: /en-US/docs/Mozilla/Firefox/Releases/111
Title: Firefox 111 for developers

(comment last updated: 2023-03-13 15:01:57)

@jenseng jenseng force-pushed the form-data-submitter branch from de47be4 to e88099d Compare January 30, 2023 16:12
@jenseng
Copy link
Copy Markdown
Contributor Author

jenseng commented Jan 30, 2023

cc @annevk

- : An HTML {{HTMLElement("form")}} element — when specified, the {{domxref("FormData")}} object will be populated with the form's current keys/values using the name property of each element for the keys and their submitted value for the values. It will also encode file input content.
- : An HTML {{HTMLElement("form")}} element — when specified, the {{domxref("FormData")}} object will be populated with the `form`'s current keys/values using the name property of each element for the keys and their submitted value for the values. It will also encode file input content.
- `submitter` {{optional_inline}}
- : A {{Glossary("submit button")}} that is a member of the `form`. If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '<input type="image">')}}`, it will be included in the form data set.
Copy link
Copy Markdown
Collaborator

@jpmedley jpmedley Jan 30, 2023

Choose a reason for hiding this comment

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

Suggested change
- : A {{Glossary("submit button")}} that is a member of the `form`. If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '<input type="image">')}}`, it will be included in the form data set.
- : A {{Glossary("submit button")}} that is a member of the `form`. If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '<input type="image">')}}`, the value of the name attribute will be included in the form data set.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This might be misleading, as that could be understood to mean the value attribute. While the name + value are included for a <button> or <input type="submit">, that's not the case for an <input type="image"> (i.e. value is unused and instead you get two entries for the x/y coordinate).

Maybe we could say something like ..., its value(s) will be included ..., wdyt?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Or we could split it into two sentences, like on the Submit button page. Or perhaps keep the original wording but have will be included link directly to the relevant Form data entries heading on the Submit button page.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I changed the wording slightly.

Copy link
Copy Markdown
Contributor Author

@jenseng jenseng Jan 31, 2023

Choose a reason for hiding this comment

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

Hmm, that's still not quite accurate, as name-less image inputs will add entries to the form data set. e.g. clicking <input type="image" /> will yield something like x=123&y=234

How about this wording tweak, which also adds an example for the common case?

A {{Glossary("submit button")}} that is a member of the `form`. If the `submitter`
has a `name` attribute or is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`,
its data [will be included](...) in the form data set (e.g. `buttonName=buttonValue`).

will be included would link directly to the relevant explainer on the Submit button page.

@github-actions
Copy link
Copy Markdown
Contributor

This pull request has merge conflicts that must be resolved before it can be merged.

@github-actions github-actions bot added the merge conflicts 🚧 [PR only] label Mar 3, 2023
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 3, 2023

This pull request has merge conflicts that must be resolved before it can be merged.

@jenseng jenseng force-pushed the form-data-submitter branch from e88099d to b763944 Compare March 9, 2023 20:41
@github-actions github-actions bot removed the merge conflicts 🚧 [PR only] label Mar 9, 2023
@jenseng
Copy link
Copy Markdown
Contributor Author

jenseng commented Mar 9, 2023

Rebased and made some wording tweaks, also added some more links. LMK what you think @jpmedley, thanks!

@github-actions github-actions bot added the Content:Other Any docs not covered by another "Content:" label label Mar 9, 2023
@jenseng
Copy link
Copy Markdown
Contributor Author

jenseng commented Mar 9, 2023

Added a entry for the firefox 111 release when this is landing

@jenseng jenseng requested review from jpmedley and removed request for Elchi3 and schalkneethling March 10, 2023 22:54
@github-actions github-actions bot added the merge conflicts 🚧 [PR only] label Mar 12, 2023
@github-actions
Copy link
Copy Markdown
Contributor

This pull request has merge conflicts that must be resolved before it can be merged.

jenseng added 4 commits March 12, 2023 14:22
Also add a "Submit button" glossary page and link to it from various places
to help facilitate a consistent and correct understanding of what a submit
button is :)

Spec PR (merged): whatwg/xhr#366
Spec: https://xhr.spec.whatwg.org/#interface-formdata
Copy link
Copy Markdown
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

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

Thank you! Great work 👍

@Elchi3 Elchi3 merged commit 37370d5 into mdn:main Mar 14, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Content:Glossary Glossary entries Content:HTML Hypertext Markup Language docs Content:Learn Learning area docs Content:Other Any docs not covered by another "Content:" label Content:WebAPI Web API docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document FormData constructor submitter parameter

4 participants