Class DifferentialFieldSpecification

Describes and implements the behavior for a custom field on Differential revisions. Along with other configuration, you can extend this class to add custom fields to Differential revisions and commit messages.

Generally, you should implement all methods from the storage task and then the methods from one or more interface tasks.

This method allows you to take action when a commit appears in a tracked branch (for example, by closing tasks associated with the commit).

Hook after an edit operation has completed. This allows you to update link tables or do other write operations which should happen after the revision is saved. Normally you don't need to implement this.

Optionally, return a column class for revision list tables.

Key which identifies this field in parsed commit messages. Commit messages exist in two forms: raw textual commit messages and parsed dictionaries of fields. This method must return a unique string which identifies this field in dictionaries. Principally, this dictionary is shipped to and from arc over Conduit. Keys should be appropriate property names, like "testPlan" (not "Test Plan") and must be globally unique.

You must implement this method if you return true from shouldAppearOnCommitMessage().

Get the list of properties for a diff set by setManualDiff().

Get a property of a diff set by setManualDiff().

Get the handle for an object PHID. You must overload getRequiredHandlePHIDs() (or a more specific version thereof) and include the PHID you want in the list for it to be available here.

Specify which PhabricatorObjectHandles need to be loaded for your field to render correctly.

This is a convenience method which makes the handles available on all interfaces where the field appears. If your field needs handles on only some interfaces (or needs different handles on different interfaces) you can overload the more specific methods to customize which interfaces you retrieve handles for. Requesting only the handles you need will improve the performance of your field.

You can later retrieve these handles by calling getHandle().

Specify which PhabricatorObjectHandles need to be loaded for your field to render correctly on the commit message interface.

This is a more specific version of getRequiredHandlePHIDs() which can be overridden to improve field performance by loading only data you need.

Specify which PhabricatorObjectHandles need to be loaded for your field to render correctly on the edit interface.

This is a more specific version of getRequiredHandlePHIDs() which can be overridden to improve field performance by loading only data you need.

Specify which PhabricatorObjectHandles need to be loaded for your field to render correctly on the list interface.

This is a more specific version of getRequiredHandlePHIDs() which can be overridden to improve field performance by loading only data you need.

Specify which PhabricatorObjectHandles need to be loaded for your field to render correctly on the view interface.

This is a more specific version of getRequiredHandlePHIDs() which can be overridden to improve field performance by loading only data you need.

Return a unique string used to key storage of this field's value, like "mycompany.fieldname" or similar. You can return null (the default) to indicate that this field does not use any storage. This is appropriate for display fields, like DifferentialLinesFieldSpecification. If you implement this, you must also implement getValueForStorage() and setValueFromStorage().

Return one or more labels which this field parses in commit messages. For example, you might parse all of "Task", "Tasks" and "Task Numbers" or similar. This is just to make it easier to get commit messages to parse when users are typing in the fields manually as opposed to using a template, by accepting alternate spellings / pluralizations / etc. By default, only the label returned from renderLabelForCommitMessage() is parsed.

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

Determine if revision context is currently available.

Parse a list of mailable objects into a canonical PHID list.

Parse and lookup a list of object names, converting them to PHIDs.

Parse a list of users into a canonical PHID list.

Parse a raw text block from a commit message into a canonical representation of the field value. For example, the "CC" field accepts a comma-delimited list of usernames and emails and parses them into valid PHIDs, emitting a PHID list.

If you encounter errors (like a nonexistent username) while parsing, you should throw a DifferentialFieldParseException.

Generally, this method should accept whatever you return from renderValueForCommitMessage() and parse it back into a sensible representation.

You must implement this method if you return true from shouldAppearOnCommitMessage().

Build a renderable object (generally, some AphrontFormControl) which can be appended to a AphrontFormView and represents the interface the user sees on the "Edit Revision" screen when interacting with this field.

For example:

return id(new AphrontFormTextControl())
  ->setLabel('Custom Field')
  ->setName('my-custom-key')
  ->setValue($this->value);

You must implement this if you implement shouldAppearOnEdit().

Return a column header for revision list tables.

Render a human-readable label for this field, like "Summary" or "Test Plan". This is distinct from the commit message key, but generally they should be similar.

Return a string field label which will appear in the diff detail table.

You must implement this method if you return true from shouldAppearOnDiffView().

Return a string field label which will appear in the revision detail table.

You must implement this method if you return true from shouldAppearOnRevisionView().

