Merge pull request #1220 from RedZone908/form_documentation_enhancements

FlorianRappl · web-flow · commit 4f3f1aaf5fa0 · 2025-03-25T00:46:23.000+01:00
Form documentation enhancements
diff --git a/docs/tutorials/04-Forms.md b/docs/tutorials/04-Forms.md
@@ -30,6 +30,15 @@ if (queryInput != null)
 
 The latter version is much more verbose and requires additional checking on our side. The upside of this version is that we can also treat the error case (i.e., the expected field with the name `q` is not found or is not an `IHtmlInputElement`), which is completely ignored in the former version.
 
+Some webpages will not handle the form submission correctly unless it is triggered from a specific control on the page. This can be done like:
+
+``` cs
+// first research how to identify the submit element on the page you're working with, then...
+IHtmlInputElement submitButton = queryDocument.QuerySelection<IHtmlInputElement>("#submitbutton");
+IDocument resultDocument = await form.SubmitAsync(submitButton);
+```
+Note that the above scenario requires setting the form values via the more verbose mechanism.
+
 An important aspect of submitting forms is that we require at least a default loader. Forms usually require making an HTTP request for loading a new document (mostly using the POST verb), which yields the demand for having a requester configured upfront. Note that sometimes forms even come with stronger requirements, especially if they are properly secured. In such cases the use of `WithCookies()` to configure a cookie container could be mandatory.
 
 The code for using a cookie container looks almost identical:
diff --git a/docs/tutorials/06-Questions.md b/docs/tutorials/06-Questions.md
@@ -188,6 +188,8 @@ var input = document.QuerySelector<IHtmlInputElement>("input[type=file][name=myI
 input?.Files.Add(file);
 ```
 
+Depending on the webpage, you may also need to set `input.Value` to the name of the file, or alternatively set it in `SubmitAsync()`'s overload that accepts the form values. If your file-based form submission results in a `System.NullReferenceException` from `HtmlFormElement.SubmitAsync()`, that indicates that `input.Value` is what is missing.
+
 In the previously used example the file variable refers to any IFile instance. AngleSharp is a PCL does not come with a proper implementation out of the box, however, a simple one may look like:
 
 ```cs
