Page MenuHomePhorge
Files F2686409

D25688.1734713835.diff
No OneTemporary
Actions

D25688.1734713835.diff
View Options

diff --git a/src/docs/contributor/rendering_html.diviner b/src/docs/contributor/rendering_html.diviner
--- a/src/docs/contributor/rendering_html.diviner
+++ b/src/docs/contributor/rendering_html.diviner
@@ -13,13 +13,13 @@
This document describes the right way to build HTML components so they are safe
from XSS and render correctly. Broadly:
- - Use @{function@arcanist:phutil_tag} (and @{function:javelin_tag}) to build
+ - Use @{function:phutil_tag} (and @{function:javelin_tag}) to build
tags.
- - Use @{function@arcanist:hsprintf} where @{function@arcanist:phutil_tag}
+ - Use @{function:hsprintf} where @{function:phutil_tag}
is awkward.
- Combine elements with arrays, not string concatenation.
- @{class:AphrontView} subclasses should return a
- @{class@arcanist:PhutilSafeHTML} object from their `render()` method.
+ @{class:PhutilSafeHTML} object from their `render()` method.
- @{class:AphrontView} subclasses act like tags when rendering.
- @{function:pht} has some special rules.
- There are some other things that you should be aware of.
@@ -28,7 +28,7 @@
= Building Tags: phutil_tag() =
-Build HTML tags with @{function@arcanist:phutil_tag}. For example:
+Build HTML tags with @{function:phutil_tag}. For example:
phutil_tag(
'div',
@@ -37,10 +37,10 @@
),
$content);
-@{function@arcanist:phutil_tag} will properly escape the content and all the
-attributes, and return a @{class@arcanist:PhutilSafeHTML} object. The rendering
+@{function:phutil_tag} will properly escape the content and all the
+attributes, and return a @{class:PhutilSafeHTML} object. The rendering
pipeline knows that this object represents a properly escaped HTML tag. This
-allows @{function@arcanist:phutil_tag} to render tags with other tags as
+allows @{function:phutil_tag} to render tags with other tags as
content correctly (without double-escaping):
phutil_tag(
@@ -52,14 +52,14 @@
$content));
In Phorge, the @{function:javelin_tag} function is similar to
-@{function@arcanist:phutil_tag}, but provides special handling for the
+@{function:phutil_tag}, but provides special handling for the
`sigil` and `meta` attributes.
= Building Blocks: hsprintf() =
-Sometimes, @{function@arcanist:phutil_tag} can be particularly awkward to
-use. You can use @{function@arcanist:hsprintf} to build larger and more
-complex blocks of HTML, when @{function@arcanist:phutil_tag} is a poor fit.
+Sometimes, @{function:phutil_tag} can be particularly awkward to
+use. You can use @{function:hsprintf} to build larger and more
+complex blocks of HTML, when @{function:phutil_tag} is a poor fit.
@{function:hsprintf} has `sprintf()` semantics, but `%s` escapes HTML:
// Safely build fragments or unwieldy blocks.
@@ -72,13 +72,13 @@
- You need to build a block with a lot of tags, like a table with rows and
cells.
- You need to build part of a tag (usually you should avoid this, but if you
- do need to, @{function@arcanist:phutil_tag} can not do it).
+ do need to, @{function:phutil_tag} can not do it).
Note that it is unsafe to provide any user-controlled data to the first
-parameter of @{function@arcanist:hsprintf} (the `sprintf()`-style pattern).
+parameter of @{function:hsprintf} (the `sprintf()`-style pattern).
-Like @{function@arcanist:phutil_tag}, this function returns a
-@{class@arcanist:PhutilSafeHTML} object.
+Like @{function:phutil_tag}, this function returns a
+@{class:PhutilSafeHTML} object.
= Composing Tags =
@@ -99,7 +99,7 @@
// Render a tag containing other tags safely.
phutil_tag('div', array(), array($header, $body));
-If you concatenate @{class@arcanist:PhutilSafeHTML} objects, they revert to
+If you concatenate @{class:PhutilSafeHTML} objects, they revert to
normal strings and are no longer marked as properly escaped tags.
(In the future, these objects may stop converting to strings, but for now they
@@ -118,7 +118,7 @@
= AphrontView Classes =
Subclasses of @{class:AphrontView} in Phorge should return a
-@{class@arcanist:PhutilSafeHTML} object. The easiest way to do this is to
+@{class:PhutilSafeHTML} object. The easiest way to do this is to
return `phutil_tag()` or `javelin_tag()`:
return phutil_tag('div', ...);
@@ -130,8 +130,8 @@
= Internationalization: pht() =
The @{function:pht} function has some special rules. If any input to
-@{function:pht} is a @{class@arcanist:PhutilSafeHTML} object, @{function:pht}
-returns a @{class@arcanist:PhutilSafeHTML} object itself. Otherwise, it returns
+@{function:pht} is a @{class:PhutilSafeHTML} object, @{function:pht}
+returns a @{class:PhutilSafeHTML} object itself. Otherwise, it returns
normal text.
This is generally safe because translations are not permitted to have more tags
@@ -146,23 +146,23 @@
NOTE: This section describes dangerous methods which can bypass XSS protections.
If possible, do not use them.
-You can build @{class@arcanist:PhutilSafeHTML} out of a string explicitly by
+You can build @{class:PhutilSafeHTML} out of a string explicitly by
calling @{function:phutil_safe_html} on it. This is **dangerous**, because if
you are wrong and the string is not actually safe, you have introduced an XSS
vulnerability. Consequently, you should avoid calling this if possible.
-You can use @{function@arcanist:phutil_escape_html_newlines} to escape HTML
+You can use @{function:phutil_escape_html_newlines} to escape HTML
while converting newlines to `<br />`. You should not need to explicitly use
-@{function@arcanist:phutil_escape_html} anywhere.
+@{function:phutil_escape_html} anywhere.
If you need to apply a string function (such as `trim()`) to safe HTML, use
-@{method@arcanist:PhutilSafeHTML::applyFunction}.
+@{method:PhutilSafeHTML::applyFunction}.
-If you need to extract the content of a @{class@arcanist:PhutilSafeHTML}
+If you need to extract the content of a @{class:PhutilSafeHTML}
object, you should call `getHTMLContent()`, not cast it to a string. Eventually,
we would like to remove the string cast entirely.
-Functions @{function@arcanist:phutil_tag} and @{function@arcanist:hsprintf}
+Functions @{function:phutil_tag} and @{function:hsprintf}
are not safe if you pass the user input for the tag or attribute name. All the
following examples are dangerous:

File Metadata

Mime Type
text/plain
Expires
Fri, Dec 20, 16:57 (18 h, 6 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1019146
Default Alt Text
D25688.1734713835.diff (6 KB)

Event Timeline

Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0