[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @task children   Managing Children
   5   */
   6  abstract class AphrontView extends Phobject
   7    implements PhutilSafeHTMLProducerInterface {
   8  
   9    protected $user;
  10    protected $children = array();
  11  
  12  
  13  /* -(  Configuration  )------------------------------------------------------ */
  14  
  15  
  16    /**
  17     * @task config
  18     */
  19    public function setUser(PhabricatorUser $user) {
  20      $this->user = $user;
  21      return $this;
  22    }
  23  
  24  
  25    /**
  26     * @task config
  27     */
  28    protected function getUser() {
  29      return $this->user;
  30    }
  31  
  32  
  33  /* -(  Managing Children  )-------------------------------------------------- */
  34  
  35  
  36    /**
  37     * Test if this View accepts children.
  38     *
  39     * By default, views accept children, but subclases may override this method
  40     * to prevent children from being appended. Doing so will cause
  41     * @{method:appendChild} to throw exceptions instead of appending children.
  42     *
  43     * @return bool   True if the View should accept children.
  44     * @task children
  45     */
  46    protected function canAppendChild() {
  47      return true;
  48    }
  49  
  50  
  51    /**
  52     * Append a child to the list of children.
  53     *
  54     * This method will only work if the view supports children, which is
  55     * determined by @{method:canAppendChild}.
  56     *
  57     * @param  wild   Something renderable.
  58     * @return this
  59     */
  60    final public function appendChild($child) {
  61      if (!$this->canAppendChild()) {
  62        $class = get_class($this);
  63        throw new Exception(
  64          pht("View '%s' does not support children.", $class));
  65      }
  66  
  67      $this->children[] = $child;
  68  
  69      return $this;
  70    }
  71  
  72  
  73    /**
  74     * Produce children for rendering.
  75     *
  76     * Historically, this method reduced children to a string representation,
  77     * but it no longer does.
  78     *
  79     * @return wild Renderable children.
  80     * @task
  81     */
  82    final protected function renderChildren() {
  83      return $this->children;
  84    }
  85  
  86  
  87    /**
  88     * Test if an element has no children.
  89     *
  90     * @return bool True if this element has children.
  91     * @task children
  92     */
  93    final public function hasChildren() {
  94      if ($this->children) {
  95        $this->children = $this->reduceChildren($this->children);
  96      }
  97      return (bool)$this->children;
  98    }
  99  
 100  
 101    /**
 102     * Reduce effectively-empty lists of children to be actually empty. This
 103     * recursively removes `null`, `''`, and `array()` from the list of children
 104     * so that @{method:hasChildren} can more effectively align with expectations.
 105     *
 106     * NOTE: Because View children are not rendered, a View which renders down
 107     * to nothing will not be reduced by this method.
 108     *
 109     * @param   list<wild>  Renderable children.
 110     * @return  list<wild>  Reduced list of children.
 111     * @task children
 112     */
 113    private function reduceChildren(array $children) {
 114      foreach ($children as $key => $child) {
 115        if ($child === null) {
 116          unset($children[$key]);
 117        } else if ($child === '') {
 118          unset($children[$key]);
 119        } else if (is_array($child)) {
 120          $child = $this->reduceChildren($child);
 121          if ($child) {
 122            $children[$key] = $child;
 123          } else {
 124            unset($children[$key]);
 125          }
 126        }
 127      }
 128      return $children;
 129    }
 130  
 131    public function getDefaultResourceSource() {
 132      return 'phabricator';
 133    }
 134  
 135    public function requireResource($symbol) {
 136      $response = CelerityAPI::getStaticResourceResponse();
 137      $response->requireResource($symbol, $this->getDefaultResourceSource());
 138      return $this;
 139    }
 140  
 141    public function initBehavior($name, $config = array()) {
 142      Javelin::initBehavior(
 143        $name,
 144        $config,
 145        $this->getDefaultResourceSource());
 146    }
 147  
 148  
 149  /* -(  Rendering  )---------------------------------------------------------- */
 150  
 151  
 152    abstract public function render();
 153  
 154  
 155  /* -(  PhutilSafeHTMLProducerInterface  )------------------------------------ */
 156  
 157  
 158    public function producePhutilSafeHTML() {
 159      return $this->render();
 160    }
 161  
 162  }