mor about form element handling and a bunch of typos fixed

src/site/xdoc/codingConventions.xml

@@ -31,15 +31,15 @@
         <section name="Unit tests">
             <p>
                 All code must have 100% automated test coverage using the <a href="http://www.junit.org">JUnit</a>
-                testing framework.  It is strongly suggested that you write the code test-first but it is fine
+                testing framework.  It is strongly suggested that you write the code test-first, but it is fine
                 as long as there are full tests for everything.  Run the tests with the following target:
                 <source>mvn test</source>
             </p>
         </section>
 
         <section name="Abbreviations">
             <p>
-                Abbreviations obscure meaning and therefore they are not to be used in variable/method names.
+                Abbreviations obscure meaning, and therefore they are not to be used in variable/method names.
                 If you saw the following code, would you have any idea what it was doing?
             </p>
             <source>cob.getTrh()</source>
@@ -152,7 +152,7 @@ import java.util.ArrayList;
                 deprecate the existing API (using the javadoc @deprecated tag). Code deprecated in
                 this way should be left in the source for at least 6 months and at least 2 releases,
                 meaning the time could be longer than 6 months if there are not 2 releases in a
-                6 month period but never less than 6 months.
+                6 month' period but never less than 6 months.
 
                 When deprecation is not possible a <a href="changes-report.html">change log</a> message
                 containing "INCOMPATIBLE CHANGE" should be added to make these changes easy to find.

src/site/xdoc/details.xml

@@ -98,7 +98,7 @@ client .getPage(wr);
 
         <section name="Animations based on Window.requestAnimationFrame()"  id="animations">
             <p>
-                All browsers supporded by HtmlUnit are able to do animations based on the
+                All browsers supported by HtmlUnit are able to do animations based on the
                 <a href='https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame'>Window.requestAnimationFrame() API</a>.
                 A typical example for this is <a href='https://www.chartjs.org/'>Chart.js</a>.
                 This kind of animation support is not triggered automatically because HtmlUnit is headless.
@@ -114,7 +114,7 @@ try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
 
     // page is loaded and async js done
 
