Page MenuHomePhabricator
Diviner Phabricator Tech Docs PhabricatorStandardCustomField

abstract class PhabricatorStandardCustomField
Phabricator Technical Documentation (Custom Fields)

This class is not documented.

Tasks

Building Applications with Custom Fields

Core Properties and Field Identity

  • public function getFieldKey()
  • public function getFieldName()
  • public function getFieldDescription()
  • 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()
  • 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

Integration with Edit Views

Integration with Property Views

Integration with List views

Integration with ApplicationSearch

Integration with ApplicationTransactions

Integration with Transaction Mail

Integration with Global Search

Integration with Herald

Other Methods

conduit

Methods

public static function getObjectFields($object, $role)
Inherited

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

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

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

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

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

public function getFieldKey()

PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Return
stringString which uniquely identifies this field.

public function getModernFieldKey()

This method is not documented.
Return
wild

public function getFieldName()

PhabricatorCustomField

Return a human-readable field name.

PhabricatorStandardCustomField
This method is not documented.
Return
stringHuman readable field name.

public function getFieldDescription()

PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Return
string|nullOptional human-readable description.

public function createFields($object)
Inherited

PhabricatorCustomField

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()

PhabricatorCustomField

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.

PhabricatorStandardCustomField
This method is not documented.
Return
boolFalse to completely disable this field for all roles.

public function shouldEnableForRole($role)
Inherited

PhabricatorCustomField

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()
Inherited

PhabricatorCustomField

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()
Inherited

This method is not documented.
Return
wild

final public function getFieldIndex()
Inherited

PhabricatorCustomField

Return an index string which uniquely identifies this field.

Return
stringIndex string which uniquely identifies this field.

public function canSetProxy()
Inherited

PhabricatorCustomField

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)
Inherited

PhabricatorCustomField

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

Parameters
PhabricatorCustomField$proxyField implementation.
Return
this

final public function getProxy()
Inherited

PhabricatorCustomField

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)
Inherited

PhabricatorCustomField

Sets the object this field belongs to.

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

public function readValueFromObject($object)
Inherited

PhabricatorCustomField

Read object data into local field storage, if applicable.

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

final public function getObject()
Inherited

PhabricatorCustomField

Get the object this field belongs to.

Return
PhabricatorCustomFieldInterfaceThe object this field belongs to.

protected function didSetObject($object)
Inherited

PhabricatorCustomField

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)
Inherited

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

final public function getViewer()
Inherited

This method is not documented.
Return
wild

final protected function requireViewer()
Inherited

This method is not documented.
Return
wild

protected function renderHandleList($handles)
Inherited

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

public function shouldUseStorage()

PhabricatorCustomField

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().

PhabricatorStandardCustomField
This method is not documented.
Return
boolTrue to use storage.

public function newStorageObject()

PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldStorageNew empty storage object.

public function getValueForStorage()

PhabricatorCustomField

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).

PhabricatorStandardCustomField
This method is not documented.
Return
stringSerialized field value.

public function setValueFromStorage($value)

PhabricatorCustomField

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().

PhabricatorStandardCustomField
This method is not documented.
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
PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Return
boolTrue to appear in ApplicationSearch.

public function buildFieldIndexes()

PhabricatorCustomField

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;
PhabricatorStandardCustomField
This method is not documented.
Return
list<PhabricatorCustomFieldIndexStorage>List of indexes.

public function buildOrderIndex()

PhabricatorCustomField

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.

PhabricatorStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldIndexStorageA single index to order by.

protected function newStringIndexStorage()

PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldStringIndexStorageStorage object.

protected function newNumericIndexStorage()

PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldStringIndexStorageStorage object.

protected function newStringIndex($value)
Inherited

PhabricatorCustomField

Build and populate storage for a string index.

Parameters
string$valueString to index.
Return
PhabricatorCustomFieldStringIndexStoragePopulated storage.

protected function newNumericIndex($value)
Inherited

