html/template: document handling of namespaced and data- attributes

Attributes with a namespace or a data- prefix are handled as if they
had no namespace/data- prefix.

There is also a special case, where attributes with a "xmlns" namespace
are always treated as containing URLs.

This could surprise users of the package, since this behaviour was not
documented anywhere, so this change adds some documentation for all
three cases.

Fixes #12648

Change-Id: If57a2ec49fec91a330fc04795726e8cffa9b75c0
Reviewed-on: https://go-review.googlesource.com/c/go/+/79895
Run-TryBot: Andrew Bonventre <andybons@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>

diff --git a/src/html/template/doc.go b/src/html/template/doc.go
index 290ec81b9672a2f9910aa406662d4193d4339cac..650e7147a366886d0bf7e784cdd52b0a46e622e4 100644 (file)
--- a/src/html/template/doc.go
+++ b/src/html/template/doc.go
@@ -73,6 +73,51 @@ functions.
 For these internal escaping functions, if an action pipeline evaluates to
 a nil interface value, it is treated as though it were an empty string.
 
+Namespaced and data- attributes
+
+Attributes with a namespace are treated as if they had no namespace.
+Given the excerpt
+
+  <a my:href="{{.}}"></a>
+
+At parse time the attribute will be treated as if it were just "href".
+So at parse time the template becomes:
+
+  <a my:href="{{. | urlescaper | attrescaper}}"></a>
+
+Similarly to attributes with namespaces, attributes with a "data-" prefix are
+treated as if they had no "data-" prefix. So given
+
+  <a data-href="{{.}}"></a>
+
+At parse time this becomes
+
+  <a data-href="{{. | urlescaper | attrescaper}}"></a>
+
+If an attribute has both a namespace and a "data-" prefix, only the namespace
+will be removed when determining the context. For example
+
+  <a my:data-href="{{.}}"></a>
+
+This is handled as if "my:data-href" was just "data-href" and not "href" as
+it would be if the "data-" prefix were to be ignored too. Thus at parse
+time this becomes just
+
+  <a my:data-href="{{. | attrescaper}}"></a>
+
+As a special case, attributes with the namespace "xmlns" are always treated
+as containing URLs. Given the excerpts
+
+  <a xmlns:title="{{.}}"></a>
+  <a xmlns:href="{{.}}"></a>
+  <a xmlns:onclick="{{.}}"></a>
+
+At parse time they become:
+
+  <a xmlns:title="{{. | urlescaper | attrescaper}}"></a>
+  <a xmlns:href="{{. | urlescaper | attrescaper}}"></a>
+  <a xmlns:onclick="{{. | urlescaper | attrescaper}}"></a>
+
 Errors
 
 See the documentation of ErrorCode for details.