-    // we now processing the animation
+    // we are now processing the animation
     Window window = page.getEnclosingWindow().getScriptableObject();
     int i = 0; // to be able to limit the animation cycles
     do {
@@ -138,7 +138,7 @@ try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
                 Normally pages are loaded inline: clicking on
                 a link, for example, loads the linked page in the current window. Attached pages are different
                 in that they are intended to be loaded outside of this flow: clicking on a link prompts the
-                user to either save the linked page, or open it outside of the current window, but does not
+                user to either save the linked page, or open it outside the current window, but does not
                 load the page in the current window.
             </p>
             <p>
@@ -160,7 +160,7 @@ try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
             <subsection name="Blocking based on the request (URL)">
                 <p>
                     This simple form of content blocking works based on the requested url. Usually you have
-                    to use a list of bolked url's or some url patterns to detect the blocked url. In case
+                    to use a list of blocked urls or some url patterns to detect the blocked url. In case
                     the url is blocked the request is not sent to the server; instead a simple page is returned.
                 </p>
                 <p>
@@ -208,10 +208,10 @@ try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
             <subsection name="Blocking based on the response (headers)">
                 <p>requires HtmlUnit 3.4.0 or later</p>
                 <p>
-                    For blocking based on the response a more sophisticated approche is needed.
+                    For blocking based on the response a more sophisticated approach is needed.
                     The following sample code shows blocking base on the content length header. Using
-                    this you are able to check the header of the respons and stop downloading the whole
-                    response directly. This might be helpfull to improve the speed of some test cases.
+                    this you are able to check the header of the response and stop downloading the whole
+                    response directly. This might be helpful to improve the speed of some test cases.
                 </p>
                 <p>
                     For the implementation we have to deal with the real web connection to be able to
@@ -279,7 +279,7 @@ try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
                 HtmlUnit supports the Web Storage API.
             </p>
             <p>
-                But for testing purposes it might be usefull to add some entries to the storage before running a test 
+                But for testing purposes it might be useful to add some entries to the storage before running a test
                 and also accessing the stored content. Therefor the storage is accessible from the web client using the
                 StorageHolder implementation.
             </p>

src/site/xdoc/filedownload-howto.xml

@@ -15,11 +15,11 @@
 
         <section name="File downloads in real browsers">
             <p>
-                Because file download is a tricky story (at least with HtmlUnit), i like to start from the beginning with some info about
+                Because file download is a tricky story (at least with HtmlUnit), lets start from the beginning with some info about
                 file download in real browsers.<br/>
                 When surfing the internet, you usually opening url's pointing to content (files) containing (X)Html. And your favorite browser
                 'eats' this stuff and renders the content on your screen. There are also some more file types your browser is able to handle like
-                CSS or JavaScript stuff. And for course all kind of images, sound and video files. This is all done behind the scenes
+                CSS or JavaScript stuff. And for course all kind of images, sound and video files. This is all done behind the scenes,
                 and you can see all the fancy stuff the internet has to offer.<br/>
                 Only in three cases, your browser hands over the control about the content handling to you
             </p>
@@ -50,7 +50,7 @@
 
             <subsection name="UnexpectedPage (default)">
                 <p>
-                    HtmlUnit handles all unknown content similar to known content - the content is wrapped in an page object and the page is placed inside the window.
+                    HtmlUnit handles all unknown content similar to known content - the content is wrapped in a page object and the page is placed inside the window.
                     For all unknown content HtmlUnit uses the UnexpectedPage. In most cases the UnexpectedPage replaces the current (Html)page in the current window,
                     but in some cases a new additional window gets opened (e.g. clicking an anchor with a download attribute defined).
                 </p>
@@ -64,7 +64,6 @@ try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
 
     .... // click some anchor/button that forces a file download
 
-    // we now processing the animation
     UnexpectedPage downloadPage = (UnexpectedPage) window.getEnclosedPage();
 
     try (InputStream downloadedContent = downloadPage.getInputStream()) {

src/site/xdoc/fileupload-howto.xml

@@ -51,7 +51,7 @@ firstPage.getHtmlElementById("mySubmit").click();
 ]]></source>
             </subsection>
 
-            <subsection name="Upload multiple files (if the 'multiple' attribut is set for the file input control)">
+            <subsection name="Upload multiple files (if the 'multiple' attribute is set for the file input control)">
 <source><![CDATA[
 String filename1 = "HtmlFileInputTest_one.txt";
 String path1 = getClass().getResource(filename1).toExternalForm();

src/site/xdoc/frame-howto.xml

@@ -47,8 +47,8 @@ packageListPage.getAnchors().get(5).click();]]></source>
                 To get the page of the frame named 'packageFrame' (at lower left) and click the second link:
             </p>
             <source><![CDATA[
-final HtmlPage pakcagePage = (HtmlPage) mainPage.getFrameByName("packageFrame").getEnclosedPage();
-pakcagePage.getAnchors().get(1).click();]]></source>
+final HtmlPage packagePage = (HtmlPage) mainPage.getFrameByName("packageFrame").getEnclosedPage();
+packagePage.getAnchors().get(1).click();]]></source>
 
             <p>
                 To get the page of the frame named 'classFrame' (at right):

src/site/xdoc/gettingStarted.xml

@@ -24,19 +24,19 @@
                 all of the tests. (see <a href="webclient.html">WebClient - the browser</a>)
             </p>
             <p><strong>Android</strong><br/>
-                Using HtmlUnit on Android has some challanges because of the subtle technical distinction
-                of java on android. Because of this we offer a customized distribution to work around these problem.
+                Using HtmlUnit on Android has some challenges because of the subtle technical distinction
+                of java on android. Because of this, we offer a customized distribution to work around these problem.
                 Please check out <a href="https://github.com/HtmlUnit/htmlunit-android" target="_blank">htmlunit-android</a> on github.
             </p>
             <p>