PhabricatorCustomField

Build and populate storage for a numeric index.

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

public function readApplicationSearchValueFromRequest($engine, $request)

PhabricatorCustomField

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.

PhabricatorStandardCustomField
This method is not documented.
Parameters
PhabricatorApplicationSearchEngine$engineEngine building the query.
AphrontRequest$requestRequest to read from.
Return
wild

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

PhabricatorCustomField

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

PhabricatorStandardCustomField
This method is not documented.
Parameters
PhabricatorApplicationSearchEngine$engineEngine executing the query.
PhabricatorCursorPagedPolicyAwareQuery$queryQuery to constrain.
wild$valueConstraint provided by the user.
Return
void

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

PhabricatorCustomField

Append search controls to the interface.

PhabricatorStandardCustomField
This method is not documented.
Parameters
PhabricatorApplicationSearchEngine$engineEngine constructing the form.
AphrontFormView$formThe form to update.
wild$valueValue from the saved query.
Return
void
PhabricatorCustomField

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

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

public function getApplicationTransactionType()
Inherited

This method is not documented.
Return
wild

public function getApplicationTransactionMetadata()
Inherited

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

public function getNewValueForApplicationTransactions()
Inherited

This method is not documented.
Return
wild

public function setValueFromApplicationTransactions($value)
Inherited

This method is not documented.
Parameters
$value
Return
wild

public function getNewValueFromApplicationTransactions($xaction)
Inherited

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

public function getApplicationTransactionHasEffect($xaction)
Inherited

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

public function applyApplicationTransactionInternalEffects($xaction)
Inherited

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

public function getApplicationTransactionRemarkupBlocks($xaction)
Inherited

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

public function applyApplicationTransactionExternalEffects($xaction)
Inherited

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

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

PhabricatorCustomField

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.

PhabricatorStandardCustomField
This method is not documented.
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

public function getApplicationTransactionHasChangeDetails($xaction)
Inherited

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

public function getApplicationTransactionChangeDetails($xaction, $viewer)
Inherited

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

public function getApplicationTransactionRequiredHandlePHIDs($xaction)
Inherited

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

public function shouldHideInApplicationTransactions($xaction)
Inherited

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

public function shouldAppearInTransactionMail()
Inherited

This method is not documented.
Return
wild

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

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

public function getEditEngineFields($engine)
Inherited

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

protected function newEditField()
Inherited

This method is not documented.
Return
wild

protected function newStandardEditField()

This method is not documented.
Return
wild

protected function getBulkEditLabel()
Inherited

This method is not documented.
Return
wild

public function getBulkParameterType()
Inherited

This method is not documented.
Return
wild

protected function newBulkParameterType()
Inherited

This method is not documented.
Return
wild

protected function getHTTPParameterType()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInEditView()

This method is not documented.
Return
wild

public function shouldAppearInEditEngine()
Inherited

This method is not documented.
Return
wild

public function readValueFromRequest($request)

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

public function getRequiredHandlePHIDsForEdit()
Inherited

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()
Inherited

This method is not documented.
Return
wild

public function renderPropertyViewValue($handles)

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

public function getStyleForPropertyView()
Inherited

This method is not documented.
Return
wild

public function getIconForPropertyView()
Inherited

This method is not documented.
Return
wild

public function getRequiredHandlePHIDsForPropertyView()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInListView()
Inherited

This method is not documented.
Return
wild

public function renderOnListItem($view)
Inherited

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()
Inherited

This method is not documented.
Return
wild

public function newExportField()
Inherited

This method is not documented.
Return
wild

public function newExportData()

This method is not documented.
Return
wild

protected function newExportFieldType()
Inherited

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

public function getConduitSearchParameterType()
Inherited

This method is not documented.
Return
wild

protected function newConduitSearchParameterType()
Inherited

This method is not documented.
Return
wild

public function getConduitEditParameterType()
Inherited

This method is not documented.
Return
wild

protected function newConduitEditParameterType()
Inherited

