Differential D25007 Diff 23 src/docs/user/configuration/custom_fields.diviner

Changeset View

Standalone View

src/docs/user/configuration/custom_fields.diviner

	@title Configuring Custom Fields			@title Configuring Custom Fields
	@group config			@group config

	How to add custom fields to applications which support them.			How to add custom fields to applications which support them.

	= Overview =			= Overview =

	Several Phabricator applications allow the configuration of custom fields. These			Several Phorge applications allow the configuration of custom fields. These
	fields allow you to add more information to objects, and in some cases reorder			fields allow you to add more information to objects, and in some cases reorder
	or remove builtin fields.			or remove builtin fields.

	For example, you could use custom fields to add an "Estimated Hours" field to			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.			tasks, a "Lead" field to projects, or a "T-Shirt Size" field to users.

	These applications currently support custom fields:			These applications currently support custom fields:

	▲ Show 20 Lines • Show All 112 Lines • ▼ Show 20 Lines
	The `strings` value supports different strings per control type. They are:			The `strings` value supports different strings per control type. They are:

	- bool			- bool
	- edit.checkbox Text for the edit interface, no default.			- edit.checkbox Text for the edit interface, no default.
	- view.yes Text for the view interface, defaults to "Yes".			- view.yes Text for the view interface, defaults to "Yes".
	- search.default Text for the search interface, defaults to "(Any)".			- search.default Text for the search interface, defaults to "(Any)".
	- search.require Text for the search interface, defaults to "Require".			- search.require Text for the search interface, defaults to "Require".

	Internally, Phabricator implements some additional custom field types and			Internally, Phorge implements some additional custom field types and
	options. These are not intended for general use and are subject to abrupt			options. These are not intended for general use and are subject to abrupt
	change, but are documented here for completeness:			change, but are documented here for completeness:

	- Credentials: Controls with type `credential` allow selection of a			- Credentials: Controls with type `credential` allow selection of a
	Passphrase credential which provides `credential.provides`, and creation			Passphrase credential which provides `credential.provides`, and creation
	of credentials of `credential.type`.			of credentials of `credential.type`.
	- Datasource: Controls with type `datasource` allow selection of tokens			- Datasource: Controls with type `datasource` allow selection of tokens
	from an arbitrary datasource, controlled with `datasource.class` and			from an arbitrary datasource, controlled with `datasource.class` and
	`datasource.parameters`.			`datasource.parameters`.

	= Advanced Custom Fields =			= Advanced Custom Fields =

	If you want custom fields to have advanced behaviors (sophisticated rendering,			If you want custom fields to have advanced behaviors (sophisticated rendering,
	advanced validation, complicated controls, interaction with other systems, etc),			advanced validation, complicated controls, interaction with other systems, etc),
	you can write a custom field as an extension and add it to Phabricator.			you can write a custom field as an extension and add it to Phorge.

	NOTE: This API is somewhat new and fairly large. You should expect that there			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.			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			To do this, extend the appropriate `CustomField` class for the application you
	want to add a field to:			want to add a field to:

	\| Application \| Extend \|			\| Application \| Extend \|
	\|-------------\|---------\|			\|-------------\|---------\|
	\| Differential \| @{class:DifferentialCustomField} \|			\| Differential \| @{class:DifferentialCustomField} \|
	\| Diffusion \| @{class:PhabricatorCommitCustomField} \|			\| Diffusion \| @{class:PhabricatorCommitCustomField} \|
	\| Maniphest \| @{class:ManiphestCustomField} \|			\| Maniphest \| @{class:ManiphestCustomField} \|
	\| Owners \| @{class:PhabricatorOwnersCustomField} \|			\| Owners \| @{class:PhabricatorOwnersCustomField} \|
	\| People \| @{class:PhabricatorUserCustomField} \|			\| People \| @{class:PhabricatorUserCustomField} \|
	\| Projects \| @{class:PhabricatorProjectCustomField} \|			\| Projects \| @{class:PhabricatorProjectCustomField} \|

	The easiest way to get started is to drop your subclass into			The easiest way to get started is to drop your subclass into
	`phabricator/src/extensions/`. If Phabricator is configured in development			`phorge/src/extensions/`. If Phorge is configured in development
	mode, the class should immediately be available in the UI. If not, you can			mode, the class should immediately be available in the UI. If not, you can
	restart Phabricator (for help, see @{article:Restarting Phabricator}).			restart Phorge (for help, see @{article:Restarting Phorge}).

	For example, this is a simple template which adds a custom field to Maniphest:			For example, this is a simple template which adds a custom field to Maniphest:

	name=ExampleManiphestCustomField.php			name=ExampleManiphestCustomField.php
	<?php			<?php

	final class ExampleCustomField extends ManiphestCustomField {			final class ExampleCustomField extends ManiphestCustomField {

	Show All 25 Lines
	architecture, and it may be useful to look at them. For details on available			architecture, and it may be useful to look at them. For details on available
	integrations, see the base class for your application and			integrations, see the base class for your application and
	@{class:PhabricatorCustomField}.			@{class:PhabricatorCustomField}.

	= Next Steps =			= Next Steps =

	Continue by:			Continue by:

	- learning more about extending Phabricator with custom code in			- learning more about extending Phorge with custom code in
	@{article@phabcontrib:Adding New Classes};			@{article@contrib:Adding New Classes};
	- or returning to the @{article: Configuration Guide}.			- or returning to the @{article: Configuration Guide}.