From f05af7764fa1acc0ea66913766bd954df54bfbfc Mon Sep 17 00:00:00 2001
From: Gavin * JCOGS <gavin@jcogs.net>
Date: Sat, 6 Jun 2020 16:47:42 +0100
Subject: [PATCH] Update Documentation for Attribute Pass-Through forms

These documentation edits complement the proposed changes to the `form_declaration` function in `Functions.php`

They provide updated instructions concerning how to 'pass through' FORM attributes via tag parameters.

The pass through function is available to any tag that uses the form_declaration function to draw its opening `<FORM>` tag.  I think all the cases covered by this are included in this documentation update: AFAIK the `Comment` form does not use this function and so does not benefit from these changes.
---
 docs/add-ons/consent.md                | 12 ++++++++++++
 docs/add-ons/email.md                  | 13 +++++++++++++
 docs/add-ons/search/advanced.md        | 12 ++++++++++++
 docs/add-ons/search/simple.md          | 13 +++++++++++++
 docs/channels/channel-form/overview.md | 14 +++++++++++++-
 docs/member/index.md                   | 13 +++++++++++++
 6 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/docs/add-ons/consent.md b/docs/add-ons/consent.md
index ec0ea60cb..5beac838e 100755
--- a/docs/add-ons/consent.md
+++ b/docs/add-ons/consent.md
@@ -38,6 +38,8 @@ Consent Forms allow the visitor to grant or withdraw consent to one or more Cons
 
 ## Parameters
 