-                Most unit testing will be done within a framework like <a href="http://www.junit.org">JUnit</a>
+                Most unit testing will be done within a framework like <a href="https://junit.org">JUnit</a>
                 so all the examples here will assume that we are using that.
             </p>
             <p>
                 In the first sample, we create the web client and have it load the homepage from the HtmlUnit website.
                 We then verify that this page has the correct title.  Note that getPage() can return different types
-                of pages based on the content type of the returned data.  In this case we are expecting a content
-                type of text/html so we cast the result to an org.htmlunit.html.HtmlPage.
+                of pages based on the content type of the returned data.  In this case, we are expecting a content
+                type of text/html, so we cast the result to an org.htmlunit.html.HtmlPage.
             </p>
             <source><![CDATA[
 @Test
@@ -84,7 +84,7 @@ public void submittingForm() throws Exception {
 
             <subsection name="Finding form elements">
                 <p>
-                    For filling out a form you first have to find the form elements you like to interact with.
+                    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>
@@ -115,38 +115,86 @@ final HtmlTextInput textField = form.getInputByName("userid");]]></source>
                 </p>
             </subsection>
 
-            <subsection name="Text input">
+            <subsection name="Text input &lt;input type='test'&gt;">
                 <p>
-                    Todo
+                    These form elements represented as instances of class HtmlTextInput.
+                </p>
+                <source><![CDATA[
+final HtmlTextInput textField = form.getInputByName("userid");]]></source>
+                <p>
+                    To replace the value with some new text you should use the method 
+                    <a href='apidocs/org/htmlunit/html/HtmlElement.html#type-java.lang.String-'>HtmlElement#type(String)</a>.
+                    This call takes care of setting the focus (if required; including triggering all the focus related events) and
+                    then simulating the typing of the provided string (char by char, including the keyboard events).
+                </p>
+                <source><![CDATA[
+textField.type("RBRi");]]></source>
+                <p>
+                    If all the events not really needed, you can also use the method
+                    <a href='apidocs/org/htmlunit/html/HtmlSelectableTextInput.html#setValue-java.lang.String-'>HtmlSelectableTextInput#setValue(String)</a>.
                 </p>
             </subsection>
 
-            <subsection name="Radio buttons and checkboxes">
+            <subsection name="Text area &lt;textarea&gt;">
                 <p>
-                    Todo
+                    These form elements represented as instances of class HtmlTextArea.
                 </p>
+                <source><![CDATA[
+final HtmlTextArea textArea = form.getInputByName("comment");]]></source>
+                <p>
+                    The usage of HtmlTextArea is similar to HtmlTextInput (because both derived from HtmlSelectableTextInput).
+                    This means you can also use type(String) or even setValue(String) for updating these elements.
+                </p>
+                <source><![CDATA[
+textArea.type("HtmlUnit is a great library...");]]></source>
             </subsection>
-        </section>
 
-        <section name="Imitating a specific browser">
-            <p>
-                Often you will want to simulate a specific browser. This is done by passing a
-                org.htmlunit.BrowserVersion into the WebClient constructor.
-                Constants have been provided for some common browsers but you can create your own specific
-                version by instantiating a BrowserVersion.
-            </p>
-            <source><![CDATA[
-@Test
-public void homePage_Firefox() throws Exception {
-    try (final WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
-        final HtmlPage page = webClient.getPage("https://www.htmlunit.org/");
-        Assert.assertEquals("HtmlUnit – Welcome to HtmlUnit", page.getTitleText());
-    }
-}]]></source>
-            <p>
-                Specifying this BrowserVersion will change the user agent header that is sent up to the
-                server and will change the behavior of some of the JavaScript.
-            </p>
+            <subsection name="Radio buttons &lt;input type='radio'&gt; and Checkboxes &lt;input type='checkbox'&gt;">
+                <p>
+                    These form elements represented as instances of class HtmlRadioButtonInput/HtmlCheckBoxInput.
+                </p>
+                <source><![CDATA[
+final HtmlRadioButtonInput countryGermany = form.getInputByName("radio_country_germany");
+final HtmlCheckBoxInput programmingLanguage = form.getInputByName("check_language_java");]]></source>
+                <p>
+                    Usually your form contains many of these elements organized in groups. To check a radio button
+                    of a checkbox you have to use 
+                    <a href='apidocs/org/htmlunit/html/HtmlRadioButtonInput.html#setChecked-boolean-'>HtmlRadioButtonInput#setChecked(boolean)</a>
+                    or
+                    <a href='apidocs/org/htmlunit/html/HtmlCheckBoxInput.html#setChecked-boolean-'>HtmlCheckBoxInput#setChecked(boolean)</a>.
+                </p>
+                <source><![CDATA[
+countryGermany.setChecked(true);
+programmingLanguage.setChecked(true);]]></source>
+                <p>
+                    Checking a single radio button will automatically uncheck all other radio buttons in the same group.
+                </p>
+            </subsection>
+
+            <subsection name="Select &lt;select&gt;">
+                <p>
+                    These form elements represented as instances of class HtmlSelect. The individual options are represented by
+                    instances of class HtmlOption.
+                </p>
+                <source><![CDATA[
+final HtmlSelect currency = form.getInputByName("currency");
+                <p>
+                    The simplest way to select one of the options is the method
+                    <a href='apidocs/org/htmlunit/html/HtmlSelect.html#setSelectedIndex-int-'>HtmlSelect.html#setSelectedIndex(int)</a>.
+                </p>
+                <source><![CDATA[
+currency.setSelectedIndex(true);]]></source>
+                <p>
+                    To make your code more readable and robust, you have to search for the HtmlOption to select and then use
+                    <a href='apidocs/org/htmlunit/html/HtmlSelect.html#setSelectedAttribute-org.htmlunit.html.HtmlOption-boolean-'>HtmlSelect.html#setSelectedAttribute(HtmlOption, boolean)</a>.
+                </p>
+                <source><![CDATA[
+HtmlOption euro = currency.getOptionByValue("Euro");
+currency.setSelectedAttribute(euro, true);]]></source>
+                <p>
+                    For single selection select elements, this call also deselects all other options.
+                </p>
+            </subsection>
         </section>
 
         <section name="Finding a specific element">

src/site/xdoc/images-howto.xml

@@ -11,7 +11,7 @@
                 Because HtmlUnit is a headless browsers you might think HtmlUnit can be agnostic to image formats.
                 This is in general true but not if you look at the details. Even if HtmlUnit is headless there is
                 still support for layout related methods like Element.getBoundingClientRect(). A second case is
-                Canvas.drawImage(). To support this HtmlUnit has to be able to determine the dimensions of an given
+                Canvas.drawImage(). To support this HtmlUnit has to be able to determine the dimensions of a given
                 image (for the first case) and produce a raster version (for the second case).
             </p>
             <p>

src/site/xdoc/implementation.xml

@@ -15,10 +15,10 @@
             <p>
                 To be able to stay in sync with the development of real browsers, we try to write
                 tests in a way that enables us to compare the results of executing the tests with real
-                browsers to our own results. This also directy leads to a test firsts approach - write
+                browsers to our own results. This also directly leads to a test firsts approach - write
                 the test; run the test with all real browsers and adjust the expectations, run the test
-                with HtmlUnit and finally fix the implementation if needed. Additionally we try to make the
-                test as small as possible to make the connetion between a failing test and the related
+                with HtmlUnit and finally fix the implementation if needed. Additionally, we try to make the
+                test as small as possible to make the connection between a failing test and the related
                 implementation as direct as possible.
             </p>
             <p>