Differential D25007 Diff 23 src/docs/contributor/rendering_html.diviner

Changeset View

Standalone View

src/docs/contributor/rendering_html.diviner

@title Rendering HTML		@title Rendering HTML
@group developer		@group developer

Rendering HTML in the Phabricator environment.		Rendering HTML in the Phorge environment.

= Overview =		= Overview =

Phabricator attempts to prevent XSS by treating strings as default-unsafe when		Phorge attempts to prevent XSS by treating strings as default-unsafe when
rendering. This means that if you try to build HTML through string		rendering. This means that if you try to build HTML through string
concatenation, it won't work: the string will be escaped by the rendering		concatenation, it won't work: the string will be escaped by the rendering
pipeline, and the browser will treat it as plain text, not HTML.		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@arcanist:phutil_tag} (and @{function:javelin_tag}) to build
Show All 29 Lines	content correctly (without double-escaping):
phutil_tag(		phutil_tag(
'div',		'div',
array(),		array(),
phutil_tag(		phutil_tag(
'strong',		'strong',
array(),		array(),
$content));		$content));

In Phabricator, 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@arcanist: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@arcanist:phutil_tag} can be particularly awkward to
use. You can use @{function@arcanist:hsprintf} to build larger and more		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.		complex blocks of HTML, when @{function@arcanist:phutil_tag} is a poor fit.
▲ Show 20 Lines • Show All 49 Lines • ▼ Show 20 Lines	@{function:phutil_implode_html}:
// Render links with commas between them.		// Render links with commas between them.
phutil_tag(		phutil_tag(
'div',		'div',
array(),		array(),
phutil_implode_html(', ', $list_of_links));		phutil_implode_html(', ', $list_of_links));

= AphrontView Classes =		= AphrontView Classes =

Subclasses of @{class:AphrontView} in Phabricator 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@arcanist: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', ...);

You can use an @{class:AphrontView} subclass like you would a tag:		You can use an @{class:AphrontView} subclass like you would a tag:

phutil_tag('div', array(), $view);		phutil_tag('div', array(), $view);
▲ Show 20 Lines • Show All 54 Lines • Show Last 20 Lines