Load users, their current statuses and return a markup with links to the user profiles and information about their current status.

Render a human-readable value for this field when it appears in commit messages (for instance, lists of users should be rendered as user names).

The $is_edit parameter allows you to distinguish between commit messages being rendered for editing and those being rendered for amending or commit. Some fields may decline to render a value in one mode (for example, "Reviewed By" appears only when doing commit/amend, not while editing).

Return a markup block representing the field for the diff detail view. Note that you can return null to suppress display (for instance, if the field shows related objects of some type and the revision doesn't have any related objects).

You must implement this method if you return true from shouldAppearOnDiffView().

Return plain text to render in e-mail messages. The text may span multiple lines.

Return a table cell value for revision list tables.

Return a markup block representing the field for the revision detail view. Note that you can return null to suppress display (for instance, if the field shows related objects of some type and the revision doesn't have any related objects).

You must implement this method if you return true from shouldAppearOnRevisionView().

Return a markup block representing a warning to display with the comment box when preparing to accept a diff. A return value of null indicates no warning box should be displayed for this field.

Set this field's value from a value in a parsed commit message dictionary. Afterward, this field will go through the normal write workflows and the change will be permanently stored via either the storage mechanisms (if your field implements them), revision write hooks (if your field implements them) or discarded (if your field implements neither, e.g. is just a display field).

The value you receive will either be null or something you originally returned from parseValueFromCommitMessage().

You must implement this method if you return true from shouldAppearOnCommitMessage().

Set the field's value from an HTTP request. Generally, you should read the value of some field name you emitted in renderEditControl() and save it into the object, e.g.:

$this->value = $request->getStr('my-custom-field');

If you have some particularly complicated field, you may need to read more data; this is why you have access to the entire request.

You must implement this if you implement shouldAppearOnEdit().

You should not perform field validation here; instead, you should implement validateField().

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

Determine if this field should appear in commit messages. You should return true if this field participates in any part of the commit message workflow, even if it is not rendered by default.

If you implement this method, you must implement getCommitMessageKey() and setValueFromParsedCommitMessage().

Return true if this field should be suggested to the user during "arc diff --edit". Basicially, return true if the field is something the user might want to fill out (like "Summary"), and false if it's a system/display/readonly field (like "Differential Revision"). If this method returns true, the field will be rendered even if it has no value during edit and update operations.

Determine if this field should appear on the diff detail view interface. One use of this interface is to add purely informational fields to the diff view, without any sort of backing storage.

If you return true from this method, you must implement the methods renderLabelForDiffView() and renderValueForDiffView().

Determine if this field should appear on the "Edit Revision" interface. If you return true from this method, you must implement setValueFromRequest(), renderEditControl() and validateField().

For a concrete example of a field which implements an edit interface, see DifferentialRevertPlanFieldSpecification.

Determine if this field should appear in the table on the revision list interface.

Determine if this field should appear on the revision detail view interface. One use of this interface is to add purely informational fields to the revision view, without any sort of backing storage.

If you return true from this method, you must implement the methods renderLabelForRevisionView() and renderValueForRevisionView().

Determine if user mentions should be extracted from the value and added to CC when creating revision. Mentions are then extracted from the string returned by renderValueForCommitMessage().

By default, mentions are not extracted.

In revision control systems which read revision information from the working copy, the user may edit the commit message outside of invoking "arc diff --edit". When they do this, only some fields (those fields which can not be edited by other users) are safe to overwrite. For instance, it is fine to overwrite "Summary" because no one else can edit it, but not to overwrite "Reviewers" because reviewers may have been added or removed via the web interface.

If a field is safe to overwrite when edited in a working copy commit message, return true. If the authoritative value should always be used, return false. By default, fields can not be overwritten.

arc will only attempt to overwrite field values if run with "--verbatim".

This method will be called after setValueFromRequest() but before the field is saved. It gives you an opportunity to inspect the field value and throw a DifferentialFieldValidationException if there is a problem with the value the user has provided (for example, the value the user entered is not correctly formatted). This method is also called after setValueFromParsedCommitMessage() before the revision is saved.

By default, fields are not validated.

Hook for applying revision changes via the editor. Normally, you should not implement this, but a number of builtin fields use the revision object itself as storage. If you need to do something similar for whatever reason, this method gives you an opportunity to interact with the editor or revision before changes are saved (for example, you can write the field's value into some property of the revision).