PhabricatorMarkupInterface.php

<?php

/**
 * 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 @{class: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.
 *
 * @task markup Markup Interface
 */
interface PhabricatorMarkupInterface {


/* -(  Markup Interface  )--------------------------------------------------- */


  /**
   * 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}"
   *
   * @param string Field name.
   * @return string Cache key up to 125 characters.
   *
   * @task markup
   */
  public function getMarkupFieldKey($field);


  /**
   * Build the engine the field should use.
   *
   * @param string Field name.
   * @return PhutilRemarkupEngine Markup engine to use.
   * @task markup
   */
  public function newMarkupEngine($field);


  /**
   * Return the contents of the specified field.
   *
   * @param string Field name.
   * @return string The raw markup contained in the field.
   * @task markup
   */
  public function getMarkupText($field);


  /**
   * Callback for final postprocessing of output. Normally, you can return
   * the output unmodified.
   *
   * @param string Field name.
   * @param string The finalized output of the engine.
   * @param string The engine which generated the output.
   * @return string Final output.
   * @task markup
   */
  public function didMarkupText(
    $field,
    $output,
    PhutilMarkupEngine $engine);


  /**
   * 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.
   *
   * @return bool True to use the markup cache.
   * @task markup
   */
  public function shouldUseMarkupCache($field);

}