diff --git a/src/docs/user/configuration/custom_fields.diviner b/src/docs/user/configuration/custom_fields.diviner index ce7bd22b32..cfde51569e 100644 --- a/src/docs/user/configuration/custom_fields.diviner +++ b/src/docs/user/configuration/custom_fields.diviner @@ -1,197 +1,199 @@ @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. - **instructions**: Optional block of remarkup text which will appear above the control when rendered on the edit view. + - **placeholder**: A placeholder text that appears on text boxes. Only + supported in text, int and remarkup fields (optional). 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. Internally, Phabricator implements some additional custom field types and options. These are not intended for general use and are subject to abrupt change, but are documented here for completeness: - **Credentials**: Controls with type `credential` allow selection of a Passphrase credential which provides `credential.provides`, and creation of credentials of `credential.type`. = 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/infrastructure/customfield/standard/PhabricatorStandardCustomField.php b/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php index 0a7ef680fd..8f9394589c 100644 --- a/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php +++ b/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php @@ -1,389 +1,394 @@ setAncestorClass(__CLASS__) ->loadObjects(); $types = mpull($types, null, 'getFieldType'); $fields = array(); foreach ($config as $key => $value) { $type = idx($value, 'type', 'text'); if (empty($types[$type])) { // TODO: We should have better typechecking somewhere, and then make // this more serious. continue; } $namespace = $template->getStandardCustomFieldNamespace(); $full_key = "std:{$namespace}:{$key}"; $template = clone $template; $standard = id(clone $types[$type]) ->setRawStandardFieldKey($key) ->setFieldKey($full_key) ->setFieldConfig($value) ->setApplicationField($template); $field = $template->setProxy($standard); $fields[] = $field; } return $fields; } public function setApplicationField( PhabricatorStandardCustomFieldInterface $application_field) { $this->applicationField = $application_field; return $this; } public function getApplicationField() { return $this->applicationField; } public function setFieldName($name) { $this->fieldName = $name; return $this; } public function getFieldValue() { return $this->fieldValue; } public function setFieldValue($value) { $this->fieldValue = $value; return $this; } public function setCaption($caption) { $this->caption = $caption; return $this; } public function getCaption() { return $this->caption; } public function setFieldDescription($description) { $this->fieldDescription = $description; return $this; } public function setFieldConfig(array $config) { foreach ($config as $key => $value) { switch ($key) { case 'name': $this->setFieldName($value); break; case 'description': $this->setFieldDescription($value); break; case 'strings': $this->setStrings($value); break; case 'caption': $this->setCaption($value); break; case 'required': $this->setRequired($value); $this->setFieldError(true); break; case 'default': $this->setFieldValue($value); break; case 'type': // We set this earlier on. break; } } $this->fieldConfig = $config; return $this; } public function getFieldConfigValue($key, $default = null) { return idx($this->fieldConfig, $key, $default); } public function setFieldError($field_error) { $this->fieldError = $field_error; return $this; } public function getFieldError() { return $this->fieldError; } public function setRequired($required) { $this->required = $required; return $this; } public function getRequired() { return $this->required; } public function setRawStandardFieldKey($raw_key) { $this->rawKey = $raw_key; return $this; } public function getRawStandardFieldKey() { return $this->rawKey; } /* -( PhabricatorCustomField )--------------------------------------------- */ public function setFieldKey($field_key) { $this->fieldKey = $field_key; return $this; } public function getFieldKey() { return $this->fieldKey; } public function getFieldName() { return coalesce($this->fieldName, parent::getFieldName()); } public function getFieldDescription() { return coalesce($this->fieldDescription, parent::getFieldDescription()); } public function setStrings(array $strings) { $this->strings = $strings; return; } public function getString($key, $default = null) { return idx($this->strings, $key, $default); } public function shouldUseStorage() { return true; } public function getValueForStorage() { return $this->getFieldValue(); } public function setValueFromStorage($value) { return $this->setFieldValue($value); } public function shouldAppearInApplicationTransactions() { return true; } public function shouldAppearInEditView() { return $this->getFieldConfigValue('edit', true); } public function readValueFromRequest(AphrontRequest $request) { $value = $request->getStr($this->getFieldKey()); if (!strlen($value)) { $value = null; } $this->setFieldValue($value); } public function getInstructionsForEdit() { return $this->getFieldConfigValue('instructions'); } + public function getPlaceholder() { + return $this->getFieldConfigValue('placeholder', null); + } + public function renderEditControl(array $handles) { return id(new AphrontFormTextControl()) ->setName($this->getFieldKey()) ->setCaption($this->getCaption()) ->setValue($this->getFieldValue()) ->setError($this->getFieldError()) - ->setLabel($this->getFieldName()); + ->setLabel($this->getFieldName()) + ->setPlaceholder($this->getPlaceholder()); } public function newStorageObject() { return $this->getApplicationField()->newStorageObject(); } public function shouldAppearInPropertyView() { return $this->getFieldConfigValue('view', true); } public function renderPropertyViewValue(array $handles) { if (!strlen($this->getFieldValue())) { return null; } return $this->getFieldValue(); } public function shouldAppearInApplicationSearch() { return $this->getFieldConfigValue('search', false); } protected function newStringIndexStorage() { return $this->getApplicationField()->newStringIndexStorage(); } protected function newNumericIndexStorage() { return $this->getApplicationField()->newNumericIndexStorage(); } public function buildFieldIndexes() { return array(); } public function readApplicationSearchValueFromRequest( PhabricatorApplicationSearchEngine $engine, AphrontRequest $request) { return; } public function applyApplicationSearchConstraintToQuery( PhabricatorApplicationSearchEngine $engine, PhabricatorCursorPagedPolicyAwareQuery $query, $value) { return; } public function appendToApplicationSearchForm( PhabricatorApplicationSearchEngine $engine, AphrontFormView $form, $value, array $handles) { return; } public function validateApplicationTransactions( PhabricatorApplicationTransactionEditor $editor, $type, array $xactions) { $this->setFieldError(null); $errors = parent::validateApplicationTransactions( $editor, $type, $xactions); if ($this->getRequired()) { $value = $this->getOldValueForApplicationTransactions(); $transaction = null; foreach ($xactions as $xaction) { $value = $xaction->getNewValue(); if (!$this->isValueEmpty($value)) { $transaction = $xaction; break; } } if ($this->isValueEmpty($value)) { $error = new PhabricatorApplicationTransactionValidationError( $type, pht('Required'), pht('%s is required.', $this->getFieldName()), $transaction); $error->setIsMissingFieldError(true); $errors[] = $error; $this->setFieldError(pht('Required')); } } return $errors; } protected function isValueEmpty($value) { if (is_array($value)) { return empty($value); } return !strlen($value); } public function getApplicationTransactionTitle( PhabricatorApplicationTransaction $xaction) { $author_phid = $xaction->getAuthorPHID(); $old = $xaction->getOldValue(); $new = $xaction->getNewValue(); if (!$old) { return pht( '%s set %s to %s.', $xaction->renderHandleLink($author_phid), $this->getFieldName(), $new); } else if (!$new) { return pht( '%s removed %s.', $xaction->renderHandleLink($author_phid), $this->getFieldName()); } else { return pht( '%s changed %s from %s to %s.', $xaction->renderHandleLink($author_phid), $this->getFieldName(), $old, $new); } } public function getApplicationTransactionTitleForFeed( PhabricatorApplicationTransaction $xaction, PhabricatorFeedStory $story) { $author_phid = $xaction->getAuthorPHID(); $object_phid = $xaction->getObjectPHID(); $old = $xaction->getOldValue(); $new = $xaction->getNewValue(); if (!$old) { return pht( '%s set %s to %s on %s.', $xaction->renderHandleLink($author_phid), $this->getFieldName(), $new, $xaction->renderHandleLink($object_phid)); } else if (!$new) { return pht( '%s removed %s on %s.', $xaction->renderHandleLink($author_phid), $this->getFieldName(), $xaction->renderHandleLink($object_phid)); } else { return pht( '%s changed %s from %s to %s on %s.', $xaction->renderHandleLink($author_phid), $this->getFieldName(), $old, $new, $xaction->renderHandleLink($object_phid)); } } public function getHeraldFieldValue() { return $this->getFieldValue(); } } diff --git a/src/view/form/control/AphrontFormTextControl.php b/src/view/form/control/AphrontFormTextControl.php index 78078fd949..a507b0e74e 100644 --- a/src/view/form/control/AphrontFormTextControl.php +++ b/src/view/form/control/AphrontFormTextControl.php @@ -1,42 +1,55 @@ disableAutocomplete = $disable; return $this; } + private function getDisableAutocomplete() { return $this->disableAutocomplete; } + public function getPlaceholder() { + return $this->placeholder; + } + + public function setPlaceholder($placeholder) { + $this->placeholder = $placeholder; + return $this; + } + public function getSigil() { return $this->sigil; } + public function setSigil($sigil) { $this->sigil = $sigil; return $this; } protected function getCustomControlClass() { return 'aphront-form-control-text'; } protected function renderInput() { return javelin_tag( 'input', array( 'type' => 'text', 'name' => $this->getName(), 'value' => $this->getValue(), 'disabled' => $this->getDisabled() ? 'disabled' : null, 'autocomplete' => $this->getDisableAutocomplete() ? 'off' : null, 'id' => $this->getID(), 'sigil' => $this->getSigil(), + 'placeholder' => $this->getPlaceholder() )); } } diff --git a/webroot/rsrc/css/phui/phui-form-view.css b/webroot/rsrc/css/phui/phui-form-view.css index 52f266174a..10d7cfdae5 100644 --- a/webroot/rsrc/css/phui/phui-form-view.css +++ b/webroot/rsrc/css/phui/phui-form-view.css @@ -1,453 +1,467 @@ /** * @provides phui-form-view-css */ .phui-form-view { padding: 16px; } .phui-form-view.phui-form-full-width { padding: 0; } /* only used in transaction comments */ .phui-form-shaded .phui-form-view { border-bottom: 1px solid #D4DAE0; background: #F4F5F8; } .phui-form-view label.aphront-form-label { padding-top: 5px; width: 19%; float: left; text-align: right; font-weight: bold; font-size: 13px; color: {$bluetext}; -webkit-font-smoothing: antialiased; } .device-phone .phui-form-view label.aphront-form-label, .phui-form-full-width.phui-form-view label.aphront-form-label { display: block; float: none; text-align: left; width: 100%; margin-bottom: 3px; } .aphront-form-input { margin-left: 20%; margin-right: 20%; width: 60%; } .device-phone .aphront-form-input, .phui-form-full-width .aphront-form-input { margin-left: 0%; margin-right: 0%; width: 100%; } +.aphront-form-input *::-webkit-input-placeholder { + color:{$greytext} !important; +} + +.aphront-form-input *::-moz-placeholder { + color:{$greytext} !important; + opacity: 1; /* Firefox nudges the opacity to 0.4 */ +} + +.aphront-form-input *:-ms-input-placeholder { + color:{$greytext} !important; +} + + .aphront-form-error { width: 18%; float: right; color: {$red}; font-weight: bold; padding-top: 5px; } .aphront-dialog-body .phui-form-full-width { margin-top: -10px; } .aphront-dialog-body .phui-form-view { padding: 0; } .device-phone .aphront-form-error, .phui-form-full-width .aphront-form-error { float: none; width: 100%; } .device-phone .aphront-form-drag-and-drop-upload { display: none; } .aphront-form-required { font-weight: normal; color: {$lightgreytext}; font-size: 11px; -webkit-font-smoothing: antialiased; } .aphront-form-input input { width: 100%; } .aphront-form-input textarea { display: block; width: 100%; box-sizing: border-box; height: 12em; } .aphront-form-control { padding: 4px; } .phui-form-full-width .aphront-form-control { padding: 4px 0; } .aphront-form-control-submit button, .aphront-form-control-submit a.button { float: right; margin: 4px 0 0 8px; } .phui-form-control-multi-submit input, .phui-form-control-multi-submit button, .phui-form-control-multi-submit a { float: right; margin: 4px 0 0 8px; width: auto; } .aphront-form-control-textarea textarea.aphront-textarea-very-short { height: 44px; } .aphront-form-control-textarea textarea.aphront-textarea-very-tall { height: 24em; } .aphront-form-control-select .aphront-form-input { padding-top: 2px; } .phui-form-view .aphront-form-caption { font-size: 12px; color: {$bluetext}; padding: 8px 4px; text-align: right; margin-right: 20%; margin-left: 20%; -webkit-font-smoothing: antialiased; line-height: 15px; } .device-phone .phui-form-view .aphront-form-caption, .phui-form-full-width .phui-form-view .aphront-form-caption { margin-right: 0%; } /* override for when inside an aphront-panel-view */ .aphront-panel-view .phui-form-view h1 { padding: 0em 0em .8em 0em; } .aphront-form-instructions { width: 60%; margin-left: 20%; padding: 10px 4px; } .device .aphront-form-instructions, .phui-form-full-width .aphront-form-instructions { width: 100%; margin: 0; } .aphront-form-important { margin: .5em 0; background: #ffffdd; padding: .5em 1em; } .aphront-form-important code { display: block; padding: .25em; margin: .5em 2em; } .aphront-form-control-static .aphront-form-input, .aphront-form-control-markup .aphront-form-input { padding-top: 6px; font-size: 13px; } .aphront-form-control-togglebuttons .aphront-form-input { padding: 2px 0 0 0; } table.aphront-form-control-radio-layout, table.aphront-form-control-checkbox-layout { margin-top: 3px; font-size: 13px; } table.aphront-form-control-radio-layout th { padding-top: 3px; padding-left: 8px; padding-bottom: 4px; font-weight: bold; color: {$darkgreytext}; } table.aphront-form-control-checkbox-layout th { padding-top: 2px; padding-left: 8px; padding-bottom: 4px; color: {$darkgreytext}; } .aphront-form-control-radio-layout td input, .aphront-form-control-checkbox-layout td input { margin-top: 4px; width: auto; } .aphront-form-control-radio-layout label.disabled, .aphront-form-control-checkbox-layout label.disabled { color: {$greytext}; } .aphront-form-radio-caption { margin-top: 4px; font-size: 12px; font-weight: normal; color: #555; } .aphront-form-control-image span { margin: 0 4px 0 2px; } .aphront-form-control-image .default-image { display: inline; width: 12px; } .aphront-form-input hr { border: none; background: #bbbbbb; height: 1px; position: relative; } .aphront-form-inset { margin: 0 0 8px; padding: 8px; background: #fff; border: 1px solid #d4dae0; } .aphront-form-inset h1 { color: {$greytext}; font-weight: normal; padding-bottom: 8px; } .aphront-form-drag-and-drop-file-list { width: 400px; } .drag-and-drop-instructions { color: {$darkgreytext}; font-size: 11px; padding: 6px 8px; } .drag-and-drop-file-target { border: 1px dashed #bfbfbf; padding-top: 12px; padding-bottom: 12px; } .aphront-textarea-drag-and-drop { background: {$lightgreen}; border-color: {$green}; } .aphront-form-crop .crop-box { cursor: move; overflow: hidden; } .aphront-form-crop .crop-box .crop-image { position: relative; top: 0px; left: 0px; } .calendar-button { display: inline; background: url(/rsrc/image/icon/fatcow/calendar_edit.png) no-repeat center center; padding: 8px 12px; margin: 2px 8px 2px 2px; position: relative; border: 1px solid transparent; } .aphront-form-date-container { position: relative; display: inline; } .aphront-form-date-container select { margin: 2px; display: inline; } .aphront-form-date-container input.aphront-form-date-enabled-input { width: auto; display: inline; margin-right: 8px; font-size: 16px; } .aphront-form-date-container input.aphront-form-date-time-input { width: 7em; display: inline; } .fancy-datepicker { position: absolute; width: 240px; } .fancy-datepicker-core { padding: 1px; font-size: 11px; font-family: Verdana; text-align: center; } .fancy-datepicker-core .month-table, .fancy-datepicker-core .day-table { margin: 0 auto; border-collapse: separate; border-spacing: 1px; width: 100%; } .fancy-datepicker-core .month-table { margin-bottom: 6px; } .fancy-datepicker-core .month-table td.lrbutton { width: 20%; } .fancy-datepicker-core .month-table td { padding: 4px; font-weight: bold; color: {$darkgreytext}; } .fancy-datepicker-core .month-table td.lrbutton { background: #e6e6e6; border: 1px solid; border-color: #a6a6a6 #969696 #868686 #a6a6a6; } .fancy-datepicker-core .day-table td { overflow: hidden; background: #f6f6f6; vertical-align: center; text-align: center; border: 1px solid #d6d6d6; padding: 4px 0; } .fancy-datepicker-core .day-table td.day-placeholder { border-color: transparent; background: transparent; } .fancy-datepicker-core .day-table td.weekend { color: {$greytext}; border-color: #e6e6e6; } .fancy-datepicker-core .day-table td.day-name { background: transparent; border: 1px transparent; vertical-align: bottom; color: {$lightgreytext}; } .fancy-datepicker-core .day-table td.today { background: #eeee99; border-color: #aaaa66; } .fancy-datepicker-core .day-table td.datepicker-selected { background: #0099ff; border-color: #0066cc; } .fancy-datepicker-core td { cursor: pointer; } .fancy-datepicker-core td.novalue { cursor: inherit; } .picker-open .calendar-button, .fancy-datepicker-core { background-color: white; border: 1px solid {$greytext}; box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.25); } .picker-open .calendar-button { border-left: 1px solid white; } .login-to-comment { margin: 12px; } .phui-form-divider hr { height: 1px; border: 0; background: #c0c0c0; width: 85%; margin: 15px auto; } .recaptcha_only_if_privacy { display: none; } .phabricator-standard-custom-field-header { font-size: 16px; color: {$bluetext}; border-bottom: 1px solid {$lightbluetext}; padding: 16px 0 4px; margin-bottom: 4px; } .device-desktop .text-with-submit-control-outer-bounds { position: relative; } .device-desktop .text-with-submit-control-text-bounds { position: absolute; left: 0; right: 184px; } .device-desktop .text-with-submit-control-submit-bounds { text-align: right; } .device-desktop .text-with-submit-control-submit { width: 180px; }