mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-22 06:42:42 +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
|
||||
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 @@ See below for discussion.
|
|||
|
||||
= 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 @@ Build HTML tags with @{function@arcanist:phutil_tag}. For example:
|
|||
),
|
||||
$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 correctly (without double-escaping):
|
|||
$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 @@ 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
|
||||
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 @@ Instead, use an array:
|
|||
// 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 @@ If you need to build a list of items with some element in between each of them
|
|||
= 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 @@ You can use an @{class:AphrontView} subclass like you would a tag:
|
|||
= 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 @@ like you would expect, but it is worth being aware of.
|
|||
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:
|
||||
|
||||
|
|
Loading…
Reference in a new issue