mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-22 14:52:41 +01:00
Fix broken URIs on "Rendering HTML" Diviner page
Summary: Remove incorrect book scope from numerous `find` URIs on the "Rendering HTML" Diviner page in order to get results instead of 404 pages. Test Plan: Refresh Diviner documentation from Phorge directory: ./bin/diviner generate Go to https://we.phorge.it/book/contrib/article/rendering_html/ and click random links on that page. Reviewers: O1 Blessed Committers, valerio.bozzolan Reviewed By: O1 Blessed Committers, valerio.bozzolan Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno Differential Revision: https://we.phorge.it/D25688
This commit is contained in:
parent
43d3fd9eac
commit
91815cefc5
1 changed files with 25 additions and 25 deletions
|
@ -13,13 +13,13 @@ pipeline, and the browser will treat it as plain text, not HTML.
|
||||||
This document describes the right way to build HTML components so they are safe
|
This document describes the right way to build HTML components so they are safe
|
||||||
from XSS and render correctly. Broadly:
|
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.
|
tags.
|
||||||
- Use @{function@arcanist:hsprintf} where @{function@arcanist:phutil_tag}
|
- Use @{function:hsprintf} where @{function:phutil_tag}
|
||||||
is awkward.
|
is awkward.
|
||||||
- Combine elements with arrays, not string concatenation.
|
- Combine elements with arrays, not string concatenation.
|
||||||
- @{class:AphrontView} subclasses should return a
|
- @{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.
|
- @{class:AphrontView} subclasses act like tags when rendering.
|
||||||
- @{function:pht} has some special rules.
|
- @{function:pht} has some special rules.
|
||||||
- There are some other things that you should be aware of.
|
- There are some other things that you should be aware of.
|
||||||
|
@ -28,7 +28,7 @@ See below for discussion.
|
||||||
|
|
||||||
= Building Tags: phutil_tag() =
|
= 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(
|
phutil_tag(
|
||||||
'div',
|
'div',
|
||||||
|
@ -37,10 +37,10 @@ Build HTML tags with @{function@arcanist:phutil_tag}. For example:
|
||||||
),
|
),
|
||||||
$content);
|
$content);
|
||||||
|
|
||||||
@{function@arcanist:phutil_tag} will properly escape the content and all the
|
@{function:phutil_tag} will properly escape the content and all the
|
||||||
attributes, and return a @{class@arcanist:PhutilSafeHTML} object. The rendering
|
attributes, and return a @{class:PhutilSafeHTML} object. The rendering
|
||||||
pipeline knows that this object represents a properly escaped HTML tag. This
|
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):
|
content correctly (without double-escaping):
|
||||||
|
|
||||||
phutil_tag(
|
phutil_tag(
|
||||||
|
@ -52,14 +52,14 @@ content correctly (without double-escaping):
|
||||||
$content));
|
$content));
|
||||||
|
|
||||||
In Phorge, the @{function:javelin_tag} function is similar to
|
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.
|
`sigil` and `meta` attributes.
|
||||||
|
|
||||||
= Building Blocks: hsprintf() =
|
= Building Blocks: hsprintf() =
|
||||||
|
|
||||||
Sometimes, @{function@arcanist:phutil_tag} can be particularly awkward to
|
Sometimes, @{function:phutil_tag} can be particularly awkward to
|
||||||
use. You can use @{function@arcanist:hsprintf} to build larger and more
|
use. You can use @{function:hsprintf} to build larger and more
|
||||||
complex blocks of HTML, when @{function@arcanist:phutil_tag} is a poor fit.
|
complex blocks of HTML, when @{function:phutil_tag} is a poor fit.
|
||||||
@{function:hsprintf} has `sprintf()` semantics, but `%s` escapes HTML:
|
@{function:hsprintf} has `sprintf()` semantics, but `%s` escapes HTML:
|
||||||
|
|
||||||
// Safely build fragments or unwieldy blocks.
|
// Safely build fragments or unwieldy blocks.
|
||||||
|
@ -72,13 +72,13 @@ complex blocks of HTML, when @{function@arcanist:phutil_tag} is a poor fit.
|
||||||
- You need to build a block with a lot of tags, like a table with rows and
|
- You need to build a block with a lot of tags, like a table with rows and
|
||||||
cells.
|
cells.
|
||||||
- You need to build part of a tag (usually you should avoid this, but if you
|
- 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
|
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
|
Like @{function:phutil_tag}, this function returns a
|
||||||
@{class@arcanist:PhutilSafeHTML} object.
|
@{class:PhutilSafeHTML} object.
|
||||||
|
|
||||||
= Composing Tags =
|
= Composing Tags =
|
||||||
|
|
||||||
|
@ -99,7 +99,7 @@ Instead, use an array:
|
||||||
// Render a tag containing other tags safely.
|
// Render a tag containing other tags safely.
|
||||||
phutil_tag('div', array(), array($header, $body));
|
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.
|
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
|
(In the future, these objects may stop converting to strings, but for now they
|
||||||
|
@ -118,7 +118,7 @@ If you need to build a list of items with some element in between each of them
|
||||||
= AphrontView Classes =
|
= AphrontView Classes =
|
||||||
|
|
||||||
Subclasses of @{class:AphrontView} in Phorge should return a
|
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()` or `javelin_tag()`:
|
||||||
|
|
||||||
return phutil_tag('div', ...);
|
return phutil_tag('div', ...);
|
||||||
|
@ -130,8 +130,8 @@ You can use an @{class:AphrontView} subclass like you would a tag:
|
||||||
= Internationalization: pht() =
|
= Internationalization: pht() =
|
||||||
|
|
||||||
The @{function:pht} function has some special rules. If any input to
|
The @{function:pht} function has some special rules. If any input to
|
||||||
@{function:pht} is a @{class@arcanist:PhutilSafeHTML} object, @{function:pht}
|
@{function:pht} is a @{class:PhutilSafeHTML} object, @{function:pht}
|
||||||
returns a @{class@arcanist:PhutilSafeHTML} object itself. Otherwise, it returns
|
returns a @{class:PhutilSafeHTML} object itself. Otherwise, it returns
|
||||||
normal text.
|
normal text.
|
||||||
|
|
||||||
This is generally safe because translations are not permitted to have more tags
|
This is generally safe because translations are not permitted to have more tags
|
||||||
|
@ -146,23 +146,23 @@ like you would expect, but it is worth being aware of.
|
||||||
NOTE: This section describes dangerous methods which can bypass XSS protections.
|
NOTE: This section describes dangerous methods which can bypass XSS protections.
|
||||||
If possible, do not use them.
|
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
|
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
|
you are wrong and the string is not actually safe, you have introduced an XSS
|
||||||
vulnerability. Consequently, you should avoid calling this if possible.
|
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
|
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
|
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,
|
object, you should call `getHTMLContent()`, not cast it to a string. Eventually,
|
||||||
we would like to remove the string cast entirely.
|
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
|
are not safe if you pass the user input for the tag or attribute name. All the
|
||||||
following examples are dangerous:
|
following examples are dangerous:
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue