Merge pull request #235 from bigskysoftware/bencroker-patch-1

Added docs for hx-vals and added security consideration

www/attributes/hx-vals.md

@@ -0,0 +1,24 @@
+---
+layout: layout.njk
+title: </> htmx - hx-vals
+---
+
+## `hx-vals`
+
+The `hx-vals` attribute allows you to safely add to the parameters that will be submitted with an AJAX request.  
+
+The value of this attribute is a list of name-expression values in [JSON (JavaScript Object Notation)](https://www.json.org/json-en.html) format.
+
+```html
+  <div hx-get="/example" hx-vals='{"myVal": "My Value"}'>Get Some HTML, Including A Value in the Request</div>
+```
+
+### Security Considerations
+
+* The value of `hx-vals` must be valid [JSON](https://developer.mozilla.org/en-US/docs/Glossary/JSON). It is **not** dynamically computed, making it a safer alternative to [hx-vars](/attributes/hx-vars), especially when dealing with user input such as query strings or user-generated content, which could otherwise introduce a [Cross-Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/) vulnerability. 
+
+### Notes
+
+* `hx-vals` is inherited and can be placed on a parent element.
+* A child declaration of a variable overrides a parent declaration.
+* Input values with the same name will be overridden by variable declarations.

www/attributes/hx-vars.md

@@ -8,14 +8,18 @@ title: </> htmx - hx-vars
 The `hx-vars` attribute allows you to dynamically add to the parameters that will be submitted with an AJAX request.  
 
 The value of this attribute is a comma separated list of `name`:`<expression>` values, the same as the internal
-syntax of javascript [Object Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Object_literals)
+syntax of javascript [Object Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Object_literals).
 
 ```html
   <div hx-get="/example" hx-vars="myVar:computeMyVar()">Get Some HTML, Including A Dynamic Value in the Request</div>
 ```
 
+### Security Considerations
+
+* The expressions in `hx-vars` are dynamically computed which allows you to add JavaScript code that will be executed. Be careful to **never** trust user input in your expressions as this may lead to a [Cross-Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/) vulnerability. If you are dealing with user input such as query strings or user-generated content, consider using [hx-vals](/attributes/hx-vals) which is a safer alternative. 
+
 ### Notes
 
 * `hx-vars` is inherited and can be placed on a parent element.
 * A child declaration of a variable overrides a parent declaration.
-* Input values with the same name override variable declarations.
+* Input values with the same name will be overridden by variable declarations.

www/docs.md

@@ -374,11 +374,10 @@ differently.
 Note that htmx fires a `htmx:xhr:progress` event periodically based on the standard `progress` event during upload, 
 which you can hook into to show the progress of the upload.
 
-#### <a name="vars"></a> [Variables](#variables)
+#### <a name="extra-values"></a> [Extra Values](#extra-values)
 
-You can also include dynamically computed variables in the parameters of a request by using the 
+You can include extra values in a request using the [hx-vals](/attributes/hx-vals) (name-expression pairs in JSON format) and
-[hx-vars](/attributes/hx-vars) attribute.  This attributes allows you to use name-expression pairs to include additional
+[hx-vars](/attributes/hx-vars) attributes (comma-separated name-expression pairs that are dynamically computed).
-computed variables in a request.
 
 ## <a name="boosting"></a>[Boosting](#boosting)