mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-15 11:22:40 +01:00
67 lines
2.6 KiB
Text
67 lines
2.6 KiB
Text
|
@title Maniphest User Guide: Adding Custom Fields
|
||
|
|
@group userguide
|
||
|
|
|
||
|
|
How to add custom fields to Maniphest.
|
||
|
|
|
||
|
|
= Overview =
|
||
|
|
|
||
|
|
Maniphest provides some support for adding new fields to tasks, like an
|
||
|
|
"cost" field, a "milestone" field, etc.
|
||
|
|
|
||
|
|
NOTE: Currently, these fields are somewhat limited. They primarily give you a
|
||
|
|
structured way to record data on tasks, but there isn't much support for
|
||
|
|
bringing them into other interfaces (e.g., querying by them, aggregating them,
|
||
|
|
drawing graphs, etc.). If you have a use case, let us know what you want to do
|
||
|
|
and maybe we can figure something out. This data is also exposed via the Conduit
|
||
|
|
API, so you might be able to write your own interface if you want to do
|
||
|
|
something very custom.
|
||
|
|
|
||
|
|
= Simple Field Customization =
|
||
|
|
|
||
|
|
If you don't need complicated display controls or sophisticated validation, you
|
||
|
|
can add simple fields. These allow you to attach things like strings, numbers,
|
||
|
|
and dropdown menus to the task template.
|
||
|
|
|
||
|
|
Customize Maniphest fields by setting ##maniphest.custom-fields## in your
|
||
|
|
configuration. For example, suppose you want to add "Estimated Hours" and
|
||
|
|
"Actual Hours" fields. To do this, set your configuration like this:
|
||
|
|
|
||
|
|
'maniphest.custom-fields' => array(
|
||
|
|
'mycompany:estimated-hours' => array(
|
||
|
|
'label' => 'Estimated Hours',
|
||
|
|
'type' => 'int',
|
||
|
|
'caption' => 'Estimated number of hours this will take.',
|
||
|
|
'required' => false,
|
||
|
|
),
|
||
|
|
'mycompany:actual-hours' => array(
|
||
|
|
'label' => 'Actual Hours',
|
||
|
|
'type' => 'int',
|
||
|
|
'required' => false,
|
||
|
|
),
|
||
|
|
)
|
||
|
|
|
||
|
|
Each array key must be unique, and is used to organize the internal storage of
|
||
|
|
the field. These options are available:
|
||
|
|
|
||
|
|
- **label**: Display label for the field on the edit and detail interfaces.
|
||
|
|
- **type**: Field type, one of **int**, **string** or **select**.
|
||
|
|
- **caption**: A caption to display underneath the field (optional).
|
||
|
|
- **required**: True if the user should be required to provide a value.
|
||
|
|
- **options**: If type is set to **select**, provide options for the dropdown
|
||
|
|
as a dictionary.
|
||
|
|
|
||
|
|
= Advanced Field Customization =
|
||
|
|
|
||
|
|
If you want to add fields with more specialized validation, storage, or
|
||
|
|
rendering logic, you can do so with a little work:
|
||
|
|
|
||
|
|
- Extend @{class:ManiphestAuxiliaryFieldSpecification} and implement
|
||
|
|
your specialized rendering, validation, storage, etc., logic.
|
||
|
|
- Extend @{class:ManiphestTaskExtensions} and return a list of fields which
|
||
|
|
includes your custom field objects.
|
||
|
|
- Set 'maniphest.custom-extensions' to the name of your new extensions
|
||
|
|
class.
|
||
|
|
|
||
|
|
This is relatively advanced but should give you significant flexibility in
|
||
|
|
defining custom fields.
|