revi-archive/phorge-phorge
1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-26 00:32:42 +01:00
Code Issues Releases Wiki Activity

Fix broken URIs on "Rendering HTML" Diviner page

Browse source 
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:
Andre Klapper 2024-06-11 01:13:33 +02:00
parent 43d3fd9eac
commit 91815cefc5
1 changed files with 25 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
src/docs/contributor/rendering_html.diviner
View file

@ -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: