Homec4science
Diffusion Phabricator (feature/testing) Browse

phab/src/applications/settings/panel/PhabricatorSettingsPanel.php
fe2a96e37ff0feature/testing

Last Change
Raw File

PhabricatorSettingsPanel.php
View Options

<?php
/**
* Defines a settings panel. Settings panels appear in the Settings application,
* and behave like lightweight controllers -- generally, they render some sort
* of form with options in it, and then update preferences when the user
* submits the form. By extending this class, you can add new settings
* panels.
*
* NOTE: This stuff is new and might not be completely stable.
*
* @task config Panel Configuration
* @task panel Panel Implementation
* @task internal Internals
*
* @group settings
*/
abstract class PhabricatorSettingsPanel {
/* -( Panel Configuration )------------------------------------------------ */
/**
* Return a unique string used in the URI to identify this panel, like
* "example".
*
* @return string Unique panel identifier (used in URIs).
* @task config
*/
abstract public function getPanelKey();
/**
* Return a human-readable description of the panel's contents, like
* "Example Settings".
*
* @return string Human-readable panel name.
* @task config
*/
abstract public function getPanelName();
/**
* Return a human-readable group name for this panel. For instance, if you
* had several related panels like "Volume Settings" and
* "Microphone Settings", you might put them in a group called "Audio".
*
* When displayed, panels are grouped with other panels that have the same
* group name.
*
* @return string Human-readable panel group name.
* @task config
*/
abstract public function getPanelGroup();
/**
* Return false to prevent this panel from being displayed or used. You can
* do, e.g., configuration checks here, to determine if the feature your
* panel controls is unavailble in this install. By default, all panels are
* enabled.
*
* @return bool True if the panel should be shown.
* @task config
*/
public function isEnabled() {
return true;
}
/**
* You can use this callback to generate multiple similar panels which all
* share the same implementation. For example, OAuth providers each have a
* separate panel, but the implementation for each panel is the same.
*
* To generate multiple panels, build them here and return a list. By default,
* the current panel (`$this`) is returned alone. For most panels, this
* is the right implementation.
*
* @return list<PhabricatorSettingsPanel> Zero or more panels.
* @task config
*/
public function buildPanels() {
return array($this);
}
/* -( Panel Implementation )----------------------------------------------- */
/**
* Process a user request for this settings panel. Implement this method like
* a lightweight controller. If you return an @{class:AphrontResponse}, the
* response will be used in whole. If you return anything else, it will be
* treated as a view and composed into a normal settings page.
*
* Generally, render your settings panel by returning a form, then return
* a redirect when the user saves settings.
*
* @param AphrontRequest Incoming request.
* @return wild Response to request, either as an
* @{class:AphrontResponse} or something which can
* be composed into a @{class:AphrontView}.
* @task panel
*/
abstract public function processRequest(AphrontRequest $request);
/**
* Get the URI for this panel.
*
* @param string? Optional path to append.
* @return string Relative URI for the panel.
* @task panel
*/
final public function getPanelURI($path = '') {
$key = $this->getPanelKey();
$key = phutil_escape_uri($key);
return '/settings/panel/'.$key.'/'.ltrim($path, '/');
}
/* -( Internals )---------------------------------------------------------- */
/**
* Generates a key to sort the list of panels.
*
* @return string Sortable key.
* @task internal
*/
final public function getPanelSortKey() {
return sprintf(
'%s'.chr(255).'%s',
$this->getPanelGroup(),
$this->getPanelName());
}
}
c4science · Help