From d7f86ee78eefe2094927082209cf79e1ba616be7 Mon Sep 17 00:00:00 2001
From: Ronald Brill <rbri@rbri.de>
Date: Tue, 10 Oct 2023 20:54:22 +0200
Subject: [PATCH] more form usage documentation (#647) (wip)

---
 src/site/xdoc/gettingStarted.xml | 45 ++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/src/site/xdoc/gettingStarted.xml b/src/site/xdoc/gettingStarted.xml
index bfe0cef1fb7..06ea893405b 100644
--- a/src/site/xdoc/gettingStarted.xml
+++ b/src/site/xdoc/gettingStarted.xml
@@ -81,6 +81,51 @@ public void submittingForm() throws Exception {
         final HtmlPage page2 = button.click();
     }
 }]]></source>
+
+            <subsection name="Finding form elements">
+                <p>
+                    For filling out a form you first have to find the form elements you like to interact with.
+                </p>
+            <source><![CDATA[
+final HtmlTextInput textField = form.getInputByName("userid");]]></source>
+                <p>
+                    In addition to all the general ways of finding dom elements (see <a href="#Finding_a_specific_element">below</a>) the HtmlForm object
+                    offers some convenient methods to find form elements:
+                </p>
+                <ul>
+                    <li>HtmlForm.getButtonByName(String)</li>
+                    <li>HtmlForm.getButtonsByName(String)</li>
+                    <li>HtmlForm.getCheckedRadioButton(String)</li>
+                    <li>HtmlForm.getInputByName(String)</li>
+                    <li>HtmlForm.getInputByValue(String)</li>
+                    <li>HtmlForm.getInputsByName(String)</li>
+                    <li>HtmlForm.getInputsByValue(String)</li>
+                    <li>HtmlForm.getRadioButtonsByName(String)</li>
+                    <li>HtmlForm.getSelectByName(String)</li>
+                    <li>HtmlForm.getSelectsByName(String)</li>
+                    <li>HtmlForm.getTextAreaByName(String)</li>
+                    <li>HtmlForm.getTextAreasByName(String)</li>
+                    <li>HtmlForm.getElements()</li>
+                </ul>
+                <p>
+                    All these methods are working based on a list of all dom elements associated with this form -
+                    this list includes all descendants of the form element AND all other elements associated to
+                    this form using the 'form' attribute. In general the method HtmlForm.getElements() builds this
+                    list and all other methods using this list as base for more filtering.
+                </p>
+            </subsection>
+
+            <subsection name="Text input">
+                <p>
+                    Todo
+                </p>
+            </subsection>
+
+            <subsection name="Radio buttons and checkboxes">
+                <p>
+                    Todo
+                </p>
+            </subsection>
         </section>
 
         <section name="Imitating a specific browser">