From 7be740cd306ea2d79e2e002e01a570d9f279583b Mon Sep 17 00:00:00 2001 From: epriestley Date: Fri, 14 Mar 2014 14:50:27 -0700 Subject: [PATCH] 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 --- .../user/configuration/custom_fields.diviner | 187 ++++++++++++++++++ .../user/userguide/maniphest_custom.diviner | 64 ------ 2 files changed, 187 insertions(+), 64 deletions(-) create mode 100644 src/docs/user/configuration/custom_fields.diviner delete mode 100644 src/docs/user/userguide/maniphest_custom.diviner diff --git a/src/docs/user/configuration/custom_fields.diviner b/src/docs/user/configuration/custom_fields.diviner new file mode 100644 index 0000000000..cc7d45dae3 --- /dev/null +++ b/src/docs/user/configuration/custom_fields.diviner @@ -0,0 +1,187 @@ +@title Configuring Custom Fields +@group config + +How to add custom fields to applications which support them. + += Overview = + +Several Phabricator applications allow the configuration of custom fields. These +fields allow you to add more information to objects, and in some cases reorder +or remove builtin fields. + +For example, you could use custom fields to add an "Estimated Hours" field to +tasks, a "Lead" field to projects, or a "T-Shirt Size" field to users. + +These applications currently support custom fields: + +| Application | Support | +|-------------|---------| +| Maniphest | Full Support | +| Projects | Full Support | +| People | Full Support | +| Differential | Partial Support | +| Diffusion | Limited Support | + +Custom fields can appear in many interfaces and support search, editing, and +other features. + += Basic Custom Fields = + +To get started with custom fields, you can use configuration to select and +reorder fields and to add new simple fields. + +If you don't need complicated display controls or sophisticated validation, +these simple fields should cover most use cases. They allow you to attach +things like strings, numbers, and dropdown menus to objects. + +The relevant configuration settings are: + +| Application | Add Fields | Select Fields | +|-------------|------------|---------------| +| Maniphest | `maniphest.custom-field-definitions` | `maniphest.fields` | +| Projects | `projects.custom-field-definitions` | `projects.fields` | +| People | `user.custom-field-definitions` | `user.fields` | +| Differential | Planned | `differential.fields` | +| Diffusion | Planned | Planned | + +When adding fields, you'll specify a JSON blob like this (for example, as the +value of `maniphest.custom-field-definitions`): + + { + "mycompany:estimated-hours": { + "name": "Estimated Hours", + "type": "int", + "caption": "Estimated number of hours this will take.", + "required": true + }, + "mycompany:actual-hours": { + "name": "Actual Hours", + "type": "int", + "caption": "Actual number of hours this took." + }, + "mycompany:favorite-dinosaur": { + "name": "Favorite Dinosaur", + "type": "text" + } + } + +The fields will then appear in the other config option for the application +(for example, in `maniphest.fields`) and you can enable, disable, or reorder +them. + +For details on how to define a field, see the next section. + += Custom Field Configuration = + +When defining custom fields using a configuration option like +`maniphest.custom-field-definitions`, these options are available: + + - **name**: Display label for the field on the edit and detail interfaces. + - **description**: Optional text shown when managing the field. + - **type**: Field type. The supported field types are: + - **int**: An integer, rendered as a text field. + - **text**: A string, rendered as a text field. + - **bool**: A boolean value, rendered as a checkbox. + - **select**: Allows the user to select from several options, rendered + as a dropdown. + - **remarkup**: A text area which allows the user to enter markup. + - **users**: A typeahead which allows multiple users to be input. + - **date**: A date/time picker. + - **header**: Renders a visual divider which you can use to group fields. + - **edit**: Show this field on the application's edit interface (this + defaults to `true`). + - **view**: Show this field on the application's view interface (this + defaults to `true`). + - **search**: Show this field on the application's search interface, allowing + users to filter objects by the field value. + - **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. + - **default**: Default field value. + - **strings**: Allows you to override specific strings based on the field + type. See below. + +The `strings` value supports different strings per control type. They are: + + - **bool** + - **edit.checkbox** Text for the edit interface, no default. + - **view.yes** Text for the view interface, defaults to "Yes". + - **search.default** Text for the search interface, defaults to "(Any)". + - **search.require** Text for the search interface, defaults to "Require". + +Some applications have specific options which only work in that application. + +In **Maniphest**: + + - **copy**: When a user creates a task, the UI gives them an option to + "Create Another Similar Task". Some fields from the original task are copied + into the new task, while others are not; by default, fields are not copied. + If you want this field to be copied, specify `true` for the `copy` property. + += Advanced Custom Fields = + +If you want custom fields to have advanced behaviors (sophisticated rendering, +advanced validation, complicated controls, interaction with other systems, etc), +you can write a custom field as an extension and add it to Phabricator. + +NOTE: This API is somewhat new and fairly large. You should expect that there +will be occasional changes to the API requiring minor updates in your code. + +To do this, extend the appropriate `CustomField` class for the application you +want to add a field to: + +| Application | Extend | +|-------------|---------| +| Maniphest | @{class:ManiphestCustomField} | +| Projects | @{class:PhabricatorProjectCustomField} | +| People | @{class:PhabricatorUserCustomField} | +| Differential | @{class:DifferentialCustomField} | +| Diffusion | @{class:PhabricatorCommitCustomField} | + +The easiest way to get started is to drop your subclass into +`phabricator/src/extensions/`, which should make it immediately available in the +UI (if you use APC, you may need to restart your webserver). For example, this +is a simple template which adds a custom field to Maniphest: + + name=ExampleManiphestCustomField.php + 'color: #ff00ff', + ), + pht('It worked!')); + } + + } + +Broadly, you can then add features by overriding more methods and implementing +them. Many of the native fields are implemented on the custom field +architecture, and it may be useful to look at them. For details on available +integrations, see the base class for your application and +@{class:PhabricatorCustomField}. + += Next Steps = + +Continue by: + + - learning more about extending Phabricator with custom code in + @{article:libphutil Libraries User Guide}; + - or returning to the @{article: Configuration Guide}. diff --git a/src/docs/user/userguide/maniphest_custom.diviner b/src/docs/user/userguide/maniphest_custom.diviner deleted file mode 100644 index f285fe69d4..0000000000 --- a/src/docs/user/userguide/maniphest_custom.diviner +++ /dev/null @@ -1,64 +0,0 @@ -@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-field-definitions` 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( - 'name' => 'Estimated Hours', - 'type' => 'int', - 'caption' => 'Estimated number of hours this will take.', - 'required' => true, - ), - 'mycompany:actual-hours' => array( - 'name' => 'Actual Hours', - 'type' => 'int', - ), - ) - -Each array key must be unique, and is used to organize the internal storage of -the field. These options are available: - - - **name**: Display label for the field on the edit and detail interfaces. - - **type**: Field type. The supported field types are: - - **int**: An integer, rendered as a text field. - - **text**: A string, rendered as a text field. - - **bool**: A boolean value, rendered as a checkbox. - - **select**: Allows the user to select from several options, rendered - as a dropdown. - - **remarkup**: A text area which allows the user to enter markup. - - **users**: A typeahead which allows multiple users to be input. - - **date**: A date/time picker. - - **header**: Renders a visual divider which you can use to group fields. - - **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. - - **default**: Default field value. - - **copy**: When a user creates a task, the UI gives them an option to - "Create Another Similar Task". Some fields from the original task are copied - into the new task, while others are not; by default, fields are not copied. - If you want this field to be copied, specify `true` for the `copy` property.