Page MenuHomeClusterLabs Projects
Diviner Tech Docs PhabricatorMarkupInterface

interface PhabricatorMarkupInterface
Phorge Technical Documentation (Remarkup)

An object which has one or more fields containing markup that can be rendered into a display format. Commonly, the fields contain Remarkup and are rendered into HTML. Implementing this interface allows you to render objects through PhabricatorMarkupEngine and benefit from caching and pipelining infrastructure.

An object may have several "fields" of markup. For example, Differential revisions have a "summary" and a "test plan". In these cases, the $field parameter is used to identify which field is being operated on. For simple objects like comments, you might only have one field (say, "body"). In these cases, the implementation can largely ignore the $field parameter.

Tasks

Markup Interface

  • public function getMarkupFieldKey($field) — Get a key to identify this field. This should uniquely identify the block of text to be rendered and be usable as a cache key. If the object has a PHID, using the PHID and the field name is likely reasonable:
  • public function newMarkupEngine($field) — Build the engine the field should use.
  • public function getMarkupText($field) — Return the contents of the specified field.
  • public function didMarkupText($field, $output, $engine) — Callback for final postprocessing of output. Normally, you can return the output unmodified.
  • public function shouldUseMarkupCache($field) — Determine if the engine should try to use the markup cache or not. Generally you should use the cache for durable/permanent content but should not use the cache for temporary/draft content.

Methods

public function getMarkupFieldKey($field)

Get a key to identify this field. This should uniquely identify the block of text to be rendered and be usable as a cache key. If the object has a PHID, using the PHID and the field name is likely reasonable:

"{$phid}:{$field}"
Parameters
string$fieldField name.
Return
stringCache key up to 125 characters.

public function newMarkupEngine($field)

Build the engine the field should use.

Parameters
string$fieldField name.
Return
PhutilRemarkupEngineMarkup engine to use.

public function getMarkupText($field)

Return the contents of the specified field.

Parameters
string$fieldField name.
Return
stringThe raw markup contained in the field.

public function didMarkupText($field, $output, $engine)

Callback for final postprocessing of output. Normally, you can return the output unmodified.

Parameters
string$fieldField name.
string$outputThe finalized output of the engine.
string$engineThe engine which generated the output.
Return
stringFinal output.

public function shouldUseMarkupCache($field)

Determine if the engine should try to use the markup cache or not. Generally you should use the cache for durable/permanent content but should not use the cache for temporary/draft content.

Parameters
$field
Return
boolTrue to use the markup cache.
Defined
src/infrastructure/markup/PhabricatorMarkupInterface.php:18