From acfc3c3e5d8456603fc2da51e7c27e2e115a93b3 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Tue, 25 Mar 2014 16:12:49 -0700
Subject: [PATCH] Add an "instructions" key to custom fields

Summary: Ref T1049. I'm planning to use this in Harbormaster custom fields shortly.

Test Plan: {F133843}

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: epriestley

Maniphest Tasks: T1049

Differential Revision: https://secure.phabricator.com/D8606
---
 src/docs/user/configuration/custom_fields.diviner     |  2 ++
 .../customfield/field/PhabricatorCustomField.php      | 11 +++++++++++
 .../customfield/field/PhabricatorCustomFieldList.php  |  6 ++++++
 .../standard/PhabricatorStandardCustomField.php       |  4 ++++
 4 files changed, 23 insertions(+)

diff --git a/src/docs/user/configuration/custom_fields.diviner b/src/docs/user/configuration/custom_fields.diviner
index cc7d45dae3..254a04a0b6 100644
--- a/src/docs/user/configuration/custom_fields.diviner
+++ b/src/docs/user/configuration/custom_fields.diviner
@@ -101,6 +101,8 @@ When defining custom fields using a configuration option like
   - **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.
 
 The `strings` value supports different strings per control type. They are:
 
diff --git a/src/infrastructure/customfield/field/PhabricatorCustomField.php b/src/infrastructure/customfield/field/PhabricatorCustomField.php
index f9bf92ac4d..3e03f7dffd 100644
--- a/src/infrastructure/customfield/field/PhabricatorCustomField.php
+++ b/src/infrastructure/customfield/field/PhabricatorCustomField.php
@@ -1060,6 +1060,17 @@ abstract class PhabricatorCustomField {
   }
 
 
+  /**
+   * @task edit
+   */
+  public function getInstructionsForEdit() {
+    if ($this->proxy) {
+      return $this->proxy->getInstructionsForEdit();
+    }
+    return null;
+  }
+
+
   /**
    * @task edit
    */
diff --git a/src/infrastructure/customfield/field/PhabricatorCustomFieldList.php b/src/infrastructure/customfield/field/PhabricatorCustomFieldList.php
index df3b6a4ea2..d7ff2a3585 100644
--- a/src/infrastructure/customfield/field/PhabricatorCustomFieldList.php
+++ b/src/infrastructure/customfield/field/PhabricatorCustomFieldList.php
@@ -108,6 +108,12 @@ final class PhabricatorCustomFieldList extends Phobject {
 
     foreach ($enabled as $field_key => $field) {
       $field_handles = array_select_keys($handles, $phids[$field_key]);
+
+      $instructions = $field->getInstructionsForEdit();
+      if (strlen($instructions)) {
+        $form->appendRemarkupInstructions($instructions);
+      }
+
       $form->appendChild($field->renderEditControl($field_handles));
     }
   }
diff --git a/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php b/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php
index 14a9ef6d54..9df9e6f1e8 100644
--- a/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php
+++ b/src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php
@@ -211,6 +211,10 @@ abstract class PhabricatorStandardCustomField
     $this->setFieldValue($value);
   }
 
+  public function getInstructionsForEdit() {
+    return $this->getFieldConfigValue('instructions');
+  }
+
   public function renderEditControl(array $handles) {
     return id(new AphrontFormTextControl())
       ->setName($this->getFieldKey())