recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1<?php
2
3/**
4 * An object which has one or more fields containing markup that can be
5 * rendered into a display format. Commonly, the fields contain Remarkup and
6 * are rendered into HTML. Implementing this interface allows you to render
7 * objects through @{class:PhabricatorMarkupEngine} and benefit from caching
8 * and pipelining infrastructure.
9 *
10 * An object may have several "fields" of markup. For example, Differential
11 * revisions have a "summary" and a "test plan". In these cases, the `$field`
12 * parameter is used to identify which field is being operated on. For simple
13 * objects like comments, you might only have one field (say, "body"). In
14 * these cases, the implementation can largely ignore the `$field` parameter.
15 *
16 * @task markup Markup Interface
17 */
18interface PhabricatorMarkupInterface {
19
20
21/* -( Markup Interface )--------------------------------------------------- */
22
23
24 /**
25 * Get a key to identify this field. This should uniquely identify the block
26 * of text to be rendered and be usable as a cache key. If the object has a
27 * PHID, using the PHID and the field name is likely reasonable:
28 *
29 * "{$phid}:{$field}"
30 *
31 * @param string $field Field name.
32 * @return string Cache key up to 125 characters.
33 *
34 * @task markup
35 */
36 public function getMarkupFieldKey($field);
37
38
39 /**
40 * Build the engine the field should use.
41 *
42 * @param string $field Field name.
43 * @return PhutilRemarkupEngine Markup engine to use.
44 * @task markup
45 */
46 public function newMarkupEngine($field);
47
48
49 /**
50 * Return the contents of the specified field.
51 *
52 * @param string $field Field name.
53 * @return string The raw markup contained in the field.
54 * @task markup
55 */
56 public function getMarkupText($field);
57
58
59 /**
60 * Callback for final postprocessing of output. Normally, you can return
61 * the output unmodified.
62 *
63 * @param string $field Field name.
64 * @param string $output The finalized output of the engine.
65 * @param PhutilMarkupEngine $engine The engine which generated the output.
66 * @return string Final output.
67 * @task markup
68 */
69 public function didMarkupText(
70 $field,
71 $output,
72 PhutilMarkupEngine $engine);
73
74
75 /**
76 * Determine if the engine should try to use the markup cache or not.
77 * Generally you should use the cache for durable/permanent content but
78 * should not use the cache for temporary/draft content.
79 *
80 * @return bool True to use the markup cache.
81 * @task markup
82 */
83 public function shouldUseMarkupCache($field);
84
85}