[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Defines a settings panel. Settings panels appear in the Settings application,
   5   * and behave like lightweight controllers -- generally, they render some sort
   6   * of form with options in it, and then update preferences when the user
   7   * submits the form. By extending this class, you can add new settings
   8   * panels.
   9   *
  10   * NOTE: This stuff is new and might not be completely stable.
  11   *
  12   * @task config   Panel Configuration
  13   * @task panel    Panel Implementation
  14   * @task internal Internals
  15   */
  16  abstract class PhabricatorSettingsPanel {
  17  
  18    private $user;
  19    private $viewer;
  20    private $overrideURI;
  21  
  22  
  23    public function setUser(PhabricatorUser $user) {
  24      $this->user = $user;
  25      return $this;
  26    }
  27  
  28    public function getUser() {
  29      return $this->user;
  30    }
  31  
  32    public function setViewer(PhabricatorUser $viewer) {
  33      $this->viewer = $viewer;
  34      return $this;
  35    }
  36  
  37    public function getViewer() {
  38      return $this->viewer;
  39    }
  40  
  41    public function setOverrideURI($override_uri) {
  42      $this->overrideURI = $override_uri;
  43      return $this;
  44    }
  45  
  46  
  47  /* -(  Panel Configuration  )------------------------------------------------ */
  48  
  49  
  50    /**
  51     * Return a unique string used in the URI to identify this panel, like
  52     * "example".
  53     *
  54     * @return string Unique panel identifier (used in URIs).
  55     * @task config
  56     */
  57    abstract public function getPanelKey();
  58  
  59  
  60    /**
  61     * Return a human-readable description of the panel's contents, like
  62     * "Example Settings".
  63     *
  64     * @return string Human-readable panel name.
  65     * @task config
  66     */
  67    abstract public function getPanelName();
  68  
  69  
  70    /**
  71     * Return a human-readable group name for this panel. For instance, if you
  72     * had several related panels like "Volume Settings" and
  73     * "Microphone Settings", you might put them in a group called "Audio".
  74     *
  75     * When displayed, panels are grouped with other panels that have the same
  76     * group name.
  77     *
  78     * @return string Human-readable panel group name.
  79     * @task config
  80     */
  81    abstract public function getPanelGroup();
  82  
  83  
  84    /**
  85     * Return false to prevent this panel from being displayed or used. You can
  86     * do, e.g., configuration checks here, to determine if the feature your
  87     * panel controls is unavailble in this install. By default, all panels are
  88     * enabled.
  89     *
  90     * @return bool True if the panel should be shown.
  91     * @task config
  92     */
  93    public function isEnabled() {
  94      return true;
  95    }
  96  
  97  
  98    /**
  99     * You can use this callback to generate multiple similar panels which all
 100     * share the same implementation. For example, OAuth providers each have a
 101     * separate panel, but the implementation for each panel is the same.
 102     *
 103     * To generate multiple panels, build them here and return a list. By default,
 104     * the current panel (`$this`) is returned alone. For most panels, this
 105     * is the right implementation.
 106     *
 107     * @return list<PhabricatorSettingsPanel> Zero or more panels.
 108     * @task config
 109     */
 110    public function buildPanels() {
 111      return array($this);
 112    }
 113  
 114  
 115    /**
 116     * Return true if this panel is available to administrators while editing
 117     * system agent accounts.
 118     *
 119     * @return bool True to enable edit by administrators.
 120     * @task config
 121     */
 122    public function isEditableByAdministrators() {
 123      return false;
 124    }
 125  
 126  
 127  /* -(  Panel Implementation  )----------------------------------------------- */
 128  
 129  
 130    /**
 131     * Process a user request for this settings panel. Implement this method like
 132     * a lightweight controller. If you return an @{class:AphrontResponse}, the
 133     * response will be used in whole. If you return anything else, it will be
 134     * treated as a view and composed into a normal settings page.
 135     *
 136     * Generally, render your settings panel by returning a form, then return
 137     * a redirect when the user saves settings.
 138     *
 139     * @param   AphrontRequest  Incoming request.
 140     * @return  wild            Response to request, either as an
 141     *                          @{class:AphrontResponse} or something which can
 142     *                          be composed into a @{class:AphrontView}.
 143     * @task panel
 144     */
 145    abstract public function processRequest(AphrontRequest $request);
 146  
 147  
 148    /**
 149     * Get the URI for this panel.
 150     *
 151     * @param string? Optional path to append.
 152     * @return string Relative URI for the panel.
 153     * @task panel
 154     */
 155    final public function getPanelURI($path = '') {
 156      $path = ltrim($path, '/');
 157  
 158      if ($this->overrideURI) {
 159        return rtrim($this->overrideURI, '/').'/'.$path;
 160      }
 161  
 162      $key = $this->getPanelKey();
 163      $key = phutil_escape_uri($key);
 164  
 165      if ($this->getUser()->getPHID() != $this->getViewer()->getPHID()) {
 166        $user_id = $this->getUser()->getID();
 167        return "/settings/{$user_id}/panel/{$key}/{$path}";
 168      } else {
 169        return "/settings/panel/{$key}/{$path}";
 170      }
 171    }
 172  
 173  
 174  /* -(  Internals  )---------------------------------------------------------- */
 175  
 176  
 177    /**
 178     * Generates a key to sort the list of panels.
 179     *
 180     * @return string Sortable key.
 181     * @task internal
 182     */
 183    final public function getPanelSortKey() {
 184      return sprintf(
 185        '%s'.chr(255).'%s',
 186        $this->getPanelGroup(),
 187        $this->getPanelName());
 188    }
 189  
 190  }