src/applications/settings/panel/PhabricatorSettingsPanel.php

   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  * @task config   Panel Configuration
  11  * @task panel    Panel Implementation
  12  * @task internal Internals
  13  */
  14 abstract class PhabricatorSettingsPanel extends Phobject {
  15
  16   private $user;
  17   private $viewer;
  18   private $controller;
  19   private $navigation;
  20   private $overrideURI;
  21   private $preferences;
  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   final public function setController(PhabricatorController $controller) {
  47     $this->controller = $controller;
  48     return $this;
  49   }
  50
  51   final public function getController() {
  52     return $this->controller;
  53   }
  54
  55   final public function setNavigation(AphrontSideNavFilterView $navigation) {
  56     $this->navigation = $navigation;
  57     return $this;
  58   }
  59
  60   final public function getNavigation() {
  61     return $this->navigation;
  62   }
  63
  64   public function setPreferences(PhabricatorUserPreferences $preferences) {
  65     $this->preferences = $preferences;
  66     return $this;
  67   }
  68
  69   public function getPreferences() {
  70     return $this->preferences;
  71   }
  72
  73   final public static function getAllPanels() {
  74     $panels = id(new PhutilClassMapQuery())
  75       ->setAncestorClass(__CLASS__)
  76       ->setUniqueMethod('getPanelKey')
  77       ->execute();
  78     return msortv($panels, 'getPanelOrderVector');
  79   }
  80
  81   final public static function getAllDisplayPanels() {
  82     $panels = array();
  83     $groups = PhabricatorSettingsPanelGroup::getAllPanelGroupsWithPanels();
  84     foreach ($groups as $group) {
  85       foreach ($group->getPanels() as $key => $panel) {
  86         $panels[$key] = $panel;
  87       }
  88     }
  89
  90     return $panels;
  91   }
  92
  93   final public function getPanelGroup() {
  94     $group_key = $this->getPanelGroupKey();
  95
  96     $groups = PhabricatorSettingsPanelGroup::getAllPanelGroupsWithPanels();
  97     $group = idx($groups, $group_key);
  98     if (!$group) {
  99       throw new Exception(
 100         pht(
 101           'No settings panel group with key "%s" exists!',
 102           $group_key));
 103     }
 104
 105     return $group;
 106   }
 107
 108
 109 /* -(  Panel Configuration  )------------------------------------------------ */
 110
 111
 112   /**
 113    * Return a unique string used in the URI to identify this panel, like
 114    * "example".
 115    *
 116    * @return string Unique panel identifier (used in URIs).
 117    * @task config
 118    */
 119   public function getPanelKey() {
 120     return $this->getPhobjectClassConstant('PANELKEY');
 121   }
 122
 123
 124   /**
 125    * Return a human-readable description of the panel's contents, like
 126    * "Example Settings".
 127    *
 128    * @return string Human-readable panel name.
 129    * @task config
 130    */
 131   abstract public function getPanelName();
 132
 133
 134   /**
 135    * Return an icon for the panel in the menu.
 136    *
 137    * @return string Icon identifier.
 138    * @task config
 139    */
 140   public function getPanelMenuIcon() {
 141     return 'fa-wrench';
 142   }
 143
 144   /**
 145    * Return a panel group key constant for this panel.
 146    *
 147    * @return const Panel group key.
 148    * @task config
 149    */
 150   abstract public function getPanelGroupKey();
 151
 152
 153   /**
 154    * Return false to prevent this panel from being displayed or used. You can
 155    * do, e.g., configuration checks here, to determine if the feature your
 156    * panel controls is unavailable in this install. By default, all panels are
 157    * enabled.
 158    *
 159    * @return bool True if the panel should be shown.
 160    * @task config
 161    */
 162   public function isEnabled() {
 163     return true;
 164   }
 165
 166
 167   /**
 168    * Return true if this panel is available to users while editing their own
 169    * settings.
 170    *
 171    * @return bool True to enable management on behalf of a user.
 172    * @task config
 173    */
 174   public function isUserPanel() {
 175     return true;
 176   }
 177
 178
 179   /**
 180    * Return true if this panel is available to administrators while managing
 181    * bot and mailing list accounts.
 182    *
 183    * @return bool True to enable management on behalf of accounts.
 184    * @task config
 185    */
 186   public function isManagementPanel() {
 187     return false;
 188   }
 189
 190
 191   /**
 192    * Return true if this panel is available while editing settings templates.
 193    *
 194    * @return bool True to allow editing in templates.
 195    * @task config
 196    */
 197   public function isTemplatePanel() {
 198     return false;
 199   }
 200
 201   /**
 202    * Return true if this panel should be available when enrolling in MFA on
 203    * a new account with MFA requiredd.
 204    *
 205    * @return bool True to allow configuration during MFA enrollment.
 206    * @task config
 207    */
 208   public function isMultiFactorEnrollmentPanel() {
 209     return false;
 210   }
 211
 212
 213 /* -(  Panel Implementation  )----------------------------------------------- */
 214
 215
 216   /**
 217    * Process a user request for this settings panel. Implement this method like
 218    * a lightweight controller. If you return an @{class:AphrontResponse}, the
 219    * response will be used in whole. If you return anything else, it will be
 220    * treated as a view and composed into a normal settings page.
 221    *
 222    * Generally, render your settings panel by returning a form, then return
 223    * a redirect when the user saves settings.
 224    *
 225    * @param   AphrontRequest  Incoming request.
 226    * @return  wild            Response to request, either as an
 227    *                          @{class:AphrontResponse} or something which can
 228    *                          be composed into a @{class:AphrontView}.
 229    * @task panel
 230    */
 231   abstract public function processRequest(AphrontRequest $request);
 232
 233
 234   /**
 235    * Get the URI for this panel.
 236    *
 237    * @param string? Optional path to append.
 238    * @return string Relative URI for the panel.
 239    * @task panel
 240    */
 241   final public function getPanelURI($path = '') {
 242     $path = ltrim($path, '/');
 243
 244     if ($this->overrideURI) {
 245       return rtrim($this->overrideURI, '/').'/'.$path;
 246     }
 247
 248     $key = $this->getPanelKey();
 249     $key = phutil_escape_uri($key);
 250
 251     $user = $this->getUser();
 252     if ($user) {
 253       if ($user->isLoggedIn()) {
 254         $username = $user->getUsername();
 255         return "/settings/user/{$username}/page/{$key}/{$path}";
 256       } else {
 257         // For logged-out users, we can't put their username in the URI. This
 258         // page will prompt them to login, then redirect them to the correct
 259         // location.
 260         return "/settings/panel/{$key}/";
 261       }
 262     } else {
 263       $builtin = $this->getPreferences()->getBuiltinKey();
 264       return "/settings/builtin/{$builtin}/page/{$key}/{$path}";
 265     }
 266   }
 267
 268
 269 /* -(  Internals  )---------------------------------------------------------- */
 270
 271
 272   /**
 273    * Generates a key to sort the list of panels.
 274    *
 275    * @return string Sortable key.
 276    * @task internal
 277    */
 278   final public function getPanelOrderVector() {
 279     return id(new PhutilSortVector())
 280       ->addString($this->getPanelName());
 281   }
 282
 283   protected function newDialog() {
 284     return $this->getController()->newDialog();
 285   }
 286
 287   protected function writeSetting(
 288     PhabricatorUserPreferences $preferences,
 289     $key,
 290     $value) {
 291     $viewer = $this->getViewer();
 292     $request = $this->getController()->getRequest();
 293
 294     $editor = id(new PhabricatorUserPreferencesEditor())
 295       ->setActor($viewer)
 296       ->setContentSourceFromRequest($request)
 297       ->setContinueOnNoEffect(true)
 298       ->setContinueOnMissingFields(true);
 299
 300     $xactions = array();
 301     $xactions[] = $preferences->newTransaction($key, $value);
 302     $editor->applyTransactions($preferences, $xactions);
 303   }
 304
 305
 306   public function newBox($title, $content, $actions = array()) {
 307     $header = id(new PHUIHeaderView())
 308       ->setHeader($title);
 309
 310     foreach ($actions as $action) {
 311       $header->addActionLink($action);
 312     }
 313
 314     $view = id(new PHUIObjectBoxView())
 315       ->setHeader($header)
 316       ->appendChild($content)
 317       ->setBackground(PHUIObjectBoxView::WHITE_CONFIG);
 318
 319     return $view;
 320   }
 321
 322 }