[Summary view] [Print] [Text view]

   1  @title Configuring Custom Fields
   2  @group config
   3  
   4  How to add custom fields to applications which support them.
   5  
   6  = Overview =
   7  
   8  Several Phabricator applications allow the configuration of custom fields. These
   9  fields allow you to add more information to objects, and in some cases reorder
  10  or remove builtin fields.
  11  
  12  For example, you could use custom fields to add an "Estimated Hours" field to
  13  tasks, a "Lead" field to projects, or a "T-Shirt Size" field to users.
  14  
  15  These applications currently support custom fields:
  16  
  17  | Application | Support |
  18  |-------------|---------|
  19  | Maniphest | Full Support |
  20  | Projects | Full Support |
  21  | People | Full Support |
  22  | Differential | Partial Support |
  23  | Diffusion | Limited Support |
  24  
  25  Custom fields can appear in many interfaces and support search, editing, and
  26  other features.
  27  
  28  = Basic Custom Fields =
  29  
  30  To get started with custom fields, you can use configuration to select and
  31  reorder fields and to add new simple fields.
  32  
  33  If you don't need complicated display controls or sophisticated validation,
  34  these simple fields should cover most use cases. They allow you to attach
  35  things like strings, numbers, and dropdown menus to objects.
  36  
  37  The relevant configuration settings are:
  38  
  39  | Application | Add Fields | Select Fields |
  40  |-------------|------------|---------------|
  41  | Maniphest | `maniphest.custom-field-definitions` | `maniphest.fields` |
  42  | Projects | `projects.custom-field-definitions` | `projects.fields` |
  43  | People | `user.custom-field-definitions` | `user.fields` |
  44  | Differential | Planned | `differential.fields` |
  45  | Diffusion | Planned | Planned |
  46  
  47  When adding fields, you'll specify a JSON blob like this (for example, as the
  48  value of `maniphest.custom-field-definitions`):
  49  
  50    {
  51      "mycompany:estimated-hours": {
  52        "name": "Estimated Hours",
  53        "type": "int",
  54        "caption": "Estimated number of hours this will take.",
  55        "required": true
  56      },
  57      "mycompany:actual-hours": {
  58        "name": "Actual Hours",
  59        "type": "int",
  60        "caption": "Actual number of hours this took."
  61      },
  62      "mycompany:company-jobs": {
  63        "name": "Job Role",
  64        "type": "select",
  65        "options": {
  66          "mycompany:engineer": "Engineer",
  67          "mycompany:nonengineer": "Other"
  68        }
  69      },
  70      "mycompany:favorite-dinosaur": {
  71        "name": "Favorite Dinosaur",
  72        "type": "text"
  73      }
  74    }
  75  
  76  The fields will then appear in the other config option for the application
  77  (for example, in `maniphest.fields`) and you can enable, disable, or reorder
  78  them.
  79  
  80  For details on how to define a field, see the next section.
  81  
  82  = Custom Field Configuration =
  83  
  84  When defining custom fields using a configuration option like
  85  `maniphest.custom-field-definitions`, these options are available:
  86  
  87    - **name**: Display label for the field on the edit and detail interfaces.
  88    - **description**: Optional text shown when managing the field.
  89    - **type**: Field type. The supported field types are:
  90      - **int**: An integer, rendered as a text field.
  91      - **text**: A string, rendered as a text field.
  92      - **bool**: A boolean value, rendered as a checkbox.
  93      - **select**: Allows the user to select from several options as defined
  94        by **options**, rendered as a dropdown.
  95      - **remarkup**: A text area which allows the user to enter markup.
  96      - **users**: A typeahead which allows multiple users to be input.
  97      - **date**: A date/time picker.
  98      - **header**: Renders a visual divider which you can use to group fields.
  99    - **edit**: Show this field on the application's edit interface (this
 100      defaults to `true`).
 101    - **view**: Show this field on the application's view interface (this
 102      defaults to `true`). (Note: Empty fields are not shown.)
 103    - **search**: Show this field on the application's search interface, allowing
 104      users to filter objects by the field value.
 105    - **fulltext**: Index the text in this field as part of the object's global
 106      full-text index. This allows users to find the object by searching for
 107      the field's contents using global search.
 108    - **caption**: A caption to display underneath the field (optional).
 109    - **required**: True if the user should be required to provide a value.
 110    - **options**: If type is set to **select**, provide options for the dropdown
 111      as a dictionary.
 112    - **default**: Default field value.
 113    - **strings**: Allows you to override specific strings based on the field
 114      type. See below.
 115    - **instructions**: Optional block of remarkup text which will appear
 116      above the control when rendered on the edit view.
 117    - **placeholder**: A placeholder text that appears on text boxes. Only
 118      supported in text, int and remarkup fields (optional).
 119  
 120  The `strings` value supports different strings per control type. They are:
 121  
 122    - **bool**
 123      - **edit.checkbox** Text for the edit interface, no default.
 124      - **view.yes** Text for the view interface, defaults to "Yes".
 125      - **search.default** Text for the search interface, defaults to "(Any)".
 126      - **search.require** Text for the search interface, defaults to "Require".
 127  
 128  Some applications have specific options which only work in that application.
 129  
 130  In **Maniphest**:
 131  
 132    - **copy**: When a user creates a task, the UI gives them an option to
 133      "Create Another Similar Task". Some fields from the original task are copied
 134      into the new task, while others are not; by default, fields are not copied.
 135      If you want this field to be copied, specify `true` for the `copy` property.
 136  
 137  Internally, Phabricator implements some additional custom field types and
 138  options. These are not intended for general use and are subject to abrupt
 139  change, but are documented here for completeness:
 140  
 141    - **Credentials**: Controls with type `credential` allow selection of a
 142      Passphrase credential which provides `credential.provides`, and creation
 143      of credentials of `credential.type`.
 144  
 145  = Advanced Custom Fields =
 146  
 147  If you want custom fields to have advanced behaviors (sophisticated rendering,
 148  advanced validation, complicated controls, interaction with other systems, etc),
 149  you can write a custom field as an extension and add it to Phabricator.
 150  
 151  NOTE: This API is somewhat new and fairly large. You should expect that there
 152  will be occasional changes to the API requiring minor updates in your code.
 153  
 154  To do this, extend the appropriate `CustomField` class for the application you
 155  want to add a field to:
 156  
 157  | Application | Extend  |
 158  |-------------|---------|
 159  | Maniphest | @{class:ManiphestCustomField} |
 160  | Projects | @{class:PhabricatorProjectCustomField} |
 161  | People | @{class:PhabricatorUserCustomField} |
 162  | Differential | @{class:DifferentialCustomField} |
 163  | Diffusion | @{class:PhabricatorCommitCustomField} |
 164  
 165  The easiest way to get started is to drop your subclass into
 166  `phabricator/src/extensions/`, which should make it immediately available in the
 167  UI (if you use APC, you may need to restart your webserver). For example, this
 168  is a simple template which adds a custom field to Maniphest:
 169  
 170    name=ExampleManiphestCustomField.php
 171    <?php
 172  
 173    final class ExampleCustomField extends ManiphestCustomField {
 174  
 175      public function getFieldKey() {
 176        return 'example:test';
 177      }
 178  
 179      public function shouldAppearInPropertyView() {
 180        return true;
 181      }
 182  
 183      public function renderPropertyViewLabel() {
 184        return pht('Example Custom Field');
 185      }
 186  
 187      public function renderPropertyViewValue(array $handles) {
 188        return phutil_tag(
 189          'h1',
 190          array(
 191            'style' => 'color: #ff00ff',
 192          ),
 193          pht('It worked!'));
 194      }
 195  
 196    }
 197  
 198  Broadly, you can then add features by overriding more methods and implementing
 199  them. Many of the native fields are implemented on the custom field
 200  architecture, and it may be useful to look at them. For details on available
 201  integrations, see the base class for your application and
 202  @{class:PhabricatorCustomField}.
 203  
 204  = Next Steps =
 205  
 206  Continue by:
 207  
 208    - learning more about extending Phabricator with custom code in
 209      @{article:libphutil Libraries User Guide};
 210    - or returning to the @{article: Configuration Guide}.