Page MenuHomeClusterLabs Projects
Diviner Tech Docs PhabricatorCustomField

abstract class PhabricatorCustomField
Phorge Technical Documentation (Custom Fields)

This class is not documented.

Tasks

Building Applications with Custom Fields

Core Properties and Field Identity

  • public function getFieldKey() — Return a key which uniquely identifies this field, like "mycompany:dinosaur:count". Normally you should provide some level of namespacing to prevent collisions.
  • public function getFieldName() — Return a human-readable field name.
  • public function getFieldDescription() — Return a short, human-readable description of the field's behavior. This provides more context to administrators when they are customizing fields.
  • public function createFields($object) — Most field implementations are unique, in that one class corresponds to one field. However, some field implementations are general and a single implementation may drive several fields.
  • public function isFieldEnabled() — You can return `false` here if the field should not be enabled for any role. For example, it might depend on something (like an application or library) which isn't installed, or might have some global configuration which allows it to be disabled.
  • public function shouldEnableForRole($role) — Low level selector for field availability. Fields can appear in different roles (like an edit view, a list view, etc.), but not every field needs to appear everywhere. Fields that are disabled in a role won't appear in that context within applications.
  • public function canDisableField() — Allow administrators to disable this field. Most fields should allow this, but some are fundamental to the behavior of the application and can be locked down to avoid chaos, disorder, and the decline of civilization.
  • final public function getFieldIndex() — Return an index string which uniquely identifies this field.

Field Proxies

  • public function canSetProxy() — Proxies allow a field to use some other field's implementation for most of their behavior while still subclassing an application field. When a proxy is set for a field with @{method:setProxy}, all of its methods will call through to the proxy by default.

Contextual Data

  • final public function setObject($object) — Sets the object this field belongs to.
  • public function readValueFromObject($object) — Read object data into local field storage, if applicable.
  • final public function getObject() — Get the object this field belongs to.
  • final public function setViewer($viewer)
  • final public function getViewer()
  • final protected function requireViewer()

Rendering Utilities

Field Storage

  • public function shouldUseStorage() — Return true to use field storage.
  • public function newStorageObject() — Return a new, empty storage object. This should be a subclass of @{class:PhabricatorCustomFieldStorage} which is bound to the application's database.
  • public function getValueForStorage() — Return a serialized representation of the field value, appropriate for storing in auxiliary field storage. You must implement this method if you implement @{method:shouldUseStorage}.
  • public function setValueFromStorage($value) — Set the field's value given a serialized storage value. This is called when the field is loaded; if no data is available, the value will be null. You must implement this method if you implement @{method:shouldUseStorage}.

Integration with Edit Views

Integration with Property Views

Integration with List views

Integration with ApplicationSearch

  • public function shouldAppearInApplicationSearch() — Appearing in ApplicationSearch allows a field to be indexed and searched for.
  • public function buildFieldIndexes() — Return one or more indexes which this field can meaningfully query against to implement ApplicationSearch.
  • public function buildOrderIndex() — Return an index against which this field can be meaningfully ordered against to implement ApplicationSearch.
  • protected function newStringIndexStorage() — Build a new empty storage object for storing string indexes. Normally, this should be a concrete subclass of @{class:PhabricatorCustomFieldStringIndexStorage}.
  • protected function newNumericIndexStorage() — Build a new empty storage object for storing string indexes. Normally, this should be a concrete subclass of @{class:PhabricatorCustomFieldStringIndexStorage}.
  • protected function newStringIndex($value) — Build and populate storage for a string index.
  • protected function newNumericIndex($value) — Build and populate storage for a numeric index.
  • public function readApplicationSearchValueFromRequest($engine, $request) — Read a query value from a request, for storage in a saved query. Normally, this method should, e.g., read a string out of the request.
  • public function applyApplicationSearchConstraintToQuery($engine, $query, $value) — Constrain a query, given a field value. Generally, this method should use `with...()` methods to apply filters or other constraints to the query.
  • public function appendToApplicationSearchForm($engine, $form, $value) — Append search controls to the interface.

Integration with ApplicationTransactions

Integration with Transaction Mail

Integration with Global Search

Integration with Herald

Other Methods

conduit

Methods

public static function getObjectFields($object, $role)

This method is not documented.
Parameters
PhabricatorCustomFieldInterface$object
$role
Return
wild

public static function getObjectField($object, $role, $field_key)

This method is not documented.
Parameters
PhabricatorCustomFieldInterface$object
$role
$field_key
Return
wild

public static function buildFieldList($base_class, $spec, $object, $options)