+The Consent Form Tag will create an HTML form and include within its opening tag the minimum attributes necessary for it to work.  If you need additional attributes to be specified, The Simple Search Form Tag allows you to specify these attributes as additional parameters within the tag itself.  See the entry for [pass_through_attributes](#pass_through_attributes) in the parameter listing for more information.
+
 [TOC=3]
 
 ### `consent=`
@@ -64,6 +66,16 @@ Specify the HTML `class=` attribute.
 
 Specify the HTML `id=` attribute.
 
+### `pass through attributes`
+
+    data-automobile_type="buick" role="search" name="some name"
+
+You can include in your tag a parameter with a name identical to any valid [HTML Form}(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) attribute, any [HTML Global Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), or the [ARIA Search role attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Search_role).  
+
+If you assign a value to your parameter the value will be assigned to the attribute in the completed Form tag.  To include an attribute which does not take a value (e.g. `novalidate`) you need to define a null value for the parameter (i.e. `novalidate=""`).
+
+If you specify a parameter with a name that is the same as an attribute already being set by Consent Form, the parameter value you enter will be ignored.
+
 ### `return=`
 
     return='site/consent'
diff --git a/docs/add-ons/email.md b/docs/add-ons/email.md
index af52a207a..6f34e5aa5 100755
--- a/docs/add-ons/email.md
+++ b/docs/add-ons/email.md
@@ -54,6 +54,9 @@ The contact form is created similar to a standard web form, only you **do not**
 
 ## Parameters
 
+The Email Contact Form Tag will create an HTML form and include within its opening tag the minimum attributes necessary for it to work.  If you need additional attributes to be specified, The Simple Search Form Tag allows you to specify these attributes as additional parameters within the tag itself.  See the entry for [pass_through_attributes](#pass_through_attributes) in the parameter listing for more information.
+
+
 [TOC=3]
 
 ### `charset=`
@@ -68,6 +71,16 @@ This allows you to set the character set of the email being sent. Use this if yo
 
 This allows you to set a name= attribute for the form. Keep in mind that name= is deprecated in XHTML.
 
+### `pass through attributes`
+
+    data-automobile_type="buick" role="search" name="some name"
+
+You can include in your tag a parameter with a name identical to any valid [HTML Form}(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) attribute, any [HTML Global Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), or the [ARIA Search role attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Search_role).  
+
+If you assign a value to your parameter the value will be assigned to the attribute in the completed Form tag.  To include an attribute which does not take a value (e.g. `novalidate`) you need to define a null value for the parameter (i.e. `novalidate=""`).
+
+If you specify a parameter with a name that is the same as an attribute already being set by the Email Contact Form tag, the parameter value you enter will be ignored.
+
 ### `recipients=`
 
 This optional parameter allows you to specify an email address to receive the email:
diff --git a/docs/add-ons/search/advanced.md b/docs/add-ons/search/advanced.md
index 6815a99ad..4be1964cb 100755
--- a/docs/add-ons/search/advanced.md
+++ b/docs/add-ons/search/advanced.md
@@ -141,6 +141,8 @@ The search results are displayed on the page you specify as the [result_page=](#
 
 ## Parameters
 
+The Advanced Search Form Tag will create an HTML form and include within its opening tag the minimum attributes necessary for it to work.  If you need additional attributes to be specified, The Advanced Search Form Tag allows you to specify these attributes as additional parameters within the tag itself.  See the entry for [pass_through_attributes](#pass_throug_attributes) in the parameter listing for more information.
+
 [TOC=3]
 
 ### `category=`
@@ -177,6 +179,16 @@ Specify the name attribute for the &lt;form&gt; tag, which will allow you to spe
 
 You may specify a particular Template to display in the case when there are no results. This takes a standard "Template_Group/Template" as input.
 
+### `pass through attributes`
+
+    data-automobile_type="buick" role="search" name="some name"
+
+You can include in your tag a parameter with a name identical to any valid [HTML Form}(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) attribute, any [HTML Global Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), or the [ARIA Search role attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Search_role).  
+
+If you assign a value to your parameter the value will be assigned to the attribute in the completed Form tag.  To include an attribute which does not take a value (e.g. `novalidate`) you need to define a null value for the parameter (i.e. `novalidate=""`).
+
+If you specify a parameter with a name that is the same as an attribute already being set by the Advanced Search Form tag, the parameter value you enter will be ignored.
+
 ### `result_page=`
 
     result_page="news/searches"
diff --git a/docs/add-ons/search/simple.md b/docs/add-ons/search/simple.md
index b473c8dc1..ccc27333a 100755
--- a/docs/add-ons/search/simple.md
+++ b/docs/add-ons/search/simple.md
@@ -73,6 +73,9 @@ Besides specifying whether future entries are included in the search using the [
 
 ## Parameters
 
+The Simple Search Form Tag will create an HTML form and include within its opening tag the minimum attributes necessary for it to work.  If you need additional attributes to be specified, The Simple Search Form Tag allows you to specify these attributes as additional parameters within the tag itself.  See the entry for [pass_through_attributes](#pass_through_attributes) in the parameter listing for more information.
+
+
 ### `name=`
 
     name="search_form"
@@ -85,6 +88,16 @@ Specify the name attribute for the &lt;form&gt; tag, which will allow you to spe
 
 You may specify a particular Template to display in the case when there are no results. This takes a standard "Template_Group/Template" as input.
 
+### `pass through attributes`
+
+    data-automobile_type="buick" role="search" name="some name"
+
+You can include in your tag a parameter with a name identical to any valid [HTML Form}(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) attribute, any [HTML Global Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), or the [ARIA Search role attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Search_role).  
+
+If you assign a value to your parameter the value will be assigned to the attribute in the completed Form tag.  To include an attribute which does not take a value (e.g. `novalidate`) you need to define a null value for the parameter (i.e. `novalidate=""`).
+
+If you specify a parameter with a name that is the same as an attribute already being set by the Simple Search Form tag, the parameter value you enter will be ignored.
+
 ### `result_page=`
 
     result_page="news/searches"
diff --git a/docs/channels/channel-form/overview.md b/docs/channels/channel-form/overview.md
index 6963f5041..4da80a226 100755
--- a/docs/channels/channel-form/overview.md
+++ b/docs/channels/channel-form/overview.md
@@ -61,7 +61,9 @@ By default, validation errors will be displayed using the User Message Template.
 
 [TOC=3 hide]
 
-The Following parameters are available for the `{exp:channel:form}`:
+The Channel Form tag will create an HTML form and include within its opening tag the minimum attributes necessary for it to work.  If you need additional attributes to be specified, Channel Form allows you to specify these attributes as additional parameters within the tag itself.  See the entry for [pass_through_attributes](#pass_through_attributes) in the parameter listing for more information.
+
+The following parameters are available for the `{exp:channel:form}`:
 
 ### `allow_comments=`
 
@@ -157,6 +159,16 @@ Output your results in JSON format, instead of performing a redirect.
 
 In order to allow logged out users to use the entry form, you must specify a member_id which will be used as the author of the entry.
 
+### `pass through attributes`
+
+    data-automobile_type="buick" role="search" name="some name"
+
+You can include in your tag a parameter with a name identical to any valid [HTML Form}(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) attribute, any [HTML Global Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), or the [ARIA Search role attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Search_role).  
+
+If you assign a value to your parameter the value will be assigned to the attribute in the completed Form tag.  To include an attribute which does not take a value (e.g. `novalidate`) you need to define a null value for the parameter (i.e. `novalidate=""`).
+
+If you specify a parameter with a name that is the same as an attribute already being set by the Channel Form tag, the parameter value you enter will be ignored.
+
 ### `require_entry=`
 
     require_entry="yes"
diff --git a/docs/member/index.md b/docs/member/index.md
index 5d6521a68..8800b0d11 100755
--- a/docs/member/index.md
+++ b/docs/member/index.md
@@ -72,6 +72,8 @@ Here is how you might use the tag:
 
 ### Parameters
 
+The Login Form Tag will create an HTML form and include within its opening tag the minimum attributes necessary for it to work.  If you need additional attributes to be specified, The Simple Search Form Tag allows you to specify these attributes as additional parameters within the tag itself.  See the entry for [pass_through_attributes](#pass_through_attributes) in the parameter listing for more information.
+
 [TOC=4]
 
 #### `action=`
@@ -98,6 +100,17 @@ This parameter allows you to specify the id attribute for the &lt;form&gt; tag.
 
 This parameter allows you to specify a name attribute for the &lt;form&gt; tag.
 
+### `pass through attributes`
+
+    data-automobile_type="buick" role="search" name="some name"
+
+You can include in your tag a parameter with a name identical to any valid [HTML Form}(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) attribute, any [HTML Global Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), or the [ARIA Search role attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Search_role).  
+
+If you assign a value to your parameter the value will be assigned to the attribute in the completed Form tag.  To include an attribute which does not take a value (e.g. `novalidate`) you need to define a null value for the parameter (i.e. `novalidate=""`).
+
+If you specify a parameter with a name that is the same as an attribute already being set by the Login Form tag, the parameter value you enter will be ignored.
+
+
 #### `return=`
 
     return="site/index"