[Summary view] [Print] [Text view]

   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   */
  18  interface 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 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 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 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 name.
  64     * @param string The finalized output of the engine.
  65     * @param string 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  }