This method is not documented.
Parameters
$base_class
array$spec
$object
array$options
Return
wild

public function getFieldKey()

Return a key which uniquely identifies this field, like "mycompany:dinosaur:count". Normally you should provide some level of namespacing to prevent collisions.

Return
stringString which uniquely identifies this field.

public function getModernFieldKey()

This method is not documented.
Return
wild

public function getFieldName()

Return a human-readable field name.

Return
stringHuman readable field name.

public function getFieldDescription()

Return a short, human-readable description of the field's behavior. This provides more context to administrators when they are customizing fields.

Return
string|nullOptional human-readable description.

public function createFields($object)

Most field implementations are unique, in that one class corresponds to one field. However, some field implementations are general and a single implementation may drive several fields.

For general implementations, the general field implementation can return multiple field instances here.

Parameters
object$objectThe object to create fields for.
Return
list<PhabricatorCustomField>List of fields.

public function isFieldEnabled()

You can return false here if the field should not be enabled for any role. For example, it might depend on something (like an application or library) which isn't installed, or might have some global configuration which allows it to be disabled.

Return
boolFalse to completely disable this field for all roles.

public function shouldEnableForRole($role)

Low level selector for field availability. Fields can appear in different roles (like an edit view, a list view, etc.), but not every field needs to appear everywhere. Fields that are disabled in a role won't appear in that context within applications.

Normally, you do not need to override this method. Instead, override the methods specific to roles you want to enable. For example, implement shouldUseStorage()() to activate the 'storage' role.

Parameters
$role
Return
boolTrue to enable the field for the given role.

public function canDisableField()

Allow administrators to disable this field. Most fields should allow this, but some are fundamental to the behavior of the application and can be locked down to avoid chaos, disorder, and the decline of civilization.

Return
boolFalse to prevent this field from being disabled through configuration.

public function shouldDisableByDefault()

This method is not documented.
Return
wild

final public function getFieldIndex()

Return an index string which uniquely identifies this field.

Return
stringIndex string which uniquely identifies this field.

public function canSetProxy()

Proxies allow a field to use some other field's implementation for most of their behavior while still subclassing an application field. When a proxy is set for a field with setProxy(), all of its methods will call through to the proxy by default.

This is most commonly used to implement configuration-driven custom fields using PhabricatorStandardCustomField.

This method must be overridden to return true before a field can accept proxies.

Return
boolTrue if you can @{method:setProxy} this field.

final public function setProxy($proxy)

Set the proxy implementation for this field. See canSetProxy() for discussion of field proxies.

Parameters
PhabricatorCustomField$proxyField implementation.
Return
this

final public function getProxy()

Get the field's proxy implementation, if any. For discussion, see canSetProxy().

Return
PhabricatorCustomField|nullProxy field, if one is set.

final public function setObject($object)

Sets the object this field belongs to.

Parameters
PhabricatorCustomFieldInterface$objectThe object this field belongs to.
Return
this

public function readValueFromObject($object)

Read object data into local field storage, if applicable.

Parameters
PhabricatorCustomFieldInterface$objectThe object this field belongs to.
Return
this

final public function getObject()

Get the object this field belongs to.

Return
PhabricatorCustomFieldInterfaceThe object this field belongs to.

protected function didSetObject($object)

This is a hook, primarily for subclasses to load object data.

Parameters
PhabricatorCustomFieldInterface$object
Return
PhabricatorCustomFieldInterfaceThe object this field belongs to.

final public function setViewer($viewer)

This method is not documented.
Parameters
PhabricatorUser$viewer
Return
wild

final public function getViewer()

This method is not documented.
Return
wild

final protected function requireViewer()

This method is not documented.
Return
wild

protected function renderHandleList($handles)

This method is not documented.
Parameters
array$handles
Return
wild

public function shouldUseStorage()

Return true to use field storage.

Fields which can be edited by the user will most commonly use storage, while some other types of fields (for instance, those which just display information in some stylized way) may not. Many builtin fields do not use storage because their data is available on the object itself.

If you implement this, you must also implement getValueForStorage() and setValueFromStorage().

Return
boolTrue to use storage.

public function newStorageObject()

Return a new, empty storage object. This should be a subclass of PhabricatorCustomFieldStorage which is bound to the application's database.

Return
PhabricatorCustomFieldStorageNew empty storage object.

public function getValueForStorage()

Return a serialized representation of the field value, appropriate for storing in auxiliary field storage. You must implement this method if you implement shouldUseStorage().

If the field value is a scalar, it can be returned unmodiifed. If not, it should be serialized (for example, using JSON).