This method is not documented.
Return
wild

public function getCommentAction()
Inherited

This method is not documented.
Return
wild

protected function newCommentAction()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInHerald()
Inherited

PhabricatorCustomField

Return true to make this field available in Herald.

Return
boolTrue to expose the field in Herald.

public function getHeraldFieldName()
Inherited

PhabricatorCustomField

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

Return
stringHerald field name.

public function getHeraldFieldValue()

PhabricatorCustomField

Get the field value for evaluation by Herald.

PhabricatorStandardCustomField
This method is not documented.
Return
wildField value.

public function getHeraldFieldConditions()
Inherited

PhabricatorCustomField

Get the available conditions for this field in Herald.

Return
list<const>List of Herald condition constants.

public function getHeraldFieldValueType($condition)
Inherited

PhabricatorCustomField

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()
Inherited

This method is not documented.
Return
wild

public function getHeraldDatasource()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInHeraldActions()
Inherited

This method is not documented.
Return
wild

public function getHeraldActionName()
Inherited

This method is not documented.
Return
wild

public function getHeraldActionStandardType()
Inherited

This method is not documented.
Return
wild

public function getHeraldActionDescription($value)
Inherited

This method is not documented.
Parameters
$value
Return
wild

public function getHeraldActionEffectDescription($value)
Inherited

This method is not documented.
Parameters
$value
Return
wild

public function getHeraldActionDatasource()
Inherited

This method is not documented.
Return
wild

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

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

abstract public function getFieldType()

This method is not documented.
Return
wild

public static function buildStandardFields($template, $config, $builtin)

This method is not documented.
Parameters
PhabricatorCustomField$template
array$config
$builtin
Return
wild

public function setApplicationField($application_field)

This method is not documented.
Parameters
PhabricatorStandardCustomFieldInterface$application_field
Return
wild

public function getApplicationField()

This method is not documented.
Return
wild

public function setFieldName($name)

This method is not documented.
Parameters
$name
Return
wild

public function getFieldValue()

This method is not documented.
Return
wild

public function setFieldValue($value)

This method is not documented.
Parameters
$value
Return
wild

public function setCaption($caption)

This method is not documented.
Parameters
$caption
Return
wild

public function getCaption()

This method is not documented.
Return
wild

public function setFieldDescription($description)

This method is not documented.
Parameters
$description
Return
wild

public function setIsBuiltin($is_builtin)

This method is not documented.
Parameters
$is_builtin
Return
wild

public function getIsBuiltin()

This method is not documented.
Return
wild

public function setFieldConfig($config)

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

public function getFieldConfigValue($key, $default)

This method is not documented.
Parameters
$key
$default
Return
wild

public function setFieldError($field_error)

This method is not documented.
Parameters
$field_error
Return
wild

public function getFieldError()

This method is not documented.
Return
wild

public function setRequired($required)

This method is not documented.
Parameters
$required
Return
wild

public function getRequired()

This method is not documented.
Return
wild

public function setRawStandardFieldKey($raw_key)

This method is not documented.
Parameters
$raw_key
Return
wild

public function getRawStandardFieldKey()

This method is not documented.
Return
wild

public function setIsEnabled($is_enabled)

This method is not documented.
Parameters
$is_enabled
Return
wild

public function getIsEnabled()

This method is not documented.
Return
wild

public function setFieldKey($field_key)

This method is not documented.
Parameters
$field_key
Return
wild

public function setStrings($strings)

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

public function getString($key, $default)

This method is not documented.
Parameters
$key
$default
Return
wild

public function setIsCopyable($is_copyable)

This method is not documented.
Parameters
$is_copyable
Return
wild

public function getIsCopyable()

This method is not documented.
Return
wild

public function getPlaceholder()

This method is not documented.
Return
wild

protected function isValueEmpty($value)

This method is not documented.
Parameters
$value
Return
wild

public function getFieldControlID($key)

This method is not documented.
Parameters
$key
Return
wild