<?php
/**
* @task children Managing Children
*/
abstract class AphrontView extends Phobject
implements PhutilSafeHTMLProducerInterface {
private $viewer;
protected $children = array();
/* -( Configuration )------------------------------------------------------ */
/**
* Set the user viewing this element.
*
* @param PhabricatorUser Viewing user.
* @return this
*/
public function setViewer(PhabricatorUser $viewer) {
$this->viewer = $viewer;
return $this;
}
/**
* Get the user viewing this element.
*
* Throws an exception if no viewer has been set.
*
* @return PhabricatorUser Viewing user.
*/
public function getViewer() {
if (!$this->viewer) {
throw new PhutilInvalidStateException('setViewer');
}
return $this->viewer;
}
/**
* Test if a viewer has been set on this element.
*
* @return bool True if a viewer is available.
*/
public function hasViewer() {
return (bool)$this->viewer;
}
/**
* Deprecated, use @{method:setViewer}.
*
* @task config
* @deprecated
*/
public function setUser(PhabricatorUser $user) {
return $this->setViewer($user);
}
/**
* Deprecated, use @{method:getViewer}.
*
* @task config
* @deprecated
*/
protected function getUser() {
if (!$this->hasViewer()) {
return null;
}
return $this->getViewer();
}
/* -( Managing Children )-------------------------------------------------- */
/**
* Test if this View accepts children.
*
* By default, views accept children, but subclases may override this method
* to prevent children from being appended. Doing so will cause
* @{method:appendChild} to throw exceptions instead of appending children.
*
* @return bool True if the View should accept children.
* @task children
*/
protected function canAppendChild() {
return true;
}
/**
* Append a child to the list of children.
*
* This method will only work if the view supports children, which is
* determined by @{method:canAppendChild}.
*
* @param wild Something renderable.
* @return this
*/
final public function appendChild($child) {
if (!$this->canAppendChild()) {
$class = get_class($this);
throw new Exception(
pht("View '%s' does not support children.", $class));
}
$this->children[] = $child;
return $this;
}
/**
* Produce children for rendering.
*
* Historically, this method reduced children to a string representation,
* but it no longer does.
*
* @return wild Renderable children.
* @task
*/
final protected function renderChildren() {
return $this->children;
}
/**
* Test if an element has no children.
*
* @return bool True if this element has children.
* @task children
*/
final public function hasChildren() {
if ($this->children) {
$this->children = $this->reduceChildren($this->children);
}
return (bool)$this->children;
}
/**
* Reduce effectively-empty lists of children to be actually empty. This
* recursively removes `null`, `''`, and `array()` from the list of children
* so that @{method:hasChildren} can more effectively align with expectations.
*
* NOTE: Because View children are not rendered, a View which renders down
* to nothing will not be reduced by this method.
*
* @param list<wild> Renderable children.
* @return list<wild> Reduced list of children.
* @task children
*/
private function reduceChildren(array $children) {
foreach ($children as $key => $child) {
if ($child === null) {
unset($children[$key]);
} else if ($child === '') {
unset($children[$key]);
} else if (is_array($child)) {
$child = $this->reduceChildren($child);
if ($child) {
$children[$key] = $child;
} else {
unset($children[$key]);
}
}
}
return $children;
}
public function getDefaultResourceSource() {
return 'phabricator';
}
public function requireResource($symbol) {
$response = CelerityAPI::getStaticResourceResponse();
$response->requireResource($symbol, $this->getDefaultResourceSource());
return $this;
}
public function initBehavior($name, $config = array()) {
Javelin::initBehavior(
$name,
$config,
$this->getDefaultResourceSource());
return $this;
}
/* -( Rendering )---------------------------------------------------------- */
/**
* Inconsistent, unreliable pre-rendering hook.
*
* This hook //may// fire before views render. It is not fired reliably, and
* may fire multiple times.
*
* If it does fire, views might use it to register data for later loads, but
* almost no datasources support this now; this is currently only useful for
* tokenizers. This mechanism might eventually see wider support or might be
* removed.
*/
public function willRender() {
return;
}
abstract public function render();
/* -( PhutilSafeHTMLProducerInterface )------------------------------------ */
public function producePhutilSafeHTML() {
return $this->render();
}
}