Return
stringSerialized field value.

public function setValueFromStorage($value)

Set the field's value given a serialized storage value. This is called when the field is loaded; if no data is available, the value will be null. You must implement this method if you implement shouldUseStorage().

Usually, the value can be loaded directly. If it isn't a scalar, you'll need to undo whatever serialization you applied in getValueForStorage().

Parameters
string|null$valueSerialized field representation (from @{method:getValueForStorage}) or null if no value has ever been stored.
Return
this

public function didSetValueFromStorage()

This method is not documented.
Return
wild

Appearing in ApplicationSearch allows a field to be indexed and searched for.

Return
boolTrue to appear in ApplicationSearch.

public function buildFieldIndexes()

Return one or more indexes which this field can meaningfully query against to implement ApplicationSearch.

Normally, you should build these using newStringIndex() and newNumericIndex(). For example, if a field holds a numeric value it might return a single numeric index:

return array($this->newNumericIndex($this->getValue()));

If a field holds a more complex value (like a list of users), it might return several string indexes:

$indexes = array();
foreach ($this->getValue() as $phid) {
  $indexes[] = $this->newStringIndex($phid);
}
return $indexes;
Return
list<PhabricatorCustomFieldIndexStorage>List of indexes.

public function buildOrderIndex()

Return an index against which this field can be meaningfully ordered against to implement ApplicationSearch.

This should be a single index, normally built using newStringIndex() and newNumericIndex().

The value of the index is not used.

Return null from this method if the field can not be ordered.

Return
PhabricatorCustomFieldIndexStorageA single index to order by.

protected function newStringIndexStorage()

Build a new empty storage object for storing string indexes. Normally, this should be a concrete subclass of PhabricatorCustomFieldStringIndexStorage.

Return
PhabricatorCustomFieldStringIndexStorageStorage object.

protected function newNumericIndexStorage()

Build a new empty storage object for storing string indexes. Normally, this should be a concrete subclass of PhabricatorCustomFieldStringIndexStorage.

Return
PhabricatorCustomFieldStringIndexStorageStorage object.

protected function newStringIndex($value)

Build and populate storage for a string index.

Parameters
string$valueString to index.
Return
PhabricatorCustomFieldStringIndexStoragePopulated storage.

protected function newNumericIndex($value)

Build and populate storage for a numeric index.

Parameters
string$valueNumeric value to index.
Return
PhabricatorCustomFieldNumericIndexStoragePopulated storage.

public function readApplicationSearchValueFromRequest($engine, $request)

Read a query value from a request, for storage in a saved query. Normally, this method should, e.g., read a string out of the request.

Parameters
PhabricatorApplicationSearchEngine$engineEngine building the query.
AphrontRequest$requestRequest to read from.
Return
wild

public function applyApplicationSearchConstraintToQuery($engine, $query, $value)

Constrain a query, given a field value. Generally, this method should use with...() methods to apply filters or other constraints to the query.

Parameters
PhabricatorApplicationSearchEngine$engineEngine executing the query.
PhabricatorCursorPagedPolicyAwareQuery$queryQuery to constrain.
wild$valueConstraint provided by the user.
Return
void

public function appendToApplicationSearchForm($engine, $form, $value)

Append search controls to the interface.

Parameters
PhabricatorApplicationSearchEngine$engineEngine constructing the form.
AphrontFormView$formThe form to update.
wild$valueValue from the saved query.
Return
void

Appearing in ApplicationTrasactions allows a field to be edited using standard workflows.

Return
boolTrue to appear in ApplicationTransactions.
This method is not documented.
Return
wild
This method is not documented.
Return
wild
This method is not documented.
Return
wild
This method is not documented.
Return
wild

public function setValueFromApplicationTransactions($value)

This method is not documented.
Parameters
$value
Return
wild

public function getNewValueFromApplicationTransactions($xaction)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionHasEffect($xaction)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild
This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionRemarkupBlocks($xaction)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild
This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function validateApplicationTransactions($editor, $type, $xactions)

Validate transactions for an object. This allows you to raise an error when a transaction would set a field to an invalid value, or when a field is required but no transactions provide value.

Parameters
PhabricatorLiskDAO$editorEditor applying the transactions.
string$typeTransaction type. This type is always `PhabricatorTransactions::TYPE_CUSTOMFIELD`, it is provided for convenience when constructing exceptions.
list<PhabricatorApplicationTransaction>$xactionsTransactions being applied, which may be empty if this field is not being edited.
Return
list<PhabricatorApplicationTransactionValidationError>Validation errors.

