@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Modernize CustomField documentation
Summary: Fixes T4102. Document all the new stuff that CustomField supports now, and all the applications you can use it with.
Test Plan: Generated and read documentation.
Reviewers: chad, btrahan
Reviewed By: btrahan
Subscribers: epriestley
Maniphest Tasks: T4102
Differential Revision: https://secure.phabricator.com/D8541
+187
-64
+187
src/docs/user/configuration/custom_fields.diviner
+187
src/docs/user/configuration/custom_fields.diviner
···
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:favorite-dinosaur": {
63
+
"name": "Favorite Dinosaur",
64
+
"type": "text"
65
+
}
66
+
}
67
+
68
+
The fields will then appear in the other config option for the application
69
+
(for example, in `maniphest.fields`) and you can enable, disable, or reorder
70
+
them.
71
+
72
+
For details on how to define a field, see the next section.
73
+
74
+
= Custom Field Configuration =
75
+
76
+
When defining custom fields using a configuration option like
77
+
`maniphest.custom-field-definitions`, these options are available:
78
+
79
+
- **name**: Display label for the field on the edit and detail interfaces.
80
+
- **description**: Optional text shown when managing the field.
81
+
- **type**: Field type. The supported field types are:
82
+
- **int**: An integer, rendered as a text field.
83
+
- **text**: A string, rendered as a text field.
84
+
- **bool**: A boolean value, rendered as a checkbox.
85
+
- **select**: Allows the user to select from several options, rendered
86
+
as a dropdown.
87
+
- **remarkup**: A text area which allows the user to enter markup.
88
+
- **users**: A typeahead which allows multiple users to be input.
89
+
- **date**: A date/time picker.
90
+
- **header**: Renders a visual divider which you can use to group fields.
91
+
- **edit**: Show this field on the application's edit interface (this
92
+
defaults to `true`).
93
+
- **view**: Show this field on the application's view interface (this
94
+
defaults to `true`).
95
+
- **search**: Show this field on the application's search interface, allowing
96
+
users to filter objects by the field value.
97
+
- **caption**: A caption to display underneath the field (optional).
98
+
- **required**: True if the user should be required to provide a value.
99
+
- **options**: If type is set to **select**, provide options for the dropdown
100
+
as a dictionary.
101
+
- **default**: Default field value.
102
+
- **strings**: Allows you to override specific strings based on the field
103
+
type. See below.
104
+
105
+
The `strings` value supports different strings per control type. They are:
106
+
107
+
- **bool**
108
+
- **edit.checkbox** Text for the edit interface, no default.
109
+
- **view.yes** Text for the view interface, defaults to "Yes".
110
+
- **search.default** Text for the search interface, defaults to "(Any)".
111
+
- **search.require** Text for the search interface, defaults to "Require".
112
+
113
+
Some applications have specific options which only work in that application.
114
+
115
+
In **Maniphest**:
116
+
117
+
- **copy**: When a user creates a task, the UI gives them an option to
118
+
"Create Another Similar Task". Some fields from the original task are copied
119
+
into the new task, while others are not; by default, fields are not copied.
120
+
If you want this field to be copied, specify `true` for the `copy` property.
121
+
122
+
= Advanced Custom Fields =
123
+
124
+
If you want custom fields to have advanced behaviors (sophisticated rendering,
125
+
advanced validation, complicated controls, interaction with other systems, etc),
126
+
you can write a custom field as an extension and add it to Phabricator.
127
+
128
+
NOTE: This API is somewhat new and fairly large. You should expect that there
129
+
will be occasional changes to the API requiring minor updates in your code.
130
+
131
+
To do this, extend the appropriate `CustomField` class for the application you
132
+
want to add a field to:
133
+
134
+
| Application | Extend |
135
+
|-------------|---------|
136
+
| Maniphest | @{class:ManiphestCustomField} |
137
+
| Projects | @{class:PhabricatorProjectCustomField} |
138
+
| People | @{class:PhabricatorUserCustomField} |
139
+
| Differential | @{class:DifferentialCustomField} |
140
+
| Diffusion | @{class:PhabricatorCommitCustomField} |
141
+
142
+
The easiest way to get started is to drop your subclass into
143
+
`phabricator/src/extensions/`, which should make it immediately available in the
144
+
UI (if you use APC, you may need to restart your webserver). For example, this
145
+
is a simple template which adds a custom field to Maniphest:
146
+
147
+
name=ExampleManiphestCustomField.php
148
+
<?php
149
+
150
+
final class ExampleCustomField extends ManiphestCustomField {
151
+
152
+
public function getFieldKey() {
153
+
return 'example:test';
154
+
}
155
+
156
+
public function shouldAppearInPropertyView() {
157
+
return true;
158
+
}
159
+
160
+
public function renderPropertyViewLabel() {
161
+
return pht('Example Custom Field');
162
+
}
163
+
164
+
public function renderPropertyViewValue(array $handles) {
165
+
return phutil_tag(
166
+
'h1',
167
+
array(
168
+
'style' => 'color: #ff00ff',
169
+
),
170
+
pht('It worked!'));
171
+
}
172
+
173
+
}
174
+
175
+
Broadly, you can then add features by overriding more methods and implementing
176
+
them. Many of the native fields are implemented on the custom field
177
+
architecture, and it may be useful to look at them. For details on available
178
+
integrations, see the base class for your application and
179
+
@{class:PhabricatorCustomField}.
180
+
181
+
= Next Steps =
182
+
183
+
Continue by:
184
+
185
+
- learning more about extending Phabricator with custom code in
186
+
@{article:libphutil Libraries User Guide};
187
+
- or returning to the @{article: Configuration Guide}.
-64
src/docs/user/userguide/maniphest_custom.diviner
-64
src/docs/user/userguide/maniphest_custom.diviner
···
1
-
@title Maniphest User Guide: Adding Custom Fields
2
-
@group userguide
3
-
4
-
How to add custom fields to Maniphest.
5
-
6
-
= Overview =
7
-
8
-
Maniphest provides some support for adding new fields to tasks, like an
9
-
"cost" field, a "milestone" field, etc.
10
-
11
-
NOTE: Currently, these fields are somewhat limited. They primarily give you a
12
-
structured way to record data on tasks, but there isn't much support for
13
-
bringing them into other interfaces (e.g., querying by them, aggregating them,
14
-
drawing graphs, etc.). If you have a use case, let us know what you want to do
15
-
and maybe we can figure something out. This data is also exposed via the Conduit
16
-
API, so you might be able to write your own interface if you want to do
17
-
something very custom.
18
-
19
-
= Simple Field Customization =
20
-
21
-
If you don't need complicated display controls or sophisticated validation, you
22
-
can add simple fields. These allow you to attach things like strings, numbers,
23
-
and dropdown menus to the task template.
24
-
25
-
Customize Maniphest fields by setting `maniphest.custom-field-definitions` in
26
-
your configuration. For example, suppose you want to add "Estimated Hours" and
27
-
"Actual Hours" fields. To do this, set your configuration like this:
28
-
29
-
'maniphest.custom-fields' => array(
30
-
'mycompany:estimated-hours' => array(
31
-
'name' => 'Estimated Hours',
32
-
'type' => 'int',
33
-
'caption' => 'Estimated number of hours this will take.',
34
-
'required' => true,
35
-
),
36
-
'mycompany:actual-hours' => array(
37
-
'name' => 'Actual Hours',
38
-
'type' => 'int',
39
-
),
40
-
)
41
-
42
-
Each array key must be unique, and is used to organize the internal storage of
43
-
the field. These options are available:
44
-
45
-
- **name**: Display label for the field on the edit and detail interfaces.
46
-
- **type**: Field type. The supported field types are:
47
-
- **int**: An integer, rendered as a text field.
48
-
- **text**: A string, rendered as a text field.
49
-
- **bool**: A boolean value, rendered as a checkbox.
50
-
- **select**: Allows the user to select from several options, rendered
51
-
as a dropdown.
52
-
- **remarkup**: A text area which allows the user to enter markup.
53
-
- **users**: A typeahead which allows multiple users to be input.
54
-
- **date**: A date/time picker.
55
-
- **header**: Renders a visual divider which you can use to group fields.
56
-
- **caption**: A caption to display underneath the field (optional).
57
-
- **required**: True if the user should be required to provide a value.
58
-
- **options**: If type is set to **select**, provide options for the dropdown
59
-
as a dictionary.
60
-
- **default**: Default field value.
61
-
- **copy**: When a user creates a task, the UI gives them an option to
62
-
"Create Another Similar Task". Some fields from the original task are copied
63
-
into the new task, while others are not; by default, fields are not copied.
64
-
If you want this field to be copied, specify `true` for the `copy` property.