public function getApplicationTransactionTitle($xaction)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionTitleForFeed($xaction)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild
This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionChangeDetails($xaction, $viewer)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
PhabricatorUser$viewer
Return
wild
This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function shouldHideInApplicationTransactions($xaction)

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild
This method is not documented.
Return
wild

public function updateTransactionMailBody($body, $editor, $xactions)

This method is not documented.
Parameters
PhabricatorMetaMTAMailBody$body
PhabricatorApplicationTransactionEditor$editor
array$xactions
Return
wild

public function getEditEngineFields($engine)

This method is not documented.
Parameters
PhabricatorEditEngine$engine
Return
wild

protected function newEditField()

This method is not documented.
Return
wild

protected function newStandardEditField()

This method is not documented.
Return
wild

protected function getBulkEditLabel()

This method is not documented.
Return
wild

public function getBulkParameterType()

This method is not documented.
Return
wild

protected function newBulkParameterType()

This method is not documented.
Return
wild

protected function getHTTPParameterType()

This method is not documented.
Return
wild

public function shouldAppearInEditView()

This method is not documented.
Return
wild

public function shouldAppearInEditEngine()

This method is not documented.
Return
wild

public function readValueFromRequest($request)

This method is not documented.
Parameters
AphrontRequest$request
Return
wild
This method is not documented.
Return
wild

public function getInstructionsForEdit()

This method is not documented.
Return
wild

public function renderEditControl($handles)

This method is not documented.
Parameters
array$handles
Return
wild

public function shouldAppearInPropertyView()

This method is not documented.
Return
wild

public function renderPropertyViewLabel()

This method is not documented.
Return
wild

public function renderPropertyViewValue($handles)

This method is not documented.
Parameters
array$handles
Return
wild

public function getStyleForPropertyView()

This method is not documented.
Return
wild

public function getIconForPropertyView()

This method is not documented.
Return
wild
This method is not documented.
Return
wild

public function shouldAppearInListView()

This method is not documented.
Return
wild

public function renderOnListItem($view)

This method is not documented.
Parameters
PHUIObjectItemView$view
Return
wild

public function shouldAppearInGlobalSearch()

This method is not documented.
Return
wild

public function updateAbstractDocument($document)

This method is not documented.
Parameters
PhabricatorSearchAbstractDocument$document
Return
wild

public function shouldAppearInDataExport()

This method is not documented.
Return
wild

public function newExportField()

This method is not documented.
Return
wild

public function newExportData()

This method is not documented.
Return
wild

protected function newExportFieldType()

This method is not documented.
Return
wild
This method is not documented.
Return
wild

public function getConduitDictionaryValue()

This method is not documented.
Return
wild
This method is not documented.
Return
wild
This method is not documented.
Return
wild

protected function newConduitSearchParameterType()

This method is not documented.
Return
wild

public function getConduitEditParameterType()

This method is not documented.
Return
wild

protected function newConduitEditParameterType()

This method is not documented.
Return
wild

public function getCommentAction()

This method is not documented.
Return
wild

protected function newCommentAction()

This method is not documented.
Return
wild

public function shouldAppearInHerald()

Return true to make this field available in Herald.

Return
boolTrue to expose the field in Herald.

public function getHeraldFieldName()

Get the name of the field in Herald. By default, this uses the normal field name.

Return
stringHerald field name.

public function getHeraldFieldValue()

Get the field value for evaluation by Herald.

Return
wildField value.

public function getHeraldFieldConditions()

Get the available conditions for this field in Herald.

Return
list<const>List of Herald condition constants.

public function getHeraldFieldValueType($condition)

Get the Herald value type for the given condition.

Parameters
const$conditionHerald condition constant.
Return
const|nullHerald value type, or null to use the default.

public function getHeraldFieldStandardType()

This method is not documented.
Return
wild

public function getHeraldDatasource()

This method is not documented.
Return
wild

public function shouldAppearInHeraldActions()

This method is not documented.
Return
wild

public function getHeraldActionName()

This method is not documented.
Return
wild

public function getHeraldActionStandardType()

This method is not documented.
Return
wild

public function getHeraldActionDescription($value)

This method is not documented.
Parameters
$value
Return
wild

public function getHeraldActionEffectDescription($value)

This method is not documented.
Parameters
$value
Return
wild

public function getHeraldActionDatasource()

This method is not documented.
Return
wild

private static function adjustCustomFieldsForObjectSubtype($object, $role, $fields)

This method is not documented.
Parameters
PhabricatorCustomFieldInterface$object
$role
array$fields
Return
wild